OmniRoute OpenCode插件指南：@omniroute/opencode-provider原生集成教程

OmniRoute OpenCode插件指南：@omniroute/opencode-provider原生集成教程

【免费下载链接】OmniRoute Never stop coding. Free MIT AI gateway: one endpoint, 350 providers (90+ free), 1200+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 450+ contributors 项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute

OmniRoute 是一个免费开源（MIT）的 AI 网关：一个端点接入 350 家供应商、1200+ 模型，支持配额感知的自动故障转移与 RTK+Caveman 压缩。本教程面向新手，手把手讲解如何用 @omniroute/opencode-provider 与 @omniroute/opencode-plugin 两个官方包，把 OpenCode（终端/桌面 AI 编程客户端）原生集成到 OmniRoute，让 Claude、GPT、Gemini、Kimi、GLM 等模型在 OpenCode 中随叫随到。

📦 先搞懂两个官方包：provider 还是 plugin？

OmniRoute 仓库提供了两个 OpenCode 集成包，职责不同，选错会踩坑：

⚠️ 重要提示：@omniroute/opencode-provider 已被标记弃用——它写入的模型列表是硬编码的，OmniRoute 新增模型后不会自动出现在 OpenCode 中。官方推荐用一行插件配置替代（迁移方法见下文）。两者源码分别在 src/index.ts 和 src/index.ts，官方集成文档见 docs/frameworks/OPENCODE.md。

🚀 三种集成方式：从最快到最灵活

方式一：一条命令一键安装（推荐新手）

插件已随 v3.8.23+ 的 omniroute npm 包内置预构建，一条命令即可完成复制插件 + 写配置 + 登录鉴权：

# 复制插件到 ~/.config/opencode/plugins/ 并更新 opencode.json
omniroute setup opencode --auth
# 按交互提示输入 OmniRoute API Key
# 重启 OpenCode 后，/models 即可看到完整实时模型目录

该命令会自动执行 opencode auth login --provider opencode-omniroute 把密钥写入 auth.json，并自动清理旧的 @omniroute/opencode-provider 残留条目，可重复执行以升级插件或更换地址（--base-url 指定非默认地址）。

方式二：CLI 生成器写入 opencode.json（无需 npm install）

omniroute config opencode \
  --base-url http://localhost:20128 \
  --api-key "$OMNIROUTE_API_KEY"

它对现有 opencode.json 做非破坏性合并——其他供应商配置与注释原样保留，OmniRoute 条目被原子化地添加或替换。

方式三：编程式生成配置（CI / 脚本场景）

@omniroute/opencode-provider 的核心 API 只有两个函数，适合在 Node/TS 脚本中动态生成配置：

import { buildOmniRouteOpenCodeConfig } from "@omniroute/opencode-provider";

const config = buildOmniRouteOpenCodeConfig({
  baseURL: "http://localhost:20128",
  apiKey: process.env.OMNIROUTE_API_KEY ?? "sk_omniroute",
  models: ["auto", "claude-opus-4-7", "gpt-5.5"], // 可选：自定义模型目录
});
// config 可直接 JSON.stringify 写入 opencode.json

生成的配置中 provider.omniroute.npm 指向 @ai-sdk/openai-compatible（OpenCode 自带），运行时所有请求走 OmniRoute 的 OpenAI 兼容 /v1 表面，因此自动获得 Auto-Combo 路由、熔断器、密钥策略、可观测性等网关能力——OpenCode 无需感知上游是哪家供应商。

🔑 API Key 与鉴权配置

在 Dashboard 的 Endpoint 页面可查看 API 端点地址（默认 http://localhost:20128/v1）与已注册的 API Keys。鉴权按实例配置二选一：

OpenCode 侧统一发送 Authorization: Bearer <apiKey>，无需任何 Anthropic 风格的特殊处理。密钥存入 ~/.local/share/opencode/auth.json，与插件的 baseURL 配置相互独立。

🧠 模型目录如何工作：从 8 个默认模型到 1200+ 实时目录

静态模式（provider 包） 默认只暴露 8 个精选模型（默认目录定义）：cc/claude-opus-4-8、cc/claude-sonnet-4-6、claude-opus-4-5-thinking、gemini-3-flash 等。建议额外加入：

• "auto" — 暴露 OmniRoute 的 Auto-Combo 零配置路由器，由网关挑选当前最优模型；
• "<combo-name>" — 你在 Dashboard 中定义的任意路由组合，网关透明解析。

动态模式（plugin 包） 则完全交给网关做"唯一事实来源"：

• 启动时拉取 /v1/models + /api/combos，-low/-medium/-high/-thinking 变体与 Combo 均作为一等 ID 出现，不做客户端合成；
• 默认 5 分钟 TTL 自动刷新（modelCacheTtl），运行期还有后台自动发现（autoSyncIntervalMs），新模型无需重启 OpenCode 即可出现；
• 输入 /omni-sync 可强制立即同步，/omni-autosync 查看同步状态；
• Combo 的上下文窗口按成员最小值（LCD 聚合）计算，避免 null 值导致的 4K token 截断。

⚙️ 插件进阶特性：精选模型选择器

OmniRoute 实例通常提供 600+ 模型，OpenCode 的选择器会"翻不动"。插件的 features 块（全部可选）帮你治理：

生产推荐组合：usableOnly: true + diskCache: true + visibleModels 白名单。完整参数说明见 插件 README。

🛠 三个高频故障的 30 秒排查法

📂 相关资源索引

• 集成官方文档：docs/frameworks/OPENCODE.md
• 静态生成器包：@omniroute/opencode-provider/（默认模型目录）
• 运行时插件包：@omniroute/opencode-plugin/（插件入口）
• 配置合并核心服务：src/shared/services/opencodeConfig.ts

至此，OpenCode 已经通过 OmniRoute 网关接入全部模型——配额耗尽自动切换供应商、Token 节省 15–95%，而你在终端里只需一句 omniroute setup opencode --auth。🎉

【免费下载链接】OmniRoute Never stop coding. Free MIT AI gateway: one endpoint, 350 providers (90+ free), 1200+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 450+ contributors 项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute