1. 为什么你需要 Claude Code 子代理Claude Code 的子代理Sub Agents本质上是一套「角色分工」机制你不再把所有任务都丢给一个通用助手而是为前端、后端、代码审查、文档研究等场景分别定义专职代理。每个子代理拥有独立的上下文窗口、系统提示词和工具权限主对话只保留调度与结论token 消耗更可控输出也更稳定。它适合谁如果你已经在用 Claude Code 写代码但经常遇到「上下文越聊越乱」「同一个项目里前端后端风格不统一」「审查意见时有时无」这类问题子代理就是为你准备的。你可以把它理解成给 AI 配了一个小型开发团队有人专门写组件有人专门盯安全有人专门查文档。这篇指南聚焦落地配置从settings.json骨架到agents/目录下的子代理定义再到用 TaoToken 统一 Key 接入多个 AI 编程工具。全程可复制、可验证最后附一份报错排查清单。2. TaoToken 前置统一 Key 与 API 通道在配置子代理之前先把「入口」统一。TaoToken 提供统一的 API 通道官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点为 https://taotoken.net/api 。你只需要在控制台创建一个 Key就能让 Claude Code、Coding Plan 等多个工具共用同一条通道避免每个工具各配一套密钥。操作路径很直接进入控制台创建 API Key然后按文档把 Key 写入环境变量或工具配置。控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。注意Key 只放在环境变量或本地配置里不要写进会提交到 Git 的文件。子代理的settings.json里引用变量名即可。统一 Key 的好处在于子代理切换模型、切换工具时不需要重新申请凭证排查问题时也只需检查一条通道而不是在多个配置之间来回对照。3. 可复制配置settings.json 与 agents/ 骨架Claude Code 的配置分两层项目级.claude/settings.json负责权限与工具开关agents/目录负责子代理定义。先看settings.json骨架把它放在项目根目录的.claude/下{ permissions: { allow: [ Read, Grep, Glob ], deny: [ Bash(rm -rf *), Write(.env*) ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: ${TAOTOKEN_API_KEY} } }这里的关键点ANTHROPIC_BASE_URL指向 TaoToken 的 API 端点ANTHROPIC_API_KEY用环境变量占位实际值由你的 shell 注入。permissions.allow是全局默认放行的工具子代理可以在自己的定义里覆盖。接着是子代理定义。在项目根目录创建agents/文件夹每个子代理一个 Markdown 文件文件名即代理名。先写一个只读的生产代码验证器agents/production-validator.md--- name: production-validator description: 在文件创建或修改后检查生产就绪性发现占位符、TODO、硬编码密钥时阻断 tools: Read, Grep, Glob --- 你是生产代码质量检查员。发现以下问题必须明确指出文件和行号 立即阻断 - TODO / FIXME 注释 - 占位符文本如 Replace with actual... - 硬编码的 API Key、密码、令牌 - console.log / print / debug 语句 - 被注释掉的代码块 代码质量 - API 调用缺少错误处理 - 未使用的导入或变量 - 函数超过 50 行 - 缺少 TypeScript 类型 只报告问题不自动修改文件。再写一个前端专家agents/frontend-ui-expert.md授予编辑权限--- name: frontend-ui-expert description: Next.js、Tailwind、shadcn/ui 专家构建或修改 UI 组件时主动使用 tools: Read, Write, Edit, MultiEdit, Bash --- 你是前端 UI 专家。技术栈偏好 - Next.js 14 App Router不用 Pages Router - Tailwind CSS 处理所有样式 - shadcn/ui 作为基础组件 - 始终 TypeScript函数组件加 hooks 设计原则 - 移动优先响应式 - 使用 CSS 变量支持暗模式 - 可访问性不可妥协图片必须有 alt 不要做内联样式、硬编码颜色、非语义化 HTML。两个文件放好后目录结构是.claude/settings.json加agents/production-validator.md、agents/frontend-ui-expert.md。如果你用 Codex 类工具对应的config.toml片段如下同样把通道指向 TaoToken[model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY [profiles.default] model_provider taotoken model claude-sonnet-4-202505144. 验证请求让子代理真正跑起来配置写完必须验证否则你只是写了一堆 Markdown。第一步在 shell 里注入 Keyexport TAOTOKEN_API_KEY你的Key第二步启动 Claude Code 后运行/agents命令确认列表里出现production-validator和frontend-ui-expert。如果没出现检查文件是否在agents/目录、frontmatter 的name是否与文件名一致。第三步造一个带问题的测试文件test-file.jsconst API_KEY hardcoded-secret-key-123; function fetchData() { console.log(Fetching data...); // TODO: 在这里添加错误处理 fetch(/api/data) .then(response response.json()) .then(data { console.log(data); }); }第四步在 Claude Code 里发出指令「用 production-validator 检查 test-file.js」。预期结果是代理在自己的上下文里运行并逐条列出硬编码密钥、console.log、TODO 注释、缺少错误处理。如果它只回一句「有问题」说明系统提示词不够具体回到agents/production-validator.md把「必须指出文件和行号」写得更硬。第五步验证前端专家。指令「用 frontend-ui-expert 创建一个响应式用户资料卡组件包含头像、姓名、角色和联系按钮。」预期输出应包含 TypeScript 接口、移动优先类名、shadcn/ui 组件引用且没有内联样式。两次验证都通过说明统一 Key 通道和子代理调度都正常。5. 本篇常见错排查清单报错一401 Unauthorized或invalid api key。先确认TAOTOKEN_API_KEY已在当前 shell 生效用echo $TAOTOKEN_API_KEY检查是否为空。再确认settings.json里写的是${TAOTOKEN_API_KEY}而不是把 Key 直接写死。如果 Key 刚创建等几秒再试。报错二/agents列表为空。检查agents/是否在项目根目录而不是.claude/agents/。frontmatter 必须以---开头和结尾name字段不能有空格。文件扩展名必须是.md。报错三子代理不触发主对话直接回答。说明description里的触发条件不够明确。把「在文件创建或修改时自动检查」这类触发词写进description并在指令里显式点名代理例如「用 production-validator 检查」。报错四子代理能读不能写。检查该代理的tools是否包含Write、Edit。只读代理故意不给写权限这是设计而非故障。需要写操作就新建一个带写权限的代理。报错五config.toml里模型名报错。模型名要与 TaoToken 文档中列出的可用模型一致不要凭记忆填。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照更新即可。报错六上下文仍然混乱。子代理隔离的是执行上下文但主对话的调度记录仍会累积。把大任务拆成「调研—实现—审查」三段每段交给对应代理主对话只保留结论。6. 把工具串起来从单代理到编程军团单代理验证通过后真正的效率来自编排。一个可落地的工作流是研究助手查文档 → API 架构师设计接口 → 前端专家写组件 → 代码审查执行者把关 → 生产验证器做最后检查。每个环节用/agents显式点名主对话只做任务分发和结果汇总。如果你要长期跑编码任务或 Agent 工作流建议用 Coding Plan 统一管理额度与通道https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。需要快速验证模型输出时用模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。接入与排障优先看 API Keys 和文档https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 、https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。我自己的习惯是每新增一个子代理先只给只读权限跑一周确认它的输出稳定、误报可控再决定是否放开写权限。代理不是越多越好四个职责清晰的代理比十个互相重叠的代理更容易维护。