1. 为什么要在 Claude Code 里复现 Oh-My-OpenCode 的 Subagent 骨架Claude Code 是 Anthropic 官方推出的命令行编程智能体它最被低估的能力不是补全代码而是 Subagent子智能体机制主对话可以派生出多个拥有独立上下文、独立模型、独立工具权限的子智能体并行处理同一项目的不同部分。Oh-My-OpenCode 之所以在社区里火是因为它把「一人抵一个开发团队」这件事做成了可配置的骨架——一个主 Agent 负责编排架构师、构建师、验证者、记录员各司其职通过共享文件交换状态。这套思路完全可以搬到 Claude Code 上。你不需要装 OpenCode也不需要额外的插件市场只要在项目里放好.claude/agents/*.md和一份共享的WORK_PLAN.md就能跑通一个最小可用的多智能体协作结构。适合谁适合已经用过 Claude Code 基础对话、想让多个角色并行干活、又不想把项目结构搞得太重的开发者。下面我会给出可直接复制的settings.json与config.toml片段再演示一次从架构设计到测试验证的完整协作流程。2. 前置准备TaoToken 接入与 Claude Code 环境Claude Code 默认走官方账号体系但很多团队希望用统一的 API 网关来管理密钥、额度和模型路由。TaoToken 提供的就是这一层一个兼容 Anthropic 接口规范的入口你可以在控制台生成 API Key然后让 Claude Code 通过环境变量指向它。这样多智能体协作时不同 Subagent 调用不同模型opus/sonnet/haiku也能在同一份额度下统一计费。先到控制台创建密钥https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建完成后拿到形如sk-xxxx的 Key接下来配置环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY两个变量指向 TaoToken 的 API 地址即可export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的密钥如果你用的是 Windows PowerShell写法是$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的密钥注意ANTHROPIC_BASE_URL只写到/api不要在后面拼/v1或具体路径Claude Code 会自己补全。写错会导致 404这是最常见的接入坑。验证环境是否生效直接跑一条最小请求claude -p 只回复 ok 两个字母如果返回ok说明网关链路通了。这一步没过就别急着配 Subagent否则后面报错你分不清是配置问题还是网络问题。密钥管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 可以随时轮换。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的项目级配置放在.claude/settings.jsonSubagent 定义放在.claude/agents/目录。先建目录mkdir -p my-project/.claude/agents cd my-project3.1 settings.json权限与模型路由.claude/settings.json控制主进程的权限白名单和默认模型。多智能体场景下我建议把常用工具预先放行避免每个 Subagent 启动时都弹权限确认{ permissions: { allow: [ Read, Write, Edit, Bash(git status), Bash(npm test:*), Bash(pytest:*), Grep, Glob ], deny: [ Bash(rm -rf:*), Bash(curl:*) ] }, model: claude-sonnet-4-20250514, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api } }allow里放的是各 Subagent 高频使用的工具deny里挡掉危险命令。注意Bash(npm test:*)这种带冒号的写法是前缀匹配只有以npm test开头的命令才放行。3.2 config.tomlSubagent 注册表如果你习惯 TOML 风格可以在项目根放一份config.toml作为 Subagent 的元数据索引方便团队 review 时一眼看清谁负责什么[orchestrator] name main role 编排者 model claude-sonnet-4-20250514 description 接收用户指令拆分任务调度 Subagent [[subagents]] name architect file .claude/agents/architect.md model claude-opus-4-20250514 tools [Read, WebSearch, WebFetch, Write] [[subagents]] name builder file .claude/agents/builder.md model claude-sonnet-4-20250514 tools [Read, Edit, Write, Bash, Grep, Glob] [[subagents]] name validator file .claude/agents/validator.md model claude-sonnet-4-20250514 tools [Read, Write, Edit, Bash] [[subagents]] name scribe file .claude/agents/scribe.md model claude-haiku-4-20250514 tools [Read, Write, Edit]这份 TOML 不是 Claude Code 强制读取的它的作用是让「谁用什么模型、拿什么工具」变成可审计的配置而不是散落在各个 md 文件的 frontmatter 里。真正生效的还是.claude/agents/下的文件。3.3 四个核心 Subagent 定义架构师architect.md负责需求分析和任务分解--- name: architect description: 架构设计专家。分析需求、研究方案、规划架构、分解任务到 WORK_PLAN.md model: claude-opus-4-20250514 tools: Read, WebSearch, WebFetch, Write --- 你是架构师智能体。职责 1. 分析用户需求识别核心问题与约束 2. 研究技术方案与最佳实践 3. 规划系统架构与技术栈 4. 将任务分解写入 WORK_PLAN.md每项标注负责的 agent 输出要求在 WORK_PLAN.md 中创建带复选框的任务列表完成后返回不超过 200 字的总结。构建师builder.md负责按计划写代码--- name: builder description: 代码实现专家。根据 WORK_PLAN.md 编写代码并更新任务状态 model: claude-sonnet-4-20250514 tools: Read, Edit, Write, Bash, Grep, Glob --- 你是构建师智能体。职责 1. 读取 WORK_PLAN.md 中分配给你的任务 2. 按项目现有风格编写代码 3. 完成后把 [ ] 改为 [x] 4. 遇到架构层面问题在计划中标注 architect 代码规范处理错误分支、考虑边界条件、补必要注释。完成后报告改了哪些文件。验证者validator.md负责测试--- name: validator description: 测试验证专家。编写测试、运行测试、报告问题 model: claude-sonnet-4-20250514 tools: Read, Write, Edit, Bash --- 你是验证者智能体。职责 1. 阅读已实现代码 2. 编写覆盖正常路径、边界条件、错误处理的测试 3. 运行测试套件 4. 发现问题记录到 WORK_PLAN.md 的问题区 测试通过后在计划中标记验证完成。记录员scribe.md负责文档--- name: scribe description: 文档专家。为已完成功能撰写文档、优化注释 model: claude-haiku-4-20250514 tools: Read, Write, Edit --- 你是记录员智能体。职责 1. 阅读已实现且测试通过的代码 2. 撰写 README 使用说明与 API 注释 3. 优化代码内联注释 文档要求简洁、准确、有可运行的示例。3.4 共享状态文件 WORK_PLAN.md多智能体协作的关键是共享状态。在项目根创建# 工作计划 所有 Agent 的共享状态用于任务分配与进度跟踪 ## 任务列表 _由 architect 填充_ ## 问题记录 _遇到的问题记录在这里_ ## 完成状态 _任务完成后打钩_这个文件就是 Oh-My-OpenCode 里 Sisyphus 架构的简化版主 Agent 不直接写代码而是通过读写这份计划来协调。每个 Subagent 有独立上下文但都指向同一个文件状态就不会丢。4. 验证请求跑通一次多 Subagent 协作配置就绪后进入 Claude Code 交互模式先让架构师出计划claude在对话里输入使用 architect 智能体。我要构建一个待办事项管理 API支持增删改查。 请研究最佳实践创建工作计划。架构师会读取需求、搜索方案然后写出WORK_PLAN.md。你会看到类似这样的任务分解## 任务列表 - [ ] 设计数据模型与 Prisma schema builder - [ ] 实现 POST /todos 创建接口 builder - [ ] 实现 GET /todos 列表接口 builder - [ ] 实现 PUT /todos/:id 更新接口 builder - [ ] 实现 DELETE /todos/:id 删除接口 builder - [ ] 编写集成测试 validator - [ ] 撰写 API 文档 scribe计划出来后并行启动多个构建师。Claude Code 支持在一条消息里派发多个 Subagent同时执行 1. 使用 builder 智能体实现数据模型与 Prisma 配置 2. 使用 builder 智能体实现创建与列表接口 3. 使用 builder 智能体实现更新与删除接口主对话会真正并行地拉起三个 Subagent各自在独立上下文里干活完成后把结果汇总回来。这一步是整套骨架的价值所在串行写四个接口可能要等四轮并行之后墙钟时间大幅缩短。接口写完后让验证者接手使用 validator 智能体为已实现的接口编写集成测试并运行。验证者会读代码、写测试、跑npm test把失败项记到WORK_PLAN.md的问题区。最后让记录员收尾使用 scribe 智能体为已通过测试的接口撰写 API 文档。成功的结果是WORK_PLAN.md里所有任务变成[x]问题区为空或已解决项目根多出README.md和测试目录。整个过程你只发了四条指令剩下的分工由 Subagent 自己完成。5. 本篇常见错排查Subagent 没被识别检查.claude/agents/目录名是否拼错文件名是否以.md结尾frontmatter 的---是否成对闭合。少一个---整个文件会被忽略。模型名报错frontmatter 里的model字段要写完整模型 ID比如claude-sonnet-4-20250514写sonnet这种简称在部分版本不生效。如果网关不支持某个模型会返回 404换回 sonnet 即可。权限反复弹窗说明settings.json的allow没覆盖到。把报错里提示的工具名加进allow数组注意 Bash 命令要带前缀匹配写法。并行 Subagent 互相覆盖文件这是共享状态设计的经典坑。两个 builder 同时改同一个文件会冲突。解决办法是在WORK_PLAN.md里把任务按文件边界拆开一个文件只分配给一个 builder。WORK_PLAN.md 状态不同步Subagent 有独立上下文不会自动感知别人改了计划。让每个 Subagent 在开始前先Read一次计划文件完成后立刻写回能大幅降低状态漂移。接入返回 401多半是ANTHROPIC_API_KEY没生效或密钥被禁用。到 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认密钥状态再检查环境变量是否在当前 shell 会话里。测试命令被 deny 挡住settings.json的deny优先级高于allow如果你 deny 了Bash(curl:*)而测试脚本内部调了 curl就会被拦。按需调整 deny 列表。6. 继续深入把骨架用起来跑通最小结构后下一步可以按需扩展。想让不同 Subagent 用不同模型控制成本就按config.toml里的分工来架构师用 opus 做深度思考构建师用 sonnet 平衡质量与速度记录员用 haiku 处理文档这种成本敏感任务。想验证某个模型的实际表现可以直接在模型对话里试https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite如果你打算长期用这套骨架做编码和 Agent 任务Coding Plan 比按量计费更划算适合高频调用多 Subagent 的场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入细节和参数说明都在文档里遇到配置问题先查这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后给一个实操建议别第一天就上四个 Subagent。先让 architect 和 builder 两个角色跑通一个接口确认共享文件读写正常再逐步加 validator 和 scribe。骨架的价值在于可迭代而不是一次配齐。 多智能体协作专家：用 Claude Code 复现 Oh-My-OpenCode 的 Subagent 配置骨架
1. 为什么要在 Claude Code 里复现 Oh-My-OpenCode 的 Subagent 骨架Claude Code 是 Anthropic 官方推出的命令行编程智能体它最被低估的能力不是补全代码而是 Subagent子智能体机制主对话可以派生出多个拥有独立上下文、独立模型、独立工具权限的子智能体并行处理同一项目的不同部分。Oh-My-OpenCode 之所以在社区里火是因为它把「一人抵一个开发团队」这件事做成了可配置的骨架——一个主 Agent 负责编排架构师、构建师、验证者、记录员各司其职通过共享文件交换状态。这套思路完全可以搬到 Claude Code 上。你不需要装 OpenCode也不需要额外的插件市场只要在项目里放好.claude/agents/*.md和一份共享的WORK_PLAN.md就能跑通一个最小可用的多智能体协作结构。适合谁适合已经用过 Claude Code 基础对话、想让多个角色并行干活、又不想把项目结构搞得太重的开发者。下面我会给出可直接复制的settings.json与config.toml片段再演示一次从架构设计到测试验证的完整协作流程。2. 前置准备TaoToken 接入与 Claude Code 环境Claude Code 默认走官方账号体系但很多团队希望用统一的 API 网关来管理密钥、额度和模型路由。TaoToken 提供的就是这一层一个兼容 Anthropic 接口规范的入口你可以在控制台生成 API Key然后让 Claude Code 通过环境变量指向它。这样多智能体协作时不同 Subagent 调用不同模型opus/sonnet/haiku也能在同一份额度下统一计费。先到控制台创建密钥https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite创建完成后拿到形如sk-xxxx的 Key接下来配置环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY两个变量指向 TaoToken 的 API 地址即可export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的密钥如果你用的是 Windows PowerShell写法是$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的密钥注意ANTHROPIC_BASE_URL只写到/api不要在后面拼/v1或具体路径Claude Code 会自己补全。写错会导致 404这是最常见的接入坑。验证环境是否生效直接跑一条最小请求claude -p 只回复 ok 两个字母如果返回ok说明网关链路通了。这一步没过就别急着配 Subagent否则后面报错你分不清是配置问题还是网络问题。密钥管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 可以随时轮换。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的项目级配置放在.claude/settings.jsonSubagent 定义放在.claude/agents/目录。先建目录mkdir -p my-project/.claude/agents cd my-project3.1 settings.json权限与模型路由.claude/settings.json控制主进程的权限白名单和默认模型。多智能体场景下我建议把常用工具预先放行避免每个 Subagent 启动时都弹权限确认{ permissions: { allow: [ Read, Write, Edit, Bash(git status), Bash(npm test:*), Bash(pytest:*), Grep, Glob ], deny: [ Bash(rm -rf:*), Bash(curl:*) ] }, model: claude-sonnet-4-20250514, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api } }allow里放的是各 Subagent 高频使用的工具deny里挡掉危险命令。注意Bash(npm test:*)这种带冒号的写法是前缀匹配只有以npm test开头的命令才放行。3.2 config.tomlSubagent 注册表如果你习惯 TOML 风格可以在项目根放一份config.toml作为 Subagent 的元数据索引方便团队 review 时一眼看清谁负责什么[orchestrator] name main role 编排者 model claude-sonnet-4-20250514 description 接收用户指令拆分任务调度 Subagent [[subagents]] name architect file .claude/agents/architect.md model claude-opus-4-20250514 tools [Read, WebSearch, WebFetch, Write] [[subagents]] name builder file .claude/agents/builder.md model claude-sonnet-4-20250514 tools [Read, Edit, Write, Bash, Grep, Glob] [[subagents]] name validator file .claude/agents/validator.md model claude-sonnet-4-20250514 tools [Read, Write, Edit, Bash] [[subagents]] name scribe file .claude/agents/scribe.md model claude-haiku-4-20250514 tools [Read, Write, Edit]这份 TOML 不是 Claude Code 强制读取的它的作用是让「谁用什么模型、拿什么工具」变成可审计的配置而不是散落在各个 md 文件的 frontmatter 里。真正生效的还是.claude/agents/下的文件。3.3 四个核心 Subagent 定义架构师architect.md负责需求分析和任务分解--- name: architect description: 架构设计专家。分析需求、研究方案、规划架构、分解任务到 WORK_PLAN.md model: claude-opus-4-20250514 tools: Read, WebSearch, WebFetch, Write --- 你是架构师智能体。职责 1. 分析用户需求识别核心问题与约束 2. 研究技术方案与最佳实践 3. 规划系统架构与技术栈 4. 将任务分解写入 WORK_PLAN.md每项标注负责的 agent 输出要求在 WORK_PLAN.md 中创建带复选框的任务列表完成后返回不超过 200 字的总结。构建师builder.md负责按计划写代码--- name: builder description: 代码实现专家。根据 WORK_PLAN.md 编写代码并更新任务状态 model: claude-sonnet-4-20250514 tools: Read, Edit, Write, Bash, Grep, Glob --- 你是构建师智能体。职责 1. 读取 WORK_PLAN.md 中分配给你的任务 2. 按项目现有风格编写代码 3. 完成后把 [ ] 改为 [x] 4. 遇到架构层面问题在计划中标注 architect 代码规范处理错误分支、考虑边界条件、补必要注释。完成后报告改了哪些文件。验证者validator.md负责测试--- name: validator description: 测试验证专家。编写测试、运行测试、报告问题 model: claude-sonnet-4-20250514 tools: Read, Write, Edit, Bash --- 你是验证者智能体。职责 1. 阅读已实现代码 2. 编写覆盖正常路径、边界条件、错误处理的测试 3. 运行测试套件 4. 发现问题记录到 WORK_PLAN.md 的问题区 测试通过后在计划中标记验证完成。记录员scribe.md负责文档--- name: scribe description: 文档专家。为已完成功能撰写文档、优化注释 model: claude-haiku-4-20250514 tools: Read, Write, Edit --- 你是记录员智能体。职责 1. 阅读已实现且测试通过的代码 2. 撰写 README 使用说明与 API 注释 3. 优化代码内联注释 文档要求简洁、准确、有可运行的示例。3.4 共享状态文件 WORK_PLAN.md多智能体协作的关键是共享状态。在项目根创建# 工作计划 所有 Agent 的共享状态用于任务分配与进度跟踪 ## 任务列表 _由 architect 填充_ ## 问题记录 _遇到的问题记录在这里_ ## 完成状态 _任务完成后打钩_这个文件就是 Oh-My-OpenCode 里 Sisyphus 架构的简化版主 Agent 不直接写代码而是通过读写这份计划来协调。每个 Subagent 有独立上下文但都指向同一个文件状态就不会丢。4. 验证请求跑通一次多 Subagent 协作配置就绪后进入 Claude Code 交互模式先让架构师出计划claude在对话里输入使用 architect 智能体。我要构建一个待办事项管理 API支持增删改查。 请研究最佳实践创建工作计划。架构师会读取需求、搜索方案然后写出WORK_PLAN.md。你会看到类似这样的任务分解## 任务列表 - [ ] 设计数据模型与 Prisma schema builder - [ ] 实现 POST /todos 创建接口 builder - [ ] 实现 GET /todos 列表接口 builder - [ ] 实现 PUT /todos/:id 更新接口 builder - [ ] 实现 DELETE /todos/:id 删除接口 builder - [ ] 编写集成测试 validator - [ ] 撰写 API 文档 scribe计划出来后并行启动多个构建师。Claude Code 支持在一条消息里派发多个 Subagent同时执行 1. 使用 builder 智能体实现数据模型与 Prisma 配置 2. 使用 builder 智能体实现创建与列表接口 3. 使用 builder 智能体实现更新与删除接口主对话会真正并行地拉起三个 Subagent各自在独立上下文里干活完成后把结果汇总回来。这一步是整套骨架的价值所在串行写四个接口可能要等四轮并行之后墙钟时间大幅缩短。接口写完后让验证者接手使用 validator 智能体为已实现的接口编写集成测试并运行。验证者会读代码、写测试、跑npm test把失败项记到WORK_PLAN.md的问题区。最后让记录员收尾使用 scribe 智能体为已通过测试的接口撰写 API 文档。成功的结果是WORK_PLAN.md里所有任务变成[x]问题区为空或已解决项目根多出README.md和测试目录。整个过程你只发了四条指令剩下的分工由 Subagent 自己完成。5. 本篇常见错排查Subagent 没被识别检查.claude/agents/目录名是否拼错文件名是否以.md结尾frontmatter 的---是否成对闭合。少一个---整个文件会被忽略。模型名报错frontmatter 里的model字段要写完整模型 ID比如claude-sonnet-4-20250514写sonnet这种简称在部分版本不生效。如果网关不支持某个模型会返回 404换回 sonnet 即可。权限反复弹窗说明settings.json的allow没覆盖到。把报错里提示的工具名加进allow数组注意 Bash 命令要带前缀匹配写法。并行 Subagent 互相覆盖文件这是共享状态设计的经典坑。两个 builder 同时改同一个文件会冲突。解决办法是在WORK_PLAN.md里把任务按文件边界拆开一个文件只分配给一个 builder。WORK_PLAN.md 状态不同步Subagent 有独立上下文不会自动感知别人改了计划。让每个 Subagent 在开始前先Read一次计划文件完成后立刻写回能大幅降低状态漂移。接入返回 401多半是ANTHROPIC_API_KEY没生效或密钥被禁用。到 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 确认密钥状态再检查环境变量是否在当前 shell 会话里。测试命令被 deny 挡住settings.json的deny优先级高于allow如果你 deny 了Bash(curl:*)而测试脚本内部调了 curl就会被拦。按需调整 deny 列表。6. 继续深入把骨架用起来跑通最小结构后下一步可以按需扩展。想让不同 Subagent 用不同模型控制成本就按config.toml里的分工来架构师用 opus 做深度思考构建师用 sonnet 平衡质量与速度记录员用 haiku 处理文档这种成本敏感任务。想验证某个模型的实际表现可以直接在模型对话里试https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite如果你打算长期用这套骨架做编码和 Agent 任务Coding Plan 比按量计费更划算适合高频调用多 Subagent 的场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite接入细节和参数说明都在文档里遇到配置问题先查这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后给一个实操建议别第一天就上四个 Subagent。先让 architect 和 builder 两个角色跑通一个接口确认共享文件读写正常再逐步加 validator 和 scribe。骨架的价值在于可迭代而不是一次配齐。