OpenCode 配置

1. OpenCode 是什麼，以及你需要準備什麼

OpenCode 是一個開源的 AI 編碼代理，可以在終端裡閱讀倉庫、修改代碼、執行命令，也可以和桌面端、Web 界面、IDE 擴展配合使用。

在通過 RouteAPI 接入 OpenCode 之前，建議先準備好：

一個可正常使用的終端環境
你的 RouteAPI 密鑰
RouteAPI 控制台中可用、並且適合編碼任務的模型
優先選擇支持 OpenAI-compatible 協議和工具調用的模型

2. 安裝 OpenCode

安裝 CLI

如果你使用的是 macOS / Linux / WSL，官方推薦的安裝方式是：

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

如果你更習慣通過 Node.js 全局安裝，也可以使用：

npm install -g opencode-ai

如果你使用的是 Windows PowerShell 原生環境，可以直接運行：

npm install -g opencode-ai

驗證安裝

opencode --version

如果輸出了版本號，說明 OpenCode CLI 已經安裝成功。

3. 推薦方式：先保存密鑰，再寫項目配置

OpenCode 官方文檔建議先通過 /connect 保存憑證，再在配置文件裡聲明 provider 和 model。對於 RouteAPI 這種不在內置列表中的網關，選擇 Other 即可。

在 OpenCode 裡保存 RouteAPI 密鑰

先啟動 OpenCode：

opencode

然後在會話裡運行：

/connect

接著按順序完成：

選擇 Other
將 provider ID 填成 routeapi
粘貼你的 RouteAPI 密鑰

憑證會由 OpenCode 自動寫入本地 ~/.local/share/opencode/auth.json，通常不需要手動編輯。

在項目根目錄創建 `opencode.json`

OpenCode 官方文檔同時支持全局配置 ~/.config/opencode/opencode.json 和項目根目錄下的 opencode.json。對於團隊協作，通常更推薦把非敏感配置寫在項目根目錄。

{
      "$schema": "https://opencode.ai/config.json",
      "provider": {
        "routeapi": {
          "npm": "@ai-sdk/openai-compatible",
          "name": "RouteAPI",
          "options": {
            "baseURL": "https://www.routeapi.ai/v1"
          },
          "models": {
            "your-routeapi-model-id": {
              "name": "RouteAPI Model"
            }
          }
        }
      },
      "model": "routeapi/your-routeapi-model-id"
}

上面這段配置裡：

routeapi：自定義 provider 的唯一 ID，必須與 /connect 時填寫的 provider ID 完全一致
npm：/v1/chat/completions 使用 @ai-sdk/openai-compatible；/v1/responses 使用 @ai-sdk/openai
options.baseURL：https://www.routeapi.ai/v1
models：鍵名填寫 RouteAPI 控制台裡真實可用的模型 ID，不要填展示名稱
model：默認模型格式是 provider_id/model_id，這裡就是 routeapi/your-routeapi-model-id

4. 不想用 `/connect` 時：改用環境變量

如果你更習慣讓密鑰來自環境變量，也可以直接在 opencode.json 裡填寫 options.apiKey。這是 OpenCode 官方文檔支持的變量寫法。

4.1 設置環境變量

如果你使用的是 macOS / Linux / WSL 中的 bash、zsh 或 sh：

export ROUTEAPI_KEY="你的 RouteAPI 密鑰"

如果你使用的是 Windows PowerShell：

$env:ROUTEAPI_KEY="你的 RouteAPI 密鑰"

4.2 在 `opencode.json` 中引用環境變量

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
"routeapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "RouteAPI",
      "options": {
        "baseURL": "https://www.routeapi.ai/v1",
        "apiKey": "{env:ROUTEAPI_KEY}"
      },
      "models": {
        "your-routeapi-model-id": {
          "name": "RouteAPI Model"
        }
      }
}
  },
  "model": "routeapi/your-routeapi-model-id"
}

5. 選擇模型並啟動 OpenCode

完成配置後，可以這樣選擇模型並啟動：

啟動 OpenCode：

opencode

在會話中運行：

/models

選擇 routeapi 下的模型；如果你已經在 opencode.json 裡設置了 model，OpenCode 會默認使用它

如果你只想臨時切換當前會話的模型，也可以直接使用命令行參數：

opencode -m routeapi/your-routeapi-model-id

如果你想給標題生成等輕量任務單獨指定一個更便宜的模型，還可以在配置裡補充：

{
  "small_model": "routeapi/your-small-model-id"
}

6. 常見排查

運行 opencode auth list，確認本地已經保存了 routeapi 的憑證
如果 /models 裡看不到你的自定義 provider，先檢查 /connect 時填寫的 provider ID 是否和 opencode.json 裡的 routeapi 完全一致
如果模型能列出來但請求報協議錯誤，優先檢查 npm 包是否選對了：/v1/chat/completions 用 @ai-sdk/openai-compatible，/v1/responses 用 @ai-sdk/openai
如果你在 Windows 上遇到文件訪問慢、終端行為異常或路徑不一致，優先改到 WSL 中運行 OpenCode
如果你還想對比其他 RouteAPI 客戶端接入方式，可以繼續閱讀 Codex 配置指南、Cursor 配置指南和 Claude Code 配置指南