1. 从一次权限系统翻车说起为什么单个 AI 扛不住大任务先聊一个真实场景。几个月前有个需求给某平台的前后端加一套完整的权限系统。前端要做路由守卫、动态菜单渲染、按钮级别的权限控制后端要设计 RBAC 数据模型、写权限中间件、给每个接口补上鉴权逻辑。任务不小当时还没用 Subagent觉得 Claude Code 能搞定就直接上了。开始挺顺的AI 一路改我一路看。但改到后半程上下文越来越长AI 开始出问题。它「忘了」前面设计好的权限数据结构后端中间件和前端路由守卫的权限字段开始对不上。同一个接口的鉴权逻辑前面写了一版后面又另写了一遍两版行为不一样。改前端 Vue 组件时还会悄悄动后端的路由配置。到最后 commit 的时候打开 diff 看了半天——前后端改动交织在一起逻辑互相影响根本没法 review。后来我才想明白问题不是 AI 能力不够是一个 AI 扛不住这么大的任务。上下文窗口满了早期的决定被「忘掉」后面的操作开始跟前面打架。任务越大越容易翻车。Subagent 就是为这种情况设计的。说白了Subagent 就是从主 AI 拆出去的「专属助手」。每个 Subagent 有自己独立的上下文窗口、自己的系统提示、自己的工具权限甚至可以跑不同的 AI 模型。主 AI 遇到适合某个 Subagent 的任务就委派给它。Subagent 独立完成把结果返回来整个过程不会污染主会话的上下文。这个系列一直用「新员工」来比喻 AIRule 是规章制度Command 是操作手册Skill 是专项技能Hook 是安检闸机。Subagent就是你的团队成员。你是项目负责人主 Agent遇到前端任务交给前端 Subagent遇到安全审查交给安全 Subagent遇到要搜索代码交给专门探索代码库的 Subagent。每个 Subagent 专注自己的领域各干各的。很多人第一反应这不就是多开几个 Claude Code 窗口吗表面上看确实像但有几个本质区别。新开窗口时你自己要充当「中间人」——把主对话的背景信息复制过去再把结果粘贴回来任务一多来回倒腾很累Subagent 则由主 Agent 自动完成任务委派、上下文传递、结果接收整个过程不需要你手动干预。新开窗口时同时管几个窗口靠你自己记住每个窗口在做什么协调起来容易乱Subagent 可以同时派出多个并行跑结果统一汇总你只需要看主对话的最终结果。新开窗口时新会话完全空白你得手动把相关背景交代清楚Subagent 拿到的是主 Agent 打包好的「够用的信息」不会带着主对话的全部历史。用一个比喻新开对话窗口是你自己同时接两个电话两边的信息靠你自己来回传话Subagent 是你有一个团队把任务交代下去他们做完直接给你汇报。Claude Code 内置了几个常用的 Subagent会根据场景自动调用。Explore 是代码探索员用途是搜索和理解代码库模型用 Haiku速度快、成本低权限只读不能写文件。你让 AI 理解某个模块的结构或者全局搜索某个函数在哪里被调用它会把这个任务交给 Explore Subagent 去干搜索过程中产生的大量中间上下文留在 Explore 那边不会撑满你的主会话。Plan 是规划师进入 Plan 模式后收集上下文、制定方案模型继承主会话权限只读。你用 /plan 让 AI 先做规划再动手背后就是 Plan Subagent 在帮你读代码、分析依赖、整理思路。General-purpose 是全能手处理复杂的多步骤任务既要读又要改模型继承主会话权限是全部工具。需要探索加修改组合的任务比如「读懂这个模块然后帮我重构」交给 General-purpose。不是所有任务都适合拆成 Subagent。有四个判断维度重复频繁这个任务每天、每个项目都会遇到比如代码审查、文档生成、安全检查上下文重完成这个任务需要读大量文件会快速消耗主会话的上下文容量流程固定这个任务有明确的执行步骤每次做法都差不多可以并行这个任务不依赖其他任务的输出可以同时开工。满足两个以上就值得做成 Subagent。2. 把 settings 改到 TaoToken统一 Key 与 API 通道的前置准备Subagent 跑起来之后一个绕不开的问题是每个 Subagent 都要调模型Key 和 Base URL 怎么统一管理如果每个 Subagent 各自配一套改起来就是灾难。我的做法是把 Claude Code 的 settings 统一指向 TaoToken 的 API 通道所有 Subagent 共用同一套 Key 和 Base URL改一处全局生效。TaoToken 在这里扮演的角色是统一的模型调用入口。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。你需要在控制台创建一个 API Key然后把它写进 Claude Code 的 settings 文件里。先说清楚为什么要在 Subagent 场景下做这件事。Subagent 的模型字段可以指定 haiku、sonnet 等不同模型如果底层通道不统一每个模型都要单独配一套凭证维护成本很高。统一到 TaoToken 之后你只需要在 settings 里写一次 Base URL 和 KeySubagent 里写 model 字段就行模型切换、成本控制都在一个地方管。前置准备分三步。第一步拿到 API Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 Key复制出来。这个 Key 就是后面所有配置里要填的凭证。第二步确认你要用的模型 ID。TaoToken 的模型对话页面在 https://taotoken.net/models 你可以在这里看到当前可用的模型列表记下你要在 Subagent 里用的模型 ID比如 claude-sonnet 系列或者 claude-haiku 系列。第三步找到 Claude Code 的 settings 文件位置。全局配置在 ~/.claude/settings.json项目级配置在项目根目录的 .claude/settings.json。Subagent 的模型调用会走这个 settings 里的通道配置。这里有个容易踩的坑很多人以为 Subagent 的 model 字段写的是模型名实际上它最终会映射到 settings 里配置的通道。如果你 settings 里没配好 Base URLSubagent 里的 model 字段写得再对也调不通。所以顺序一定是先配 settings再配 Subagent。还有一个细节Claude Code 的 settings 支持环境变量覆盖。你可以把 Key 放在环境变量里settings 里引用变量名这样 Key 不会明文写在文件里。对于团队协作场景项目级 settings 提交 git 时环境变量方式更安全。个人使用的话直接写在 settings 里也行但要注意别把 settings 文件误提交到公开仓库。配置完成后你可以先用一次简单的模型对话验证通道是否通。打开 https://taotoken.net/models 的对话界面选一个模型发一条消息确认返回正常。这一步是排除通道问题避免后面 Subagent 调不通时你分不清是配置问题还是 Subagent 本身的问题。3. 可复制的 Subagent 配置片段与 settings 写法这一节直接给可复制的配置。先看 settings 的写法再看 Subagent 的 Markdown 文件格式最后给一个完整的协作配置示例。settings.json 的写法全局路径 ~/.claude/settings.json项目级路径 .claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的_TaoToken_API_Key }, model: claude-sonnet-4-20250514 }如果你想把 Key 放在环境变量里改成这样{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: ${TAOTOKEN_API_KEY} } }然后在 shell 的配置文件里 export TAOTOKEN_API_KEY你的Key。这样 settings 文件可以安全提交。接下来是 Subagent 文件。Subagent 是一个 Markdown 文件放在两个目录之一~/.claude/agents/ 是个人全局所有项目可用.claude/agents/ 是项目级可提交 git团队共享。文件格式用 YAML frontmatter 加正文系统提示。先给一个检索型 Subagent负责代码库探索--- name: code-explorer description: 搜索和分析代码库结构、函数调用关系、依赖关系。当用户说「梳理这个模块的调用关系」「搜索这个函数在哪里被调用」「分析代码库结构」时触发。 tools: Read, Grep, Glob model: haiku color: red --- 你是代码库探索助手。快速搜索和分析代码结构给出清晰的摘要。 工作流程 1. 先用 Glob 定位相关文件 2. 用 Grep 搜索关键符号的引用位置 3. 用 Read 读取关键文件片段 4. 输出结构化摘要文件路径、关键函数、调用关系、依赖项 不要修改任何文件。只读。再给一个编码型 Subagent负责后端接口开发--- name: backend-dev description: 后端接口开发。当用户说「写这个接口」「实现后端逻辑」「补 CRUD」时触发。 tools: Read, Write, Edit, Grep, Bash model: sonnet color: blue --- 你是后端开发工程师。负责实现接口逻辑、数据模型、中间件。 工作原则 - 先读现有代码风格保持一致 - 接口实现要包含参数校验、错误处理 - 数据模型变更要同步更新迁移文件 - 不要改前端文件 输出改动文件列表、关键逻辑说明、需要前端配合的接口契约。再给一个验证型 Subagent负责改完之后的检查--- name: verifier description: 代码验证。当用户说「验证一下」「检查改动」「跑测试」时触发。 tools: Read, Grep, Glob, Bash disallowedTools: Write, Edit model: sonnet color: green --- 你是验证工程师。负责检查代码改动是否符合预期。 检查项 1. 接口返回是否符合契约 2. 单元测试是否通过 3. 是否有明显的边界问题 4. 改动是否影响了其他模块 对每个问题给出位置、严重程度、复现步骤、修复建议。 不要修改文件只报告。最后给一个完整的协作配置示例把三个 Subagent 放在一起主 Agent 负责拆解任务。这个示例演示一个权限系统开发任务的分发--- name: permission-orchestrator description: 权限系统开发协调。当用户说「做权限系统」「加鉴权」时触发。 tools: Read, Grep, Glob, Task model: sonnet --- 你是权限系统开发的主协调 Agent。你的职责是拆解任务并分发给 Subagent。 任务拆解规则 1. 先派 code-explorer 梳理现有认证相关代码 2. 根据探索结果派 backend-dev 实现 RBAC 数据模型和权限中间件 3. 同时派 frontend-dev 实现路由守卫和按钮级权限 4. 两边完成后派 verifier 检查接口契约和权限字段一致性 注意backend-dev 和 frontend-dev 可以并行但都要等 code-explorer 的结果。 verifier 必须等两个开发 Subagent 都完成后才能启动。这里有个关键点Subagent 不能再派发 Subagent。套娃不支持。主 Agent 可以调用 Subagent但 Subagent 不能再调用另一个 Subagent。任务只能拆一层。所以上面的 orchestrator 本身是一个 Subagent它调用其他 Subagent 的能力来自 Task 工具但被它调用的 Subagent 不能再往下派。配置写完之后不需要重启 Claude Code立即生效。你可以用 /agents 命令查看当前所有 Subagent 列表确认配置被正确加载。4. 一次真实任务演示任务分发与结果回收的验证动作配置写好了跑一次真实任务看看效果。我用一个权限系统的小需求来演示给一个已有的 Express 后端加一个 /api/permission 的 CRUD 接口同时给前端加对应的调用层。第一步启动主 Agent。在 Claude Code 里输入用 permission-orchestrator 帮我做权限系统后端加 /api/permission 的 CRUD前端加对应的 API 调用层。主 Agent 收到任务后会先派 code-explorer 去梳理现有代码。你会在终端看到类似这样的输出[Task] 派发 code-explorer梳理现有认证相关代码 [code-explorer] 搜索 auth 相关文件... [code-explorer] 找到 src/middleware/auth.js, src/routes/user.js [code-explorer] 返回摘要现有认证用 JWT中间件在 src/middleware/auth.js路由在 src/routes/这一步的验证动作是检查 code-explorer 返回的摘要是否准确。你可以打开它提到的文件确认路径和内容对得上。如果摘要里提到的文件不存在说明探索出了问题需要检查 Glob 和 Grep 的配置。第二步主 Agent 根据探索结果派发开发任务。你会看到[Task] 派发 backend-dev实现 /api/permission CRUD [Task] 派发 frontend-dev实现前端 API 调用层 [backend-dev] 读取 src/routes/user.js 参考风格... [backend-dev] 创建 src/routes/permission.js [backend-dev] 创建 src/models/permission.js [frontend-dev] 创建 src/api/permission.js [backend-dev] 完成改动文件src/routes/permission.js, src/models/permission.js [frontend-dev] 完成改动文件src/api/permission.js这一步的验证动作是检查两个 Subagent 是否真的并行跑了。如果 backend-dev 先完成frontend-dev 才开始说明任务之间有依赖主 Agent 判断成了顺序执行。并行的前提是两个任务不依赖、不改同一个文件。这里后端改 src/routes/ 和 src/models/前端改 src/api/文件边界清晰可以并行。第三步主 Agent 派发验证任务[Task] 派发 verifier检查接口契约和权限字段一致性 [verifier] 读取 src/routes/permission.js 和 src/api/permission.js [verifier] 检查接口路径后端 /api/permission前端调用 /api/permission一致 [verifier] 检查字段后端返回 { id, name, actions }前端使用 id, name, actions一致 [verifier] 检查测试运行 npm test3 个测试通过 [verifier] 返回无问题这一步的验证动作是检查 verifier 的报告是否覆盖了关键点。接口路径、字段名、测试结果这三项是权限系统最容易出问题的地方。如果 verifier 报告了不一致主 Agent 会自动派发修复任务给对应的开发 Subagent。第四步检查最终结果。主 Agent 会汇总所有 Subagent 的输出给你一个最终报告任务完成。 - code-explorer梳理了现有认证代码 - backend-dev创建了 src/routes/permission.js, src/models/permission.js - frontend-dev创建了 src/api/permission.js - verifier检查通过无问题 改动文件 - src/routes/permission.js新增 - src/models/permission.js新增 - src/api/permission.js新增这时候你打开 git diff会看到改动集中在三个新文件没有交织。这就是 Subagent 的核心价值每个 Subagent 只改自己负责的文件主会话上下文不被污染diff 清晰可 review。如果你想看后台任务的状态用 /tasks 命令。如果想把某个任务推到后台跑按 CtrlB。后台任务适合文档生成、单元测试生成这类不急的任务。整个流程跑下来你会发现主 Agent 的上下文里只有任务分发和结果汇总没有中间过程的大量文件内容。这就是上下文膨胀问题的解法。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置和跑任务的过程中有几个报错很常见。这一节逐个对照真实报错给排查方法。第一个401 Unauthorized。报错长这样API Error: 401 Unauthorized - invalid api key原因通常是 Key 没配对或者 Base URL 写错了。排查步骤先确认 settings.json 里的 ANTHROPIC_API_KEY 是不是你在 https://taotoken.net/api-keys 创建的那个 Key注意不要有多余空格。再确认 ANTHROPIC_BASE_URL 是不是 https://taotoken.net/api 注意结尾不要多加斜杠。如果 Key 放在环境变量里确认 shell 里 echo $TAOTOKEN_API_KEY 能输出正确的值。还有一个容易忽略的点如果你同时配了全局 settings 和项目级 settings项目级的会覆盖全局的检查一下项目级 settings 里有没有写错的 Key。第二个local proxy failed。报错长这样Error: local proxy failed to connect这个报错通常出现在你本地有代理配置但代理没启动或者端口不对。排查步骤检查环境变量里有没有 HTTP_PROXY 或 HTTPS_PROXY如果有确认代理服务在运行。如果你不需要代理把这两个环境变量清掉再试。Claude Code 的 settings 里如果配了 proxy 相关字段也检查一下。这个报错和 Subagent 本身无关是网络层的问题先解决网络层再跑 Subagent。第三个reading choices。报错长这样Error: reading choices - unexpected response format这个报错说明 API 返回的格式和 Claude Code 预期的格式不一致。常见原因是 Base URL 指向了一个不兼容的端点。排查步骤确认 ANTHROPIC_BASE_URL 是 https://taotoken.net/api 不要指向其他路径。如果你用的是自定义的模型 ID确认这个模型 ID 在 https://taotoken.net/models 里存在。还有一个可能是模型 ID 写错了比如把 claude-sonnet 写成了 claude-sonnet-4 但实际没有这个版本检查一下 Subagent 文件里的 model 字段。第四个OAuth 相关报错。报错长这样Error: OAuth token expired or invalid这个报错通常出现在你之前用 OAuth 方式登录过 Claude Code后来改成 API Key 方式但旧的 OAuth 凭证还在。排查步骤检查 ~/.claude/ 目录下有没有 OAuth 相关的凭证文件如果有清理掉。然后确认 settings.json 里用的是 ANTHROPIC_API_KEY 而不是 OAuth 相关字段。如果你在团队环境里确认没有其他人覆盖了你的 settings。除了这四个报错还有一个 Subagent 特有的问题Subagent 不触发。你明明配了 Subagent但主 Agent 不调用它。原因通常是 description 写得太宽泛或者太窄。写「帮我做任何代码任务」这种会导致几乎所有任务都被委派过去适得其反写得太窄主 Agent 匹配不上。排查方法把 description 改成具体的触发条件比如「当用户说 XX」「当遇到 XX 情况时」。然后手动指定一次看能不能调起来。如果能手动调起来但自动不触发就是 description 的问题。还有一个问题Subagent 并行时互相覆盖文件。两个 Subagent 同时改同一个文件结果会互相覆盖。排查方法检查两个 Subagent 的 tools 字段和任务描述确认它们的文件边界不重叠。如果任务之间有依赖关系就得顺序执行不能强行并行。6. 把 Subagent 用起来从配置到日常协作配置和排障都讲完了最后聊怎么把 Subagent 用进日常。我的做法是分三步走先手动指定再自动触发最后固化流程。刚开始用的时候不要依赖 Claude 自己判断。关键操作直接说名字「用 security-reviewer 帮我检查一下 src/api/ 目录下的接口安全性」。这样你能控制什么时候用哪个 Subagent也方便观察它的行为。跑几次之后你对每个 Subagent 的能力边界有感觉了再逐步放开自动触发。自动触发适合探索、搜索这类辅助型任务。description 写清楚触发条件让 Claude 自己决定就行。比如 code-explorer 的 description 里写「当用户说梳理调用关系、搜索函数引用时触发」Claude 匹配到这类请求就会自动派发。关键流程手动指定非关键流程交给自动触发是比较稳的用法。固化流程的意思是把常用的 Subagent 组合写成一个 orchestrator。比如权限系统开发每次都是探索、后端、前端、验证这个顺序就把它写成一个 orchestrator Subagent下次直接调它。这样你不需要每次重新交代任务拆解规则主 Agent 按固定流程走。几个实用技巧。第一让 Subagent 用更便宜的模型。简单的搜索、探索任务不需要最强的模型model 字段写 haiku速度更快费用也更低。第二限制 Subagent 的权限。只读的审查 Subagent 不应该有写文件的权限用 disallowedTools 字段把 Write 和 Edit 禁掉。第三写清楚「不要做什么」。系统提示里不只要写 Subagent 该做什么也要把边界说清楚否则 AI 容易好心办坏事功能跑起来了但顺手改了一堆不该改的地方。第四个人 Subagent 和团队 Subagent 分开放。个人习惯型的放 ~/.claude/agents/团队共用的放 .claude/agents/ 并提交 git。Subagent 和 Skill 可以配合用。创建 Subagent 时可以在 frontmatter 里用 skills 字段把现成的 Skill 预加载进去Subagent 一启动就具备了那个 Skill 的能力。两者可以叠加不是非此即彼。如果你想把 Subagent 用在长期编码和 Agent 协作场景可以了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它适合需要持续跑 Subagent、多任务并行的场景。如果你只是想先验证模型通道打开 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条消息试试。配置过程中遇到接入问题接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后说一个我踩过的坑Subagent 的 description 不要写得太宽泛。我一开始给一个代码审查 Subagent 写的是「帮我做代码相关的事」结果几乎所有任务都被委派过去主 Agent 反而不干活了。后来改成具体的触发条件比如「当用户说做安全 review、检查代码安全性时触发」行为就正常了。description 是 Subagent 的入口写清楚触发条件比写功能描述重要得多。