Claude Code 子代理怎么用？Subagents 配置教程与实用示例（2026）
Claude Code 子代理怎么用？这篇 Claude Code Subagents 教程讲清子代理是什么、有哪些内置子代理，演示 .claude/agents 子代理文件的写法和 frontmatter 字段，说明自动委派与手动调用、前台与后台运行、模型选择和 Token 成本，并附代码审查、测试运行等可直接复制的子代理示例。
SupaStore 开发者体验组 ·
Claude Code 子代理（Subagents）是 Claude 可以把任务委派出去的"专职助手"：每个子代理有独立的上下文窗口、专门的系统提示词和受限的工具权限。把搜代码、跑测试、做代码审查这类会产生大量输出的工作交给子代理，主对话只拿回一份总结，上下文更干净，Token 也更省。
本文讲清 Claude Code 子代理是什么、内置了哪些子代理，演示如何编写自定义子代理文件，并说明调用方式、模型选择和成本控制。还不熟悉 Claude Code 的话，先看《Claude Code 教程：2026 Claude Code 安装与使用指南》。
Claude Code 子代理是什么
官方文档的说法是：每个子代理在自己的上下文窗口中运行，拥有自定义的系统提示词、特定的工具权限和独立的权限设置。使用子代理的好处：
- 保持主对话干净：探索代码、跑测试产生的大量输出留在子代理里；
- 限制权限：比如代码审查子代理只给读权限，不能改文件；
- 复用配置：用户级子代理可以在所有项目中使用；
- 专业分工：用专门的系统提示词处理特定领域的任务；
- 控制成本：把简单任务交给 Haiku 这类更快、更便宜的模型。
子代理和 Skills 有什么区别
Skills 是在当前对话里加载一套流程说明；子代理则是开一个独立的上下文去完成任务，再把结果交回来。需要隔离大量中间输出、或者需要不同权限和模型时，用子代理更合适。
Claude Code 内置子代理
| 子代理 | 用途 | 权限 |
|---|---|---|
| Explore | 快速搜索和分析代码库，可选 quick、medium、very thorough 三档深度 | 只读，不能编辑文件 |
| Plan | 计划模式下收集上下文，为方案做调研 | 只读 |
| general-purpose | 需要同时探索和动手的复杂多步任务 | 可使用全部工具 |
日常使用中，Claude 会自动调用这些内置子代理，例如在大项目里找某个函数的所有调用位置时，常常会先派出 Explore。
自定义 Claude Code 子代理
子代理文件放在哪里
| 位置 | 生效范围 | 优先级 |
|---|---|---|
| 组织托管设置 | 整个组织 | 最高 |
--agents 启动参数 |
当前会话 | 2 |
.claude/agents/ |
当前项目，可提交到 Git 共享 | 3 |
~/.claude/agents/ |
你的所有项目 | 4 |
插件的 agents/ 目录 |
启用插件的项目 | 最低 |
同名子代理按优先级取高的那个。Claude Code 会监听 .claude/agents/ 和 ~/.claude/agents/，修改文件后几秒内生效。
子代理文件格式
子代理是一个 Markdown 文件：开头用 YAML frontmatter 写配置，正文就是它的系统提示词。官方示例：
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
常用 frontmatter 字段
只有 name 和 description 是必填的。
| 字段 | 作用 |
|---|---|
name |
子代理的唯一标识 |
description |
什么时候应该委派给它，Claude 据此自动判断 |
tools |
允许使用的工具，不写则继承全部可用工具 |
disallowedTools |
禁止使用的工具 |
model |
sonnet、opus、haiku、fable、完整模型 ID 或 inherit（沿用主对话模型） |
effort |
思考强度：low ～ max |
permissionMode |
权限模式，如 default、acceptEdits、plan |
maxTurns |
最多执行多少轮 |
skills |
启动时预加载的 Skills |
mcpServers |
这个子代理可用的 MCP 服务器 |
isolation |
设为 worktree 时在临时 Git 工作树中运行 |
background |
设为 true 时始终在后台运行 |
字段名区分大小写，写错的字段会被静默忽略，不会报错。
3 个实用 Claude Code 子代理示例
示例一：只读的代码审查员
.claude/agents/code-reviewer.md：
---
name: code-reviewer
description: 代码改动完成后主动使用。审查最近的改动，检查正确性、安全和可维护性。
tools: Read, Grep, Glob, Bash
model: sonnet
---
你是一名资深代码审查员。被调用时：
1. 运行 git diff 查看最近的改动
2. 只审查改动涉及的代码
3. 按"必须修复 / 建议修改 / 可以考虑"三级列出问题，每条附文件和行号
4. 不要直接修改代码
description 里写"主动使用"（use proactively 这类措辞），Claude 会更积极地自动委派。
示例二：用便宜模型跑测试
.claude/agents/test-runner.md：
---
name: test-runner
description: 运行测试并汇总失败原因。需要跑测试或检查测试是否通过时使用。
tools: Bash, Read, Grep
model: haiku
---
运行项目的测试命令，只汇报：
- 通过 / 失败的数量
- 每个失败用例的名称、报错信息和最可能的原因
- 不要贴完整日志，不要修改代码
测试日志往往有几千行，交给 Haiku 子代理处理，主对话只收到几行总结，既省上下文又省钱。
示例三：调试专家
.claude/agents/debugger.md：
---
name: debugger
description: 遇到报错、测试失败或异常行为时使用，定位根因并给出最小修复。
tools: Read, Edit, Bash, Grep, Glob
---
你是调试专家。按以下步骤工作：
1. 复现问题，记录完整报错
2. 定位根因，而不是只处理表面症状
3. 做最小范围的修复，并运行相关测试验证
4. 说明根因、修复方式和验证结果
没写 model 时，子代理按默认规则选择模型，通常沿用主对话的模型。
如何调用 Claude Code 子代理
自动委派
Claude 会根据你的请求、子代理的 description 和当前上下文，自动决定是否委派。description 写得越清楚，自动委派越准确。
手动指定
- 自然语言：直接说"用 test-runner 子代理修复失败的测试"；
- @ 提及：输入
@agent-code-reviewer，后面跟上任务； - 整个会话都用它：启动时运行
claude --agent code-reviewer。
前台与后台
前台子代理会阻塞主对话直到完成，权限确认会转给你处理；后台子代理与主对话并行运行，你可以继续做别的事。从主对话派出的子代理默认在后台运行，运行中的任务也可以按 Ctrl+B 转到后台。
Claude Code 子代理的 Token 成本
子代理有独立的上下文，它不会看到你的对话历史，也会发出自己的请求，这些请求同样计入你的用量和账单。控制成本的几个要点：
- 给简单任务配便宜模型：读日志、跑测试用
model: haiku，复杂判断再用sonnet或opus； - 让子代理只返回总结：在系统提示词里明确"不要贴完整日志"；
- description 写短：所有自定义子代理的描述都会加载到上下文，合计超过 1.5 万 Token 时 Claude Code 会在启动时警告；
- 频繁来回沟通的任务留在主对话：子代理适合"交出去、拿回结果"的独立任务。
更多降低 Claude Code Token 消耗的方法，见《Claude Code Token 消耗太快？10 个 Claude Code 省 Token 技巧》；各模型的价格差异见《Claude Opus 和 Sonnet 有什么区别？2026 Claude 模型对比与选型指南》。通过中转站使用时，子代理的请求同样走中转站，扣费明细可以在控制台日志中按模型查看，配置方法见《Claude API 中转怎么用？国内 Claude Code 中转站配置教程》。
常见问题 (FAQ)
Q: Claude Code 子代理文件放在哪里？
答： 项目级子代理放在 .claude/agents/ 目录，可以提交到 Git 与团队共享；个人在所有项目都能用的子代理放在 ~/.claude/agents/ 目录，同名时项目级优先。
Q: 子代理文件必须写哪些字段？
答： 只有 name 和 description 是必填的，name 是唯一标识，description 说明什么时候应该委派给它；tools、model 等字段不写时会继承默认设置。
Q: 子代理用什么模型？
答： 可以在 model 字段中指定 sonnet、opus、haiku、fable、完整模型 ID 或 inherit；不指定时按默认规则选择，通常沿用主对话的模型。
Q: 子代理会额外消耗 Token 吗？
答： 会，子代理发出的请求和主对话一样计入用量和费用；但它能把大量中间输出隔离在自己的上下文里，配合便宜的模型使用，整体往往更省。
Q: 怎么让 Claude 使用指定的子代理？
答： 可以直接用自然语言要求，例如"用 code-reviewer 子代理审查这次改动"，也可以输入 @agent-子代理名 进行提及，或用 claude --agent 子代理名 让整个会话都使用它。