如何安裝與使用 OpenCode：完整指南

大约 13 分鐘

如何安裝與使用 OpenCode：完整指南

OpenCode 是一款開源的 AI 程式碼代理，將人工智慧的力量直接帶入你的終端機。與傳統只在編輯器或瀏覽器中運作的 AI 程式碼工具不同，OpenCode 提供了基於終端機的介面、桌面應用程式與 IDE 擴充功能，全部都是為了讓你成為更高效率的開發者而設計。本篇全面指南將帶你了解安裝、設定與有效使用 OpenCode 的所有必要知識。

什麼是 OpenCode？

OpenCode 是一款由 AI 驅動的程式碼助理，可以幫助你：

更快撰寫程式碼，透過智慧化的程式碼生成與補全
高效偵錯，分析錯誤並建議修正方案
理解程式碼庫，以自然語言查詢為基礎
新增功能，自動規劃與實作
程式碼審查，以 AI 分析並提供建議
自動化工作流程，利用 AI 代理與自訂工具

它支援多個大型語言模型（LLM）提供者，包括 Anthropic、OpenAI、Google 等，讓你可靈活選擇最適合需求的模型。

系統需求

前置條件

安裝 OpenCode 前請確認：

現代終端機模擬器（用於 TUI 操作）：
- WezTerm - 跨平台
- Alacritty - 跨平台
- Ghostty - Linux 與 macOS
- Kitty - Linux 與 macOS
Node.js（用於 npm/bun/pnpm/yarn 安裝）：
- 建議 Node.js 版本 18 或以上
LLM 提供者的 API 金鑰：
- Anthropic API key（用於 Claude 模型）
- OpenAI API key（用於 GPT 模型）
- 或其他支援提供者的金鑰

安裝方式

方式一：安裝腳本（推薦）

最快速的安裝方式是使用官方安裝腳本：

curl -fsSL https://opencode.ai/install | bash

此方法適用於 macOS、Linux 與 Windows（須有 Git Bash 或 WSL）。

方式二：使用 Node.js 套件管理器

使用 npm：

npm install -g opencode-ai

使用 Bun：

bun install -g opencode-ai

使用 pnpm：

pnpm install -g opencode-ai

使用 Yarn：

yarn global add opencode-ai

方式三：使用 Homebrew（macOS 與 Linux）

brew install opencode

方式四：使用 Paru（Arch Linux）

paru -S opencode-bin

方式五：Windows 特別安裝方式

使用 Chocolatey：

choco install opencode

使用 Scoop：

scoop bucket add extras
scoop install extras/opencode

使用 Mise：

mise use -g github:sst/opencode

方式六：Docker

容器化使用方式：

docker run -it --rm ghcr.io/sst/opencode

方式七：下載執行檔

你可以直接從 GitHub Releases 頁面下載預編譯的二進位檔。

驗證安裝

安裝完成後，驗證是否正常運作：

opencode --version

應該會顯示版本號。

初始設定

連接到 OpenCode Zen（新手推薦）

OpenCode Zen 是 OpenCode 團隊精選且測試過的模型清單，方便快速入門。

啟動 OpenCode：

cd /path/to/your/project
opencode

在 TUI 執行連接指令：

/connect

從提供者清單中選擇 "opencode"
前往認證網址：opencode.ai/auth
登入並新增付款資訊（若有免費額度可使用）
複製你的 API 金鑰，並在終端機提示時貼上

連接其他提供者

你也可以將 OpenCode 連接到其他 LLM 服務：

使用 `/connect` 指令：

/connect

選擇你偏好的提供者（Anthropic、OpenAI、Google 等）並依照流程認證。

使用 CLI 認證：

opencode auth login

此指令會引導你設定 Models.dev 支援的任一提供者 API 金鑰。

列出已設定的提供者：

opencode auth list

或簡短指令：

opencode auth ls

登出提供者：

opencode auth logout

設定專案上下文

設定好提供者後，初始化你的專案：

cd /path/to/your/project

啟動 OpenCode：

opencode

執行初始化指令：

/init

這會分析你的專案架構，並在專案根目錄建立 AGENTS.md 檔案，幫助 OpenCode 了解你的編程模式、框架與專案結構。

小提醒：將 AGENTS.md 提交到 Git，有助於維持團隊間一致性，並隨著時間提升 OpenCode 對專案的理解。

使用終端機使用者介面（TUI）

OpenCode 的 TUI 在終端機提供互動式體驗。

啟動 TUI

直接執行：

opencode

或搭配選項：

# 繼續上次會話
opencode --continue

# 繼續指定會話
opencode --session <session-id>

# 以提示語開始
opencode --prompt "Explain this codebase"

# 使用特定模型
opencode --model anthropic/claude-sonnet-4-5

# 使用特定代理人
opencode --agent plan

基本 TUI 操作

捲動：使用滑鼠滾輪或方向鍵
切換模式：按 Tab 鍵在規劃模式與建置模式間切換
執行指令：輸入 / 進入指令面板
搜尋檔案：使用 @ 符號模糊搜尋專案檔案
離開：按 Ctrl+C 或使用 /exit

提問

你可以向 OpenCode 問關於程式碼庫的問題：

How is authentication handled in @packages/functions/src/api/index.ts

使用 @ 符號引用特定檔案，OpenCode 會分析並提供詳細說明。

新增功能

OpenCode 透過雙模式工作流程來幫助新增功能：

第一步：規劃模式

按 Tab 切換到 規劃模式
描述需求：

When a user deletes a note, we'd like to flag it as deleted in the database.
Then create a screen that shows all the recently deleted notes.
From this screen, the user can undelete a note or permanently delete it.

審核建議方案
依回饋調整：

We'd like to design this new screen using a design I've used before.
[Image #1] Take a look at this image and use it as a reference.

小提醒：你可以將圖片拖放進終端機，OpenCode 將會掃描並分析。

第二步：建置模式

再次按 Tab 切換到 建置模式
確認實作：

Sounds good! Go ahead and make the changes.

OpenCode 隨即開始實作，根據需求建立與修改檔案。

直接修改

針對簡單的變更，可以跳過規劃：

We need to add authentication to the /settings route.
Take a look at how this is handled in the /notes route
in @packages/functions/src/notes.ts and implement the same logic
in @packages/functions/src/settings.ts

還原與重做變更

犯錯了？使用還原指令：

/undo

這會回復最後一批變更，方便你調整提示語。

重做剛剛還原的變更：

/redo

你可以多次使用 /undo 還原多次變更。

CLI 指令

OpenCode 提供強大的 CLI 功能，方便程式化存取與自動化。

執行直接提示

非互動式執行 OpenCode：

opencode run "Explain how closures work in JavaScript"

適合腳本、整合或快速解答，不需啟動 TUI。

管理模型

列出所有可用模型：

opencode models

依提供者過濾：

opencode models anthropic

刷新模型快取（新增模型時有用）：

opencode models --refresh

顯示詳細模型資訊（含成本）：

opencode models --verbose

啟動無界面伺服器

啟動 HTTP 伺服器以供 API 存取：

opencode serve

指定自訂埠號：

opencode serve --port 3000

方便與網頁應用整合，或在腳本中避免 MCP 伺服器冷啟動，提高回應速度。

附加到伺服器

先在一個終端機啟動伺服器：

opencode serve

另一個終端機附加使用，加快執行：

opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"

管理代理人

建立新的自訂代理人：

opencode agent create

引導你設定包含系統提示及工具配置的代理人。

GitHub 整合

安裝 GitHub 代理人以實現倉庫自動化：

opencode github install

設定 GitHub Actions 工作流程，用於自動程式碼審查與問題管理。

升級 OpenCode

升級到最新版本：

opencode upgrade

或升級到指定版本：

opencode upgrade v0.1.48

必要時指定安裝方式：

opencode upgrade --method brew

設定

OpenCode 支援透過 JSON 配置檔靈活設定。

設定檔位置

配置檔會合併，不會覆蓋，支援全域、專案專屬及自訂設定。

全域設定：~/.config/opencode/opencode.json
- 用於主題、提供者、快捷鍵與一般設定
專案設定：專案根目錄下的 opencode.json
- 用於專案特定的提供者、代理人或設定
- 可以安全提交到 Git
自訂設定路徑：透過環境變數 OPENCODE_CONFIG 設定
自訂設定目錄：透過環境變數 OPENCODE_CONFIG_DIR 設定

基本設定範例

建立以下結構的配置檔：

{
  "$schema": "https://opencode.ai/config.json",
  
  // 主題選擇
  "theme": "opencode",
  
  // 使用的主要模型
  "model": "anthropic/claude-sonnet-4-5",
  
  // 輕量任務的小型模型
  "small_model": "anthropic/claude-haiku-4-5",
  
  // 自動更新設定
  "autoupdate": true
}

配置提供者

直接在配置檔中設定 API 金鑰：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

建議使用環境變數，安全性更佳。格式為 {env:VARIABLE_NAME}。

使用檔案參考

也可以引用檔案以儲存敏感資料：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

自訂指令

定義重複任務的自訂指令：

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run full test suite with coverage report and show any failures.\nFocus on failing tests and suggest fixes.",
      "description": "執行測試並產生覆蓋率",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "建立新元件"
    }
  }
}

在 TUI 中以 /test 或 /component MyComponent 呼叫。

自訂代理人

建立專用代理人：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "審查程式碼，針對最佳實踐與潛在問題",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一位程式碼審查員。重點在安全性、效能與可維護性。",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

權限設定

控制 OpenCode 不須徵詢即可執行的操作：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

設定操作需使用者批准，避免意外操作。

程式碼格式化工具

設定自動格式化程式碼：

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": false
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

TUI 設定

客製化終端機介面：

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

進階功能

分享對話

可與團隊分享會話內容：

/share

建立可分享的連結並複製到剪貼簿，預設對話不會自動共享。

配置分享行為：

{
  "share": "manual"  // "manual"（手動）、"auto"（自動）、"disabled"（禁用）
}

MCP 伺服器

Model Context Protocol (MCP) 伺服器可擴展 OpenCode 功能：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    }
  }
}

指令與規則

提供專案特定指令：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

OpenCode 會利用這些文件了解你的專案編程標準與慣例。

環境變數

透過環境變數設定 OpenCode：

# 自動分享會話
export OPENCODE_AUTO_SHARE=true

# 自訂設定路徑
export OPENCODE_CONFIG=/path/to/config.json

# 設定配置目錄
export OPENCODE_CONFIG_DIR=/path/to/config-dir

# 禁用自動更新
export OPENCODE_DISABLE_AUTOUPDATE=true

# 禁用預設外掛
export OPENCODE_DISABLE_DEFAULT_PLUGINS=true

# 啟用實驗性模型
export OPENCODE_ENABLE_EXPERIMENTAL_MODELS=true

# 啟用 Exa 網頁搜尋
export OPENCODE_ENABLE_EXA=true

實驗性功能

啟用實驗性功能：

export OPENCODE_EXPERIMENTAL=true

特定實驗功能：

# 啟用圖示偵測
export OPENCODE_EXPERIMENTAL_ICON_DISCOVERY=true

# 在 TUI 禁止選取時拷貝
export OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT=true

# 設定 bash 指令最大輸出長度
export OPENCODE_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTH=10000

# 設定 bash 指令預設逾時（毫秒）
export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=30000