Agent Teams / Swarms 实战：用 Claude Code Subagents 搭一套可复用的智能体协作骨架

1. 从单智能体到智能体团队为什么需要 Agent Teams如果你已经在用 Claude Code 写代码大概率经历过这样的场景一个复杂需求丢进去主 Agent 从需求分析、写前端、写后端、跑测试一路串行干下来上下文越堆越满到后面它开始忘记前面的约定改一个文件又把另一个文件改坏。这不是模型不行而是单智能体的架构天花板——一个上下文窗口、一条执行链路注定扛不住大项目。Agent Teams / Swarms智能体团队/蜂群就是为解决这个问题出现的。一句话说清楚它由 1 个协调者Lead 多个独立智能体Teammates组成每个 Teammate 是独立的 Claude 实例拥有自己的上下文窗口彼此之间可以点对点通信、共享任务列表、互相校验结果。Lead 负责拆解任务、分配角色、合并产出Teammates 并行干活。这套机制在 Claude Code 里以 Subagents 为基础演进而来从「主 Agent 派活、子 Agent 单向汇报」升级到「全通信网络 并行独立上下文 自组织协调」。它适合谁适合正在做全栈开发、大型代码库重构、多模块并行开发、安全审计这类任务的开发者。如果你只是改个 bug、写个脚本单智能体反而更省资源。这篇会带你从零搭一套可复用的智能体协作骨架包括 settings.json 与 config.toml 配置、TaoToken 统一 Key/API 通道接入以及用一次多子智能体任务验证整条协作链路。2. 前置准备TaoToken 统一 Key 与 API 通道多智能体协作最怕什么每个 Agent 各自配一套 Key、各自走一条通道结果就是额度分散、调用失败排查困难、成本不可控。所以第一步不是急着开 Teams而是先把 API 通道统一。TaoToken 在这里的作用是提供一个统一的 Key 和 API 入口让 Lead 和所有 Teammates 共用同一条通道。这样你只需要维护一份凭证所有子智能体的请求都从同一个出口走排查问题时看一处日志就够了。接入步骤很直接。先到官网注册并进入控制台在 API Keys 页面创建一个 Key官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content创建好 Key 之后API 基础地址统一用https://taotoken.net/api这个地址不加 UTM 参数直接作为 base_url 使用。接下来把它写进环境变量Claude Code 和所有子智能体都会读取这个变量export TAOTOKEN_API_KEYsk-你的Key export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY$TAOTOKEN_API_KEY注意不同版本的 Claude Code 读取的环境变量名可能略有差异有的版本认ANTHROPIC_AUTH_TOKEN。如果启动后报鉴权失败把上面两个变量名都设一遍最稳妥。这一步做完你的所有智能体就共享同一条 API 通道了。接下来才是配置 Teams 本身。3. 可复制的配置骨架settings.json 与 config.tomlClaude Code 的 Agent Teams 目前是实验特性需要显式开启。开启方式有两种建议两个都配上避免版本差异导致不生效。第一种是环境变量在启动 Claude Code 之前导出export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS1第二种是写进settings.json。这个文件通常放在项目根目录的.claude/下或者用户级的~/.claude/settings.json。下面是一份可以直接复制的骨架{ experimental: { agentTeams: true }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key }, permissions: { allow: [ Read, Write, Edit, Bash(git:*), Bash(npm:*), Bash(pytest:*) ] }, teammates: { maxConcurrent: 4, defaultRole: general, sharedTaskList: true, sharedInbox: true } }这里几个字段值得说明。maxConcurrent控制同时并行的 Teammate 数量新手建议从 3 到 4 开始太多会吃满资源且协调开销变大。sharedTaskList和sharedInbox打开后所有 Agent 共享同一份任务列表和消息邮箱这是 Teams 模式的核心。permissions.allow里按需放开命令权限否则子智能体执行 git、npm 这类操作时会被反复拦截。如果你用的是支持config.toml的编排工具比如社区里的 claude-swarm、Maestro 这类增强编排器可以再加一份 TOML 配置把角色分工写清楚[team] name fullstack-squad lead architect [team.api] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [[teammates]] name frontend role 前端开发 scope [src/web/**, src/components/**] [[teammates]] name backend role 后端开发 scope [src/api/**, src/services/**] [[teammates]] name tester role 测试与校验 scope [tests/**] [communication] shared_inbox true shared_task_list true cross_review truescope字段是防止多个 Agent 同时改同一个文件导致冲突的关键。前端只碰src/web后端只碰src/api测试只碰tests边界清晰合并时才不会打架。cross_review true打开交叉校验让 tester 去审查 frontend 和 backend 的产出。4. 验证协作链路一次多子智能体任务配置写完得跑一次真实任务验证整条链路通不通。别一上来就搞大项目先用一个小而完整的任务把协作流程走一遍。启动 Claude Code确认环境变量已生效echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS echo $ANTHROPIC_BASE_URL两个都输出正确后进入项目目录在对话里输入触发指令create an agent team to build a small todo API with testsLead 会开始拆解任务它先分析需求然后创建 Teammates分配角色。你会在终端里看到类似 tmux 分屏的效果每个 Agent 一个窗口实时输出各自的进度。Lead 的窗口显示任务拆解和调度frontend、backend、tester 的窗口各自干活。一个典型的执行过程是这样的Lead 先把任务写进共享任务列表标记为 pendingbackend 认领「实现 POST /todos 和 GET /todos」frontend 认领「写一个简单的调用页面」tester 认领「为 API 写 pytest 用例」。backend 写完接口后通过 Shared Inbox 通知 tester 可以开始测了tester 跑完发现一个边界问题直接在 Inbox 里 backend 反馈backend 修复后重新通知。整个过程不需要你手动中转。验证成功的标志有三个一是共享任务列表里所有任务从 pending 变成 done二是 tester 的测试全部通过三是 Lead 最后汇总出一份变更清单列出每个 Agent 改了哪些文件。如果这三个都满足说明你的协作骨架跑通了。跑通之后你可以把这次的任务模板固化下来下次换个需求直接复用同一套角色配置只改任务描述就行。这就是「可复用骨架」的意义。5. 本篇常见错排查实际搭这套东西最容易踩的坑集中在几个地方我按出现频率排一下。鉴权失败报 401 或 invalid api key。九成是环境变量没生效。Claude Code 启动时读取的是启动那一刻的环境变量如果你是在已经打开的终端里 export然后没重启就直接跑它读不到。解决办法是 export 之后重新开一个终端或者把变量写进settings.json的env字段里让它自己加载。另外确认 base_url 是https://taotoken.net/api不要多加斜杠或路径。Agent Teams 没生效输入 create an agent team 没反应。检查CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS是否等于1以及settings.json里experimental.agentTeams是否为true。两个都配了还不行看下 Claude Code 版本实验特性在不同版本里字段名可能变过升级到较新版本再试。多个 Agent 改同一个文件合并时冲突。这是没配scope的典型后果。回到 config.toml给每个 Teammate 明确文件范围让它们的写入区域不重叠。如果确实需要改同一个文件让 Lead 串行调度或者指定一个 Agent 负责该文件的最终合并。并行数太高机器卡死或请求被限流。maxConcurrent别贪多。4 个并行已经能覆盖大多数场景16 个 Agent 那种是极端案例对机器和额度要求都高。先从 3 开始稳定了再加。同时注意 TaoToken 通道的并发限制如果频繁 429降低并发数或错峰执行。子智能体执行命令被权限拦截卡住不动。在settings.json的permissions.allow里补上对应命令。比如它要跑cargo test你只放开了Bash(pytest:*)就会被拦。按你项目的实际工具链补全。任务列表不共享各干各的。确认sharedTaskList和sharedInbox都是true。这两个是 Teams 模式和普通 Subagents 的分水岭关掉就退化成单向汇报了。6. 把骨架用起来接入与进阶入口骨架搭好只是开始真正让它产生价值的是接到你日常的开发流里。几个建议把settings.json和config.toml提交到项目仓库的.claude/目录团队里每个人拉下来就能用同一套配置把常用任务模板写成 markdown 放在.claude/tasks/下Lead 可以直接读取定期检查共享任务列表的完成情况作为协作质量的观察指标。如果你在接入过程中遇到 API 通道或 Key 的问题直接看接入文档最省时间接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content想先单独验证模型对话是否正常不急着开 Teams可以用模型对话页面发一条测试请求确认通道通了再上多智能体模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content如果你打算长期用这套骨架跑编码任务和 Agent 协作Coding Plan 会比按量调用更划算适合高频使用的场景Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content最后说个实操细节跑通第一次之后别急着扩大规模。先把一个真实的小需求用这套骨架完整走一遍观察 Lead 的拆解是否合理、Teammate 的 scope 有没有重叠、tester 的校验有没有真正拦住问题。跑顺三五个任务之后你对这套协作节奏就有手感了那时候再往上加并发、加角色才不容易翻车。