1. opencode 子代理配置为什么总在 Key 上翻车opencode 是一个把「主代理 子代理」拆开跑的编码工具主代理负责跟你对话、拆任务子代理负责具体干活跑构建、跑测试、做 lint、修报错、搜代码库。它最大的价值在于多模型协作——规划用推理强的模型执行用便宜快的模型探索用上下文长的模型。但真上手你会发现卡人的地方不是写 agent 配置而是 Key 管理。我见过太多人的opencode.json长这样executor 指向 A 家的 deepseekexplore 指向 B 家的长上下文模型plan 又指向 C 家的推理模型。于是环境变量里躺着三四个 Key每个 Key 对应不同的 Base URL、不同的计费账户、不同的额度。切换项目时忘了改环境变量子代理直接 401某个 Key 额度用完整个并行任务链断在中间想临时把 executor 换成另一个模型对比效果得先去翻文档找那家的 endpoint 格式。这个场景的核心矛盾是opencode 的子代理机制天然鼓励你按任务分配模型但每接一家模型就多一套 Key 和 Base URL。子代理越多Key 越分散切换越繁琐。TaoToken 在这里的作用是做一个统一的模型接入层。你只需要一个 Key、一个 Base URL就能在 opencode 里把不同子代理路由到不同模型。opencode 的 agent 配置里model字段填的是「provider/model-id」格式只要这个 provider 指向 TaoToken模型 ID 换成对应的名字子代理就自动路由过去了。换句话说Key 收敛成一个模型选择留在配置文件里改模型不用动环境变量。这篇面向的是已经在用或准备用 opencode 的开发者尤其是那种「想让 plan 用强模型、executor 用快模型、explore 用长上下文模型」的多子代理协作场景。下面从接入配置讲到并行验证再讲几个我实际踩过的报错。2. TaoToken 统一 Key 接入 opencode 的前置准备在动opencode.json之前先把接入层准备好。这一步做对了后面子代理配置就是纯改字段的事。首先去 TaoToken 拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key。这个 Key 就是你后面所有子代理共用的唯一凭证。建议按项目建 Key方便单独看用量和随时吊销。拿到后先存好形如sk-xxxxxxxx。然后是 Base URL。opencode 走的是 OpenAI 兼容协议所以 Base URL 填https://taotoken.net/api。注意这里不要带任何多余路径opencode 会自己在后面拼/chat/completions。如果你填成https://taotoken.net/api/v1有些版本会拼成/v1/v1/chat/completions直接 404这个坑后面排障章节会细说。接着确认你要用的模型 ID。TaoToken 的模型列表在 https://taotoken.net/models 可以查也可以直接调接口拉。opencode 的 agent 配置里model字段格式是provider/model-idprovider 名你自己在 opencode 的 provider 配置里定义model-id 用 TaoToken 侧的模型名。比如你想让 executor 跑 deepseek 系列model-id 就填对应的名字。环境变量建议这样组织只留一个export TAOTOKEN_API_KEYsk-你的key不要给每个子代理单独设一个 Key 变量那样又回到分散管理的老路了。opencode 的 provider 配置里引用同一个变量即可。如果你用的是 Claude Code 那套生态TaoToken 也提供了对应的接入文档 https://taotoken.net/doc 里面有针对不同客户端的 Base URL 和鉴权写法。opencode 这边本质一样都是 OpenAI 兼容所以照着通用接入部分配就行。有一点要提醒opencode 的 provider 配置和 agent 配置是两层。provider 层定义「怎么连」agent 层定义「用哪个模型、什么权限、什么温度」。很多人把这两层混在一起写结果 agent 里的 model 找不到对应 provider。下一节会把两层都写清楚。3. 可复制的 opencode.json 子代理配置片段这一节是核心直接给能抄的配置。opencode 的配置文件默认在项目根目录的opencode.json也可以放在全局配置目录。下面这份是「一个 provider 多个子代理」的完整结构。先看 provider 层把 TaoToken 定义成一个 OpenAI 兼容的 provider{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: {env:TAOTOKEN_API_KEY} }, models: { deepseek-v4-flash: {}, deepseek-reasoner: {}, long-context-model: {} } } } }这里几个关键点。npm字段指定用 OpenAI 兼容的适配器opencode 会据此走标准协议。baseURL就是上一步说的https://taotoken.net/api不带/v1。apiKey用{env:TAOTOKEN_API_KEY}引用环境变量这样 Key 不进配置文件可以安全提交到仓库。models里列出你实际要用的模型 ID这些 ID 要和 TaoToken 侧一致写错了会在请求时报 model not found。然后是 agent 层把主代理和子代理分开配{ agent: { build: { mode: primary, model: taotoken/deepseek-reasoner, temperature: 0, permission: { *: allow }, description: 构建主代理负责执行构建任务 }, plan: { mode: primary, model: taotoken/deepseek-reasoner, temperature: 0, permission: { *: allow }, description: 计划主代理负责制定执行计划 }, executor: { mode: subagent, model: taotoken/deepseek-v4-flash, temperature: 0, permission: { *: allow }, description: 执行与修复子代理负责运行构建、测试、代码检查、错误修复及命令行操作 }, explore: { mode: subagent, model: taotoken/long-context-model, temperature: 0, permission: { *: allow }, description: 探索子代理用于快速代码库探索 }, general: { mode: subagent, model: taotoken/deepseek-v4-flash, temperature: 0, permission: { *: allow }, description: 通用子代理用于复杂搜索和多步任务 } } }把两段合并到同一个opencode.json里就是完整配置。注意每个 agent 的model都是taotoken/模型ID格式provider 名taotoken和上面 provider 层的 key 完全对应。这样五个代理共用同一个 Key 和 Base URL但各自路由到不同模型。几个配置细节值得说。mode字段区分primary和subagentprimary 是你能直接对话的入口subagent 是被主代理调用的。temperature设 0 是为了让执行类任务稳定别让它自由发挥。permission里*: allow表示允许所有操作生产环境建议按需收紧比如 executor 只给命令执行权限。如果你想让 executor 临时换个模型对比效果只改model: taotoken/另一个模型ID这一行保存后重启 opencode 即可不用碰环境变量。这就是统一 Key 带来的直接好处模型切换成本从「改环境变量 重启终端」降到「改一行配置」。配置写完后opencode 启动时会读取这个文件。如果 JSON 语法错了它会直接报解析失败并指出行号这个后面排障会讲。4. 验证请求多子代理并行调用与结果确认配置写完不算完得验证每个子代理真的按预期路由到了目标模型。这一步我建议用一个能触发多子代理并行的任务来测比如「探索代码库 跑测试 修一个已知报错」。先启动 opencode在项目根目录执行opencode进入交互界面后先确认 provider 加载成功。opencode 一般有/models或类似的命令列出可用模型你应该能看到taotoken/deepseek-v4-flash、taotoken/deepseek-reasoner这些条目。如果列表里没有说明 provider 配置没被读到检查opencode.json路径和 JSON 语法。然后给一个会触发子代理的任务比如帮我探索一下这个项目的测试目录结构然后跑一遍测试如果有失败的就修掉这个任务会同时触发 explore 子代理探索目录和 executor 子代理跑测试、修报错。opencode 会在界面上显示每个子代理的调用状态和它用的模型。你要确认的是explore 那行显示的是long-context-modelexecutor 那行显示的是deepseek-v4-flash。如果想更直接地验证路由可以单独调一个子代理。opencode 支持显式指定子代理比如让它只跑 executor用 executor 子代理跑一下 npm test观察返回结果里模型标识。如果 executor 返回的内容风格和 deepseek-v4-flash 一致且没有报 401 或 model not found说明路由正确。再验证一次并行。给一个需要 explore 和 executor 同时干活的任务比如「先探索 src 目录找出所有 TODO然后对每个 TODO 所在文件跑 lint」。opencode 会并行调度两个子代理。这时候看日志或界面两个子代理应该各自带着自己的模型标识在跑互不干扰。如果其中一个报错错误信息会指明是哪个子代理、哪个模型出的问题定位很快。成功的结果长这样任务完成后你能看到 explore 返回了目录结构executor 返回了 lint 结果两者用的模型不同但都通过同一个 TaoToken Key 鉴权。整个过程你没有切换过任何环境变量。这里有个实用技巧opencode 的日志级别可以调高把每个请求的 model 字段打出来。在配置里加日志选项或者启动时带--log-level debug就能在终端看到类似providertaotoken modeldeepseek-v4-flash的行。这是确认路由最硬核的方式比看界面显示更可靠。如果并行调用时出现某个子代理超时先别急着改配置大概率是那个模型本身响应慢或者任务太重。可以单独调那个子代理跑个简单任务确认是模型问题还是配置问题。5. 本篇常见报错排查401、local proxy failed 与 reading choices这一节列几个我在配 opencode TaoToken 时真实撞到的报错以及对应的修法。每个都给出报错原文特征和定位思路。401 Unauthorized / invalid api key报错通常长这样Error: 401 Unauthorized {error:{message:invalid api key,type:authentication_error}}原因基本是 Key 没读到或读错了。先确认环境变量在当前 shell 里生效echo $TAOTOKEN_API_KEY如果为空说明你 export 的终端和启动 opencode 的终端不是同一个。opencode 的{env:TAOTOKEN_API_KEY}是在启动时读取的所以要先 export 再启动。另一个常见原因是 Key 复制时带了空格或换行重新从 https://taotoken.net/api-keys 复制一次注意别把首尾空白带进去。local proxy failed / connection refused报错特征Error: local proxy failed: dial tcp 127.0.0.1:xxxx: connect: connection refused这个通常不是 TaoToken 的问题而是 opencode 或你本机的某个本地代理设置在捣乱。检查你的 shell 里有没有HTTP_PROXY、HTTPS_PROXY、ALL_PROXY这类环境变量指向本地端口。如果有opencode 的请求会先走本地代理而那个代理没开就报 connection refused。临时清掉unset HTTP_PROXY HTTPS_PROXY ALL_PROXY再启动 opencode。另外检查 opencode 配置里有没有误设options.baseURL指向 localhost正常应该指向https://taotoken.net/api。reading choices / Cannot read properties of undefined报错特征TypeError: Cannot read properties of undefined (reading choices)这个几乎都是响应格式不对导致的。opencode 期望 OpenAI 标准的{choices: [...]}结构如果 Base URL 填错请求打到了非兼容端点返回的 JSON 里没有choices字段就会报这个。重点检查baseURL是不是https://taotoken.net/api有没有多写/v1或少写。另一个可能是模型 ID 写错请求被路由到了一个不存在的模型返回了错误结构。对照 https://taotoken.net/models 核对模型名。model not found / unknown model报错特征Error: model taotoken/xxx not found两种可能。一是 provider 层的models里没列这个模型 IDopencode 在本地就拦下了。把要用的模型 ID 加进models对象。二是 agent 层的model字段拼错了比如 provider 名写成了taotoken-api而 provider 层定义的是taotoken两边必须完全一致。OAuth / auth.json 相关报错如果你同时装了 Claude Code 或 Codex可能会看到 OAuth token 过期或auth.json读取失败的报错。这类报错和 opencode 本身无关是另一个工具的鉴权状态问题。opencode 走的是 API Key不依赖 OAuth。确认你启动的是 opencode 而不是别的 CLI检查~/.config/opencode/下的配置有没有被其他工具的配置覆盖。如果确实要用 Codex 的auth.json那套注意它的 Base URL 和 Key 字段名和 opencode 不同别混用。排查通用思路先看报错里的 HTTP 状态码401 查 Key404 查 Base URL 和模型 ID连接类错误查本地代理解析类错误查响应格式。把这四类分开定位会快很多。6. 把统一 Key 用在长期编码与 Agent 协作上配置跑通、并行验证过之后这套方案的价值在长期使用里才真正体现出来。最直接的变化是项目切换不再折腾。以前每个项目可能要配不同的 Key 和 Base URL现在所有项目共用一份opencode.json模板只改 agent 的模型分配。新项目初始化时把配置文件复制过去export 一次 Key就能跑。团队协作时配置文件可以进仓库因为 Key 走环境变量每个人用自己的 Key模型分配保持一致。第二个变化是模型对比变得廉价。想让 executor 从 deepseek-v4-flash 换成另一个更便宜的模型改一行model字段重启跑同一个任务对比结果。不用重新申请 Key、不用改 Base URL、不用查新家的协议格式。这种低成本的试错能让你更快找到「哪个子代理配哪个模型最划算」。如果你要做更复杂的 Agent 协作比如让多个子代理串行处理一个长任务链统一 Key 还能简化额度管理。所有子代理的调用都走同一个账户用量在一个地方看不会出现某个子代理的 Key 悄悄超额把任务卡死的情况。TaoToken 的 console https://taotoken.net/console 可以看到各模型的调用明细方便你按子代理维度分析成本。对于长期跑编码任务的场景可以考虑 Coding Plan https://taotoken.net/coding-plan 它针对持续性的编码和 Agent 调用做了额度优化比按次调用更适合天天跑子代理的用法。如果你的子代理任务里还涉及模型对话调试模型对话入口 https://taotoken.net/chat 可以快速验证某个模型 ID 是否可用省得在 opencode 里反复试。最后给一个实用习惯把opencode.json里的 agent 配置按「任务类型」而不是「模型名」来组织。比如 executor 就固定叫 executor模型 ID 作为它的属性。这样以后换模型只改属性值任务语义不变配置文件的可读性和可维护性都好很多。这套配置我用了几个月从单项目到多项目、从单子代理到并行调度没再因为 Key 问题中断过任务。