企业官网建设流程全解析

1. opencode 子代理配置为什么总在 Key 上翻车

opencode 是一个把「主代理 + 子代理」拆开跑的编码工具，主代理负责跟你对话、拆任务，子代理负责具体干活：跑构建、跑测试、做 lint、修报错、搜代码库。它最大的价值在于多模型协作——规划用推理强的模型，执行用便宜快的模型，探索用上下文长的模型。但真上手你会发现，卡人的地方不是写 agent 配置，而是 Key 管理。

我见过太多人的opencode.json长这样：executor 指向 A 家的 deepseek，explore 指向 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-id，provider 名你自己在 opencode 的 provider 配置里定义，model-id 用 TaoToken 侧的模型名。比如你想让 executor 跑 deepseek 系列，model-id 就填对应的名字。

环境变量建议这样组织，只留一个：

export TAOTOKEN_API_KEY="sk-你的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和subagent，primary 是你能直接对话的入口，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-model，executor 那行显示的是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，就能在终端看到类似provider=taotoken model=deepseek-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里没列这个模型 ID，opencode 在本地就拦下了。把要用的模型 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 查 Key，404 查 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 问题中断过任务。