技术上可以实现,但你设想的“把 OpenCode agent 封装成一个 provider 节点”这个具体路径,可能不是最直接或最稳定的方式。实际情况是,OmniRoute 本身就已经内置了对 OpenCode 免费层的支持,并且有专门的机制来处理 OpenCode 的客户端合约限制。
🎯 OmniRoute 的原生支持:它已经“封装”好了
OmniRoute 将 OpenCode 的免费层归类为一种需要特殊合约处理的“无密钥(keyless)”提供商。它并非通过启动一个完整的 OpenCode agent 来代理请求,而是通过精准复刻 OpenCode 客户端的请求特征来通过官方的门禁。
OpenCode 的免费层门禁非常严格,任何一个条件不满足都会返回 403 FreeTierError。OmniRoute 的相关 PR(如 #14013)显示,它已经实现了对以下所有合约条件的满足:
- 流式响应:请求体必须包含
stream: true。 - 工具列表:必须携带一个非空的
tools数组。 - 客户端身份:必须包含特定的
User-Agent以及x-opencode-client等请求头。 - 会话标识:需要提供
x-opencode-session等会话相关的请求头。
因此,在 OmniRoute 中,你很可能不需要手动“封装”,直接在它的“免鉴权提供商”列表中选择 “OpenCode free” 并添加即可。有中文教程明确展示了这个配置路径,将其作为反代 OpenCode 免费模型的标准方法。
💡 更可靠的替代方案:专为“桥接”而生的中间件
如果你的目标是稳定地在各类外部工具(如 OmniRoute、LangChain 等)中使用 OpenCode 的免费模型,直接依赖 OmniRoute 对合约的模拟可能会有维护上的滞后。更稳健的思路是使用专门为“桥接 OpenCode”设计的中间件,让它们来处理复杂的合约和协议转换。
relayai-gateway 就是这样一个工具。它在后台自动运行 opencode serve,然后将标准的 OpenAI/Anthropic API 请求“翻译”给 OpenCode 进程。这意味着,它启动了一个真正的 OpenCode 实例来满足官方的“客户端”要求,从根本上绕过了合约模拟的脆弱性。它的文档也明确声称支持 OpenCode 的免费模型开箱即用。你可以将它部署为本地的一个 OpenAI 兼容端点(如 http://127.0.0.1:8000/v1),然后将这个端点作为自定义 provider 添加到 OmniRoute 中。这样,OmniRoute 负责路由,而 relayai-gateway 负责与 OpenCode 的合约握手,架构上更加清晰和稳定。
另一个类似的工具是 freellmpool,它同样提供一个本地 OpenAI 兼容代理,专门用于聚合和路由包括 OpenCode 在内的免费模型池。
⚠️ 关键风险与限制
在实施前,需要清楚了解以下风险:
- 违反服务条款(ToS)的风险:OpenCode 官方明确将免费层限制在“OpenCode 客户端内部使用”。所有这类封装、代理或桥接方案,在本质上都是在规避官方的访问控制。虽然技术上可行,但这可能违反其服务条款,存在账号或 IP 被限制的风险。
- 极高的不稳定性:这种方案完全依赖于 OpenCode 免费层门禁的实现细节。官方任何一次后端更新(如更改
User-Agent或请求体校验规则)都可能导致所有依赖此机制的工具立即失效。OmniRoute 和 relayai 等工具的维护者需要持续跟进修复,你也会处于被动的等待状态。 - 官方的明确立场:OpenCode 文档反复强调,免费层仅限其客户端使用,外部工具“即使有 API Key 也会收到 403”。这表明官方在有意阻止此类用法,而非疏忽。
💎 总结
你的思路方向是对的,但具体实施上,不需要(也很难)手动将 OpenCode agent 封装为一个 provider。
更实际的路径有两条:
- 直接使用 OmniRoute 的内置功能:在 OmniRoute 中添加“OpenCode free”作为免鉴权提供商,这是最快捷的方式,但稳定性完全取决于 OmniRoute 对 OpenCode 合约的跟进速度。
- 采用两段式架构(更稳健):部署 relayai-gateway 这类专用桥接工具,让它运行一个真实的 OpenCode 实例来处理合约;然后,将这个桥接工具暴露的本地 API 端点,作为自定义 provider 添加到 OmniRoute 中。
无论选择哪条路,都需要接受其固有的不稳定性和潜在的 ToS 风险。如果追求长期稳定,付费的 Go 订阅或使用其他官方支持的 provider 会是更可靠的选择。