1. 从一次上下文爆炸说起subagent 到底解决什么问题如果你最近在用 Claude Code 写稍微大一点的项目大概率遇到过这种场景主对话里塞了几十个文件的内容、几轮调试日志、一堆 git diff然后你让它顺手做个代码审查结果它开始胡言乱语或者干脆把前面聊过的需求忘了。这不是模型变笨了而是上下文窗口被塞满了。Claude Code 里的 subagent子代理就是冲着这个痛点来的。简单说subagent 是一个拥有独立上下文窗口的专用 AI 助手它有自己的系统提示词、自己的工具权限、甚至可以指定用哪个模型。主 Agent 遇到匹配的任务时会把活儿委派给对应的 subagentsubagent 在自己的上下文里干完只把结果返回给主 Agent。主对话的上下文不会被 subagent 的中间过程污染。它适合谁三类人最该关注一是经常用 Claude Code 做多步骤任务、上下文容易爆的开发者二是想让代码审查、调试、文档生成这些固定动作标准化、可复用的团队三是想控制成本把简单任务路由到更便宜模型的人。这篇就带你从概念走到落地交付一份可复制的 settings.json 配置骨架再通过 TaoToken 统一 Key 把请求跑通最后给出 subagent 的调用验证动作。2. TaoToken 前置统一 Key 与 Claude Code 的接入准备在讲 subagent 配置之前得先把请求通道打通。Claude Code 默认走 Anthropic 官方接口但很多国内开发者在网络和计费上会遇到麻烦。TaoToken 提供的是一个统一的 API 入口你申请一个 Key就能在 Claude Code、模型对话、Coding Plan 等场景里复用不用每个工具单独配一套凭证。这一步的目标很简单拿到一个可用的 API Key并让 Claude Code 知道往哪里发请求。你不需要改 Claude Code 的源码只需要通过环境变量或配置文件把 base URL 和 Key 指过去。先到 TaoToken 控制台创建一个 API Key。地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 登录后点创建复制那串以 sk- 开头的字符串先存到安全的地方。注意别把它提交到 git 仓库里后面配置里我们会用环境变量引用。TaoToken 的 API 基地址是 https://taotoken.net/api 这个地址在配置 Claude Code 时会用到。如果你只是想先验证 Key 是否有效可以打开模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条消息试试能正常返回就说明 Key 没问题。注意API Key 等同于你的账户凭证不要贴在公开的 issue、聊天记录或代码注释里。团队协作时建议每人用自己的 Key方便审计和限额。3. 可复制配置settings.json 骨架与 subagent 定义Claude Code 的配置分两层一层是全局的 settings.json管模型、API 地址、权限这些另一层是 subagent 自己的定义文件放在.claude/agents/目录下。我们先把 settings.json 的骨架搭起来。在项目根目录创建.claude/settings.json内容如下。这里的关键是把ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址ANTHROPIC_API_KEY用环境变量注入避免硬编码。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: ${TAOTOKEN_API_KEY} }, model: claude-sonnet-4-20250514, permissions: { allow: [ Read, Glob, Grep ], deny: [] } }然后在你的 shell 配置文件里导出 Key比如~/.zshrc或~/.bashrcexport TAOTOKEN_API_KEYsk-你的实际Key改完执行source ~/.zshrc让它生效。这样 Claude Code 启动时就会读取这个环境变量请求会发往 TaoToken 的入口。接下来定义第一个 subagent。在项目里创建.claude/agents/code-reviewer.md这是项目级 subagent只对当前项目生效。文件头部是 YAML frontmatter定义名称、描述、可用工具和模型。--- name: code-reviewer description: 资深代码审查专家。在编写或修改代码后主动使用审查质量、安全性和可维护性。 tools: Read, Grep, Glob, Bash model: inherit --- 你是一名资深代码审查员负责确保代码质量与安全达到高标准。 调用时执行 1. 运行 git diff 查看近期变更 2. 聚焦已修改的文件 3. 立即开始代码审查 审查清单 - 代码清晰、可读性强 - 函数与变量命名规范合理 - 无重复代码 - 具备完善的错误处理 - 未暴露密钥、API Key 等敏感信息 - 已实现输入校验 - 测试覆盖率良好 - 已考虑性能优化 按优先级整理反馈 - 严重问题必须修复 - 警告问题建议修复 - 优化建议可考虑改进 反馈中需包含具体的修复示例。model: inherit表示继承主 Agent 的模型。如果你想省钱可以把它改成model: haiku之类的轻量模型让审查这种相对模式化的任务走更便宜的通道。tools字段是白名单只允许它读文件、搜索、跑 git 命令不允许它写文件或执行任意 shell这就是前面说的“强制约束”。再定义一个调试用的 subagent创建.claude/agents/debugger.md--- name: debugger description: 专门处理错误、测试失败和异常行为的调试专家。遇到任何问题时主动使用。 tools: Read, Edit, Bash, Grep, Glob model: inherit --- 你是一名专注于根本原因分析的资深调试专家。 调用时执行 1. 捕获错误信息和堆栈跟踪 2. 明确问题复现步骤 3. 定位故障位置 4. 实施最简修复方案 5. 验证解决方案有效 调试流程 - 分析错误信息和日志 - 检查近期代码变更 - 提出并测试假设 - 添加针对性调试日志 - 检查变量状态 针对每个问题请提供 - 根本原因说明 - 支持诊断的证据 - 具体代码修复方案 - 测试方法 - 预防建议 重点修复根本问题而非表面症状。这两个文件放好后Claude Code 启动时会自动扫描.claude/agents/目录。你也可以在终端里输入/agents命令会看到已注册的 subagent 列表还能在交互界面里创建新的。通过/agents创建出来的本质上就是上面这种 Markdown 文件你完全可以手动改。4. 验证请求跑通一个最小 subagent 调用配置写完了得验证它真的能跑。分两步先确认 API 通道通再确认 subagent 被正确委派。第一步验证 TaoToken 通道。在项目目录下启动 Claude Code随便问一句claude 你好请回复通道正常四个字如果返回了预期内容说明ANTHROPIC_BASE_URL和 Key 都生效了。如果报 401 或连接错误先回到第 5 节排查。第二步触发 subagent。故意改一行代码制造一个可审查的 diff然后在 Claude Code 里输入 帮我审查一下最近的代码改动主 Agent 识别到“审查代码”这个意图会匹配到code-reviewer的 description然后把任务委派过去。你会看到界面上出现类似“Delegating to code-reviewer”的提示subagent 在自己的上下文里跑git diff、读文件、生成反馈最后把审查结果返回。整个过程主对话的上下文只增加了最终结果中间那些文件内容不会堆进来。想更直接地验证可以用/agents命令查看当前有哪些 subagent选中code-reviewer看它的配置是否和你写的一致。如果列表里没有说明文件路径或 frontmatter 格式有问题。再测一个调试场景。写一段会抛异常的代码比如def divide(a, b): return a / b print(divide(10, 0))运行后报ZeroDivisionError然后在 Claude Code 里说“帮我调试这个报错”。主 Agent 会委派给debugger它会读文件、定位到divide函数、给出加异常处理或参数校验的修复方案。你观察返回内容里是否有“根本原因”“修复方案”这些结构化字段有就说明 subagent 的系统提示词生效了。提示subagent 之间不能直接通信只有主 Agent 能委派任务给它们。所以别指望 code-reviewer 直接喊 debugger 干活得由主 Agent 来协调。5. 本篇常见错排查配置不生效与委派失败报错一401 Unauthorized 或 invalid api key。最常见的原因是环境变量没导出成功。执行echo $TAOTOKEN_API_KEY看看有没有值。如果是空的检查 shell 配置文件是否 source 了或者 Key 复制时带了空格。另外确认 settings.json 里写的是${TAOTOKEN_API_KEY}而不是直接写 Key 字符串前者才会读环境变量。报错二subagent 列表为空/agents看不到。检查目录层级。项目级是.claude/agents/个人级是~/.claude/agents/别放错。文件名后缀必须是.md。frontmatter 必须以---开头和结尾中间不能有空行隔断。name字段不能有空格用连字符。报错三主 Agent 不委派自己把活干了。这通常是 description 写得不够明确。subagent 的匹配靠 description 的语义你要把触发场景写清楚比如“在编写或修改代码后立即使用”。如果 description 太泛主 Agent 判断不出该不该委派。可以适当加“主动使用”“遇到任何问题时”这类词。报错四subagent 执行时报工具权限不足。检查 frontmatter 里的tools字段。比如 debugger 需要Edit才能改代码如果你只给了Read它就只能看不能改。反过来如果不想让某个 subagent 碰 shell就别把Bash放进去。报错五请求超时或连接被重置。确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api末尾不要多加斜杠或路径。如果公司网络有出口限制换一个网络环境再试。Key 本身有额度限制的话到控制台看看余额。报错六改了 settings.json 但没生效。Claude Code 通常在启动时读取配置改完要重启会话。另外项目级配置会覆盖全局配置如果你在全局设了 base URL项目里又设了另一个以项目为准。6. 长期编码与 Agent 协作把 subagent 用成习惯跑通最小示例后你可以把 subagent 往团队工作流里嵌。几个实用方向给每个 subagent 配不同模型审查用便宜模型、复杂重构用强模型成本能压下来不少把常用的 subagent 定义放到~/.claude/agents/做成个人级跨项目复用团队里把.claude/agents/提交到仓库新人拉下来就有一套标准化的审查和调试流程。如果你打算长期用 Claude Code 做编码和 Agent 协作可以了解一下 Coding Plan它把模型调用和额度管理打包好了地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的配置示例遇到接入问题可以先翻这里。subagent 的核心价值就一句话让专业的活交给专业的上下文去干主对话只留结果。你把 code-reviewer 和 debugger 这两个跑顺了再照着骨架加文档生成、测试补全、依赖审计基本就覆盖日常开发的大半固定动作了。