1. 从一次真实的“上下文爆炸”说起Claude Code Sub Agents 到底是什么如果你用 Claude Code 跑过稍微大一点的项目大概率遇到过这种场景让它“找一下这个项目的鉴权逻辑在哪”结果主对话里刷出几百行 grep 结果真正有用的结论被淹没在噪声里再让它“顺手改一下”上下文已经塞满模型开始胡言乱语。这不是模型不行而是你把“搜索、分析、决策”全塞进了一条对话线程里。Claude Code Sub Agents子代理就是来解决这个问题的。简单说它是一个由主对话按需派发的“专职小助手”每个子代理有自己的系统提示词、自己的工具白名单、自己的模型选择跑完任务后只把结论回传给主对话中间那堆高噪声过程留在子代理内部。你可以把它理解成公司里的“外包团队”——主对话是项目经理子代理是执行专员项目经理只要结果不要过程。它适合谁三类人最该上手一是天天用 Claude Code 写业务代码、被上下文长度折磨的开发者二是想把“代码审查”“依赖分析”“日志排查”这类重复流程固化成可复用配置的团队三是已经在用 Claude Code 但只会/agents点点点、想搞清楚底层文件格式的人。这篇就按“创建方法”这条主线从零搭一个能复用的子代理并用 TaoToken 统一 Key 把请求通道跑通最后给你一份真实报错排查清单。需要先明确一个边界子代理不是“更聪明的模型”它是“更聚焦的上下文管理工具”。它的价值在于隔离噪声、约束权限、复用配置。理解了这一点后面的 YAML 字段你才不会配得莫名其妙。2. 用 TaoToken 统一 Key 打通 Claude Code 请求通道在写子代理之前得先把 Claude Code 的请求出口理顺。很多人卡在第一步不是不会写 agent 文件而是 Key 和 Base URL 配得七零八落主对话一个 Key子代理换模型又要另一个团队里每个人环境变量还不一样。TaoToken 在这里的作用就是提供一个统一的 API 通道让主对话和所有子代理走同一个出口Key 管理、模型切换、用量查看都在一处。TaoToken 是一个面向开发者的模型 API 聚合服务官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的定位不是“替代 Claude Code”而是给 Claude Code 这类工具提供一个稳定的请求底座——你依然在终端里用 Claude Code只是它背后的模型请求通过 TaoToken 转发。配置的核心是三个环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN前者指向 TaoToken 的 API 地址后者填你在控制台生成的 Key。先登录控制台创建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite创建完 Key 后在 API Keys 页面可以随时查看和轮换https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite然后在 shell 里写入环境变量。macOS/Linux 用~/.zshrc或~/.bashrcWindows 用系统环境变量或 PowerShell 的$PROFILEexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥注意这里有个容易踩的坑ANTHROPIC_BASE_URL不要带末尾斜杠也不要自己拼/v1Claude Code 会按自己的路径规则拼接。写错了会直接 404 或 401。写完后source ~/.zshrc让配置生效用echo $ANTHROPIC_AUTH_TOKEN确认非空。如果你用的是 Claude Code 的 settings 文件方式团队协作推荐可以在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 } }这样主对话和后续所有子代理都会继承这套通道不用每个 agent 单独配。模型 ID 方面子代理的model字段填sonnet、opus、haiku这类别名即可Claude Code 会映射到对应模型如果你想指定具体版本也可以填完整模型 ID具体可用列表在模型对话页能看到https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite配好之后先别急着写子代理用一次普通对话验证通道是否通。这一步很关键因为如果主通道都不通子代理报的错会让你误以为是 agent 配置问题白白排查半天。3. 手写第一个子代理完整 agent 定义文件与可复制配置Claude Code 的子代理有三种创建方式交互式/agents向导、手写 Markdown 文件、CLI 的--agents参数临时注入。向导适合新手快速生成骨架但真正要“可复用、可版本管理”必须落到文件。子代理文件放在两个位置之一项目级.claude/agents/或用户级~/.claude/agents/。同名时项目级覆盖用户级团队共享的放项目级并提交到 Git个人通用的放用户级。文件格式是 Markdown YAML frontmatter。下面是一个可直接复制的代码审查子代理保存为.claude/agents/code-reviewer.md--- name: code-reviewer description: Review code changes for quality, security vulnerabilities, and best practices. Use proactively after code is modified or when the user asks for a code review. tools: Read, Grep, Glob, Bash model: sonnet permissionMode: plan --- 你是一个资深代码审查专家专注于安全与规范。 当被调用时按以下顺序工作 1. 先用 git diff 理解本次变更的范围不要审查未改动的文件 2. 检查安全问题注入、越权、敏感信息硬编码、不安全的反序列化 3. 检查规范问题命名、错误处理、边界条件、并发安全 4. 给出可执行的改进建议每条建议附上文件与行号 输出格式 ## 审查结果 - 安全问题[列表无则写“未发现”] - 规范问题[列表] - 改进建议[按优先级排序]几个字段的设计要点值得展开。description是整份配置里最重要的字段它决定 Claude 什么时候自动委派任务。写得模糊比如“A code reviewer”模型不知道何时调用写得具体做什么 什么时候用 加proactively才会在代码改动后主动触发。tools是白名单只列出的工具可用如果你想要“继承全部但排除少数”改用disallowedTools两者不要同时写。permissionMode: plan是系统级只读保障比在提示词里写“不要修改文件”可靠得多——即使给了 Bash也无法写入。再给一个“依赖影响分析”子代理演示skills和hooks的用法保存为.claude/agents/impact-analyzer.md--- name: impact-analyzer description: Analyze the impact scope of code changes across the full call chain. Use when a change touches shared modules or public interfaces. tools: Read, Grep, Glob, Bash model: sonnet skills: - chain-knowledge hooks: PreToolUse: - matcher: Bash hooks: - type: command command: ./scripts/validate-readonly-query.sh --- 你负责分析一次代码变更的影响范围。 工作步骤 1. 定位被修改的符号定义 2. 沿调用链向上向下各追溯两层 3. 标记受影响的公共接口与共享模块 4. 输出影响清单按风险等级排序skills字段会在子代理启动时把指定 Skill 的完整内容注入上下文子代理不会自动继承主对话的 Skill必须显式列出。hooks是子代理专属的生命周期钩子只在该子代理运行期间生效结束后自动清理——上面这个例子用 PreToolUse 拦截 Bash只放行只读查询。如果你要在 CI/CD 里临时创建、不落盘用 CLI 参数claude --agents { name: ci-linter, description: Run lint checks on changed files in CI., tools: [Read, Grep, Bash], model: haiku }这种方式创建的子代理只在当前会话存在适合流水线里的一次性任务。三种方式的选择逻辑很简单长期复用走文件临时任务走向导或 CLI。4. 验证请求跑通一次真实子代理任务并确认结果配置写完不代表能用得实际派发一次任务看结果。先确认子代理被正确加载在 Claude Code 里输入/agents列表里应该能看到code-reviewer和impact-analyzer。如果没出现八成是文件路径或 frontmatter 格式问题下一节会讲。接着制造一个真实的代码改动。随便找个 Git 仓库改一个函数并提交到工作区不用 commitgit diff --stat然后在 Claude Code 主对话里输入“我刚改了 xxx帮我审查一下这次变更。” 由于description里写了proactively after code is modifiedClaude 应该会自动委派给code-reviewer子代理而不是自己在主对话里逐行读。你会看到主对话里出现一个子代理调用标记中间过程grep、读文件折叠在子代理内部最终只回传审查结果。如果你想显式调用也可以直接点名“用 code-reviewer 子代理审查当前 diff。” 两种方式都验证一遍确认自动委派和手动调用都通。验证请求通道是否真的走了 TaoToken最直接的办法是看控制台的用量记录。跑完一次子代理任务后去用量页面刷新应该能看到对应的请求计数和 token 消耗https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果用量没动说明请求没走 TaoToken回去检查ANTHROPIC_BASE_URL是否被其他配置覆盖。Claude Code 的配置优先级是命令行参数 项目 settings 用户 settings 环境变量任何一层写错都会静默覆盖。再验证一次permissionMode: plan是否生效。故意让子代理“修改一下这个文件”它应该拒绝写入并说明处于只读模式。这一步能确认系统级权限约束真的起作用而不是靠提示词“自觉”。最后验证hooks。如果你的validate-readonly-query.sh写好了让impact-analyzer跑一条INSERT语句应该被拦截跑SELECT则通过。这一步验证的是子代理专属 Hook 的隔离性——它不会影响主对话的 Bash 行为。跑通这三层验证加载、委派、权限你的第一个子代理才算真正可用。很多人配完文件就以为完事结果上线发现权限没约束、通道没走对问题都出在跳过了验证。5. 常见报错排查清单401、local proxy failed 与 OAuth 问题子代理跑不起来报错往往不在 agent 文件本身而在请求通道或权限配置。下面按真实遇到的频率排序逐条给排查路径。401 Unauthorized / invalid api key。这是最高频的。先确认ANTHROPIC_AUTH_TOKEN非空且没有多余空格echo $ANTHROPIC_AUTH_TOKEN | wc -c看长度是否合理。然后确认 Key 没有过期或在控制台被删除。如果用的是 settings.json注意 JSON 里不能有注释、不能有尾逗号。还有一种隐蔽情况你同时设了环境变量和 settings.json两者 Key 不一致Claude Code 取了其中一个你以为用的是另一个。排查时把两处都打印出来对比。local proxy failed / connection refused。这个报错通常意味着ANTHROPIC_BASE_URL指向了一个本地不存在的服务或者地址拼错。检查是否误写成了http://localhost:xxxx或者末尾多了斜杠、多了/v1。正确写法就是https://taotoken.net/api不带任何后缀。如果你之前配过其他工具的代理设置检查 shell 里有没有残留的HTTP_PROXY、HTTPS_PROXY环境变量干扰env | grep -i proxy看一眼。Error reading choices / unexpected response format。这类报错说明请求发出去了但返回体不是 Claude Code 期望的结构。常见原因是 Base URL 指向了一个不兼容 Anthropic 消息格式的端点。确认你用的是 TaoToken 的 API 入口而不是把某个 OpenAI 兼容端点填进了ANTHROPIC_BASE_URL。两者协议不同不能混用。OAuth / authentication flow 相关报错。如果你之前用 Claude Code 的官方登录流程做过 OAuth 授权本地可能缓存了旧的凭据和现在的 Token 方式冲突。清理~/.claude/下的凭据缓存文件注意别删掉 agents 目录重新用 Token 方式登录。团队里多人共用一台机器时尤其容易出这个问题。子代理不出现 / 不被调用。先看/agents列表有没有它。没有就是文件路径或 frontmatter 问题确认文件在.claude/agents/下、扩展名是.md、frontmatter 用---包裹且name和description都存在。有但不被自动调用就是description写得太模糊补上“做什么 什么时候用 proactively”。有但调用报工具错误检查tools里列的工具名拼写以及是否和disallowedTools同时写了。权限被拒 / 子代理无法写入。如果你配了permissionMode: plan这是预期行为不是 bug。想让它能写就改成default或acceptEdits但要想清楚是否真的需要放开。安全审查类子代理保持只读是正确设计。排查顺序建议固定成先验证主对话通道普通提问能否返回→ 再验证子代理加载/agents是否可见→ 再验证委派是否被调用→ 最后验证权限工具是否按预期可用。按这个顺序走能避免在错误层级上浪费时间。6. 把子代理用起来从单次任务到可复用工作流跑通第一个子代理后真正的价值在于把它变成团队可复用的资产。项目级.claude/agents/提交到 Git新同事 clone 下来就能用同一套审查、分析流程不用每个人重新配。用户级放个人通用的小工具比如“日志摘要”“提交信息生成”。如果你要长期跑编码类、Agent 类任务单次按量调用之外可以关注 Coding Plan适合高频使用的场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入文档里有各工具的完整配置示例遇到通道问题可以先翻这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite一个实用技巧给子代理的description加上触发场景的关键词比如“when the user mentions deploy”“after tests fail”模型匹配的准确率会明显提升。另一个技巧是控制子代理数量别一上来建十个先从“审查”和“搜索”两个高频场景开始用顺了再扩展。子代理之间不能互相嵌套生成这是防止无限递归的设计规划工作流时要考虑到这一点。最后提醒一句子代理的model字段可以按任务复杂度分级简单搜索用haiku省钱复杂分析用sonnet保质量。这个分级策略配合 TaoToken 的统一通道能让你的成本和效果都可控。