深度解析 OmniRoute 与 OpenCode 集成：CLI 生成器、npm 配置包与运行时原理

深度解析 OmniRoute 与 OpenCode 集成CLI 生成器、npm 配置包与运行时原理【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute适用场景本文面向希望把 AI 网关 OmniRoute 接入 OpenCodeagentic CLI/桌面端 AI 客户端的运维人员与开发者介绍两条官方支持的集成路径、生成的配置文件结构、URL 规范化与认证模式并结合仓库源码剖析底层实现。读完本文你将能够独立完成opencode.json的生成、合并与故障排查并理解为什么插件永不触碰 HTTP、只产出配置。对应文档docs/frameworks/OPENCODE.md本文为其深化版另有一份波兰语译本位于 docs/i18n/pl/docs/frameworks/OPENCODE.md配置 schema 的事实来源src/shared/services/opencodeConfig.tsnpm 包的事实来源omniroute/opencode-provider/可发布的 workspaceOpenCode 从~/.config/opencode/opencode.json或opencode.jsonc读取 provider 目录并遵循https://opencode.ai/config.json定义的 schema。OmniRoute 向 OpenCode 暴露为标准 OpenAI 兼容的/v1接口因此 OpenCode 中任何指向 OmniRoute 的请求都会自动获得 Auto-Combo 路由、熔断器circuit breaker、密钥策略与可观测性能力。仓库提供了两条集成路径二者生成完全相同的配置任选其一即可。一、路径 1CLI 生成器无需安装 npm 包面向终端用户的推荐路径。该命令随 OmniRoute 一起发布全局安装omniroute/cli或使用本地克隆均可直接原地写回opencode.json# After installing OmniRoute (npm i -g omniroute/cli or local clone) omniroute config opencode \ --base-url http://localhost:20128 \ --api-key $OMNIROUTE_API_KEY后台机制上CLI 调用的是mergeOpenCodeConfigText()src/shared/services/opencodeConfig.ts因此已存在的opencode.json会保留其他 provider 与注释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 }, }, }, }, }1.1 无损合并的实现原理mergeOpenCodeConfigText()使用jsonc-parser以文本编辑方式modifyapplyEdits逐段改写已有文件而非整体重写解析失败时拒绝覆盖若已有配置不是合法 JSONC含尾逗号、注释均被允许函数会抛出包含解析错误码与偏移量的异常避免静默丢失注释、无关 provider 与用户设置依次写入$schema、provider.omniroutev1 结构与providers.omniroutev2 结构见下文 1.2其余内容字节级原样保留格式统一为insertSpaces: true, tabSize: 2。1.2 兼容 v1/v2 双 schema 输出值得注意mergeOpenCodeConfig/buildOpenCodeConfigDocumentopencodeConfig.ts会同时输出两套条目provider.omniroutev1npm: ai-sdk/openai-compatibleoptions.baseURLoptions.apiKeyproviders.omniroutev2package: opencode-ai/ai/providers/openai-compatiblesettings.baseURLsettings.apiKey由buildOpenCodeV2ProviderConfig从同一份 v1 配置派生。这一双写设计让同一份配置在不同 schema 版本的 OpenCode 客户端下都能被正确解析。1.3 配置文件路径解析CLI 落盘前通过 src/shared/services/opencodeConfigPath.ts 解析目标文件目录优先$XDG_CONFIG_HOME/opencode否则~/.config/opencode文件优先级若存在opencode.jsonc则写它OpenCode 将其视为可写全局配置并在两文件共存时后合并否则使用已有的opencode.json两者都不存在时默认创建opencode.json——避免新 JSON 文件遮蔽已有的 JSONC 文档。二、路径 2npm 包omniroute/opencode-provider当你在 Node/TS 中脚本化生成配置时CI 流水线、monorepo、自定义安装器推荐此路径npm install --save-dev omniroute/opencode-providerimport { 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, // Optional: override the model catalog exposed to 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 见 omniroute/opencode-provider/README.md。2.1 核心 API 一览以仓库源码为准包入口为 omniroute/opencode-provider/src/index.ts提供API说明createOmniRouteProvider(options)返回应放入opencode.json中provider.omniroute的值buildOmniRouteOpenCodeConfig(options)返回带$schema与provider.omniroute包裹层的完整文档可直接落盘normalizeBaseURL(input)去除尾部斜杠、去重尾部/v1并精确补回一个/v1空值或非法 URL 抛错mergeIntoExistingConfig(existing, options)对已解析的配置对象做浅合并保留顶层其他键、保留provider中其他条目仅覆盖omniroute条目仅在显式传入model/smallModel时写出顶层model/small_model以omniroute/id形式fetchLiveModels(baseURL, apiKey, timeoutMs?)从运行中的 OmniRouteGET /v1/models拉取实时模型目录兼容 camelCasemodelId/displayName与 snake_casemodel_id/display_name字段变体并抽取context_length/max_context_window_tokenscreateOmniRouteProvider的选项摘自源码类型定义OmniRouteProviderOptionsbaseURL必填可带或不带尾部/v1容忍尾斜杠apiKey必填本地实例REQUIRE_API_KEYfalse使用字面量sk_omniroutedisplayName可选OpenCode UI 中显示的名称默认OmniRoutemodels可选覆盖暴露的模型目录。未传时使用默认精选目录见第四节自动去重并丢弃空字符串保持顺序modelLabels可选模型 ID → 人类可读标签modelCapabilities可选按模型覆盖attachment/reasoning/temperature/tool_call能力标记对默认目录中的模型会在默认能力表之上做浅合并modelContextLengths可选按模型覆盖上下文窗口token优先级低于models中携带的contextLength的实时条目model/smallModel可选写出顶层model/small_model格式为omniroute/id。2.2 实时目录拉取让模型列表永不陈旧包内fetchLiveModels()直接从GET {baseURL}/v1/models拉取运行中的目录并从响应中抽取context_lengthsnake_caseOmniRoute 对同步模型与自定义模型都会注入或max_context_window_tokens。将其返回值直接传入models选项即可让 OpenCode 的模型列表与 OmniRoute 实例保持同步而不再依赖硬编码的默认目录。请求默认 5 秒超时AbortController实现。更进一步仓库中的 omniroute/opencode-plugin 实现了官方opencode-ai/plugin插件契约auth provider config 三类 hook在 OpenCode 启动时动态拉取/v1/models并带 TTL 缓存模型列表始终是活的它还支持多实例通过插件元组[omniroute/opencode-plugin, { providerId: omniroute-preprod }]、/connect providerId密钥注册流程、按前缀路由 Anthropic SDKcc/、claude/、anthropic/、kiro、kr等前缀走ai-sdk/anthropic等能力。对无法运行插件的场景CI、脚本化脚手架omniroute/opencode-provider依然是受支持的构建期配置生成方案。三、运行时到底发生了什么两条路径产出的都是同一个关键字段provider.omniroute.npm: ai-sdk/openai-compatible。运行时OpenCode 加载ai-sdk/openai-compatible它本就是 OpenCode 的传递依赖无需额外安装并用baseURLapiKey对其配置。此后请求链路为OpenCode UI/agent → ai-sdk/openai-compatible → HTTP POST {baseURL}/chat/completions (OmniRoute OpenAI surface) → OmniRoute /v1/chat/completions handler (open-sse/handlers/chatCore.ts) → combo routing / Auto-Combo / executor → upstream provider插件本身从不发起 HTTP 请求它只产出配置。这意味着 OmniRoute 侧的 Auto-Combo 路由、熔断、密钥策略与可观测性对 OpenCode 完全透明无需在 OpenCode 侧重复实现。3.1 新版 CLI 生成器以实时目录为准的上下文窗口若你使用的是仓库中较新的 CLI 生成器 src/lib/cli-helper/config-generator/opencode.ts其行为更进一步生成前强制请求GET {baseURL}/v1/models获取实时目录generateOpencodeConfig中fetchCatalogfalse会直接抛错目录是上下文窗口的唯一事实来源没有它 opencode.json 会携带伪造或陈旧的值每个模型的limit.context优先级为用户已有opencode.json中显式设置的limit.context 目录的context_length/max_context_window_tokens 安全兜底 128Klimit.output是 OpenCode v1 provider schema 的必填字段目录未提供max_output_tokens时兜底 8K确保 schema 校验永不因缺键报错源码注释引用 #10940/#11032/#11035能力标记attachment/reasoning/temperature/tool_call优先保留用户显式布尔值含false缺失时从目录的capabilities、vision、input_modalities中推导目录请求前经assertSafeCatalogUrl做 SSRF 防护环回地址合法放行用户自己的实例是合法来源但无条件阻断云元数据/链路本地地址169.254.169.254、metadata.google.internal等与非 http(s) 协议及内嵌凭据CodeQL js/request-forgery 加固顶层model/small_model不会被静默改写生成器仅在显式传入options.model时覆盖否则保留用户原有选择。四、默认模型目录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;在omniroute/opencode-provider的新版实现中该目录已扩展为 8 个条目包含cc/前缀的 Claude Code passthrough 模型并为每个模型预置了上下文窗口表OMNIROUTE_DEFAULT_MODEL_CONTEXT_LENGTHS与能力表OMNIROUTE_DEFAULT_MODEL_CAPABILITIES。可通过models: [...]覆盖。推荐追加auto—— 暴露 OmniRoute 的 Auto-Combo 零配置路由器让 OpenCode 自行挑选当前可用最优模型无需硬编码目录combo-name—— 在仪表盘里定义的任意 comboOmniRoute 会透明解析。同时可用modelLabels为其提供 UI 标签例如{ auto: Auto-Combo }。五、URL 规范化辅助函数同时接受两种形式并保证输出恰好一个/v1输入输出options.baseURLhttp://localhost:20128http://localhost:20128/v1http://localhost:20128/http://localhost:20128/v1http://localhost:20128/v1http://localhost:20128/v1http://localhost:20128/v1///http://localhost:20128/v1实现细节normalizeBaseURLindex.ts先new URL()校验合法性再以字符级循环去除尾部斜杠避免正则回溯引发的 CodeQL 告警随后剥离尾部/v1并重新补上一个/v1。这个去重是旧配置中最高频的故障源。如果你的opencode.json来自 v3.8.0 之前、指向/v1/v1/...请重新运行生成器或再次调用createOmniRouteProvider。六、认证模式OmniRoute 设置推荐的apiKey值REQUIRE_API_KEYfalse本地默认sk_omniroute字面占位符REQUIRE_API_KEYtrue来自 Dashboard → API Keys 的真实每用户密钥补充说明对 Anthropic 风格客户端发送x-api-keyanthropic-versionOmniRoute 的extractApiKey也会从x-api-key头中提取密钥。但 OpenCode 走的是 OpenAI 接口始终发送Authorization: Bearer ${apiKey}因此这里的 Anthropic 特例不适用。若你通过omniroute/opencode-plugin使用 Anthropic SDK 路由cc/、claude/前缀则需注意该插件在/connect流程中注册的密钥同样以 Bearer 形式注入。七、故障排查速查表现象原因修复含/v1/v1/的 URL 上所有请求404pre-v3.8 插件产出的过期配置重复追加了/v1通过路径 1 或 2 重新生成401 Invalid API keyOmniRoute 启用了REQUIRE_API_KEYtrue且密钥未知在仪表盘创建密钥或仅在本地设置REQUIRE_API_KEYfalse并使用sk_omnirouteOpenCode UI 中模型列表为空4 个默认模型全被 OmniRoute 的 provider 可见性设置隐藏传models: [auto, ...]暴露已启用模型OpenCode 500 且报cannot read property models旧版 OpenCode 0.1.x不接受内联models升级 OpenCode 至遵循 v1 schemaopencode.ai/config.json的版本生成器/CLI 报Existing OpenCode config is invalid JSONC已有配置文件是非法 JSONC修复现有文件中的语法错误后再重跑生成器拒绝覆盖防止丢失注释与其他 provider八、延伸阅读API reference —— OmniRoute 完整 REST 接口Auto-Combo ——model: auto的含义omniroute/opencode-provider README —— 包内完整 API 文档omniroute/opencode-plugin README —— 动态目录同步的官方插件路径核心源码src/shared/services/opencodeConfig.ts、src/lib/cli-helper/config-generator/opencode.ts、omniroute/opencode-provider/src/index.ts、src/shared/services/opencodeConfigPath.ts【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考