OpenCode 使用指南：安裝、模型設定、Plan/Build 代理與從 Claude Code 遷移

OpenCode 是一款開源的 AI 程式設計代理，可以在終端機、桌面應用程式或 IDE 擴充功能中使用。它常被拿來和 Anthropic 的 Claude Code 比較，因為兩者思路相近：代理讀取你的程式庫、規劃修改、編輯檔案並執行指令。最大的差別在於 OpenCode 不綁定單一模型廠商。本文整理 OpenCode 是什麼、如何安裝、如何連接模型（包括本地模型）、Plan 與 Build 兩種代理如何運作，以及它和 Claude Code 的關係。

OpenCode 是什麼

專案位於 github.com/anomalyco/opencode，採用 MIT 授權，主要以 TypeScript 撰寫。根據官方 Providers 文件，OpenCode 透過 AI SDK 與 Models.dev 支援超過 75 家模型供應商，也能執行本地模型。

要注意的是，官方文件目前區分 OpenCode 1 與 OpenCode 2。兩者都使用 opencode 指令，預設情況下無法並存安裝，所以照著教學操作前，先確認教學針對的是哪個主要版本（官方文件）。

	Claude Code	OpenCode
原始碼	閉源	開源（MIT）
模型	Anthropic 模型	75+ 家供應商與本地模型
介面	終端機、IDE 整合、桌面與網頁	終端機介面、桌面應用、IDE 擴充
專案指示檔	CLAUDE.md	AGENTS.md（無則讀取 CLAUDE.md）

安裝

macOS 與 Linux 最簡單的方式是官方安裝腳本：

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

文件也列出套件管理器的安裝方式：

npm install -g opencode-ai
brew install anomalyco/tap/opencode   # OpenCode 1 的 tap

文件說明，Homebrew 直接執行 brew install opencode 會安裝 OpenCode 2，所以要裝 1 版需使用上面的 tap。

Windows 使用者：官方建議在 WSL（Windows Subsystem for Linux）中執行，效能較好、功能也完整相容。原生方式包括 Chocolatey（choco install opencode）、Scoop（scoop install opencode）、npm、Mise 以及 Docker 映像檔。若在原生終端機遇到顯示異常，WSL 是文件建議的替代方案。官方也建議使用 WezTerm、Alacritty、Ghostty 或 Kitty 等較新的終端機。

連接模型

在介面中輸入 /connect 即可新增 API 金鑰，金鑰會存放在 ~/.local/share/opencode/auth.json。新手可以先用 OpenCode Zen，這是 OpenCode 團隊測試過的精選模型清單，在 opencode.ai/auth 登入、填寫付款資訊後貼上金鑰即可。

供應商設定寫在 opencode.json 的 provider 區塊，模型 ID 格式為「供應商/模型 ID」。

用 Ollama 跑本地模型

官方 Providers 頁面示範把 Ollama 設為 OpenAI 相容供應商：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": { "llama2": { "name": "Llama 2" } }
    }
  }
}

把模型 ID 換成你在 Ollama 中下載的模型即可。代理非常依賴穩定的工具呼叫，小型本地模型在這方面通常不如雲端旗艦模型。本地執行的主要價值是隱私與成本控制，而不是追平雲端模型的品質。

初始化專案

在專案目錄執行 opencode，再輸入 /init。OpenCode 會分析專案並在根目錄產生 AGENTS.md，官方建議把它提交到 Git，讓代理對專案結構與慣例保持一致的理解（Rules 文件）。

常用操作：

• 輸入 @ 可模糊搜尋檔案並加入提示。
• /undo 撤銷上一次修改並還原你的訊息，方便重新描述；/redo 則重新套用。
• 可以把圖片拖進終端機，例如當作設計參考。

Plan 與 Build 兩種代理

OpenCode 內建兩個主要代理，用 Tab 鍵切換（Agents 文件）：

• Build：預設代理，所有工具皆可使用。
• Plan：用於分析與規劃。預設會拒絕修改檔案（Markdown 計畫檔除外），並可主動提問釐清需求。文件特別提醒，Plan 預設不限制 bash，指令是否執行取決於你的權限設定。

另有內建子代理：General 用於多步驟研究任務，Explore 是快速、唯讀的程式碼搜尋代理，可用 @ 呼叫。

建議流程是：先在 Plan 模式描述功能並反覆調整計畫，滿意後按 Tab 切到 Build 讓它實作。

權限設定

每個工具都可設為 allow、ask 或 deny，可全域設定，也可針對單一代理，甚至針對特定 shell 指令。例如可以讓 git push 必須確認、grep 直接放行。若要讓 Plan 嚴格唯讀，文件示範將其 edit 設為 deny、bash 設為 ask。也可以用 steps 限制代理迭代次數以控制成本。

自訂代理

代理可寫在 opencode.json，或以 Markdown 檔放在 .opencode/agents/（專案）或 ~/.config/opencode/agents/（全域）。常見例子是設定 edit: deny 的唯讀程式碼審查子代理。

從 Claude Code 遷移

OpenCode 會把部分 Claude Code 慣例當作備援讀取（Rules 文件）：

• 專案中沒有 AGENTS.md 時，讀取專案的 CLAUDE.md；
• 沒有全域 OpenCode AGENTS.md 時，讀取 ~/.claude/CLAUDE.md；
• 讀取 ~/.claude/skills/ 中的技能。

可用環境變數 OPENCODE_DISABLE_CLAUDE_CODE=1 關閉。MCP 伺服器等其他設定仍需在 OpenCode 自己的設定檔中重新配置，因此遷移時要預留一些調整時間，不是完全即插即用。

適合哪些人

• 需要自由選擇模型的團隊：可透過每個代理的 model 設定，讓規劃用便宜模型、實作用較強模型。
• 重視隱私的場景：程式碼留在本機，但需接受本地模型的品質限制。
• 想檢視或擴充工具本身的開發者：原始碼完全公開。

如果你已經訂閱 Anthropic 方案、偏好單一廠商的整合體驗，Claude Code 仍是合理選擇。兩者可以裝在同一台電腦上，先在小專案試用 OpenCode，是成本很低的比較方式。

參考資料

• OpenCode 官方文件：Intro
• OpenCode 官方文件：Agents
• OpenCode 官方文件：Providers
• OpenCode 官方文件：Rules
• OpenCode GitHub