1. 从一次并行搜索说起AgentTool 到底解决了什么问题你在 Claude Code 里敲下一句「帮我并行搜索三个模块的 bug」回车之后屏幕上很快出现三路并行的搜索进度。很多人以为这是主 Agent 自己排队跑了三次搜索其实不是——它派出了三个独立的子 Agent各自带着自己的工具池和权限上下文去干活最后把结果汇总回来。这个调度入口就是 AgentTool。AgentTool 是 Claude Code 里最复杂、也最值得拆解的一个工具。它接收四个核心参数prompt任务描述、subagent_type指定 Agent 类型、name昵称、run_in_background是否异步。一旦模型生成tool_use调用整条执行链路就被触发解析 effectiveType、过滤被禁用的 Agent、独立组装工具池、可选创建 worktree 隔离最后进入runAgent()走完整的 agentic loop。这里有个容易被忽略的设计点子 Agent 走的不是简化版副本而是和主 Agent 完全相同的query()主循环。它拥有独立的工具池、独立的权限上下文、独立的 system prompt是一个完整的 Agent 实例。代价是更高的内存和 CPU 开销换来的是行为一致性——子 Agent 同样具备工具执行、错误恢复、token 预算控制能力。对做 AI 应用开发的人来说理解这套机制的价值在于你可以用同样的思路设计自己的多 Agent 系统。什么时候该 fork、什么时候该用命名 Agent、递归怎么防、工具池怎么隔离Claude Code 已经把这些工程问题踩过一遍了。下面我会把三条执行路径、两道递归防线、模型解析优先级链逐一拆开并给出可复制的配置片段和端到端验证步骤。2. TaoToken 前置统一 Key 与 API 通道准备在动手配置 AgentTool 之前先把调用通道准备好。Claude Code 这类工具最终都要落到一个模型 API 端点上如果你同时用多个模型、多个项目Key 管理会很快变成一团乱麻。TaoToken 的作用就是把这些统一到一个入口一个 Key、一个 Base URL覆盖对话、编码、Agent 调用等场景。你需要先拿到两样东西API Key 和 Base URL。Key 在控制台的 API Keys 页面创建Base URL 固定为https://taotoken.net/api。注意这里不要带任何查询参数保持干净。创建 Key 的入口在控制台登录后进入 API Keys 页面新建即可。如果你还没注册可以从官网进入https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。注册完成后控制台地址是 https://taotoken.net/console API Keys 管理页在 https://taotoken.net/api-keys 。拿到 Key 之后先别急着配 Claude Code用一条最简请求验证通道是否通。这一步能帮你把「Key 问题」和「AgentTool 配置问题」分开后面排障会省很多时间。curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 16 }如果返回里能看到choices数组和正常的content说明 Key 和通道都没问题。如果返回 401先检查 Key 是否复制完整、有没有多余空格如果返回local proxy failed之类的连接错误检查 Base URL 是否写成了https://taotoken.net/api不要多加/v1之外的路径。模型 ID 这块要留意不同模型的 ID 不一样Claude 系列常见的是claude-sonnet-4-20250514、claude-opus-4-20250514这类带日期的形式。你可以在模型对话页面先试跑一下确认某个模型 ID 可用再写进配置。模型对话入口https://taotoken.net/chat 。对于长期跑编码任务和 Agent 的场景建议直接看 Coding Plan它更适合高频调用https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc 遇到参数不确定时以文档为准。3. 可复制配置AgentTool 三条路径与递归防护参数这一节给出可以直接抄的配置。Claude Code 的配置主要落在settings.json里Agent 定义则通过 frontmatter 描述。先看 settings 片段把 Base URL、Key、模型三件套写全。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-taotoken-key, CLAUDE_CODE_SUBAGENT_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [Read, Grep, Glob] } }这里CLAUDE_CODE_SUBAGENT_MODEL是子 Agent 模型的全局覆盖项它在模型解析优先级链里排第一。如果你不设它子 Agent 会走「每次调用的 model 参数 → Agent frontmatter 的 model → 继承父对话模型」这条链。想统一控制成本就把它固定成一个性价比合适的模型。接下来是 Agent 定义。命名 Agent 通过 frontmatter 声明自己的模型、权限模式和工具集。下面是一个只读探索型 Agent 的例子--- name: Explore description: 代码库搜索与探索只读 model: haiku permissionMode: acceptEdits tools: - Read - Grep - Glob isolation: worktree --- 你是一个代码库探索 Agent。只做搜索和阅读不修改任何文件。isolation: worktree这一行很关键。当主 Agent 正在重构模块 A同时派出子 Agent 重构模块 B两者可能同时改到共享文件比如index.ts的导出。开启 worktree 后子 Agent 在独立的 git 工作副本里操作互不干扰任务完成后清理。递归防护这块Claude Code 用的是两道防线代码量很小但覆盖了两类故障模式。第一道是querySource检查子进程启动时querySource被标记为agent:builtin:fork主循环每次决定是否允许 fork 时先看这个字段发现自己已经是 fork 就不再生成新 fork。它存在运行时 context 里不受 Compaction 影响所以叫「压缩安全」。第二道是消息扫描Fork 子进程启动时会在消息里注入fork-boilerplate标签主循环启动前扫描消息历史发现标签就拒绝再次 fork。为什么两道都要querySource是内存状态理论上在进程恢复、序列化/反序列化等边缘场景可能丢失消息里的标签是持久化的作为最后一道保险。这个「运行时检查 持久化标记」的双保险模式在分布式系统里叫「幂等 外部标记」用在递归防护上同样成立。Fork 路径本身还有个工程亮点Prompt Cache 共享。Anthropic 的 Prompt Cache 按请求前缀命中只要请求头部字节完全一致就能复用缓存。Fork 把所有子进程的请求构造成「前 N-1 块完全相同只有最后一块不同」——父的全量tool_use块一致占位tool_result一致只有最后的子进程指令不同。这样缓存命中率能大幅提升并行代价被压到最低。Fork 的启用条件很严格必须同时满足三个前提feature flagFORK_SUBAGENT已启用、当前不在 Coordinator 模式中、且不是非交互式会话。任一条件不满足省略subagent_type会静默降级为 General-purpose Agent。这个降级是静默的所以如果你发现子 Agent 行为不符合预期先确认 Fork 是否真的生效了。三条路径的差异可以用一张表对照维度命名 AgentFork 子进程General-purpose 回退触发条件subagent_type 有值Fork 开启且未指定类型Fork 关闭且未指定类型System PromptAgent 自身定义继承父 Agent 完整 PromptGP Agent 定义工具池独立组装父 Agent 原始工具池独立组装上下文仅任务描述父 Agent 完整对话历史仅任务描述权限模式Agent 定义bubble 上浮到父终端Agent 定义4. 验证请求端到端跑通一次子 Agent 调用配置写完之后必须做一次端到端验证确认子 Agent 真的被生成、递归防护真的生效。验证分三步走。第一步确认通道和模型可用。用上一节的 curl 命令跑一次或者直接在模型对话页面发一条消息。这一步的目的是排除 Key 和 Base URL 的问题。第二步在 Claude Code 里触发一次命名 Agent 调用。输入一个明确需要探索的任务比如「用 Explore Agent 搜索项目里所有处理鉴权的文件」。观察输出里是否出现了子 Agent 的启动信息。如果配置了isolation: worktree你还能在 git worktree 列表里看到临时创建的工作副本。git worktree list正常情况下任务执行期间会多出一个以agent-开头的 worktree任务结束后被清理。如果任务结束后 worktree 还在说明清理逻辑没走到需要检查 Agent 定义里的 isolation 配置。第三步验证递归防护。这一步稍微 tricky 一点因为正常情况下你很难触发无限递归。可以构造一个让子 Agent 再次调用 AgentTool 的任务观察它是否被拦截。如果防护生效子 Agent 会拒绝再次 fork而不是无限嵌套下去。验证成功的标志有三个子 Agent 正常返回结果、worktree 按预期创建和清理、递归调用被拦截。三个都过了说明配置链路是通的。如果你用的是 Codex 或 Cline 这类工具配置思路类似但文件位置不同。Codex 的认证信息在auth.json里Cline 的 MCP 配置在它自己的 settings 里。无论哪个工具三件套都是 Base URL、Key、Model ID缺一不可。Cline 的 MCP 配置里如果出现command和args注意不要把生产库连接串写进去MCP 直连生产库是明确要避免的。5. 本篇常见错排查401、local proxy failed 与递归失效配置过程中最容易撞上的几类报错这里逐个对照。401 Unauthorized。最常见的原因是 Key 没写对。检查三处Key 是否复制完整有些控制台会截断显示、有没有多余空格或换行、Authorization头是不是Bearer开头。如果 Key 确认没问题还是 401检查 Base URL 是否写成了https://taotoken.net/api多写或少写路径都会导致鉴权失败。local proxy failed / connection refused。这类错误通常不是 Key 的问题而是网络层或 Base URL 配置的问题。先确认ANTHROPIC_BASE_URL的值是https://taotoken.net/api不要带尾部斜杠也不要自己拼/v1/chat/completions之外的路径。如果环境里有其他代理配置检查是否冲突。reading choices 报错。这个错误说明请求发出去了但返回体里没有预期的choices字段。常见原因是模型 ID 写错了或者请求体格式不对。对照接入文档确认模型 ID检查messages数组格式是否正确。OAuth 相关报错。如果你之前用 OAuth 方式登录过环境变量和 OAuth 凭证可能冲突。清理掉旧的 OAuth 配置统一走 API Key 方式。递归防护看起来没生效。先确认 Fork 是否真的启用了。前面说过Fork 需要三个前提同时满足任一不满足会静默降级为 GP Agent。降级之后递归防护的路径也不一样。检查 feature flag 和会话模式确认你测的是 Fork 路径还是 GP 路径。子 Agent 工具越权。如果子 Agent 用到了不该用的工具检查 Agent 定义的tools列表和permissionMode。命名 Agent 的工具池是独立组装的不继承父 Agent 的限制所以必须显式声明。Explore Agent 只给 Read/Grep/Glob 三个工具不是偷懒是权限最小化的工程护栏——防止「聪明的模型想出奇怪方法绕过限制」。worktree 残留。任务结束后 worktree 没清理通常是任务异常中断导致的。手动清理用git worktree remove path然后git worktree prune。排障时如果拿不准优先看接入文档https://taotoken.net/doc 。Key 相关的问题去 API Keys 页面重新生成一个对比测试https://taotoken.net/api-keys 。6. 语义一致 CTA把统一通道用起来AgentTool 这套机制拆完你会发现它的设计哲学其实很克制三条路径各司其职命名 Agent 换专业化Fork 换 cache 效率GP 做通用兜底递归防护用双保险运行时 context 加持久化标签两道防线缺一不可工具池独立组装是权限最小化的真实落地不是过度设计。要把这些机制跑起来前提是有一个稳定的调用通道。TaoToken 把 Key 和 Base URL 统一到一个入口省掉了多模型、多项目来回切换的麻烦。你可以从这几个入口按需进入模型对话先试跑确认模型可用https://taotoken.net/chat Coding Plan适合长期编码和 Agent 高频调用https://taotoken.net/coding-plan 控制台管理项目和用量https://taotoken.net/console API Keys创建和管理 Keyhttps://taotoken.net/api-keys 接入文档参数和配置以它为准https://taotoken.net/doc如果你主要跑 Claude Code 的 Agent 场景建议先把CLAUDE_CODE_SUBAGENT_MODEL固定下来再按需给不同 Agent 配 frontmatter。配置这件事一次写对后面省心。