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 流水线、单体仓库、自定义安装程序流程），推荐使用此方式。

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 Keys 获取的真实用户 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 中的模型列表为空	OmniRoute 的提供者可见性设置隐藏了全部 4 个默认模型。	传入 models: ["auto", ...]，以显示你已启用的模型。
OpenCode 返回 500，并显示 cannot read property 'models'	较旧版本的 OpenCode（< 0.1.x）不接受内联 models。	将 OpenCode 升级到遵循 v1 架构（opencode.ai/config.json）的版本。

---

另请参阅

• API 参考 — 完整的 OmniRoute REST 接口
• 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

---

undefined (a58000c7685f)