OpenCode Integration (中文 (繁體))

方式 1 — CLI 產生器（無須安裝 npm）

建議一般使用者採用。隨 OmniRoute 一同提供。會直接更新 opencode.json。

# 安裝 OmniRoute 後（npm i -g @omniroute/cli 或本機複製）
omniroute config opencode \
  --base-url http://localhost:20128 \
  --api-key "$OMNIROUTE_API_KEY"

CLI 會在幕後呼叫 mergeOpenCodeConfigText()（src/shared/services/opencodeConfig.ts:104），因此現有的 opencode.json 會保留其他提供者與註解。OmniRoute 項目會以不可分割的方式新增或取代。

產生的檔案（預設模型目錄）：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1",
        "apiKey": "<your-key>",
      },
      "models": {
        "claude-opus-4-5-thinking": { "name": "claude-opus-4-5-thinking" },
        "claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" },
        "gemini-3.1-pro-high": { "name": "gemini-3.1-pro-high" },
        "gemini-3-flash": { "name": "gemini-3-flash" },
      },
    },
  },
}

---

方式 2 — npm 套件 @omniroute/opencode-provider

建議透過 Node/TS 以程式方式產生設定時使用（CI 管線、monorepo、自訂安裝流程）。

npm install --save-dev @omniroute/opencode-provider

import { writeFileSync } from "node:fs";
import { buildOmniRouteOpenCodeConfig } from "@omniroute/opencode-provider";

const config = buildOmniRouteOpenCodeConfig({
  baseURL: "http://localhost:20128",
  apiKey: process.env.OMNIROUTE_API_KEY ?? "sk_omniroute",
  // 選用：覆寫公開給 OpenCode 的模型目錄
  models: ["auto", "claude-opus-4-7", "gpt-5.5"],
  modelLabels: { auto: "Auto-Combo" },
});

writeFileSync("opencode.json", JSON.stringify(config, null, 2));

若要以非破壞性方式合併現有檔案，請複製 opencodeConfig.ts 中的 mergeOpenCodeConfigText()，或呼叫 CLI 產生器。

完整 API 請參閱套件 README。

---

執行階段實際執行的操作

這兩種方式都會產生相同的 provider.omniroute.npm: "@ai-sdk/openai-compatible"。在執行階段，OpenCode 會載入 @ai-sdk/openai-compatible（已是 OpenCode 的遞移相依套件），並使用 baseURL + apiKey 進行設定。接下來的流程如下：

OpenCode UI／代理程式
   → @ai-sdk/openai-compatible
      → HTTP POST {baseURL}/chat/completions          （OmniRoute OpenAI 介面）
         → OmniRoute /v1/chat/completions 處理常式     （open-sse/handlers/chatCore.ts）
            → 組合路由／Auto-Combo／執行器
               → 上游提供者

此外掛程式絕不會接觸 HTTP。它只會產生設定。

---

模型目錄預設值

export const OMNIROUTE_DEFAULT_OPENCODE_MODELS = [
  "claude-opus-4-5-thinking",
  "claude-sonnet-4-5-thinking",
  "gemini-3.1-pro-high",
  "gemini-3-flash",
] as const;

你可以透過 models: [...] 覆寫。建議新增：

• "auto" — 顯示 OmniRoute 的 Auto-Combo 零設定路由器。讓 OpenCode 選擇「最佳可用模型」，而無須將目錄硬式編碼。
• "<combo-name>" — 你在儀表板中定義的任何組合；OmniRoute 會以透明方式解析。

---

URL 正規化

此輔助工具接受下列兩種形式，並確保只輸出一個 /v1：

輸入	輸出（options.baseURL）
http://localhost:20128	http://localhost:20128/v1
http://localhost:20128/	http://localhost:20128/v1
http://localhost:20128/v1	http://localhost:20128/v1
http://localhost:20128/v1///	http://localhost:20128/v1

此去重處理是舊版設定中最常見的故障原因。如果你有一份 v3.8.0 之前的 opencode.json，且其中指向 /v1/v1/...，請重新執行產生器，或再次呼叫 createOmniRouteProvider。

---

驗證模式

OmniRoute 設定	建議的 apiKey 值
REQUIRE_API_KEY=false（本機預設值）	sk_omniroute（字面值預留位置）
REQUIRE_API_KEY=true	來自「儀表板 → API 金鑰」的真實個別使用者 API 金鑰。

對於傳送 x-api-key + anthropic-version 的 Anthropic 風格用戶端，OmniRoute 的 extractApiKey 也會採用來自 x-api-key 的金鑰。OpenCode 使用 OpenAI 介面，因此一律會傳送 Authorization: Bearer ${apiKey} — 此處不適用 Anthropic 的特殊處理。

---

疑難排解

症狀	原因	修正方式
每個 URL 包含 /v1/v1/ 的請求都傳回 404	v3.8 之前的外掛舊設定重複加上了 /v1 後綴。	透過路徑 1 或 2 重新產生設定。
401 Invalid API key	OmniRoute 設定了 REQUIRE_API_KEY=true，且無法識別該金鑰。	在儀表板中建立金鑰，或設定 REQUIRE_API_KEY=false（僅限本機）並使用 sk_omniroute。
OpenCode UI 中的模型清單為空	4 個預設模型全都在 OmniRoute 的提供者可見性設定中設為隱藏。	傳入 models: ["auto", ...]，以顯示你已啟用的模型。
OpenCode 500 並顯示 cannot read property 'models'	較舊版本的 OpenCode（< 0.1.x）不接受內嵌的 models。	將 OpenCode 升級至遵循 v1 結構描述（opencode.ai/config.json）的版本。

---

另請參閱

• API 參考文件 — 完整的 OmniRoute REST API 介面
• Auto-Combo — model: "auto" 的含義
• @omniroute/opencode-provider README
• 原始碼：src/shared/services/opencodeConfig.ts、src/lib/cli-helper/config-generator/opencode.ts、@omniroute/opencode-provider/src/index.ts

---

OmniRoute 原始碼 (a58000c7685f)