用法

Claude Code 子代理（Subagents）教程：创建、配置和调用

Q: 怎么阻止 Claude 使用某个子代理？

把它加进 settings 的 deny 数组，格式是 Agent(subagent-name)，其中 subagent-name 要和子代理的 name 字段一致，内置和自定义子代理都适用：{"permissions": {"deny": ["Agent(Explore)", "Agent(my-custom-agent)"]}}。也可以用 claude --disallowedTools "Agent(Explore)"。想完全阻止 Claude 委派给任何子代理，文档说是拒绝 Agent 工具本身。

Q: 子代理能再生成子代理吗？

默认可以，最多在主对话之下三层。想改这个上限，把 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 设为你想要的层数；设为 1 就关闭嵌套。想让某个子代理不能生成子代理，把 Agent 从它的 tools 列表里去掉，或加进 disallowedTools。

发布于 2026 年 10 月 30 日 · 最后核对 2026 年 10 月 30 日

子代理是处理特定类型任务的专用 AI 助手，在自己的上下文窗口里干活，只把摘要还给主对话。这一页按 Anthropic 的 Create custom subagents 文档，中文整理子代理是什么、内置了哪几个、怎么创建、文件放在哪里、frontmatter 怎么写、怎么选模型、怎么调用，以及找不到子代理时怎么排查。文档于 2026 年 10 月 30 日核对。

要点

子代理是带 YAML frontmatter 的 Markdown 文件；每个子代理有自己的上下文窗口、自定义系统提示词、特定的工具权限和独立的权限。
个人子代理放 ~/.claude/agents/，项目子代理放 .claude/agents/；重名时项目优先于个人。
只有 name 和 description 是必填的；Claude 靠 description 决定什么时候委派。
tools 限制它能用的工具，省略则继承全部；model 可以设为 sonnet、opus、haiku、fable、完整模型 ID 或 inherit。
想确保某个子代理运行，用 @ 提及；想让整个会话以它运行，用 claude --agent <name>。

子代理是什么，什么时候用

文档的说法：当一个旁支任务会用你不会再引用的搜索结果、日志或文件内容淹没主对话时，就用子代理，它在自己的上下文里完成这些工作，只返回摘要。如果你总是在生成同一类工作者、用同一套指令，就定义一个自定义子代理。

每个子代理在自己的上下文窗口里运行，有自定义系统提示词、特定的工具权限和独立的权限。它也会发出自己的请求，这些请求和你的主对话计入同一份用量限额。Claude 遇到和某个子代理的描述匹配的任务时，会委派给它，它独立工作并返回结果。文档列出的好处：

保留上下文：把探索和实现挡在主对话之外
强制约束：限制子代理能用的工具
复用配置：用户级子代理可以跨项目使用
专门化行为：用聚焦的系统提示词针对特定领域
控制成本：把任务路由到更快、更便宜的模型，比如 Haiku

文档还有一条提醒：子代理在单个会话内工作。想并行跑很多独立会话并在一处监控，文档指向 background agents；想要由 Claude 生成并监督的会话团队，文档指向 agent teams。

内置子代理

Claude Code 内置了一些子代理，Claude 会在合适的时候自动使用。每个都继承父对话的权限规则，大多数以受限的工具集运行。

子代理	用途	工具	模型
`Explore`	快速、只读，用于搜索和分析代码库：文件发现、代码搜索、代码库探索	只读工具；Write 和 Edit 被拒绝	主对话的模型（主对话运行 Fable 时的情况见文档）
`Plan`	在计划模式下收集上下文，供 Claude 提出计划	只读工具；Write 和 Edit 被拒绝	继承主对话，除非设置了 `CLAUDE_CODE_SUBAGENT_MODEL` 并强制应用到每个子代理
`General-purpose`	复杂研究、多步操作、代码修改	子代理可用的所有工具	如果设置了 `CLAUDE_CODE_SUBAGENT_MODEL` 且没有其他方式指定模型，用它；否则用主对话的模型

Explore 和 Plan 启动时不带你的 CLAUDE.md 文件和 git status 快照，让调研又快又省；其他内置子代理和自定义子代理两者都会加载。调用 Explore 时，Claude 会指定彻底程度：quick 用于有针对性的查找，medium 用于均衡的探索，very thorough 用于全面分析。

文档还列出了几个通常自动调用的辅助子代理：

子代理	模型	Claude 什么时候用
`claude`	自己没有模型；Claude 把它当子代理生成时，按模型顺序决定	任务不属于更专门的子代理时。一个拥有子代理可用的所有工具的兜底选项
`statusline-setup`	Sonnet	运行 `/statusline` 配置状态栏时
`claude-code-guide`	Haiku	你询问 Claude Code 功能的问题时

想阻止 Claude 使用某个内置子代理，把它加进 permissions.deny，写法见下面的常见问题。想移除内置的 Explore 和 Plan，设置 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1，Claude 会直接读取和探索文件，需要 Claude Code v2.1.198 或更高版本。

创建第一个子代理

子代理是带 YAML frontmatter 的 Markdown 文件。创建的方式有两种：让 Claude 帮你写，或者自己写文件。下面的流程来自文档，创建一个用户级子代理，审查代码并提出改进建议。

第一步，在 Claude Code 里描述你想要的子代理和保存位置：

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude 会写出带 name、description、tools 列表、model 和系统提示词的文件。第二步，打开 ~/.claude/agents/code-improver.md，确认 frontmatter 和你要求的一致。结果类似这样：

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

文件在 ~/.claude/agents/ 里，所以这个子代理在你机器上的每个项目里都可用。想只用在一个项目，就把它移到那个项目的 .claude/agents/ 目录。第三步，让 Claude 委派给它：

Use the code-improver agent to suggest improvements in this project

Claude 会委派给新的子代理，它扫描代码库并返回改进建议。在对话记录里，委派显示为一行工具调用，写着子代理的名字和一句简短的任务描述，例如 code-improver(Suggest code improvements)。

关于 /agents：文档说，运行 /agents 会打印一条提醒，让你去问 Claude，或直接编辑 .claude/agents/ 和 ~/.claude/agents/。在 Claude Code v2.1.197 及更早版本里，/agents 会打开一个交互式向导，其中 Running 标签页列出正在运行的子代理，Library 标签页用来创建、编辑和删除子代理。

改动不需要重启：文档说，Claude Code 会监视 ~/.claude/agents/ 和 .claude/agents/，你在磁盘上添加或编辑子代理文件，或让 Claude 写一个，它会在几秒内检测到变化，下一次委派就用更新后的定义。有三种情况仍然需要重启，见后面的排查。

子代理文件放在哪里

文件的位置决定谁能用它，frontmatter 决定它能做什么。多个子代理同名时，Claude Code 使用优先级更高的位置里的那个。

位置	范围	优先级	怎么创建
托管设置	整个组织	1（最高）	通过托管设置部署
`--agents` CLI 参数	当前会话	2	启动 Claude Code 时传入 JSON
`.claude/agents/`	当前项目	3	让 Claude 创建，或手动创建文件
`~/.claude/agents/`	你的所有项目	4	让 Claude 创建，或手动创建文件
插件的 `agents/` 目录	插件启用的地方	5（最低）	随插件安装

项目子代理（.claude/agents/）适合针对某个代码库的子代理。文档建议把它们提交进版本控制，让团队一起使用和改进。
用户子代理（~/.claude/agents/）是个人子代理，在你所有项目里可用。
Claude Code 会递归扫描 .claude/agents/ 和 ~/.claude/agents/，所以可以用 agents/review/ 或 agents/research/ 这样的子文件夹整理。子目录路径不影响子代理怎么识别和调用，识别只看 name 字段。
名字要在整棵目录树里保持唯一：同一个 .claude/agents/ 目录（含子文件夹）里两个文件声明同一个名字，Claude Code 只会加载其中一个，由文件系统读取顺序决定，没有文档化的优先规则。

项目子代理通过从当前工作目录向上查找来发现，所以从那里到仓库根目录之间的每个 .claude/agents/ 都会被扫描；多个嵌套目录定义了同一个 name 时，用离工作目录最近的那个。

最常用的 frontmatter 字段

用两个 --- 标记之间的 YAML frontmatter 配置子代理，闭合 --- 之后用 Markdown 写它的系统提示词。只有 name 和 description 是必填的。多个单词的字段名用 camelCase，例如 maxTurns 和 disallowedTools，必须和表里完全一致：Claude Code 会忽略不认识的字段，而且不报错。

字段	必填	作用
`name`	是	唯一标识，最多 256 个字符，例如 `code-reviewer` 或 `reviewer-v2`。文件名不必和它一致。名字里不能有 `:`，它留给插件作用域的标识符。
`description`	是	Claude 什么时候应该委派给这个子代理。
`tools`	否	子代理能用的工具，写成逗号分隔的字符串，如 `Read, Grep, Bash`，或 YAML 列表。省略时继承子代理可用的所有工具。
`disallowedTools`	否	要拒绝的工具，从继承的或指定的列表里移除。格式和 `tools` 相同。
`model`	否	使用的模型：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（如 `claude-opus-5-5`）或 `inherit`。省略时，Claude Code 按子代理模型顺序选择。
`permissionMode`	否	权限模式：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan`，`manual` 是 `default` 的别名。对插件子代理无效。
`maxTurns`	否	子代理停止前的最大代理轮数。
`skills`	否	启动时预加载进子代理上下文的 skills，注入的是完整内容，不只是描述。
`mcpServers`	否	这个子代理可用的 MCP 服务器。对插件子代理无效。
`hooks`	否	作用域限定在这个子代理的生命周期 hooks。对插件子代理无效。
`memory`	否	持久记忆的范围：`user`、`project` 或 `local`，支持跨会话学习。
`background`	否	设为 `true`，即使 Claude 要求等待，也让这个子代理留在后台。
`effort`	否	这个子代理活跃时的 effort 级别，覆盖会话的 effort 级别，但不覆盖 `CLAUDE_CODE_EFFORT_LEVEL` 环境变量。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型。
`isolation`	否	设为 `worktree`，在临时的 git worktree 里运行子代理，给它一份隔离的仓库副本。没有改动时，worktree 会自动清理。

文档里还有 autoCompactWindow、omitClaudeMd、color、initialPrompt 和 experimental 等字段，这里不展开。有一点要注意：子代理文件的正文成为系统提示词，子代理只收到这段系统提示词加工作目录等基本环境信息，不收到 Claude Code 的系统提示词。

限制工具

限制工具用 tools 作为允许列表，或 disallowedTools 作为拒绝列表。两个都设置时，先应用 disallowedTools，再在剩下的工具池里解析 tools；两边都列出的工具会被移除。下面的例子来自文档，只允许 Read、Grep、Glob 和 Bash，子代理不能编辑文件、写文件，也不能使用任何 MCP 工具：

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

下面这个用 disallowedTools，继承子代理的工具池，只去掉 Write 和 Edit，子代理保留 Bash、MCP 工具和池里的其余部分：

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

选模型

model 字段控制子代理用哪个模型，可以是别名（sonnet、opus、haiku 或 fable）、完整模型 ID（如 claude-opus-5-5 或 claude-sonnet-5，接受和 --model 参数相同的值），或者 inherit（用和主对话相同的模型）。Claude 调用子代理时，还可以为这一次调用传一个 model 参数。Claude Code 按这个顺序决定子代理的模型：

每次调用的 model 参数
子代理定义里的 model frontmatter，其中 inherit 选主对话的模型
环境变量 CLAUDE_CODE_SUBAGENT_MODEL，当你把它设为模型别名或模型 ID 时
主对话的模型

想检查某个子代理在用哪个模型，运行 /tasks，Claude Code 会在子代理那一行写出模型名（需要 Claude Code v2.1.242 或更高版本）。文档给出的例子是，在 settings 文件的 env 块里同时设置两个变量，让每个子代理都用 Haiku：

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

CLAUDE_CODE_SUBAGENT_MODEL_FORCE 需要 Claude Code v2.1.257 或更高版本。开启它之后，Claude Code 会忽略子代理定义里的 model 字段。

子代理可以和主对话用不同的模型，而且它发出的是自己的请求。所以如果你按 token 计费，这些请求会以子代理自己的模型出现，不是主会话的模型；我们在这份说明里解释了这一点。怎么选模型见模型和思考强度怎么选。

自动委派和手动调用

自动委派。Claude 根据你请求里的任务描述、子代理配置里的 description 字段和当前上下文自动委派。想鼓励主动委派，在子代理的 description 里写上“use proactively”这样的短语。描述要简短：当你的子代理的描述合计超过 15,000 个 token（不含内置子代理），Claude Code 会在启动时显示警告，但仍会加载每个子代理。

手动调用。自动委派不够时，可以自己请求子代理。三种方式从一次性建议升级到整个会话的默认：

自然语言：在提示里点名子代理，由 Claude 决定是否委派
@ 提及：保证子代理为这一个任务运行
整个会话：通过 --agent 参数或 agent 设置，让整个会话以那个子代理运行

自然语言没有特殊语法，点名子代理，Claude 通常就会委派：

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@ 提及：输入 @，从补全列表里选子代理，和 @ 提及文件的方式一样。这能确保运行的是那个子代理，不留给 Claude 选：

@"code-reviewer (agent)" look at the auth changes

你的完整消息仍然发给 Claude，由它根据你的请求写出子代理的任务提示。@ 提及控制的是 Claude 调用哪个子代理，不是它收到什么提示。也可以不用选择器，手动输入 @agent-<name>。

整个会话以子代理运行：传入 --agent <name>，主线程本身就带上那个子代理的工具限制和模型：

claude --agent code-reviewer

启动标题里会以 @<name> 显示代理名，方便确认它已生效。想让它成为项目里每个会话的默认，在 .claude/settings.json 里设置 agent；两者同时存在时，CLI 参数优先：

{
  "agent": "code-reviewer"
}

前台和后台：前台子代理会阻塞主对话直到完成，权限提示会传给你；后台子代理在你继续工作时并发运行。文档说，什么都不配置时，Claude 从主对话生成的子代理默认在后台启动。

完整示例：代码审查子代理

下面这个例子来自文档的 Example subagents：一个只读子代理，审查代码但不修改。它展示了怎么设计一个工具权限有限（不含 Edit 和 Write）的聚焦子代理，以及一个详细说明要看什么、输出什么格式的提示词。把它存成 .claude/agents/code-reviewer.md 即可。

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

这个文件里 model: inherit，所以它用和主对话相同的模型；description 里的 “Proactively” 和 “Use immediately after writing or modifying code” 是在告诉 Claude 什么时候该委派。

文档给的提示

文档的最佳实践：

设计聚焦的子代理：每个子代理只擅长一个具体任务。
写能单独指向某一个子代理的描述：Claude 用描述决定何时委派，所以每个描述要具体到能路由到正确的子代理，并让整体保持在 15,000 token 的描述预算之内。
限制工具权限：只授予必要的权限，出于安全和专注。
提交进版本控制：和团队共享项目子代理。

文档里的常见用法：

隔离大输出的操作：运行测试、获取文档或处理日志文件会消耗大量上下文，委派给子代理后，冗长的输出留在子代理的上下文里，只有相关摘要回到主对话。例如：Use a subagent to run the test suite and report only the failing tests with their error messages
并行研究：对互相独立的调查，生成多个子代理同时工作。例如：Research the authentication, database, and API modules in parallel using separate subagents。研究路径互不依赖时效果最好。
串联子代理：多步工作流里，让 Claude 按顺序使用子代理。例如：Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

文档的警告：子代理完成后，结果会回到你的主对话。运行很多个各自返回详细结果的子代理，会消耗大量上下文，而且每个子代理运行时都会花费自己的 token。

什么时候不用子代理：任务需要频繁来回或反复修改、多个阶段共享大量上下文、只是快速而有针对性的改动，或者在意延迟（不是 fork 的子代理从头开始，可能需要时间收集上下文），就用主对话。想要在主对话上下文里运行的可复用提示词或工作流，文档建议考虑 Skills。

常见问题排查

Claude 找不到新子代理

重启 Claude Code 再试。文档说，这只发生在会话启动前 ~/.claude/agents/ 不存在的情况下，因为运行中的会话检测不到新建的 agents 目录。三种情况仍需重启：在新的 agents 目录里创建某个范围的第一个代理文件之后；在用 --add-dir 或 /add-dir 添加的目录里添加或编辑子代理之后；用 --disable-slash-commands 启动的会话（根本不监视这些目录）。

文件被悄悄跳过

文档说，frontmatter 有下面任何一个问题时，Claude Code 会跳过文件，且不在会话里报告：

没有 name：Claude Code 把这个文件当作放在代理旁边的文档。
开头的 --- 不是文件的第一行：Claude Code 认为文件没有 frontmatter，同样当作文档。
name 以 - 开头、包含 :，或超过 256 个字符：跳过文件，并把错误写进 debug 日志。
有 name 但没有 description：跳过文件，并把原因写进 debug 日志。
YAML 解析不了：不读取文件的任何字段，跳过它，并把解析错误写进 debug 日志。

要看 debug 日志，用 --debug 运行 Claude Code。要找出 frontmatter 解析失败的文件，对目录运行 claude plugin validate，例如 .claude/agents 或 ~/.claude/agents（需要 Claude Code v2.1.233 或更高版本）；它不会标出 frontmatter 能解析但缺少 name 的文件。

字段拼错了，没有任何报错

Claude Code 忽略不认识的字段且不报错。对已加载的子代理，在 shell 里运行 claude --debug，在 ~/.claude/debug/<session-id>.txt 的 debug 日志里搜索 does not recognize or apply，日志会列出最多五个它不认识的顶层字段，接近某个受支持字段时还会给出可能想写的名字（需要 Claude Code v2.1.296 或更高版本）。

子代理启动失败

当 tools 列表里没有任何条目能解析成工具，例如每个条目都拼错了，或者写的是子代理用不了的工具，Claude Code 通常会拒绝启动这个子代理，Agent 工具返回一个点名未解析条目的错误。

子代理不知道你的规则或对话

每个子代理从全新的、隔离的上下文窗口开始，看不到你的对话历史、你已调用的 skills，或 Claude 已读过的文件。Claude 会写一条委派消息，概括任务，子代理从那里开始工作。如果某条规则必须传到子代理那里，例如“忽略 vendor/ 目录”，就在你委派时给 Claude 的提示里重述它。

常见问题

怎么阻止 Claude 使用某个子代理？

把它加进 settings 的 deny 数组，格式是 Agent(subagent-name)，其中 subagent-name 要和子代理的 name 字段一致，内置和自定义子代理都适用：{"permissions": {"deny": ["Agent(Explore)", "Agent(my-custom-agent)"]}}。也可以用 claude --disallowedTools "Agent(Explore)"。想完全阻止 Claude 委派给任何子代理，文档说是拒绝 Agent 工具本身。

子代理能再生成子代理吗？

默认可以，最多在主对话之下三层。想改这个上限，把 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 设为你想要的层数；设为 1 就关闭嵌套。想让某个子代理不能生成子代理，把 Agent 从它的 tools 列表里去掉，或加进 disallowedTools。

该用子代理还是 skill？

文档的区分：任务会产生你不需要留在主上下文里的冗长输出、你想强制特定的工具限制或权限，或者工作自成一体并能返回摘要，用子代理。想要在主对话上下文里运行、而不是隔离的子代理上下文里运行的可复用提示词或工作流，考虑 skill，写法见 Claude Code Skills 使用教程。内置命令见 Claude Code 命令，省钱的做法见Claude Code 省钱指南。

来源

Claude Code：Create custom subagents（内置子代理、创建流程、文件位置与优先级、frontmatter 字段、模型顺序、调用方式、常见用法、示例、排查）