OpenCode 安裝與 OmniProxy 設定

OpenCode 是開放原始碼的程式碼編寫助理，可在終端機、IDE 或桌面環境中協助撰寫程式碼，而且不會儲存你的程式碼與上下文，適合重視隱私的專案使用。build 用於修改專案，plan 預設為唯讀，適合先理解不熟悉的程式碼並整理修改方式。模型服務可依你的需求選擇。

安裝前準備

使用安裝指令碼是最簡便的方式。你需要一款現代化終端機，也就是可執行指令及操作專案檔案的終端機程式，例如 WezTerm、Alacritty、Ghostty 或 Kitty。在 Windows 上建議優先使用 WSL；它是在 Windows 中執行 Linux 環境的工具，效能與功能都較完整。

最簡單

安裝指令碼

curl opencode.ai/install
macOS Linux 可直接使用
Windows 建議使用 WSL

macOS Linux

Homebrew tap

anomalyco/tap/opencode
比公式更新更頻繁
Arch 也有軟體套件

Windows 本機

套件管理器

choco 或 scoop
或使用 npm 全域安裝
也可下載 Releases

先使用安裝指令碼。如果已習慣套件管理工具，再使用官方列出的其他指令。

同時準備好目前模型清單中的模型 ID。模型 ID 是服務用來準確識別特定模型的名稱。

安裝並首次啟動

最簡便的安裝指令是：

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

也可以使用以下安裝方式：

Node.js：npm install -g opencode-ai。Bun、pnpm、Yarn 也有對應的全域安裝指令，請參閱本文末尾的介紹頁面。
macOS 和 Linux 的 Homebrew：brew install anomalyco/tap/opencode。請使用這個 tap，因為它比 Homebrew 團隊維護的 brew install opencode 更新得更頻繁。
Arch Linux：穩定版使用 sudo pacman -S opencode，較新版本可以使用 AUR 的 opencode-bin。
Windows：使用 choco install opencode 或 scoop install opencode，也可以使用 npm install -g opencode-ai。此外，也可以從 Releases 下載二進位檔案。在 Windows 上透過 Bun 安裝的支援仍在開發中。

進入你的專案目錄，然後啟動 OpenCode：

cd /path/to/project
opencode

首次使用時可以執行 /init。它會分析專案，並在專案根目錄建立 AGENTS.md。這個檔案可以提交至 Git，讓專案保留這份說明。

從 OmniProxy 取得連線參數

baseURL: https://your-omniproxy-origin.example/v1
API Key: <YOUR_OMNIPROXY_API_KEY>
Model ID: 從 OmniProxy 目前的模型清單複製

baseURL 是服務位址，API Key 是存取憑證，Model ID 是模型的完整名稱。

使用 /v1/chat/completions 時，npm 套件應使用 @ai-sdk/openai-compatible。這裡的 Chat Completions 是一種聊天請求介面。只有模型使用 /v1/responses 時，才改用 @ai-sdk/openai。透過 OmniProxy 使用聊天補全路徑時，請保留相容套件。

請從 OmniProxy 目前的清單完整複製模型 ID，並保留其中的斜線。2026-10-09 的兩個對照 ID 是 claude-sonnet-5-5 和 gpt-6-luna。gpt-6-luna 支援 Chat Completions；在 Chat Completions 中，只有當 reasoning_effort 設為 none 時才支援函式呼叫。不要直接複製清單中不存在的 ID。

填寫工具設定

Provider 可以理解為 OpenCode 連接模型服務時使用的一組設定。Provider 文件將「未出現在 /connect 清單中的 OpenAI 相容服務」歸類為自訂 Provider。OpenAI 相容服務是指使用相同請求格式，並可由同一類用戶端呼叫的服務。

在 OpenCode 中執行 /connect，然後捲動至 Other。
輸入一個 Provider ID。以下使用 omniproxy。這個 ID 應方便記憶，因為設定檔中必須使用相同的 ID。
輸入 OmniProxy 的 API Key。這個步驟只會儲存憑證，服務位址與模型仍須寫入 opencode.json。憑證會儲存在 ~/.local/share/opencode/auth.json。
在專案目錄中建立或修改 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniproxy": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniProxy",
      "options": {
        "baseURL": "https://your-omniproxy-origin.example/v1"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "gpt-6-luna": { "name": "GPT-6 Luna" }
      }
    }
  }
}

執行 /models，自訂 Provider 與模型便會出現在清單中。

/connect 中的 ID 必須與 opencode.json 中的鍵一致。請勿將真正的金鑰寫入這個檔案。如果不使用 /connect，也可以在 options.apiKey 中使用環境變數寫法，例如 {env:變數名稱}。2026-10-09 使用 OpenCode 1.18.34 測試時，直接將金鑰寫在專案的 options.apiKey 中而不使用 /connect，也能成功連線。如果閘道不驗證金鑰，這一項可以使用一串僅供本機使用的預留字元。models 中的鍵必須使用清單內的完整 ID。

金鑰

/connect

選擇最下方的 Other
自行設定 Provider ID
儲存在 auth.json

專案

opencode.json

provider 鍵必須同名
npm 使用相容套件
baseURL 以 /v1 結尾

選用

/models

模型出現在清單中
選擇一個再提問
ID 以閘道清單為準

金鑰與位址分別設定在兩個位置，而兩處的 Provider ID 必須相同。

驗證實際任務

先在專案目錄中執行一次實際任務。模型參照格式為 Provider ID/模型 ID，模型 ID 中的斜線必須保留：

opencode run --model omniproxy/claude-sonnet-5-5 --auto "說明你指定的一個檔案有什麼用途，不要修改檔案。"

--auto 會允許這次執行使用讀取檔案等工具。2026-10-09 使用 OpenCode 1.18.34 測試時，成功讀取了指定檔案的內容。第一次約需兩分鐘。

互動式使用方式是先執行 opencode，再透過 /models 選取模型。官方使用方式也支援以 @ 搜尋檔案。你可以執行 opencode auth list，確認透過 /connect 儲存的憑證，然後前往 OmniProxy 的呼叫記錄確認來源與模型 ID。

啟動

opencode 能啟動

先 cd 到專案
auth list 能看到 ID
設定檔位於專案中

任務

它讀取了程式碼

詢問一個特定檔案
查看它的說明
不正確時就用 /undo

記錄

閘道看得到

來源是 OpenCode
模型 ID 一致
不要提交金鑰

儲存設定檔後，還需要在專案中完成一次實際提問。

常見錯誤

/models 中沒有 OmniProxy：檢查 /connect 的 ID 是否與 opencode.json 中的鍵一致、npm 是否為 @ai-sdk/openai-compatible，以及 baseURL 是否以 /v1 結尾。
找不到憑證：執行 opencode auth list。Bedrock 這類依賴環境變數的 Provider 不會出現在這裡；自訂 Provider 透過 /connect 設定時應該會顯示。
Windows 功能不完整：改用 WSL 中的安裝指令碼。
模型 ID 無效：從 OmniProxy 目前的清單重新複製，並修改 models 中的鍵。
請求送往錯誤的介面：聊天補全應保留 @ai-sdk/openai-compatible。除非 OmniProxy 上的這個模型確實使用 /v1/responses，否則不要為了 Responses 介面而更換套件。

官方參考資料

安裝方式請參閱 OpenCode 介紹。自訂 Provider 請參閱 Providers。範例中使用的模型 ID 請參閱 Claude 模型總覽和 GPT-6 Luna。

用你自己的 OmniProxy 設定取代每個佔位符。不要發布真實金鑰。

儲存成功或 HTTP 200 不單獨代表完整 Agent 相容性。請在 OmniProxy 呼叫記錄中確認來源和模型。

官方來源 · OpenCode ↗