在终端里跑 AI Coding Agent最费时间的往往不是工具本身而是绕不开的那几件琐事接哪个模型、API Key 放哪、opencode.json怎么写、报错了从哪查。本文用一份可复现的opencode.json把OpenCode 通过 Code0 的一个 Key 调起 OpenAI / Claude / Gemini 等多家模型的全流程讲清楚重点落在四件事上配置怎么写、怎么验证、哪里容易错、成本怎么控。一、两个工具各是什么10% 背景够用即可OpenCode是一个跑在终端里的 Coding Agent采用客户端/服务器分离设计支持终端 TUI、桌面端和 IDE 三种形态。它有一个对配置很关键的特点——配置即代码用的模型、Provider、Agent 角色统统写进opencode.json可以跟着项目走、纳入版本管理而不是散落在某个交互式登录状态里找不到。Code0是面向开发者的多模型聚合 API 中转服务核心一句话——一个 Key 接入 OpenAI / Anthropic / Gemini 等主流模型。它兼容 OpenAI SDK 和 OpenAI Chat Completions 风格接口官网公开表达为 500 模型、40 接入服务商覆盖 OpenAI、Claude、Gemini、DeepSeek、Grok、Qwen、Kimi、Meta 等。需要说明的是它不是任何上游模型厂商的官方渠道而是帮你用一份配置、一个 Key 把这些模型统一调起来的中转层。两者配合的逻辑很简单OpenCode 负责在终端跑 AgentCode0 扮演那个「OpenAI 兼容的 Provider」给它供模型。因为走的是 OpenAI 兼容接口OpenCode 这边不需要任何私有 SDK本质上只是配一个baseURL、一个apiKey外加一组models。这套写法对任何 OpenAI 兼容的中转服务都通用Code0 只是本文贯穿到底的例子。二、环境准备1. 安装 OpenCode# npm跨平台通用 npm i -g opencode-ai # HomebrewmacOS / Linux brew install opencode # 官方 install 脚本 curl -fsSL https://opencode.ai/install | bash装完后终端敲opencode能进 TUI或opencode --version有版本号输出即安装成功。2. 拿到 Code0 的 Base URL 和 API Key去 Code0 控制台创建一个 API Key记下两个关键信息Base URL默认https://code0.ai/v1末尾/v1不要漏API Key形如sk-...的字符串。如果后续遇到连接不稳可以把 Base URL 切到香港节点https://hk.code0.ai排查。⚠️ 务必到 Code0 控制台确认当前可用的模型列表。后面填models时一律以控制台实际可见的模型 ID为准不要凭记忆自己造。三、核心配置一份opencode.json接入 Code0整套配置说穿了就一句话告诉 OpenCode「有个 OpenAI 兼容的 Provider 叫 code0baseURL 是这个、Key 是这个、能用的模型是这些」。1. 配置文件放哪全局 / 项目 / 环境变量OpenCode 配置有优先级远程 全局 自定义 项目常见存放位置全局~/.config/opencode/opencode.json项目项目根目录下的opencode.json自定义用OPENCODE_CONFIG指定路径关于 Key 放哪给一条明确建议把带 API Key 的 Provider 配置写进全局的~/.config/opencode/opencode.json不要写进项目里的opencode.json然后提交 Git否则 Key 会随代码泄露。如果确实要在项目里写配置就用环境变量注入 Key配置文件里只引用变量名别把明文写死。补充两种接入路径的区别/connect这类交互式认证会把凭证写进auth.json适合官方账号登录场景本文用的是在 config 里直接内联 Provider Key的方式更适合接自建服务或聚合中转好处是一份文件就能复用、能迁移。2. 完整opencode.json示例{ $schema: https://opencode.ai/config.json, provider: { code0: { npm: ai-sdk/openai-compatible, options: { baseURL: https://code0.ai/v1, apiKey: sk-你的Code0Key }, models: { gpt-5.5: { name: GPT-5.5 (Code0) }, gemini-3-pro-preview: { name: Gemini 3 Pro (Code0) } } } } }逐字段拆解顺带点出容易翻车的地方$schema编辑器补全和校验用建议保留。provider.code0code0就是 Provider ID。注意 Provider ID 大小写敏感后面在 TUI 选模型、在 Agent 里引用时都要一模一样。npm: ai-sdk/openai-compatible告诉 OpenCode 用 OpenAI 兼容适配器对接。Code0 本身就是 OpenAI 兼容接口用这个就够不需要私有包。options.baseURL填https://code0.ai/v1末尾/v1必须带上漏了直接连不通。options.apiKey填 Code0 的 Key放全局或走环境变量别进 Git。models.模型ID这个 key 必须是Code0 控制台里实际可见的模型 ID不能自己编name只是显示名方便自己认即可。3. 到底填哪些模型 ID以控制台可见列表为准这里最容易出岔子——很多教程直接抄一个型号名平台一更新就失效。正确做法是打开 Code0 控制台照着当前实际可见的模型 ID 填。选型思路可以这样搭配具体能用哪些 ID一律以 Code0 控制台当前可见为准主力 / 复杂任务如gpt-5.5、GPT-5.4这类高性能通用模型做主编码、架构推理偏好 Claude 系可选对应的高性能型号多模态 / 图片如gemini-3-pro-preview、gemini-3-pro-image-preview、gpt-image-2等图片模型接入有额外的坑见下方排错章节轻量 / 高频把检索、摘要、命名这类又多又碎的小任务丢给便宜的轻量模型能省不少额度。四、验证链路是否打通1. 先用 curl 自测/models别急着动 OpenCode先验 Key 和 Base URL 通不通curl https://code0.ai/v1/models \ -H Authorization: Bearer sk-你的Code0Key能返回一串模型列表 JSON说明 Key 有效、Base URL 没写错。如果这一步就 401先别折腾 OpenCode回头查 Key。2. 重启后在 TUI 里确认关键细节OpenCode 配置不是热加载的改完opencode.json必须重启才能生效。这一点坑了不少人偏偏又不容易查到原因。验收标准重启后进opencodeTUI在模型选择里应看到你定义的code0 分组及其下的模型跑一句实测opencode run 用一句话解释什么是幂等 -m code0/gpt-5.5能正常回答说明 OpenCode → Code0 这条链路彻底打通。五、常见报错与排查表现象大概率原因排查方向401 / 无效 KeyKey 错了或与 Provider 对不上用 curl 单独验 Key确认这个 Key 归属确实是 Code0别写成别的服务模型不存在 / 列表里看不到模型 ID 拼错或该模型当前控制台不可见回 Code0 控制台核对确切 ID逐字符比对别自己造无可用渠道尤其图片模型gpt-image-2/image2Key 分组或权限问题图片模型接入需把 Key 分组选成 gpt这类问题多与分组、权限有关按控制台分组设置调整连接超时 / 不稳定节点波动把 baseURL 从https://code0.ai/v1切到https://hk.code0.ai试试配置改了却不生效忘了重启OpenCode 非热加载改完 config 必须重启baseURL 相关连不通末尾漏了/v1检查 baseURL 是否为https://code0.ai/v1六、进阶多模型 Agent 编排与成本控制1. 按角色给 Agent 分配主力 / 轻量模型OpenCode 支持在agents/目录下用 Markdown 定义不同角色的 Agent并给每个角色单独指定模型。核心思路是让贵的模型只干它该干的活把又多又小的杂活交给便宜模型。主编码 Agent用gpt-5.5这类强推理模型处理复杂改动检索、摘要、命名等子任务交给轻量模型config 里还可以配一个small_model让工具类的辅助调用统统走轻量模型把成本再往下压。好在同一份 Code0 Key 就能覆盖这些不同模型的调用用不着为每个模型各配一套凭证。2. 切换节点与稳定性遇到偶发超时或波动把baseURL从主域名切到https://hk.code0.ai是最直接的排查手段。改完记得重启 OpenCode否则不生效。3. 额度、失败不计费与开票Code0 站内以$符号展示额度和消耗可按1.5 RMB 1 美元 API 额度的比例理解余额。它支持人民币充值、可开票而且失败的请求不计费——这一点对调试期反复试错比较友好配错了、报错了不用担心额度被白扣。再配合「主力 轻量」的模型分工日常成本通常能压得比较可控。七、FAQQ改了配置怎么不生效AOpenCode 配置不是热加载的改完opencode.json必须重启。这是最高频的一种「假故障」。Q图片模型报「无可用渠道」怎么办A多半与 Key 分组或权限有关。用gpt-image-2/image2时把 Key 分组选成 gpt再回控制台确认该模型对当前 Key 可见。Q一个 Code0 Key 能同时给多个工具用吗A能。Code0 是 OpenAI 兼容的中转除 OpenCode 外Cursor、Codex、Gemini CLI、Roo Code、Chatbox 等工具同样都是「替换 base_url / api_key / model 这三处」即可接入同一个 Key 可反复复用。Q模型 ID 照别的教程抄行不行A不建议。模型会随平台更新增减照抄容易失效。任何时候都以Code0 控制台当前可见的模型列表为准。小结按上面这套流程走完你就闭环了「配得通 用得对 花得省 排得掉错」一份opencode.json、一个 Code0 KeyOpenCode 就能在终端调起 OpenAI / Claude / Gemini 等多家模型。核心记住三件事——baseURL 要带/v1、模型 ID 以控制台为准、改完配置一定要重启剩下的照报错表逐条排查即可。如果需要统一管理多模型 API可以看 Code0 的模型列表和接口文档按控制台当前可见的模型 ID 对照配置。
