1. 为什么单 Agent 写项目总会翻车如果你用 OpenCode 做过稍微像样的项目大概率遇到过这种场面一个 Agent 既帮你分析需求又自己写方案写完代码还自己审查一遍最后告诉你“没问题”。结果跑起来一堆边界情况没处理你还得回头翻它到底改了哪些文件。这不是模型不行而是职责没拆开。单 Agent 做项目开发问题集中在四个地方。第一是职责混乱同一个上下文里既要拆需求又要写实现模型很容易在“想”和“做”之间反复横跳方案还没定就开始改文件。第二是权限过大Agent 既能 edit 又能 bash 还能联网一次误操作可能把配置改坏或者执行了不该跑的命令。第三是自审偏差实现和审查是同一个模型、同一段上下文它天然倾向于认为自己写的是对的漏掉的问题很难被自己发现。第四是视觉成本偶尔要读一张设计稿截图如果主 Agent 一直挂着视觉模型成本和模型选择都被绑死了。所以更工程化的做法是把开发流程拆成多个职责清晰的 Agent每个 Agent 只干一件事用权限配置限制它能碰什么再用一个主 Agent 负责编排和验收。这篇就按这个思路用 TaoToken 统一 Key 接入从零搭一套 7 个 Agent 协作的项目开发流程。整套配置可以直接复制跑通之后你会得到一条“需求拆解 → 方案设计 → 代码实现 → 独立审查 → 注释补充”的闭环链路。适合谁看已经在用 OpenCode、想让 AI 编程流程标准化的开发者团队里想共享一套 Agent 编排规则、而不是每个人临时写 prompt 的人以及被单 Agent 自审偏差坑过、想引入独立验证环节的人。下面从 TaoToken 的前置准备开始一步步把配置落地。2. TaoToken 前置准备统一 Key 与接入点多 Agent 场景下最烦的事情之一是 Key 管理。7 个 Agent 如果各自配一套 Key改起来就是灾难。更合理的做法是所有 Agent 走同一个 OpenAI 兼容接入点用同一个 Key模型差异通过模型 ID 区分。TaoToken 正好适合这个角色它提供统一的 API 入口你只需要维护一份 Key。先拿到 Key。打开 TaoToken 控制台在 API Keys 页面创建一个新 Key复制出来先存好后面配置里要用。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 创建 Key 的具体入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。如果你还没决定用哪些模型可以先到模型对话页面试一下各个模型的响应风格地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 试完再决定哪个 Agent 绑哪个模型。接入点在 OpenCode 里配置时baseURL 填https://taotoken.net/api注意这个地址不带任何查询参数。npm 包用ai-sdk/openai-compatible这是 OpenAI 兼容接入点的标准 SDK。模型 ID 需要提前在 provider 的 models 里声明Agent 文件里引用的模型必须在这里存在否则 OpenCode 启动或调用时会直接报错。这里有个关键原则含 API Key 的 provider 配置放用户级Agent 定义放项目级。用户级配置在~/.config/opencode/opencode.json跨项目复用不会进仓库项目级 Agent 文件放.opencode/agents/可以进 Git团队共享和 review。OpenCode 在两层配置同时存在时会做深度合并同名字段以项目级为准。也就是说团队强约束放项目级个人密钥和偏好放用户级。如果你打算长期跑这套多 Agent 流程尤其是 executor 和 reviewer 会频繁调用模型可以了解一下 Coding Plan它在高频编码场景下更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 配置过程中遇到字段疑问可以对照查。3. 可复制的配置骨架3.1 目录结构先把目录建好这是整套流程的骨架~/.config/opencode/ └── opencode.json # 用户级provider、Key、默认 Agent 项目目录/ ├── .opencode/ │ └── agents/ │ ├── orchestrator.md │ ├── architect.md │ ├── executor.md │ ├── reviewer.md │ ├── bulk.md │ ├── vision.md │ └── commenter.md └── opencode.json # 项目级可选项目强绑定配置用户级放 provider 和 Key项目级放 Agent 定义。这样团队 clone 项目后只需要自己配一份用户级 KeyAgent 编排规则直接复用。3.2 用户级 opencode.json这是接入 TaoToken 的核心配置把your-taotoken-api-key换成你刚才创建的 Key{ $schema: https://opencode.ai/config.json, default_agent: orchestrator, provider: { taotoken: { name: TaoToken, npm: ai-sdk/openai-compatible, options: { apiKey: your-taotoken-api-key, baseURL: https://taotoken.net/api }, models: { glm-5.2: { name: GLM-5.2 }, glm-5.1: { name: GLM-5.1 }, claude-opus-4-8: { name: Claude Opus 4.8 }, gpt-5.5: { name: GPT-5.5 }, kimi-k2.6: { name: KiMi-2.6, attachment: true, tool_call: true, temperature: true, modalities: { input: [text, image, pdf], output: [text] }, family: kimi, limit: { context: 128000, output: 16000 } } } } } }几个容易踩的点。default_agent设成orchestrator这样你打开 OpenCode 默认就是主编排在等你。models里声明的模型 ID 必须和 Agent 文件里model:字段引用的完全一致比如 Agent 里写taotoken/glm-5.2那这里就必须有glm-5.2这个键。视觉模型kimi-k2.6同时配了attachment: true和modalities.input包含image这两个字段缺一不可只配一个的话图片输入链路可能被客户端拦截。3.3 七个 Agent 的职责与权限对照先看整体分工再逐个看文件Agent类型职责示例模型权限原则orchestratorprimary需求拆解、任务路由、结果汇总、验收判断glm-5.2只读禁 edit/bash/联网architectsubagent需求澄清、方案设计、接口划分、测试矩阵claude-opus-4-8只读不改代码executorsubagent按方案实现、调试、运行验证命令glm-5.2可 editbash 需确认reviewersubagent读 diff、运行验证、报告阻塞问题gpt-5.5只读bash 白名单限验证命令bulksubagent变量重命名、样板代码、测试补齐glm-5.2可 edit禁 bashvisionsubagent读取截图、设计稿、错误截图kimi-k2.6hidden只读图commentersubagent补充代码注释和文档注释glm-5.1可 edit禁 bash/联网3.4 orchestrator只编排不写代码--- description: 主编排。拆解需求、调用规划 Agent、派发实现与审查任务、控制返工与验收。默认不直接修改代码。 mode: primary model: taotoken/glm-5.2 permission: read: allow glob: allow grep: allow edit: deny bash: deny webfetch: deny websearch: deny lsp: deny todowrite: allow question: allow task: *: deny architect: allow executor: allow reviewer: allow bulk: allow vision: allow commenter: allow --- 你是编排者职责严格限定为需求拆解、任务路由、汇总子 Agent 结果、控制返工与验收。 绝对禁止 - 禁止自行产出代码实现、补丁、命令脚本。 - 禁止自行产出审查结论或最终技术方案。 - 禁止自行回答本应由子 Agent 完成的工作。 - 禁止编辑文件、执行 bash、联网搜索。 你必须做且只做以下动作 1. 读取需求与上下文明确目标、边界、验收标准和风险等级。 2. 复杂任务或目标不够清晰的任务调用 architect。 3. 方案明确后调用 executor 实现。 4. 低风险机械任务调用 bulk。 5. 每次代码修改后调用 reviewer 审查和验证。 6. 若验证失败返回 executor 修复不要自己改。 7. 只根据 reviewer 的客观验证结果和风险等级做验收判断。task字段是路由白名单*: deny表示默认不允许调用任何子 Agent然后逐个放行。这样 orchestrator 只能调用你明确允许的 Agent不会乱派任务。3.5 architect只读方案设计--- description: 规划与架构。当需要需求澄清、方案设计、接口划分、数据流设计、测试矩阵或验收标准时使用。只读代码库产出决策完整的方案不修改代码。 mode: subagent model: taotoken/claude-opus-4-8 permission: read: allow glob: allow grep: allow edit: deny bash: deny webfetch: deny websearch: deny --- 你负责规划与架构。先理解相关代码和约束再输出决策完整的方案。 方案必须包括模块划分、接口变化、数据流、错误处理边界、测试矩阵和验收标准。 不写实现代码不修改文件。3.6 executor可写但 bash 需确认--- description: 实现与执行。当需要跨文件修改、调试、构建、运行测试或修复返工时使用。根据既定方案完成代码修改运行项目规定的验证命令。 mode: subagent model: taotoken/glm-5.2 permission: read: allow glob: allow grep: allow edit: allow bash: ask --- 你负责按方案实现。修改前先确认影响范围修改后运行项目规定的验证命令。 返回内容必须包括修改摘要、影响文件、运行命令、测试结果和未解决风险。bash: ask是关键executor 执行命令前会请求确认避免它自作主张跑危险操作。3.7 reviewer独立验证白名单命令--- description: 审查与验证。当需要读取 diff、运行验证命令、发现阻塞问题或判断是否返工时使用。只读 diff运行项目规定的验证命令只报告阻塞性问题不修改代码。 mode: subagent model: taotoken/gpt-5.5 permission: read: allow glob: allow grep: allow edit: deny bash: *: deny git status: allow git diff*: allow git show*: allow git log*: allow npm test*: allow pnpm test*: allow yarn test*: allow go test*: allow pytest*: allow mvn test*: allow gradle test*: allow make test*: allow npm run lint*: allow npm run typecheck*: allow tsc*: allow --- 你负责在独立上下文中审查代码。只报告阻塞性问题。 必须读取 diff并尽可能运行项目声明的验证命令。 不修改代码不提出无关风格建议。 返回内容必须包括验证命令、执行结果、阻塞问题、是否建议返工。reviewer 用和 executor 不同的模型这是降低同源自审偏差的核心手段。executor 用 glm-5.2reviewer 用 gpt-5.5实现和审查分离。3.8 bulk / vision / commenter--- description: 当需要变量重命名、样板代码、测试补齐等低风险机械任务时使用。处理明确、机械性的修改遇复杂问题停止并交回编排者。 mode: subagent model: taotoken/glm-5.2 permission: read: allow glob: allow grep: allow edit: allow bash: deny --- 你只处理明确、低风险、机械性的修改。 遇到需要架构判断、业务判断或跨模块影响的问题必须停止并交回编排者。 你的修改结果必须进入 reviewer 验证不能直接合并。--- description: 视觉读图。当需要读取图片内容、分析 UI 截图、比对设计稿或提取图片中的文字/代码/结构信息时使用。只读图并返回结构化描述不做架构判断或代码实现。 mode: subagent model: taotoken/kimi-k2.6 hidden: true permission: read: allow glob: deny grep: deny edit: deny bash: deny webfetch: deny websearch: deny --- 你是专用的视觉读图 Agent职责严格限定为读取图片内容并返回结构化描述。 绝对禁止 - 禁止产出代码实现、架构方案或技术决策。 - 禁止产出审查结论或验收判断。 - 禁止修改文件、执行命令或联网搜索。 - 禁止对图片内容进行推测性补充。 你必须做且只做以下动作 - 读取用户提供的图片。 - 准确描述图片中的可见内容。 - 以结构化格式返回便于编排者分发给其他 Agent。 - 若图片模糊、不完整或无法识别明确说明限制不要猜测。--- description: 代码注释。当需要为代码补充或完善注释、文档注释、函数说明时使用。只加注释不改业务逻辑不执行命令。 mode: subagent model: taotoken/glm-5.1 permission: read: allow glob: allow grep: allow edit: allow bash: deny webfetch: deny websearch: deny --- 你是专用的代码注释 Agent职责严格限定为为代码补充和完善注释不改业务逻辑。 绝对禁止 - 禁止修改函数签名、业务逻辑、控制流、数据结构。 - 禁止执行命令、联网搜索。 - 禁止产出架构方案或审查结论。 你必须做且只做以下动作 - 读取目标代码理解其功能与边界。 - 为函数、类、复杂逻辑补充注释。 - 优先使用项目已有注释风格。 - 不为显而易见的代码加冗余注释。 - 修改结果必须进入 reviewer 验证。vision的hidden: true表示它不会出现在默认 Agent 列表里只希望被 orchestrator 委托调用。这样主 Agent 保持纯文本模型只有需要读图时才调 vision成本和模型选择都不被绑定。4. 逐 Agent 验证协作链路配置写完不代表能跑通得逐个验证。我试过直接一把梭结果 orchestrator 路由到不存在的 Agent 上排查了半天。建议按下面的清单一步步来。4.1 验证 provider 和模型声明先确认 OpenCode 能识别 TaoToken 接入点。在项目目录下启动 OpenCode输入/models或类似命令查看可用模型列表应该能看到taotoken/glm-5.2、taotoken/gpt-5.5等。如果看不到检查用户级opencode.json的baseURL是不是https://taotoken.net/api以及models里声明的 ID 和 Agent 文件里引用的是否一致。4.2 验证 orchestrator 路由给 orchestrator 发一个简单需求比如“帮我看看这个项目用了什么测试框架”。它应该调用 architect 或直接读文件而不是自己编一个答案。如果它直接开始 edit 文件说明edit: deny没生效检查 frontmatter 缩进。4.3 验证 architect 只读让 orchestrator 派一个方案设计任务观察 architect 的输出。它应该给出模块划分、接口变化、测试矩阵但不应该出现任何文件修改。如果它试图 edit说明edit: deny没写对。4.4 验证 executor 的 bash 确认让 executor 实现一个小改动比如“把某个变量重命名”。它修改文件后如果尝试运行npm test应该弹出确认提示。如果直接跑了检查bash: ask是否生效。4.5 验证 reviewer 白名单让 reviewer 审查一次改动。它应该能运行git diff和npm test但如果尝试运行rm -rf或curl应该被拒绝。白名单外的命令一律 deny。4.6 验证 vision 委托给 orchestrator 发一张截图问“这个 UI 有什么问题”。orchestrator 应该调用 vision 子 Agentvision 返回结构化描述orchestrator 再根据描述分发给其他 Agent。如果 orchestrator 自己试图读图说明 vision 没配好或者 orchestrator 的 task 白名单没放行。4.7 跑通完整链路用一个真实小需求验证整条链路比如“做一个 HTML 五子棋游戏双人轮流落子判断胜负”。预期流程是orchestrator 拆解需求 → architect 输出棋盘数据结构、胜负判定逻辑、交互流程和验收标准 → executor 实现index.html和游戏逻辑 → reviewer 读 diff、运行验证、报告阻塞问题或放行 → 如果需要补注释调 commenter。最终五子棋能跑起来双人轮流落子能判胜负。这条链路跑通说明 7 个 Agent 的协作是成立的。价值不在于五子棋本身而在于验证了“问题拆解 → 子 Agent 分工 → 权限隔离 → reviewer 验证闭环”这套机制。5. 本篇常见错排查5.1 Agent 引用的模型没在 provider 里声明报错通常长这样Model taotoken/gpt-5.5 not found。原因是 Agent 文件里写了model: taotoken/gpt-5.5但用户级opencode.json的provider.taotoken.models里没有gpt-5.5这个键。解决方法是把用到的模型 ID 全部在 models 里声明一遍。5.2 视觉模型漏配 attachment 或 modalities如果 vision Agent 读图时报“模型不支持 image input”检查kimi-k2.6的配置里是否同时有attachment: true和modalities.input包含image。只配一个不够两个字段分别控制附件链路和图片输入放行。另外要注意这两个字段只是让 OpenCode 客户端放行模型服务端本身也必须真实支持视觉能力上线前建议用最小多模态请求验证。5.3 orchestrator 权限过大如果 orchestrator 既能 edit 又能 bash它会绕过子 Agent 分工直接实现或执行命令多 Agent 编排就失去意义。检查 orchestrator 的 frontmatter 里edit: deny和bash: deny是否都在。5.4 reviewer 没有可运行的验证命令如果项目没有测试、lint、typecheck 或类似验证命令reviewer 的价值会大幅下降它只能读 diff 做静态审查。建议至少给项目配一个npm test或npm run lint让 reviewer 有客观验证手段。5.5 真实 API Key 提交进仓库用户级opencode.json含 Key项目级 Agent 文件不含 Key。如果你把 provider 配置放到了项目级一定要确认.gitignore排除了它或者用环境变量注入 Key。更稳妥的做法是 Key 只放用户级。5.6 description 写得太模糊导致路由错乱orchestrator 的路由主要依赖每个 Agent 的description。如果 architect 的 description 写成“负责架构相关的事情”orchestrator 可能把实现任务也派给它。建议每个 description 都写成“当需要 xxx 时使用。负责 xxx不负责 xxx”的格式边界清晰。6. 继续往下走整套配置跑通后你手里就有了一套可复用的多 Agent 项目开发流程。接下来可以根据项目实际情况调整模型 ID 换成你实际用的reviewer 的 bash 白名单按技术栈增删Agent 的 description 按团队习惯微调。如果你在接入或排障过程中遇到 Key 或接入点的问题先到 API Keys 页面确认 Key 状态地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 再对照接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 检查字段。想先试模型响应风格再决定绑定关系可以去模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。长期跑编码和 Agent 任务的话Coding Plan 入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。最后提醒一句这套 7 Agent 配置是模板不是万能药。小脚本单 Agent 就够别为了多 Agent 而多 Agent。真正值得上这套流程的是那些需要需求澄清、方案设计、实现、独立审查多个环节、且团队希望标准化流程的项目。