1. 先搞清楚 Claude subagent 到底解决什么问题Claude Code 里的 subagent说白了就是给主对话配几个“专职外包”。你平时跟 Claude 聊需求、改代码上下文越堆越长到后面它容易忘事、串味甚至把前面聊过的接口约定搞混。subagent 的思路是把某类固定活儿拆出去交给一个独立上下文窗口里运行的子代理它有自己的系统提示、自己的工具白名单、自己指定的模型干完只把结果交回来。这带来几个实际好处。第一是上下文隔离子代理不会把主对话的历史全背进去省 token 也省注意力。第二是职责单一你可以做一个只读代码审查的 agent工具只给 Read、Grep、Glob它就没法乱改文件。第三是模型路由简单活儿丢给便宜快的模型复杂推理留给强模型成本可控。第四是配置可复用个人级 agent 放在用户目录下跨项目都能用。适合谁用如果你已经在用 Claude Code 写代码并且开始觉得“每次都要重复交代同一套审查规则”“主对话太长导致响应变慢变糊”那 subagent 就是为你准备的。它不是什么新框架本质就是一组 Markdown 配置文件放在.claude/agents/目录里Claude Code 启动时读取遇到匹配的任务描述就自动委派。我试过把代码审查和调试两个场景拆成独立 agent主对话明显清爽了很多。下面从统一 Key 接入讲起再一步步把 subagent 跑通。2. 用 TaoToken 统一 Key 接入 Claude Code 的前置准备Claude Code 默认走 Anthropic 官方端点但很多开发者手里不止一个模型来源希望用一个 Key 统一管理多模型调用。TaoToken 提供的就是这种统一接入层你拿到一个 Key配好 base URLClaude Code 就能通过它调用模型不用在多个平台之间来回切换配置。需要准备的东西不多一个 TaoToken 账号、一个 API Key、本机装好的 Claude Code。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进控制台创建 Key。创建 Key 的路径是控制台里的 API Keys 页面直接访问 https://taotoken.net/console/api-keys 就能到。点新建复制出来的那串就是你的凭证注意它只完整显示一次先存到安全的地方。这里有个概念要分清TaoToken 是统一接入层不是让你绕过什么它就是把多家模型的调用收敛到一个 Key 和一套端点上方便你在 Claude Code、Coding Plan 这些工具里复用同一份凭证。接入文档在 https://taotoken.net/doc 配置项和参数说明都在里面遇到字段不确定时优先查它。环境变量是最省事的接法。Claude Code 认ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个变量把 base URL 指向 TaoToken 的 API 地址把 token 换成你的 Key就完成了统一接入。API 地址是 https://taotoken.net/api 注意这个地址不带任何查询参数。3. settings.json 可复制配置骨架与 /agents 目录结构Claude Code 的配置分两层一层是模型接入写在 settings.json 里另一层是 subagent 定义写在 agents 目录的 Markdown 文件里。先把接入层配好。settings.json 通常放在~/.claude/settings.json用户级或项目里的.claude/settings.json项目级。下面是一份可复制的骨架把env段填上你的实际值{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的_TaoToken_API_Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [], deny: [] } }ANTHROPIC_MODEL这一项决定主对话默认用哪个模型你可以按需替换。如果不想写死在文件里也可以直接用 shell 环境变量导出效果一样export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKEN你的_TaoToken_API_Key配完接入层再来看 subagent 的目录结构。agents 有两个作用域作用域路径适用场景项目级.claude/agents/只在本项目生效随仓库走个人级~/.claude/agents/跨项目复用本机全局每个 subagent 就是一个.md文件文件名建议用英文短横线命名比如code-reviewer.md。文件头部是 YAML frontmatter定义 name、description、tools、model 四个关键字段下面是系统提示正文。结构长这样--- name: code-reviewer description: 资深代码审查专家。主动审查代码保障质量、安全与可维护性。在编写或修改代码后立即使用。 tools: Read, Grep, Glob, Bash model: inherit --- 你是一名资深代码审查员负责确保代码质量与安全达到高标准。 调用时执行 1. 执行 git diff 查看近期变更 2. 聚焦已修改的文件 3. 立即开始代码审查model字段可以填具体模型名也可以填inherit表示继承主对话的模型。tools是白名单没列出的工具这个 agent 就用不了这是做权限约束的关键。4. 创建并调用 subagent 的完整验证步骤配置就绪后用/agents命令来创建和管理。在 Claude Code 终端里输入/agents会弹出一个交互界面列出当前已有的 agent并提供创建入口。选Create new agent后第一步是选作用域❯ 1. Project (.claude/agents/) 2. Personal (~/.claude/agents/)选项目级就写进当前仓库的.claude/agents/选个人级就写进~/.claude/agents/。接着按提示填功能描述、勾选可用工具、选模型保存后一个 subagent 就建好了。它本质上就是生成了一个上面那种 Markdown 文件你随时可以到对应目录手动改。我建议先手动建一个文件来验证比走交互界面更直观。在项目根目录执行mkdir -p .claude/agents然后创建.claude/agents/code-reviewer.md内容用上一节那份骨架。保存后重启 Claude Code或者重新进入会话让它重新加载配置。验证是否被识别输入/agents看列表里有没有code-reviewer。有就说明加载成功。接下来触发调用最直接的方式是在对话里明确要求请用 code-reviewer 审查一下我刚改的代码主对话会把任务委派给这个 subagent它在独立上下文里执行git diff、读取变更文件、按清单输出反馈。你看到的返回是审查结论而不是它内部的全部推理过程这正是上下文隔离的体现。再建一个调试 agent 做对照文件.claude/agents/debugger.md--- name: debugger description: 专门处理错误、测试失败和异常行为的调试专家。遇到任何问题时主动使用。 tools: Read, Edit, Bash, Grep, Glob model: inherit --- 你是一名专注于根本原因分析的资深调试专家。 调用时执行 1. 捕获错误信息和堆栈跟踪 2. 明确问题复现步骤 3. 定位故障位置 4. 实施最简修复方案 5. 验证解决方案有效注意 debugger 的 tools 里带了Edit因为它需要改代码而 code-reviewer 故意不给Edit保证它只审不改。这种工具白名单的差异就是 subagent 做权限约束的实际用法。5. 本篇常见报错与排查报错一/agents里看不到新建的 agent。最常见原因是文件放错目录。项目级必须在项目根目录的.claude/agents/下个人级在~/.claude/agents/下路径差一层就读不到。另外 frontmatter 的---必须是文件第一行前面不能有空行或注释否则解析失败。报错二调用时报 401 或认证失败。检查ANTHROPIC_AUTH_TOKEN是不是完整复制了有没有多余空格或换行。Key 只在创建时完整显示一次如果当时没存回控制台重新生成一个。同时确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api不要多加斜杠或路径。报错三模型名不识别。ANTHROPIC_MODEL或 agent 里的model字段填了不存在的模型名。先用inherit继承主对话模型验证流程能跑通再换成具体模型名。具体可用模型以接入文档 https://taotoken.net/doc 为准。报错四subagent 不自动触发。自动委派依赖description字段的语义匹配。如果描述写得太泛主对话判断不出该不该委派。把 description 写具体比如“在编写或修改代码后立即使用”“遇到测试失败时主动使用”命中率会明显提高。实在不触发就在对话里显式点名调用。报错五agent 想用某个工具却用不了。这是 tools 白名单在起作用不是 bug。需要哪个工具就往tools里加不需要的别加保持最小权限。改完文件后重新加载会话生效。排查时有个通用顺序先确认文件路径和 frontmatter 格式再确认 Key 和 base URL最后确认模型名和 description。大部分问题出在前两步。6. 把统一 Key 和 subagent 工作流固定下来跑通之后建议把配置沉淀成习惯。接入层用 TaoToken 统一 Key主对话和各个 subagent 共用同一份凭证换项目时只改 agents 目录不用重复配 Key。需要管理或新建 Key 时走 https://taotoken.net/console/api-keys 接入细节查 https://taotoken.net/doc 。如果你主要做长期编码和 Agent 类任务可以了解下 Coding Plan把常用模型和额度规划好访问 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先在网页里验证模型对话效果用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 直接试。subagent 的价值不在功能多炫而在于把重复的、边界清晰的活儿固化下来。我的做法是每个项目至少配一个 code-reviewer工具只给读权限每次改完代码顺手让它过一遍比事后回头补审查省心得多。调试类 agent 按需加别一上来堆一堆先跑通一个再复制模式。
1. 先搞清楚 Claude subagent 到底解决什么问题Claude Code 里的 subagent说白了就是给主对话配几个“专职外包”。你平时跟 Claude 聊需求、改代码上下文越堆越长到后面它容易忘事、串味甚至把前面聊过的接口约定搞混。subagent 的思路是把某类固定活儿拆出去交给一个独立上下文窗口里运行的子代理它有自己的系统提示、自己的工具白名单、自己指定的模型干完只把结果交回来。这带来几个实际好处。第一是上下文隔离子代理不会把主对话的历史全背进去省 token 也省注意力。第二是职责单一你可以做一个只读代码审查的 agent工具只给 Read、Grep、Glob它就没法乱改文件。第三是模型路由简单活儿丢给便宜快的模型复杂推理留给强模型成本可控。第四是配置可复用个人级 agent 放在用户目录下跨项目都能用。适合谁用如果你已经在用 Claude Code 写代码并且开始觉得“每次都要重复交代同一套审查规则”“主对话太长导致响应变慢变糊”那 subagent 就是为你准备的。它不是什么新框架本质就是一组 Markdown 配置文件放在.claude/agents/目录里Claude Code 启动时读取遇到匹配的任务描述就自动委派。我试过把代码审查和调试两个场景拆成独立 agent主对话明显清爽了很多。下面从统一 Key 接入讲起再一步步把 subagent 跑通。2. 用 TaoToken 统一 Key 接入 Claude Code 的前置准备Claude Code 默认走 Anthropic 官方端点但很多开发者手里不止一个模型来源希望用一个 Key 统一管理多模型调用。TaoToken 提供的就是这种统一接入层你拿到一个 Key配好 base URLClaude Code 就能通过它调用模型不用在多个平台之间来回切换配置。需要准备的东西不多一个 TaoToken 账号、一个 API Key、本机装好的 Claude Code。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进控制台创建 Key。创建 Key 的路径是控制台里的 API Keys 页面直接访问 https://taotoken.net/console/api-keys 就能到。点新建复制出来的那串就是你的凭证注意它只完整显示一次先存到安全的地方。这里有个概念要分清TaoToken 是统一接入层不是让你绕过什么它就是把多家模型的调用收敛到一个 Key 和一套端点上方便你在 Claude Code、Coding Plan 这些工具里复用同一份凭证。接入文档在 https://taotoken.net/doc 配置项和参数说明都在里面遇到字段不确定时优先查它。环境变量是最省事的接法。Claude Code 认ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个变量把 base URL 指向 TaoToken 的 API 地址把 token 换成你的 Key就完成了统一接入。API 地址是 https://taotoken.net/api 注意这个地址不带任何查询参数。3. settings.json 可复制配置骨架与 /agents 目录结构Claude Code 的配置分两层一层是模型接入写在 settings.json 里另一层是 subagent 定义写在 agents 目录的 Markdown 文件里。先把接入层配好。settings.json 通常放在~/.claude/settings.json用户级或项目里的.claude/settings.json项目级。下面是一份可复制的骨架把env段填上你的实际值{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的_TaoToken_API_Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [], deny: [] } }ANTHROPIC_MODEL这一项决定主对话默认用哪个模型你可以按需替换。如果不想写死在文件里也可以直接用 shell 环境变量导出效果一样export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKEN你的_TaoToken_API_Key配完接入层再来看 subagent 的目录结构。agents 有两个作用域作用域路径适用场景项目级.claude/agents/只在本项目生效随仓库走个人级~/.claude/agents/跨项目复用本机全局每个 subagent 就是一个.md文件文件名建议用英文短横线命名比如code-reviewer.md。文件头部是 YAML frontmatter定义 name、description、tools、model 四个关键字段下面是系统提示正文。结构长这样--- name: code-reviewer description: 资深代码审查专家。主动审查代码保障质量、安全与可维护性。在编写或修改代码后立即使用。 tools: Read, Grep, Glob, Bash model: inherit --- 你是一名资深代码审查员负责确保代码质量与安全达到高标准。 调用时执行 1. 执行 git diff 查看近期变更 2. 聚焦已修改的文件 3. 立即开始代码审查model字段可以填具体模型名也可以填inherit表示继承主对话的模型。tools是白名单没列出的工具这个 agent 就用不了这是做权限约束的关键。4. 创建并调用 subagent 的完整验证步骤配置就绪后用/agents命令来创建和管理。在 Claude Code 终端里输入/agents会弹出一个交互界面列出当前已有的 agent并提供创建入口。选Create new agent后第一步是选作用域❯ 1. Project (.claude/agents/) 2. Personal (~/.claude/agents/)选项目级就写进当前仓库的.claude/agents/选个人级就写进~/.claude/agents/。接着按提示填功能描述、勾选可用工具、选模型保存后一个 subagent 就建好了。它本质上就是生成了一个上面那种 Markdown 文件你随时可以到对应目录手动改。我建议先手动建一个文件来验证比走交互界面更直观。在项目根目录执行mkdir -p .claude/agents然后创建.claude/agents/code-reviewer.md内容用上一节那份骨架。保存后重启 Claude Code或者重新进入会话让它重新加载配置。验证是否被识别输入/agents看列表里有没有code-reviewer。有就说明加载成功。接下来触发调用最直接的方式是在对话里明确要求请用 code-reviewer 审查一下我刚改的代码主对话会把任务委派给这个 subagent它在独立上下文里执行git diff、读取变更文件、按清单输出反馈。你看到的返回是审查结论而不是它内部的全部推理过程这正是上下文隔离的体现。再建一个调试 agent 做对照文件.claude/agents/debugger.md--- name: debugger description: 专门处理错误、测试失败和异常行为的调试专家。遇到任何问题时主动使用。 tools: Read, Edit, Bash, Grep, Glob model: inherit --- 你是一名专注于根本原因分析的资深调试专家。 调用时执行 1. 捕获错误信息和堆栈跟踪 2. 明确问题复现步骤 3. 定位故障位置 4. 实施最简修复方案 5. 验证解决方案有效注意 debugger 的 tools 里带了Edit因为它需要改代码而 code-reviewer 故意不给Edit保证它只审不改。这种工具白名单的差异就是 subagent 做权限约束的实际用法。5. 本篇常见报错与排查报错一/agents里看不到新建的 agent。最常见原因是文件放错目录。项目级必须在项目根目录的.claude/agents/下个人级在~/.claude/agents/下路径差一层就读不到。另外 frontmatter 的---必须是文件第一行前面不能有空行或注释否则解析失败。报错二调用时报 401 或认证失败。检查ANTHROPIC_AUTH_TOKEN是不是完整复制了有没有多余空格或换行。Key 只在创建时完整显示一次如果当时没存回控制台重新生成一个。同时确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api不要多加斜杠或路径。报错三模型名不识别。ANTHROPIC_MODEL或 agent 里的model字段填了不存在的模型名。先用inherit继承主对话模型验证流程能跑通再换成具体模型名。具体可用模型以接入文档 https://taotoken.net/doc 为准。报错四subagent 不自动触发。自动委派依赖description字段的语义匹配。如果描述写得太泛主对话判断不出该不该委派。把 description 写具体比如“在编写或修改代码后立即使用”“遇到测试失败时主动使用”命中率会明显提高。实在不触发就在对话里显式点名调用。报错五agent 想用某个工具却用不了。这是 tools 白名单在起作用不是 bug。需要哪个工具就往tools里加不需要的别加保持最小权限。改完文件后重新加载会话生效。排查时有个通用顺序先确认文件路径和 frontmatter 格式再确认 Key 和 base URL最后确认模型名和 description。大部分问题出在前两步。6. 把统一 Key 和 subagent 工作流固定下来跑通之后建议把配置沉淀成习惯。接入层用 TaoToken 统一 Key主对话和各个 subagent 共用同一份凭证换项目时只改 agents 目录不用重复配 Key。需要管理或新建 Key 时走 https://taotoken.net/console/api-keys 接入细节查 https://taotoken.net/doc 。如果你主要做长期编码和 Agent 类任务可以了解下 Coding Plan把常用模型和额度规划好访问 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先在网页里验证模型对话效果用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 直接试。subagent 的价值不在功能多炫而在于把重复的、边界清晰的活儿固化下来。我的做法是每个项目至少配一个 code-reviewer工具只给读权限每次改完代码顺手让它过一遍比事后回头补审查省心得多。调试类 agent 按需加别一上来堆一堆先跑通一个再复制模式。
