1. 为什么多 Agent 并行开发总在互相踩脚如果你已经在用 ClaudeCode 做日常开发大概率遇到过这种场景主对话里让它重构一个模块它顺手改了package.json同时你另开一个会话让它补测试结果两个会话在同一份工作区里抢文件锁git status一片混乱。这不是模型不聪明而是默认情况下所有子任务共享同一个工作目录和同一份上下文。ClaudeCode 的 SubAgent 机制就是为解决这个问题设计的。它通过内置的AgentTool把复杂任务委派给专门的子 Agent并可选地给子 Agent 分配一个独立的 Git Worktree 作为工作目录。子 Agent 有自己独立的 QueryEngine 实例、独立的工具白名单、独立的 Turn 与 Token 预算执行完还能自动清理临时工作区。适合谁适合已经在做多 Agent 并行开发、或者想让代码审查/安全扫描这类高风险操作跑在隔离环境里的团队。这篇不空谈概念我会把settings.json里 SubAgent 相关的配置骨架拆开给出可复制的配置、QueryEngine 触发验证步骤以及 Worktree 隔离是否真正生效的确认方法。核心检索词先摆在这ClaudeCode、SubAgent、AgentTool、Worktree、QueryEngine后面每一步都会落到这几个词上。2. 前置准备TaoToken 接入与 Agent 定义目录在动 SubAgent 配置之前得先保证主 Agent 能正常跑起来。ClaudeCode 需要一个可用的模型接入端点我用的是 TaoToken 的 Anthropic 兼容接口配置方式很直接。先拿 API Key访问https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建一个 Key 并保存。然后设置环境变量让 ClaudeCode 走这个端点export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key注意ANTHROPIC_BASE_URL后面不要带 UTM 参数API 调用路径保持干净。如果你更习惯用配置文件而不是环境变量可以在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key } }接着准备 Agent 定义目录。ClaudeCode 会从.claude/agents/下按名字加载子 Agent 定义每个 Agent 一个 Markdown 文件文件名就是agent参数里要传的名字。比如建一个只读审查 Agent--- name: code-reviewer description: Read-only code review specialist model: claude-sonnet-4-20250514 tools: [Read, Grep, Bash] isolation: worktree max-turns: 15 --- You are a strict code reviewer. Read the target file, grep for related usages, and report issues. Never modify files.这里tools就是白名单isolation: worktree表示这个 Agent 默认跑在独立 Worktree 里。前置做完主 Agent 才有能力去调用AgentTool。3. settings.json 中 SubAgent 配置骨架SubAgent 的行为由三层配置叠加决定全局settings.json、Agent 定义文件.claude/agents/*.md、以及调用时AgentTool传入的参数。优先级是调用参数 Agent 定义 全局默认。下面是一份可以直接抄的settings.json骨架{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key }, subAgents: { enabled: true, defaultIsolation: worktree, defaultMaxTurns: 10, defaultBudget: { maxTokens: 50000 }, worktree: { root: .claude/worktrees, autoCleanup: true, symlinkNodeModules: true }, agentsDir: .claude/agents } }逐项说明关键字段。defaultIsolation设为worktree后所有没在 Agent 定义里显式声明isolation的子 Agent 都会拿到独立工作目录autoCleanup: true对应源码里「未修改则清理」的逻辑子 Agent 如果没动文件Worktree 会被自动删除不会在你仓库里堆一堆临时分支。symlinkNodeModules很实用它会在新建的 Worktree 里软链主仓库的node_modules省掉每个子 Agent 重新装依赖的时间。defaultBudget.maxTokens是硬上限子 Agent 的 QueryEngine 在每轮循环里都会检查 token 用量超了就强制终止并记录tengu_agent_budget_exceeded事件。defaultMaxTurns同理对应tengu_agent_max_turns_reached。这两个限制是防止子 Agent 无限跑下去的关键别设太大。Agent 定义文件里的字段和全局配置是覆盖关系。比如某个 Agent 想用不同模型就在 frontmatter 里写model想放开工具就写tools: [*]但生产环境不建议白名单越窄越安全。4. QueryEngine 触发验证确认子 Agent 真的被调度配置写完不代表生效得验证AgentTool的调用链真的走通了。ClaudeCode 的触发决策由模型自主判断不是硬编码规则所以我们要构造一个「必然触发」的任务描述。启动 ClaudeCode 后输入这样的指令Use the Agent tool to delegate a security review of src/auth.ts to the code-reviewer agent with worktree isolation.模型看到AgentTool的描述后会推理是否调用。为了确认它真的调了开一个终端实时看日志tail -f ~/.claude/logs/*.log | grep -E tengu_agent|worktree如果触发成功你会看到类似这样的输出tengu_agent_created agent_id8f3a... parent_agent_idmain tengu_worktree_created path.claude/worktrees/agent-code-reviewer-1712... tengu_agent_max_turns_reached agent_id8f3a... turns15 tengu_worktree_cleaned_up agent_id8f3a...这几行日志分别对应创建阶段、Worktree 创建、Turn 限制触发、清理阶段。agent_id和parent_agent_id成对出现说明审计链是通的。如果只看到tengu_agent_created但没有tengu_worktree_created说明isolation没生效回去检查 Agent 定义的 frontmatter 和settings.json的defaultIsolation。想更直观地确认 Worktree 隔离可以在子 Agent 执行期间另开终端跑git worktree list正常会看到主工作区加一个.claude/worktrees/agent-code-reviewer-xxxx的条目分支名类似agent/code-reviewer-xxxx。子 Agent 结束后如果它没改文件这个条目会自动消失如果改了文件Worktree 会被保留日志里出现tengu_worktree_preserved你可以手动进去看改动。5. 本篇常见错排查报错一Tool Write not in allowed-tools这是子 Agent 尝试调用白名单外的工具被权限检查器拦下了。源码里createSubAgentPermissionChecker会做二次验证即使主 Agent 有 Write 权限子 Agent 也不继承。解决方式是回到 Agent 定义的tools字段把需要的工具加进去或者确认这个操作本来就不该由子 Agent 做。报错二Worktree 创建失败validateWorktreeSlug报错Worktree 的 slug 有字符校验Agent 名字里带空格、大写或特殊符号会失败。把 Agent 文件名改成小写加连字符比如code-reviewer而不是Code Reviewer。报错三子 Agent 拿不到上下文回答驴唇不对马嘴这是预期行为不是 bug。子 Agent 的 QueryEngine 用initialMessages: []初始化空历史、独立文件缓存它看不到主对话的任何内容。所有必要信息必须通过description参数显式传进去。比如别只说「审查这个文件」要说「审查 src/auth.ts 的登录逻辑」。报错四tengu_agent_budget_exceeded频繁出现子 Agent 的 token 预算太小或者任务描述太宽泛导致它反复读文件。把defaultBudget.maxTokens调大同时把任务拆细。一个子 Agent 只干一件事比让它「审查整个项目」靠谱得多。报错五嵌套 Agent 不触发Skill 或子 Agent 想再创建孙子 Agent前提是它的allowed-tools里包含Agent。如果白名单里只有[Read, Grep, Bash]那它永远调不出AgentTool。检查对应 SKILL.md 或 Agent 定义的allowed-tools字段。6. 把隔离跑顺之后SubAgent 这套机制的价值不在「多开几个 Agent」本身而在于隔离边界清晰上下文隔离保证子任务不被主对话污染工具白名单保证高风险操作拿不到写权限Worktree 隔离保证并行任务不抢文件。我实测下来把代码审查和安全扫描都丢给带 Worktree 的子 Agent 之后主对话的git status终于干净了。如果你要长期跑多 Agent 并行开发建议直接上 Coding Plan把 Turn 和 Token 预算按团队规模配好避免单个子 Agent 吃掉整天的额度https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite。想先在对话里验证模型对AgentTool的调度判断可以用模型对话页快速试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite。接入细节和参数说明都在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite。最后留一个实用技巧调试阶段把autoCleanup临时设为false这样每个子 Agent 的 Worktree 都会保留你可以逐个进去 diff确认隔离和改动范围都符合预期再改回true让生产环境自动清理。
