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
更新頻率高於 formula
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: Copy from the current OmniProxy model list

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

使用 /v1/chat/completions 時，請將 npm 套件設為 @ai-sdk/openai-compatible。Chat Completions 是一種聊天請求介面。僅當模型使用 /v1/responses 時，才切換至 @ai-sdk/openai。當 OmniProxy 透過 chat completions 端點使用時，請保留相容性套件。

從 OmniProxy 當前列表中複製完整的模型 ID，包含任何斜線。截至 2026-10-09，兩個參考 ID 為 claude-sonnet-5-5 與 gpt-6-luna。gpt-6-luna 支援 Chat Completions；僅當 reasoning_effort 為 none 時，才支援透過 Chat Completions 進行函式呼叫。請勿複製列表中不存在的 ID。

輸入工具設定

供應商（Provider）可以理解為 OpenCode 用來連線至模型服務的一組配置數值。供應商文件將未列在 /connect 下的 OpenAI 相容服務視為自訂供應商。OpenAI 相容服務使用相同的請求格式，並可由相同類型的客戶端呼叫。

在 OpenCode 中執行 /connect 並捲動至 Other。
輸入供應商 ID。下方範例使用 omniproxy。請選擇一個容易記住的 ID，因為您必須在設定檔中使用相同的 ID。
輸入 OmniProxy API 金鑰。此步驟僅儲存憑證；位址與模型仍須加入 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。自訂供應商及其模型將出現在列表中。

在 /connect 下輸入的 ID 必須與 opencode.json 中的鍵值相符。請勿將真實金鑰放入此檔案。如果您不使用 /connect，可以在 options.apiKey 中使用環境變數語法，例如 {env:VARIABLE_NAME}。在 2026-10-09 使用 OpenCode 1.18.34 進行的測試中，直接將金鑰放入專案的 options.apiKey 而不使用 /connect 也能成功連線。如果 Gateway 不驗證金鑰，此數值可以是僅在本地機器上使用的佔位字串。models 下的鍵值必須使用列表中的完整 ID。

金鑰

/connect

在底部選擇 Other
選擇您自己的供應商 ID
儲存在 auth.json

專案

opencode.json

供應商鍵值必須使用相同名稱
使用相容的 npm 套件
baseURL 以 /v1 結尾

選擇

/models

模型出現在列表中
提問前先選擇一個
使用 Gateway 列表中的 ID

金鑰與位址儲存在兩個不同地方。供應商 ID 必須在兩處相同。

使用實際任務驗證

首先從專案目錄執行一個實際任務。模型參考格式為 Provider ID/model ID；請保留模型 ID 內的任何斜線：

opencode run --model omniproxy/claude-sonnet-5-5 --auto "Explain what a file you specify does. Do not modify the file."

--auto 允許此執行使用檔案讀取等工具。在 2026-10-09 使用 OpenCode 1.18.34 進行的測試中，它成功讀取了指定檔案的內容。首次執行耗時約兩分鐘。

若要互動使用，請執行 opencode，然後使用 /models 選擇模型。您可以使用 @ 搜尋檔案。使用 opencode auth list 確認透過 /connect 儲存的憑證，然後檢查 OmniProxy 的請求記錄以驗證來源與模型 ID。

啟動

OpenCode 啟動

先 cd 到專案目錄
auth list 顯示該 ID
設定檔位於專案中

任務

它讀取了程式碼

詢問特定檔案
檢視其解釋
若錯誤請使用 /undo

記錄

在 Gateway 中可見

來源為 OpenCode
模型 ID 相符
請勿提交金鑰

儲存設定檔後，在專案內完成一個實際請求。

常見錯誤

OmniProxy 未出現在 /models 下：檢查在 /connect 輸入的 ID 是否與 opencode.json 中的鍵值相符，npm 是否設為 @ai-sdk/openai-compatible，且 baseURL 是否以 /v1 結尾。
憑證遺失：執行 opencode auth list。依賴環境變數的供應商（如 Bedrock）不會出現在此；透過 /connect 配置的自訂供應商應可見。
Windows 功能不完整：請改在 WSL 內使用安裝指令碼。
模型 ID 無效：從 OmniProxy 當前列表中重新複製，並更新 models 下對應的鍵值。
請求發送至錯誤端點：聊天完成請保留 @ai-sdk/openai-compatible。除非 OmniProxy 上的該模型確實使用 /v1/responses，否則請勿更改回應介面的套件。

官方參考

安裝請參閱 OpenCode 介紹。自訂供應商請參閱供應商。範例中使用的模型 ID，請參閱 Claude 模型概覽與 GPT-6 Luna。

將所有佔位符替換為您自己的 OmniProxy 配置值。切勿發布真實金鑰。

保存的結果或 HTTP 200 單獨存在並不證明完整的 Agent 相容性。請在 OmniProxy 的呼叫記錄中檢查來源與模型。

官方來源 · OpenCode ↗