搞懂 Claude Code 的 Agent 编排原理：Sub-agents 与 Agent Teams 配置实战

1. 为什么单对话跑复杂任务会卡住如果你现在用 Claude Code 的方式是「开一个窗口把需求丢进去等它一步步做完」那在中小任务上完全没问题。但任务一旦变复杂——比如涉及十几个模块的重构、需要同时分析前后端代码的 bug 排查、或者要并行生成多个微服务脚手架——单对话就会撞上三堵墙。第一堵墙是 context window。即使模型支持很长的上下文一个全栈项目跑下来代码文件、工具调用结果、中间推理过程加在一起很容易撑满。更麻烦的是上下文越长模型在海量信息里提取关键信号的能力会下降早期结论容易被后面的噪声淹没。第二堵墙是串行执行。代码评审场景里安全漏洞检查、性能分析、规范审核、测试覆盖率评估这四件事几乎没有数据依赖完全可以同时做但单对话只能排队。第三堵墙是错误传播没有隔离。某个中间步骤推断错了后续所有步骤都会在错误前提上继续构建最后你要花大量时间回溯是哪一步歪了。Claude Code 从 1.x 版本开始系统性地引入了多智能体编排能力本质是用「空间换时间」——用多个并行 context 换取任务的并行执行。这篇文章拆解 Sub-agents 与 Agent Teams 的编排机制给出可复制的settings.json配置骨架和验证步骤帮你从单轮对话升级到任务自动分派。适合已经用过 Claude Code、想进一步做工作流自动化的开发者。2. 前置准备接入环境与模型入口在动手配多智能体之前先把调用链路理顺。Claude Code 的多智能体能力依赖底层模型 API 的稳定调用你需要一个能正常访问模型接口的入口。我目前用的是 TaoToken 作为模型调用入口官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。它的作用是提供统一的模型调用通道让你在 Claude Code 里配置好 base_url 和 key 之后就能直接跑不用自己折腾多套凭证。具体操作分三步。第一步去控制台创建一个 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建后复制保存后面配置要用。第二步如果你只是想先验证模型能不能正常对话可以直接在模型对话页面测试地址是 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 输入一句话看返回是否正常。第三步把 key 写进 Claude Code 的环境变量或配置文件。这里有个细节要注意多智能体场景下每个 agent 实例都会独立发起请求所以你的 key 需要能支撑并发调用。如果你打算长期跑编码任务和 Agent 工作流可以了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对长时间编码场景做了额度规划比按次调用更划算。配置环境变量的命令如下把sk-xxxx换成你自己的 keyexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-xxxx如果你用的是 Claude Code 的配置文件方式可以在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-xxxx } }配好之后先别急着上多智能体用单对话跑一个简单任务确认链路通。接入相关的完整说明可以看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。3. 三层并行架构与 Sub-agents 配置实战先建立一个整体认知框架。Claude Code 的多智能体能力分三层主对话Main Session是你直接交互的窗口Sub-agents 是由主对话按需创建的专家实例每个有独立 context window 和预设工具权限完成后把结果返回主对话通信是单向的Agent Teams 是实验性高级功能引入 Team Lead Teammates成员之间可以双向通信、共享任务列表。这三层有严格的创建权限约束主对话可以创建任意子智能体Sub-agent 不能创建新的子智能体这是刻意的安全设计Agent Teams 的 Teammate 本质是特殊的 Sub-agent同样受这个约束。理解层级关系能帮你避免设计工作流时踩到权限边界。3.1 写一个自定义 Sub-agent内置的四个预设子智能体Explore、Plan、General-purpose、Bash不够用时写一个 YAML 配置文件。放在项目根目录的.claude/agents/下会自动加载放在~/.claude/agents/可以跨项目复用。下面是一个 code-reviewer agent 的完整例子# .claude/agents/code-reviewer.yml name: code-reviewer description: | 专注于代码质量审查的专家 agent。 适合在 PR 合并前对具体文件做深度审查。 当你需要检查安全漏洞、性能问题或代码规范时code-reviewer 它。 system_prompt: | 你是一个经验丰富的 code reviewer专注于以下四个维度 1. 安全漏洞SQL 注入、XSS、SSRF、敏感信息泄露 2. 性能问题N1 查询、不必要的全表扫描、内存泄漏风险 3. 代码规范命名一致性、函数单一职责、注释完整性 4. 测试覆盖边界条件、异常路径、mock 使用是否合理 输出格式要求 - 每个问题标注严重程度[CRITICAL] [WARNING] [SUGGESTION] - 每个问题提供具体的代码行号和修改建议 - 不要泛泛而谈每条评论要有具体的代码依据 tools: - read_file - list_files - search_files - bash allowed_paths: - src/ - tests/ - *.go - *.ts - *.tsx model: claude-haiku-4-5几个关键点解释一下。system_prompt决定了这个 agent 的「人格」和专业领域写得越具体输出越稳定模糊的提示会导致模糊的结果。tools是工具白名单只给读文件权限、不给写权限是刻意的——reviewer 不应该直接改代码只能提建议防止 agent 在未经确认的情况下改动代码。allowed_paths限制可访问目录防止它读到不相关的配置文件或密钥。model做模型路由review 任务对推理深度要求不如架构设计高用轻量模型能把 token 成本降下来。3.2 三种调用方式自然语言调用在主对话里直接说「用 code-reviewer 帮我检查一下 src/auth/ 目录」Claude Code 会自动匹配并启动对应子智能体。-mention 调用用code-reviewer明确指定比自然语言更精确适合你知道具体要用哪个 agent 的场景。Session 级别配置在CLAUDE.md里声明哪些 agent 默认激活适合固定工作流## 默认 Agent 配置 对于这个项目以下 agent 默认激活 - 每次修改 src/ 下的文件后自动触发 code-reviewer - 每次新建功能模块时先跑 plan 生成任务清单再执行3.3 踩坑子智能体不能嵌套这是最容易踩的坑。Sub-agent 在执行过程中不能再创建新的子智能体也就是说你不能让code-reviewer发现问题后自动调起fix-agent来修复。这个限制是刻意设计的目的是控制 agent 行为边界防止递归创建导致资源失控。实际影响是如果你的工作流需要「发现问题 → 自动修复 → 验证修复」这种链式结构只能在主对话层面串联不能在子智能体内部实现。设计工作流时要把这个约束考虑进去。4. Agent Teams 配置骨架与验证步骤Agent Teams 解决了 Sub-agents 最大的限制成员之间不能互相通信。在 Sub-agents 模式下所有子智能体只和主对话通信彼此是信息孤岛Agent Teams 引入 Team Lead 角色Teammates 之间可以双向通信、共享任务列表。说白了Sub-agents 是星形拓扑Agent Teams 是部分网状拓扑。4.1 settings.json 配置骨架Agent Teams 目前需要手动启用在项目的.claude/settings.json里加配置{ experimental: { agentTeams: true }, env: { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1 }, team: { maxSize: 5, taskQueueSize: 30, coordinationModel: claude-opus-4-5, workerModel: claude-haiku-4-5 } }注意coordinationModel和workerModel分开配置——Team Lead 做协调和推理用强模型Teammates 执行具体任务用轻量模型。这个智能路由思路对 token 成本影响很显著实测下来能省三成左右。4.2 验证请求是否成功配好之后跑一个最小验证。启动一个 Team 任务claude # 进入交互后输入 /team 分析 src/ 目录下的代码分别从安全、性能、规范三个维度输出评审报告观察输出如果看到 Team Lead 先拆解任务、然后分配出多个 teammate 并行执行、最后汇总说明配置生效。你也可以在另一个终端观察请求日志确认有多个并发请求打到https://taotoken.net/api。如果只是想先验证模型对话链路可以在模型对话页面 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发一条消息确认返回正常再回来跑 Team 任务。4.3 三个真实使用场景场景一并行代码评审。同时启动安全审计、性能分析、代码规范三个 teammate 分析同一批代码Team Lead 汇总结论并解决冲突。相比串行评审时间压缩到三分之一不同维度分析互不干扰。场景二竞争假设调试。遇到诡异 bug 时让两个 agent 从不同假设出发各自排查——一个假设是并发问题另一个假设是数据序列化问题。两个 teammate 并行跑Team Lead 对比两条路径的发现这种「让 AI 互相打架」的方式在定位复杂 bug 时出奇有效。场景三跨层变更。做一个需要同时改动数据库 schema、后端 API、前端组件的功能时三个 teammate 分别负责各自的层Team Lead 维护变更依赖关系确保接口契约一致。4.4 踩坑/resume 不恢复进行中的成员Agent Teams 有个让人抓狂的已知问题如果 Team 任务中途中断比如关掉终端用/resume恢复 session 时已经在执行中的 teammate 不会被恢复只有 Team Lead 会重启它会以为所有子任务还没开始。后果是可能看到重复执行——之前完成一半的任务被重新分配导致文件被重复修改。规避方法启动 Agent Teams 任务前在任务描述里明确要求 Team Lead 先检查文件修改时间戳判断哪些子任务已完成。这是 workaround不是根本解决方案。当前 Agent Teams 还有这些已知限制每个 Team 的 teammates 上限是 10 个超出会静默失败任务队列在 session 结束后不持久化Teammate 之间通信有延迟不是实时的不支持动态扩容mid-task 无法新增 teammate调试信息不够完整与某些第三方 MCP 工具兼容性还有问题高并发下偶发 race condition。5. 本篇常见错排查5.1 报错agent 未找到或未加载如果你在对话里code-reviewer但提示找不到先检查文件路径。YAML 必须放在.claude/agents/下文件名和name字段要一致。另外确认 YAML 缩进正确system_prompt里的多行文本用|保留换行缩进错一格就会解析失败。5.2 报错Agent Teams 配置不生效/team命令没反应通常是settings.json的 JSON 格式有问题。用python -m json.tool .claude/settings.json验证一下语法。另外确认CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS环境变量确实被读取可以在启动 Claude Code 时用env | grep CLAUDE检查。5.3 请求 401 或鉴权失败多智能体场景下每个 agent 独立发请求如果 key 配置在单个 shell session 里子进程可能读不到。建议把ANTHROPIC_API_KEY写进~/.claude/settings.json的env字段而不是只 export 在终端。key 本身可以在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成确认。5.4 token 消耗远超预期这是最常见的「隐性错误」。token 成本不是线性的是乘法的。主对话消耗 20K启动 5 个 Sub-agents 每个 15K总消耗是 20K 5×15K 95K接近单对话的 5 倍。Agent Teams 因为成员间通信还要加协调开销。控制手段给简单 agent 设max_tokens限制用workerModel走轻量模型起步规模控制在 3-5 个 agent、每个 5-6 个任务。5.5 任务重复执行或文件被重复修改除了/resume问题还有一种情况是任务描述边界模糊Team Lead 无法判断子任务是否已完成。解决办法是在任务描述里明确产出物比如「每个 teammate 完成后把结果写入reports/维度.md」让完成状态有可检查的落点。6. 从单对话到任务自动分派的落地建议判断一个任务是否值得上多智能体用三个问题评估任务可以清晰分解吗子任务之间可以并行吗错误代价有多高如果边界模糊、任务链是线性的、或者错误代价极高单对话配合严格确认步骤反而更稳。我试过的起步方式是先用 3 个 agent 跑根据实际任务完成时间和 token 消耗决定要不要扩不要一上来就拉满。多智能体的加速效果来自任务图中存在的并行分支不是靠堆 agent 数量。如果你准备长期跑编码任务和 Agent 工作流建议先把接入链路固定下来。API Keys 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 管理接入细节看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 长期编码场景可以了解 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。先把单 agent 跑通再逐步加 teammate比一次性配一堆 agent 然后排查半天要高效得多。