OpenCode：安裝、模型與首次啟動

OpenCode 是一款開源的終端機 AI 程式設計代理：工具本身免費（MIT 授權），而且你可以連接任何模型，從 Claude、GPT 到透過 Ollama 執行的本機模型都可以。這個專案的 GitHub 儲存庫星數已超過二十萬。「可使用任何模型的免費 Claude Code」聽起來很吸引人，但需要說明清楚：工具免費；使用條款則取決於你選擇的模型。

以下內容均依據官方文件：介紹這款工具、如何在 macOS、Linux 或 Windows 上安裝、如何連接模型，以及首次啟動時該做什麼。文中另設費用專節，因為這裡的「免費」只適用於工具本身：模型需要付費，而這也是最常造成混淆的地方。

關於 Ailoot 的實用資訊請見文件。

簡單來說，OpenCode 是什麼？#

簡單來說，OpenCode 和 Claude Code 一樣，會以一般語言接收任務並在你的專案中執行。兩者有兩項不同之處。OpenCode 的程式碼完全開放，你可以閱讀和檢視；而且它不受限於單一模型供應商，支援 75+ 家供應商，從 Anthropic、OpenAI 到在你自己的硬體上執行的本機模型皆可使用。

這個專案由 Anomaly 團隊開發。儲存庫建立於 2025 年 4 月 30 日；截至 2026 年 10 月 4 日，已有超過 211 千顆星和 28 千個分支（已透過 GitHub API 請求查證）。使用的語言是 TypeScript。文件會持續更新，因此以下說明以目前版本為準。

不要混淆這些名稱：目前系列的 npm 套件名為 opencode-ai，儲存庫是 anomalyco/opencode，終端機命令則簡稱 opencode。較舊的文章可能會使用 sst/opencode 這個網址：組織已更名，舊連結現在會重新導向至新連結。

2026 年 10 月 4 日更新：團隊發布了 OpenCode 2.0，也就是這款工具的下一個主要世代。以下安裝與連接模型的說明仍以目前的 1.x 系列為準（使用命令 curl -fsSL https://opencode.ai/install | bash 安裝；截至 2026 年 9 月 30 日，目前版本為 1.18.34）：此版本仍獲積極支援，也是 opencode.ai/docs 官方文件安裝的版本。第二版究竟有哪些變化，以及何時該切換，會在下方的獨立章節說明。

OpenCode 和 Claude Code、Codex 有何不同？#

如果你已經訂閱 Claude，繼續將 Claude Code 作為主要工具是合理的；我們有一份詳細安裝指南。在三種情況下，OpenCode 會是不錯的選擇：你想透過 ChatGPT Plus 或 GitHub Copilot 訂閱方案工作、想執行本機模型而不產生 API 費用，或想用單一介面操作多種模型。我們也有一份 Codex 的評測與安裝指南。

如果你還在挑選工具，可以先看這份概覽：2026 年大家用什麼來寫程式。如果你已安裝 OpenCode，並需要透過 ACP 在 Devin Desktop 中與其他代理連接，請參閱我們的設定指南。

OpenCode 2.0 有哪些變化？#

第二版使用命令 curl -fsSL https://opencode.ai/v2/install | bash 安裝。根據官方遷移指南（opencode.ai/v2/docs/migrate-v1），兩個版本使用相同的 opencode 命令，預設不再並行安裝：v2 安裝程式會取代 v1 二進位檔，而且在透過套件管理員安裝 v2 之前，文件明確要求先移除 v1。不過，設定會從同一批檔案讀取：~/.config/opencode/ 和 <project>/.opencode/，因此設定、代理和 MCP 伺服器無須重寫即可沿用。有三項內容需要重寫：外掛（使用新的 API）、伺服器 API 整合（通訊協定已變更），以及終端機設定（現在改用一個共用的 cli.json 檔案，不再是多個 tui.json 檔案）。

v2 最值得注意的新功能有兩項。第一，推出了 Console，這是一項面向團隊的付費服務，提供使用量追蹤、預算，以及所有成員共用的政策。第二，團隊終於公布了 Go 訂閱方案的價格：Go 每月 $10，具備較高限額的 Go Plus 每月 $40（已於 2026 年 10 月 4 日查證 opencode.ai/go 頁面）。此前，文件只寫「低成本訂閱方案」，未列出金額。

如果你是新手，只想安裝代理，請依照下方說明操作；內容採用官方文件本身推薦的目前第一版。如果你需要新的外掛功能或團隊 Console，可以考慮 v2，但要有心理準備，必須依照新 API 重寫部分舊外掛。如果你比較感興趣的是不需要終端機的開源桌面應用程式，我們有一篇ZCode 評測，介紹另一款擁有自己介面的類似代理。

安裝前需要準備什麼？#

先多談一點終端機，因為安裝過程中只有這一環可能不如預期。OpenCode 會在終端機中呈現包含面板和醒目標示的完整介面，因此文件要求使用新式模擬器。如果啟動後介面顯示異常，先安裝上述四種選項之一：WezTerm（適用於所有系統）、Alacritty、Ghostty 或 Kitty。在 Windows 上，主要安裝方式是透過 WSL，下方有專節說明。

另一項準備是模型。OpenCode 必須透過你連接的模型運作；它本身不會處理請求。共有四種選擇：訂閱方案（ChatGPT Plus、GitHub Copilot、GitLab Duo）、任何供應商的 API 金鑰、團隊自家的模型聚合服務 OpenCode Zen，或透過 Ollama 使用本機模型。連接模型一節會介紹這四種選擇。

如果沒有專案說明，代理就得猜測建置命令、檔案結構和目前採用的慣例，因此會出現「幻覺」。OpenCode 使用 AGENTS.md 檔案來處理這件事。同樣的方法也適用於 Claude Code 和其他任何代理；只有指令檔名稱不同。

如何在 macOS 和 Linux 上安裝 OpenCode？#

建議使用官方安裝程式：

1. 執行安裝程式

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

   指令碼會偵測你的系統並下載 OpenCode。如果安裝後找不到命令，請關閉並重新開啟終端機；新的工作階段就會載入路徑。

2. 確認安裝正確

   opencode --version
   

   命令會傳回版本號，表示安裝成功。如果回應為「command not found」，請回到第一步：啟動新的終端機工作階段，或手動編輯 PATH。

如果你比較喜歡自行管理套件，可以選擇以下方法：

brew install anomalyco/tap/opencode

npm install -g opencode-ai

Homebrew 命令刻意以 anomalyco/tap/ 開頭：文件建議使用他們自己的 tap，因為 Homebrew 團隊較少更新 brew install opencode 所用的 formula。同一個套件名稱 opencode-ai 也能搭配 bun、pnpm 和 yarn 使用（bun install -g opencode-ai、yarn global add opencode-ai）。在 Arch Linux 上，請從穩定版儲存庫使用 sudo pacman -S opencode，或使用 paru -S opencode-bin 從 AUR 安裝最新版本。

使用 opencode upgrade 更新 OpenCode；如果啟用自動更新，啟動時也會自行下載更新。更新後，用熟悉的 opencode --version 檢查版本。也內建解除安裝功能：

opencode uninstall

命令會明確列出即將刪除的內容並要求確認。你可以選擇保留設定和工作階段資料：使用 --keep-config 和 --keep-data 旗標即可。

如何在 Windows 上安裝 OpenCode？#

開發者自己推薦的第一個選項是 WSL。在以系統管理員身分執行的 PowerShell 中，用一個命令安裝：

wsl --install

重新開機後，從開始功能表開啟 Ubuntu，並在其中執行熟悉的命令：

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

在 WSL 中可透過 /mnt/ 存取 Windows 磁碟機上的檔案：C: 磁碟機位於 /mnt/c/，D: 磁碟機位於 /mnt/d/。因此，位於 C:\Users\Name\project 的專案可這樣開啟：

cd /mnt/c/Users/Name/project
opencode

第二個選項是不使用 WSL，改用 Windows 套件管理員。在 PowerShell 中執行：

choco install opencode

scoop install opencode

第三個選項是桌面應用程式和網頁版。應用程式像一般程式一樣安裝，並在視窗中顯示介面，不需要終端機。網頁版使用 opencode web 命令啟動：它會在瀏覽器中開啟 OpenCode，而文件也建議從 WSL 啟動，以避免存取檔案時發生問題。文件還列出較少使用的選項：mise、Docker，以及 GitHub releases 頁面上的預先建置二進位檔。Windows 上透過 bun 安裝的功能仍在開發中；如果 bun 是你的主要套件管理員，請使用 npm 選項。

如何為 OpenCode 連接模型？#

OpenCode 透過 AI SDK 和 Models.dev 支援 75+ 家供應商，也支援本機模型。大多數模型都可在介面中使用 /connect 命令連接；本機模型則還需要在設定中指定伺服器位址。不同選項的付款方式與電腦需求各不相同：

文件建議新手從 OpenCode Zen 開始。團隊挑選了特別適合代理工作的模型，並以自己的任務測試模型與供應商的搭配方式。

連接方式如下：輸入 /connect，選擇 OpenCode Zen，登入並在 opencode.ai/auth 新增付款方式，取得金鑰後貼上。接著，/models 會顯示建議模型清單。截至 2026 年 10 月 4 日，清單包含 GPT 6.1 Sol、GPT 6 Astra、Claude Opus 5.5、Claude Sonnet 5、GLM 5.3 和 Kimi K2.5 等模型。文件也坦承清單並不完整，而且新模型每週都會推出，因此很快就會過時。

訂閱方案也使用相同的 /connect 命令連接：從清單選擇 ChatGPT Plus 或 GitHub Copilot，並登入帳戶即可，不需額外設定。

如果選擇 Anthropic，/connect 會提供兩種選項：手動輸入 API 金鑰，或選擇 Claude Pro/Max 並透過瀏覽器驗證。不過，Anthropic 禁止使用第三方外掛來利用 Claude Pro/Max 訂閱，而 OpenCode 從 1.3.0 版起已移除這類內建外掛。如果你看到較舊的「透過 Claude 訂閱使用 OpenCode」文章，那指的是已移除的外掛，並非官方授權方式。ChatGPT Plus、GitHub Copilot、標示為實驗性的 GitLab Duo，以及 Atomic Chat 訂閱方案都不需額外設定即可使用。

透過 /connect 輸入的金鑰會儲存在 ~/.local/share/opencode/auth.json 檔案中。如果不想每次都選擇模型，可以在專案根目錄的 opencode.json 設定檔中設定預設模型：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5"
}

格式為 provider/model；兩個識別碼都會顯示在 /models 的輸出中。

如何透過 Ollama 連接本機模型？#

這個選項完全不會產生 API 費用：模型在你的電腦上執行。如果你正在挑選免費模型，我們另有一篇評測，介紹哪些模型作為代理時還算實用，哪些只是紙上談兵。要在 OpenCode 中使用，請從官方網站安裝 Ollama，並下載模型：

ollama pull qwen3-coder

文件中有一項實用資訊：Ollama 可以自動為 OpenCode 完成設定，並提供獨立的整合指南。如果想手動設定，請在 opencode.json 中新增供應商，並填入本機 Ollama 伺服器的位址：

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

接著，介面中的 /models 會列出本機模型。選擇它就可以開始工作。文件有一項實務提醒：如果代理不再呼叫工具（編輯檔案或執行命令），請在 Ollama 設定中提高 num_ctx，可以先從 16k–32k 開始。本機模型在代理工作上的表現不如雲端模型，而較小的上下文會讓情況更差。如果本機版本無法滿足需求，可以使用金鑰連接雲端版 Qwen；如何取得 Qwen Code API 金鑰指南會說明取得方式。

使用 OpenCode 的費用是多少？#

這裡的費用全都與模型有關，使用方式有四種。使用 API 金鑰或 Zen 時，依實際用量付費，金額取決於代理的工作量。Go 是 OpenCode 團隊為開放模型提供的訂閱方案：Go 每月 $10，具備較高限額的 Go Plus 每月 $40（已於 2026 年 10 月 4 日查證 opencode.ai/go 頁面）。不同模型的限額各異：例如，Go 使用 Kimi K3 時每 5 小時約可提出 110 次請求（每月 440 次）；使用較輕量的 DeepSeek V4.1 Flash 時，每 5 小時約可提出 26,000 次請求。文件也列出超過限額後使用特定模型的另行費用（Kimi K3 每月 $15，Go Plus $60）。連接時請參閱訂閱頁面，查看完整模型和限額清單。使用 ChatGPT Plus 或 Copilot 時，請求由你已付費的訂閱方案涵蓋；但請記得訂閱方案也有各自的使用強度限制。最後，透過 Ollama 使用本機模型不需支付請求費用，但要讓模型快速運作，需要效能足夠好的電腦。

首次啟動時該做什麼？#

首次啟動時，先進入專案資料夾：

cd path/to/project
opencode

介面會開啟並顯示輸入欄位。首先使用 /init 命令：代理會掃描儲存庫中的重要檔案，必要時提出幾個問題，然後建立 AGENTS.md 檔案，說明專案結構、建置和測試要執行的命令，以及採用的慣例。文件建議將這個檔案提交至 git；之後 OpenCode 會將它作為永久的專案指令。就用途而言，AGENTS.md 相當於 OpenCode 生態系中的 CLAUDE.md。

接著使用 Plan 模式。按 Tab 鍵可在兩個主要代理間切換：Build 擁有檔案和命令的完整存取權；Plan 則負責分析與規劃——預設情況下，在 Plan 模式中編輯檔案和執行 bash 命令都需要你核准。文件建議新任務先從計畫開始：閱讀代理打算採取的步驟、調整措辭，再按 Tab 切回 Build。

文件提供以下建議：

任務描述越具體、提供的背景資訊越充分，就越不需要返工。使用 @ 將檔案加入請求——輸入檔名後，介面會透過模糊搜尋找出檔案。你可以直接將圖片拖入終端機；以 ! 開頭的訊息會作為 Shell 命令執行，輸出也會加入代理的上下文。如果任務弄錯，或代理做了不該做的事，/undo 會還原變更，而且可以連續執行數次。又改變主意了嗎？/redo 會還原已撤銷的內容。/share 會建立供團隊使用的對話連結；不使用這個命令，對話就不會發布到任何地方。

OpenCode 還能做什麼？#

自訂命令。任何重複性的請求都能變成命令：在 .opencode/commands/ 資料夾放入 Markdown 檔案，在 frontmatter 中設定 description、agent 和 model，並在下方撰寫提示範本。之後用 / 呼叫命令。發布前檢查專案、檢視最近的錯誤、產生遷移——任何你經常要求的工作都可以建立成命令。

子代理。除了 Build 和 Plan，還有另外三種：負責多步驟任務的 General（可使用工作清單以外的所有工具）、能快速閱讀程式碼但未獲准編輯的 Explore，以及研究外部程式庫的 Scout。在訊息中使用 @ 提及名稱即可呼叫。

MCP 伺服器。透過 opencode.json 設定中的 mcp 區段連接外部工具；本機和遠端伺服器都支援。每個 MCP 伺服器都會將自己的工具加入上下文，像 GitHub 這類資訊量大的伺服器很快就會耗盡上下文，因此請選擇性連接，只啟用需要的工具。我們有一份介紹 MCP 概念的現成設定指南，內容以 Claude Code 為例，但通訊協定是共通的。

網頁版和伺服器。opencode web 會在瀏覽器中開啟介面。若要從其他電腦存取，請使用 opencode serve --hostname 0.0.0.0 --port 4096；只要能從網路存取，務必使用 OPENCODE_SERVER_PASSWORD 變數設定密碼。沒有密碼，伺服器就沒有受到保護。

安裝出錯時該怎麼辦？#

安裝後顯示「opencode: command not found」。終端機尚未辨識新的路徑。先關閉再重新開啟終端機。如果仍然無效，找出安裝程式放置二進位檔的位置，並將該資料夾加入終端機的 PATH。

模型沒有回應或顯示授權錯誤。確認供應商已連接：輸入 /connect 並重新驗證。金鑰儲存在 ~/.local/share/opencode/auth.json；如果你從另一台電腦搬移安裝，或清除了資料夾，這個檔案可能不存在。文件分別說明 ProviderInitError 和 AI_APICallError 錯誤：遇到前者，請重新授權供應商；遇到後者，請清除 ~/.cache/opencode 資料夾並重新啟動。

介面顯示異常：面板散落，或符號變成無法辨識的字元。先檢查終端機。安裝一種推薦的選項——WezTerm 適用於三種系統——然後從該終端機啟動 OpenCode。

如果問題仍未解決，請檢查日誌：macOS 和 Linux 的日誌位於 ~/.local/share/opencode/log/；在 Windows 上，按 Win+R 並輸入 %USERPROFILE%\.local\share\opencode\log。系統會保留最近 10 個檔案；使用 opencode --log-level DEBUG 旗標啟用詳細日誌。你可以附上這些日誌，在專案的 GitHub 儲存庫提交錯誤回報。

關於 OpenCode，大家還會問什麼？#

開啟 Ailoot。