1. 为什么单 Agent 干到一半就卡住了如果你已经用 Claude Code 写过几个完整功能大概率遇到过这种场景一个会话里既要它读代码、又要它改文件、还要它跑测试聊到后面上下文越来越长它开始忘记前面说过的约束改着改着把不相关的文件也动了。这不是模型变笨而是单会话的注意力被稀释了。多 Agent 编排要解决的就是这件事把一个大任务拆成几条互不干扰的子任务每条交给一个独立的子代理去跑主会话只负责分发和汇总。Claude Code 从 v2.1 开始把 Subagents 做成了稳定能力配合 Git Worktree 的文件隔离你可以让 5 个子代理同时开工各自在自己的分支上写代码最后按依赖顺序合并回来。这篇聚焦的是最实用的一层——会话内 Subagents 并行。我会给出可直接复制的 settings.json 骨架含 TaoToken 统一 Key 和 API 通道配置、5 个子代理的定义方式、并行调度参数以及一次实测原本串行要 58 分钟的活并行 18 分钟跑完。适合已经用过 Claude Code、想把它从一个助手升级成一支小队的开发者。dmux 和 Agent Teams 会作为延伸方案讲清楚各自边界但主线是你能今天就跑起来的东西。2. TaoToken 前置一个 Key 打通多模型通道多 Agent 并行最容易被忽略的前置条件是模型通道。5 个子代理如果各自走不同的 API 端点、各自维护一套 Key光是配置就能耗掉半小时而且成本追踪会散成五份。TaoToken 在这里的作用是提供一个统一的 API 通道你只需要一个 Key就能在同一个 base_url 下调用不同模型。子代理定义里指定 model 字段即可不用为每个代理单独配环境变量。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 这个不加 UTM。具体要做的三件事第一在 TaoToken 控制台创建一个 API Key。地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建后复制出来形如sk-开头的一串。第二把 Key 写进 Claude Code 的环境变量。Claude Code 读取ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN两个变量前者指向 TaoToken 的 API 地址后者填你的 Key。第三验证通道可用。在正式配子代理之前先用一次最简单的对话确认 Key 和端点都对避免后面并行跑起来才发现是通道问题。模型对话入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 可以先在那里发一条测试消息。注意多 Agent 并行时所有子代理共用同一个 Key。TaoToken 的额度是按 Key 计的所以并行 5 个代理的消耗会累加在同一个账单上这反而方便你做成本追踪——不用去五个地方对账。3. 可复制配置settings.json 骨架与子代理定义3.1 settings.json 骨架Claude Code 的配置文件分两层全局的~/.claude/settings.json和项目级的.claude/settings.json。多 Agent 场景建议把模型通道放全局把子代理定义放项目级这样换项目不用重配通道。全局配置~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 0 }, permissions: { allow: [ Read, Edit, Write, Bash(git *), Bash(npm *), Bash(pytest *) ] } }这里CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS先设成 0因为本篇主线是 SubagentsTeams 是实验性功能等基础跑通再开。permissions.allow里把常用的 git、npm、pytest 命令放行否则每个子代理执行命令都要弹一次确认并行时会卡住。项目级配置.claude/settings.json{ subagents: { maxConcurrent: 5, defaultIsolation: worktree, summaryMaxChars: 300 } }maxConcurrent控制同时运行的子代理上限5 是个稳妥值——再多主会话的汇总压力会明显上升。defaultIsolation设为 worktree让每个子代理自动在独立分支上工作。summaryMaxChars限制子代理返回的摘要长度这是防止上下文污染的关键参数后面排障章节会展开。3.2 子代理定义子代理定义放在.claude/agents/目录下每个是一个 Markdown 文件头部用 YAML 声明元信息。以优惠券模块为例5 个子代理这样定义.claude/agents/db-migration.md--- name: db-migration description: 数据库迁移与模型定义 model: sonnet isolation: worktree tools: [Read, Write, Edit, Bash] --- 你负责数据库迁移。只允许编辑 migrations/versions/ 和 models/coupon.py。 参考 contracts/coupon_module.yaml 中的字段定义。 完成后输出不超过 300 字的摘要变更文件清单 需要人工确认的问题。.claude/agents/api-impl.md--- name: api-impl description: API 端点实现 model: sonnet isolation: worktree tools: [Read, Write, Edit, Bash] --- 实现 contracts/coupon_module.yaml 中定义的 3 个 API 端点。 文件范围api/coupons.py、schemas/coupon.py、services/coupon_service.py。 不要触碰 migrations/ 和 frontend/ 下的任何文件。.claude/agents/frontend.md--- name: frontend description: 前端组件实现 model: sonnet isolation: worktree tools: [Read, Write, Edit, Bash] --- 根据 contracts/coupon_module.yaml 的 API 类型定义实现组件。 文件范围frontend/src/components/coupon/、frontend/src/hooks/useCoupon.ts。.claude/agents/tests.md--- name: tests description: 测试套件编写 model: sonnet isolation: worktree tools: [Read, Write, Edit, Bash] --- 为优惠券模块编写测试。覆盖单元测试、接口测试、边界用例过期券、超额领取。 文件范围tests/test_coupon*.py、tests/factories/coupon.py。.claude/agents/security-review.md--- name: security-review description: 安全审查只读 model: opus isolation: worktree tools: [Read, Bash] --- 审查 API 实现代码重点检查并发领取绕过、校验逻辑、SQL 注入、输入校验完整性。 只读审查不修改任何代码。输出安全报告。注意 security-review 的 tools 里没有 Write 和 Edit这是刻意的——审查代理只读从工具层面杜绝它改代码的可能。model 用 opus 是因为安全审查需要更强的推理而它只跑一次成本可控。3.3 共享契约先行并行最大的坑是接口不一致。5 个代理各写各的合并时发现 API 字段名对不上。解法是在启动并行之前先写一份共享契约放在主分支上# contracts/coupon_module.yaml models: Coupon: fields: [id, code, discount_type, discount_value, min_order, max_uses, used_count, starts_at, expires_at, created_at] indexes: [[code, unique], [starts_at, expires_at]] api: endpoints: - POST /api/coupons/validate { code, order_total } - { valid, discount } - POST /api/coupons/redeem { code, order_id } - { success, coupon_id } - GET /api/coupons/available - [Coupon]所有子代理通过 Worktree 继承这份契约写代码时以它为准。这一步花 5 分钟能省掉后面半小时的合并冲突。4. 并行调度与验证18 分钟跑完 58 分钟的活4.1 一次 spawn 五个子代理配置就绪后在主会话里用一条指令派发全部子代理同时启动 5 个子代理完成优惠券模块共享契约在 contracts/coupon_module.yaml。 每个子代理的文件范围已在定义中分区不允许触碰其他代理的文件。 - db-migration数据库迁移 - api-implAPI 实现 - frontend前端组件 - tests测试套件 - security-review安全审查只读 按依赖顺序汇总结果不要批量合并。Claude Code 会读取.claude/agents/下的定义为每个子代理创建独立 Worktree 和分支然后并行启动。你可以在另一个终端用claude agents --json查看活跃代理数量确认是 5 个而不是更多。4.2 结果聚合所有子代理完成后主会话按依赖顺序合并。依赖关系是db-migration 无依赖api-impl 依赖 db-migrationfrontend 和 tests 依赖 api-implsecurity-review 只读不参与合并。# 第一批数据库迁移无依赖 git checkout agent-db-migration git rebase main git checkout main git merge agent-db-migration # 第二批API 实现依赖迁移已合并 git checkout agent-api-impl git rebase main git checkout main git merge agent-api-impl # 第三批前端 测试无互相依赖可连续合并 git merge agent-frontend git merge agent-tests关键点是每次合并一个分支后rebase 其余分支。批量合并是制造冲突的最快途径。4.3 实测数据基于本场景在 DeepSeek V4-Pro 通道下的实测阶段代理Token 消耗耗时人工修改数据库迁移db-migration18K in 3K out6 min1 处API 实现api-impl45K in 8K out14 min3 处前端组件frontend52K in 12K out18 min5 处测试套件tests38K in 15K out12 min0 处安全审查security-review28K in 6K out8 min只读编排开销主会话12K in 2K out5 min—总计—193K in 46K out并行 18 min9 处串行估算6 14 18 12 8 58 分钟。并行实际18 分钟最慢的 frontend 决定。加速比约 3.2 倍人工修改比例 3.7%9/239 处。安全审查还额外发现了 2 个并发领取的严重问题。4.4 验证请求成功合并完成后跑一次完整验证确认模块可用# 启动服务 uvicorn main:app --reload --port 8000 # 验证 API 端点 curl -X POST http://localhost:8000/api/coupons/validate \ -H Content-Type: application/json \ -d {code: WELCOME10, order_total: 100} # 预期返回 # {valid: true, discount: 10.0}如果返回{valid: true, discount: 10.0}说明 API 实现和数据库迁移都对上了。再跑测试套件pytest tests/test_coupon*.py -v全部通过就说明 5 个子代理的产出成功聚合。如果某个端点报 404多半是 api-impl 的合并顺序出了问题回到 4.2 检查。5. 本篇常见错排查5.1 子代理上下文污染与压缩级联现象5 个子代理同时返回主会话上下文瞬间填满触发压缩压缩后状态加新结果再次填满压缩级联不可恢复。根因子代理的返回摘要被完整塞进父会话。5 个代理各返回 3K 字摘要就是 15K tokens 同时涌入。修复在子代理定义里加输出限制。这就是 3.1 节summaryMaxChars: 300的作用同时在每个子代理的 prompt 末尾写明摘要不超过 300 字只报告关键发现和文件变更清单不要复述分析过程。验证并行 5 个子代理后用/context查看剩余容量保持在 20% 以上。5.2 子代理越界修改文件现象合并时发现 frontend 代理改了package.json和 api-impl 的改动冲突。根因子代理定义里虽然写了文件范围但模型有时会顺手改全局配置文件。修复在子代理定义里用tools字段限制能力同时在 prompt 里明确禁止触碰清单。对于package.json、tsconfig.json这类共享配置约定只允许一个代理修改其余只读。lockfile 类文件禁止任何代理修改合并后统一重新生成。5.3 Worktree 中缺少未跟踪文件现象子代理在 Worktree 里跑测试报Cannot find module .env.local。根因Git Worktree 是全新 checkout只包含 Git 跟踪的文件。.env.local这类在.gitignore里的文件不会出现。修复在项目根目录创建.worktreeinclude列出需要复制到每个 Worktree 的文件.env.local .env.development config/local.jsonClaude Code 创建 Worktree 时会自动复制这些文件。5.4 成本追踪盲区现象主会话/cost显示 $2.30但 TaoToken 控制台显示实际扣费 $3.45。根因后台子代理的 Token 不计入父会话/costsideQuery 和 auto-mode 分类器的消耗也不计入。修复以 TaoToken 控制台的账单为准做交叉验证。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 按日期筛选后对比/cost数值差值就是后台代理的消耗。如果差值超过 20%说明有子代理在跑你没预期的任务检查claude agents --json的输出。5.5 合并顺序错误导致冲突现象按 m 合并时 pre_merge 钩子报CONFLICT (content): Merge conflict in src/api/checkout.py。根因两个代理的分支修改了同一文件或者合并时没有按依赖顺序逐个 rebase。修复严格按 4.2 的三批顺序合并每次合并一个分支后 rebase 其余分支。如果已经冲突进入对应 Worktree 手动解决git status # 查看冲突文件 # 解决冲突后 git add . git commit -m resolve merge conflicts预防手段是把文件分区写进每个子代理的定义并在共享契约里明确接口边界。6. 延伸dmux 与 Agent Teams 的边界Subagents 解决的是会话内并行如果你需要跨工具协同比如 Claude Code 写后端、另一个工具写前端或者需要长期并行的多个会话可以看 dmux 和 Agent Teams。dmux 的思路是把 tmux 的终端复用和 Git Worktree 的文件隔离粘在一起每个代理一个窗格加一个独立分支。它支持跨模型适合需要 Claude 和其他工具协同的场景。安装是npm install -g dmux前置依赖 tmux 3.0。Windows 用户需要 WSL2因为原生 Windows 没有 tmux。Agent Teams 是 Claude Code 的实验性功能允许多个实例组成团队、共享任务列表、互相通信。但它目前有几个已知问题重复 spawn 风暴、上下文压缩后 Lead 丢失队友记录、不支持 Worktree 自动隔离。适合 3-5 人小团队在有人工监控的条件下做实验不适合无人值守。选型上大部分场景 Subagents 加 Worktree 就够了。需要跨工具用 dmux需要队友互相讨论质疑才考虑 Agent Teams。长期编码和 Agent 场景可以看 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。我自己的经验是先把 Subagents 的 5 代理流程跑顺把共享契约和文件分区养成习惯再考虑往上叠 dmux。跳过基础直接上 Teams大概率会在重复 spawn 和合并冲突里耗掉比串行更多的时间。