1. 子代理类型选错任务就会在凌晨三点崩掉Agent 子代理类型怎么选本质上是给不同阶段的任务分配不同“性格”的执行者。Explore 是只读的侦察兵Plan 是只出方案不动手的参谋general-purpose 是能自己判断该侦察还是该动手的默认执行者。这三者不是大中小三档粒度而是三种执行哲学。适合谁适合已经在用 Claude Code 或类似 Agent 工具、但发现任务经常跑偏、上下文被撑爆、或者反复在“先做什么”上打转的开发者。如果你只是让 Agent 改个函数名这篇文章你可以先收藏等任务复杂到跨模块、跨服务时再翻出来。我见过太多人把子代理当成一个--agent参数丢进去就祈祷它自己收敛。实际工程里子代理选错带来的代价非常具体Explore 被用在重构任务上它会花大量时间读文件却不动手Plan 被嵌套调用会像俄罗斯套娃一样层层生成方案最后把上下文窗口撑爆general-purpose 在大代码库里做元决策会悄悄吃掉 15% 左右的 token 在“决定下一步干什么”上。这些都不是玄学是可以在日志里逐条核对的行为差异。所以这篇内容按一条可跟做的路径来写先讲清三类子代理的边界和触发条件再给出可复制的配置片段然后通过统一 Key/API 通道接入最后逐类触发子代理并核对返回结果与调用日志。你跟着走一遍就能建立自己的选择直觉而不是靠猜。2. TaoToken 前置准备统一 Key 与 API 通道在动手配置子代理之前先把调用通道准备好。TaoToken 在这里的角色是统一入口你拿到一个 Key配好 Base URL后面无论触发 Explore、Plan 还是 general-purpose请求都走同一条通道调用日志也集中在一处方便你逐类核对。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时别把查询串抄进去。第一步打开控制台创建 API Key。控制台 deep link 是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 进去后找到 API Keys 页面新建一个 Key命名建议带上用途比如agent-subagent-test方便后面在日志里区分。Key 只显示一次复制后先放到本地环境变量里别直接写进会提交到 Git 的配置文件。第二步确认你要用的模型 ID。模型对话页面在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 这里能看到当前可用的模型列表和对应的 Model ID。子代理实验建议先用一个稳定的通用模型跑通链路再按需切换。记住三件套Base URL、API Key、Model ID后面所有配置片段都围绕这三个值展开。第三步把环境变量落下来。Linux/macOS 下可以这样写进 shell 配置export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODEL你的ModelIDWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-...这种形式注意只在当前会话生效要持久化得写进用户环境变量。这里有个容易踩的坑Base URL 末尾不要多加/v1或斜杠具体路径由客户端拼接多写一段会导致 404 而不是 401排查时容易误判成 Key 问题。第四步验证通道本身是通的。在正式配子代理前先用一次最小请求确认 Key 和 Base URL 没问题curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head -c 500返回里能看到模型列表就说明通道正常。如果这里就报 401先别往下走回到 API Keys 页面确认 Key 是否复制完整、是否被禁用。通道通了子代理的配置才有意义否则你会在子代理层反复怀疑是触发逻辑写错了实际是 Key 没生效。3. 可复制配置三类子代理的触发条件与 settings 片段这一节给的是可以直接抄的配置。核心思路是把“什么时候用哪类子代理”从口头约定变成配置里的显式声明减少 Agent 自己乱猜的空间。下面以 Claude Code 风格的 settings 为例路径按项目根目录的.claude/settings.json来写如果你的工具版本用的是别的文件名保持字段结构一致即可。先看整体结构这是一个包含三件套和子代理声明的 settings 片段{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key, ANTHROPIC_MODEL: 你的ModelID }, agents: { explore: { description: 只读侦察遍历目录、读配置、梳理依赖不修改任何文件, tools: [Read, Grep, Glob, Bash], trigger: 任务描述包含 分析/看看/梳理/依赖关系/怎么启动 等探索性动词 }, plan: { description: 只出方案生成多步骤行动方案与文件修改顺序不执行修改, tools: [Read, Grep, Glob], trigger: 任务描述包含 规划/重构方案/步骤/先后顺序 等决策性动词 }, general-purpose: { description: 默认执行自行判断探索或执行适合中等复杂度任务, tools: [Read, Write, Edit, Bash, Grep, Glob], trigger: 未显式指定子代理或任务描述为 修改/实现/修复 等执行性动词 } } }这里 Base URL 写的是https://taotoken.net/apiKey 用环境变量注入更安全实际落地时可以把ANTHROPIC_AUTH_TOKEN换成${TAOTOKEN_API_KEY}这种引用形式避免明文进仓库。Model ID 同理。三件套缺一不可只配 Base URL 不配 Key 会 401只配 Key 不配 Model 会在请求体里缺 model 字段报错信息往往指向reading choices之类的解析失败容易误导。触发条件清单单独列一下方便你贴在任务描述旁边对照子代理适用场景不该用的场景典型触发词Explore陌生代码库、遗留项目、先搞清楚“有什么”需要改代码的重构任务分析、看看、梳理、依赖关系Plan多步骤且有依赖、需要确定修改顺序单文件小改动、需要立即执行规划、方案、步骤、先后顺序general-purpose中等复杂度、已了解代码库、直接执行大规模代码库且需极致省 token修改、实现、修复、补测试配置写完后建议在任务描述里显式带上触发词而不是只依赖--agent参数。实测下来显式描述比单纯传参更稳因为部分版本的内部调度器会覆盖参数。比如你要探索一个 Spring Boot 项目的启动链路任务描述写成“分析这个项目是怎么启动的梳理各模块依赖关系”比只写--agent explore更容易稳定命中 Explore。还有一个边界要写清楚Plan 子代理里不要再声明 Plan。如果你发现需要嵌套规划说明任务粒度太粗应该拆成多次独立调用而不是让子代理递归。配置层面可以在 plan 的 tools 里去掉任何能再次派生子代理的能力从源头堵住套娃。4. 验证请求逐类触发并核对返回与调用日志配置落地后必须逐类触发一次核对返回结果和调用日志否则你无法确认触发条件真的生效。验证顺序建议 Explore → Plan → general-purpose因为前两者是只读的出错成本低。先验证 Explore。准备一个你不太熟的目录执行claude -p 分析当前项目的启动流程梳理入口文件和依赖关系只读不改 \ --agent explore预期结果是它调用 Read/Grep/Glob 遍历文件返回一段描述性结论比如入口类在哪、配置从哪加载、模块之间怎么引用。关键核对点日志里不应出现 Write 或 Edit 调用。如果出现了说明你的 explore 配置里 tools 没限制住或者触发词被 general-purpose 抢走了。调用日志在 TaoToken 控制台的请求记录里能看到对应的模型调用确认请求确实走了你配的 Base URL 和 Model ID。再验证 Plan。给一个多步骤任务claude -p 规划把 A 模块接口重构后同步修改 B 模块调用方并更新测试的步骤先出方案不要执行 \ --agent plan预期返回是一个带顺序的方案比如先改接口定义、再改调用方、最后补测试并标注涉及的文件。核对点返回里不应有实际文件修改日志里同样只有读类工具。如果它直接开始改代码说明 plan 的 tools 配多了把 Write/Edit 去掉再试。最后验证 general-purpose。给一个明确的小执行任务claude -p 把 utils 里那个拼写错误的函数名改掉并同步所有调用点 \ --agent general-purpose预期是它自己判断先 Grep 找调用点、再 Edit 修改返回修改清单。核对点日志里应同时出现读和写工具且最终git diff能看到改动。这一步同时验证了三件套是否完整生效——如果 Base URL 或 Key 有问题这里会直接报 401 或连接失败如果 Model ID 不对会报模型不存在或reading choices解析错误。三类都跑完后回到控制台看调用日志按时间顺序应该能看到三次独立请求分别对应你设置的 Model ID。如果某一次没出现说明那次触发被本地缓存或调度器拦截了需要检查任务描述是否足够明确。验证动作的价值在于它把“子代理选对了没有”从主观感觉变成可对照的日志证据。5. 常见报错排查401、local proxy failed 与 reading choices子代理实验里最常见的报错就那么几类逐个对照能省很多时间。下面按真实报错信息来拆。401 Unauthorized。最直接的原因是 Key 没生效。先确认环境变量在当前 shell 里真的存在echo $TAOTOKEN_API_KEY看有没有值再确认 settings 里引用的是同一个变量名别一个叫TAOTOKEN_API_KEY另一个叫ANTHROPIC_AUTH_TOKEN却没做映射。还有一种隐蔽情况Key 复制时带了首尾空格或换行请求头里变成非法字符服务端直接判 401。处理办法是把 Key 重新复制一遍用printf %s $KEY | wc -c核对长度是否符合预期。local proxy failed。这个报错通常出现在客户端尝试走本地代理但代理没起来的时候。先检查你的环境里有没有残留的HTTP_PROXY/HTTPS_PROXY变量指向一个不存在的本地端口有的话清掉再试。另一个常见原因是 Base URL 写成了带路径的形式导致客户端拼接出非法地址确认ANTHROPIC_BASE_URL就是https://taotoken.net/api不要带/v1后缀。如果报错里提到连接被拒绝优先怀疑本地端口占用或变量污染而不是服务端问题。reading choices 相关解析错误。这类报错一般发生在响应体结构不符合客户端预期时常见诱因是 Model ID 写错或为空导致服务端返回了错误结构而客户端仍按成功响应解析。核对ANTHROPIC_MODEL是否和模型列表里的 ID 完全一致大小写和连字符都别错。还有一种情况是请求被中间层改写返回了 HTML 错误页客户端解析 JSON 时在choices字段上报错。用第 2 节的 curl 先确认通道返回的是正常 JSON再回到子代理层排查。OAuth 相关报错。如果你用的是需要 OAuth 的客户端版本报错里出现 token 过期或 scope 不足时先确认你走的是 API Key 通道而不是 OAuth 通道两者不要混用。settings 里同时存在 OAuth 配置和 API Key 配置时客户端可能优先走 OAuth 导致鉴权失败。清理掉无关的 OAuth 字段只保留三件套再重试。子代理没被触发。日志里看不到[Sub-agent: Explore]这类标记时先看任务描述里的动词是否匹配触发词再确认--agent参数拼写正确。部分版本对参数大小写敏感Explore和explore行为可能不同统一用小写更稳。如果显式传参仍不生效改用任务描述里的触发词兜底两者叠加命中率最高。排查顺序建议固定为先 curl 验通道再看 settings 三件套最后看任务描述和参数。这个顺序能避免你在子代理逻辑里绕圈而问题其实在最外层。6. 把选择权留在自己手里接入文档与后续动作子代理配好、验证跑通之后日常使用里最重要的动作是“该打断就打断”。当你看到日志里同一个子代理反复横跳、上下文被无意义地消耗、或者 Plan 生成了明显不合理的方案比如看到注释里的DROP TABLE就规划删表重建直接中断重新指定子代理类型再跑。打断不是失败是工程化的必要手段。如果你想把这条通道固化到团队流程里接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有 Base URL、鉴权和请求格式的完整说明照着核对一遍能避免大部分拼接错误。需要长期跑编码类或 Agent 类任务时Coding Plan 页面在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合把子代理实验沉淀成稳定工作流。Key 管理仍然回到 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 给不同项目建不同 Key日志里一眼能分清是哪个任务触发的哪类子代理。最后留一个可执行的小练习挑一个你手头跨两个以上模块的改动先用 Explore 跑一遍摸清依赖再用 Plan 出步骤最后用 general-purpose 逐步执行每步之间手动确认。跑完对比一下总耗时和错误数你会对“什么时候该用哪类子代理”形成自己的判断而不是背别人的结论。