# Claude Code 子智能体是什么，怎样创建一个？

> Claude Code 子智能体（subagent）专门接手一件任务，在自己的上下文窗口里完成，最后只把摘要交回主对话。Claude 搜索代码库时用的 Explore 就是内置的一个。自己做的子智能体是一个带 YAML 文件头的 Markdown 文件，放在 `.claude/agents/` 或 `~/.claude/agents/` 里。任务和它的描述对得上，Claude 就会交给它。

Mindket 编辑部 · 发布于 2026-10-29 · 更新于 2026-11-03 · https://mindket.com/cn/blog/claude-code-subagents

## 要点

- 每个智能体文件都写上 `tools` 一行，它能动哪些东西，由 Claude Code 来把关。
- Claude 靠描述决定交给谁，所以描述要写清楚。一定要用某个智能体时，输入 `@` 选中它。
- `/agents` 只打印一行提醒的话，就让 Claude 替你写，或者自己写文件。
- 想试一个，就把示例存进 `.claude/agents/`，命名为 `docs-link-checker.md`，再点名使用它。

## 子智能体启动时知道什么，最后交回什么

你问 Claude 一个牵涉整个代码库的问题，它会[主动把搜索交给 Explore](https://code.claude.com/docs/en/best-practices)。Explore 在自己的上下文窗口里读文件，读完把摘要放进你的对话。它打开过的文件、跑过的命令，都不会进来。

子智能体看不到你们之前的对话，也看不到你调用过的技能和 Claude 已经读过的文件。它的工具和权限单独设定。系统提示词由这个智能体自己的提示词和 Claude Code 附上的环境信息组成，不是 Claude Code 本身的系统提示词（见 [Anthropic 的子智能体文档](https://code.claude.com/docs/en/sub-agents)）。

[CLAUDE.md 文件](https://mindket.com/cn/blog/claude-md-file)倒是会跟着加载，一起带上的还有一份 git status 快照，以及它预载技能的全文。所以 CLAUDE.md 写得越长，每个自定义子智能体启动时重复加载的内容就越多，占用的上下文也越多。内置的 Explore 和 Plan 不加载 CLAUDE.md，也不带 git 快照。

1. Claude 拿你的请求对照每个子智能体的描述和当前上下文
2. 新的上下文窗口打开，里面是这个智能体自己的提示词和工具
3. 子智能体在后台运行。这期间你可以接着忙。它需要权限时，提示会出现在你的主会话里，并写明是哪个子智能体在请求。

来源：[Claude Code 文档：创建自定义子智能体](https://code.claude.com/docs/en/sub-agents) (2026-11-03 查阅)

| 子智能体 | Claude 用它做什么 | 工具 |
| --- | --- | --- |
| Explore | 搜索和分析代码库，不做任何修改 | 只读：禁用 Write 和 Edit |
| Plan | 在计划模式下先收集背景，再给出计划 | 只读：禁用 Write 和 Edit |
| General-purpose | 既要探索又要修改，或者步骤环环相扣的任务 | 子智能体能用的全部工具 |

## 动手做一个：示例智能体文件

整个定义就是一个文件。顶部的 YAML 写名称、描述，以及工具、模型这类限制，下面的 Markdown 正文就是子智能体的系统提示词。必填的只有 `name` 和 `description`。其余可选字段，从 `maxTurns`、`skills` 到 `memory`、`isolation`，[字段说明](https://code.claude.com/docs/en/sub-agents)里都列了。

下面的示例是我们为这篇文章写的，用来检查 docs 文件夹里的链接，正是 Anthropic 建议交给 Haiku 的那种简单任务。它的 tools 一行只列了 Read、Grep 和 Glob，改文件这件事由 Claude Code 直接挡住。要是只在提示词里写一句“不要修改任何文件”，那只是请求，不算限制。

````markdown
---
name: docs-link-checker
description: Checks relative links and anchors in Markdown files under docs/ and reports broken ones. Use proactively after editing files in docs/.
tools: Read, Grep, Glob
model: haiku
---

You check links in the Markdown files you are given, or in docs/ if none are named.

1. Find every relative link and every #anchor.
2. Confirm each target file exists and each anchor matches a heading in it.
3. Skip links that start with http:// or https://.

Reply with one line per broken link: file, line, target and the reason.
If every link resolves, reply "All links resolve" and nothing else.

````

- `name` 是 Claude 和钩子看到的标识，不能有冒号，也不必和文件名一致。
- `tools` 是允许清单。不写这一项，子智能体会继承子智能体能用的全部工具。
- `model` 可以填 `sonnet`、`opus`、`haiku`、`fable`、完整的模型 ID，也可以填 `inherit`，表示沿用主对话的模型。

1. 团队共用的智能体，放进项目里的 `.claude/agents/` 文件夹。想在所有项目里都能用，就放进 `~/.claude/agents/`。
2. 把示例存进去，文件名叫 `docs-link-checker.md`。
3. 点名使用，比如说“对 docs/ 使用 docs-link-checker 子智能体”。

## 智能体文件放在哪里，出了问题先查什么

输入 `/agents` 只看到一行提醒，没有弹出菜单，这不是出了故障。在当前版本里，这个命令只会提醒你去找 Claude，或者直接编辑 `.claude/agents/` 和 `~/.claude/agents/`。原来那个交互向导，只存在于 v2.1.197 及更早的版本。

让 Claude 来写，也是文档快速上手里走的路。说清楚要什么样的智能体、存在哪里，比如放在 `~/.claude/agents/`、只读、用 Sonnet 的代码改进助手。写好之后打开文件，看文件头和你的要求是否一致，包括模型选得对不对。

Claude Code 会从[五个地方](https://code.claude.com/docs/en/sub-agents)读取智能体文件，两个定义重名时，优先级高的位置胜出。同一个 `.claude/agents/` 文件夹及其子文件夹里，就没有这种排序了：两个文件声明了同一个名字，Claude Code 只加载其中一个，挑哪个取决于文件系统返回的顺序。名字别重复。

字段拼错了，不会有任何提示。字段名用驼峰写法，Claude Code 碰到不认识的字段会直接忽略，也不报错。`maxTurns` 或 `permissionMode` 好像不起作用时，先查拼写。

[插件](https://mindket.com/cn/blog/claude-code-plugins)能把智能体连同技能、钩子和 MCP 服务器一起带到别的团队，但插件里的智能体还有一处要注意。出于安全考虑，它们会忽略 `hooks`、`mcpServers` 和 `permissionMode` 三个字段，写在这几项里的设置不会生效。

[![Sid（@sidbid）在 X 上的帖子：Claude Code 将新增自定义子智能体功能，输入 /agents 即可开始，发布于 2025 年 7 月 24 日](https://mindket.com/blog/shots/x-sidbid-custom-subagents.webp?v=8143fcf83ff3)](https://x.com/sidbid/status/1948495478146167251)

Sid（@sidbid）在 X 上，2025 年 7 月 24 日

> 2025 年那条发布帖在 X 官方嵌入卡片里的截图，拍摄于 2026 年 11 月 3 日，时间为美国太平洋时间，没有收入帖子里的视频。点击截图可到 X 上打开原帖。

## Claude 怎样挑子智能体，你又怎样自己挑

Claude 决定交给哪个子智能体时会看几样东西，其中只有 `description` 是你事先写好的。像示例那样，在描述末尾写上“Use proactively”和适用场景，Claude 就更可能主动用它。

描述还是要写短。所有子智能体的描述加起来超过 15,000 个 token，Claude Code [启动时就会警告](https://code.claude.com/docs/en/sub-agents)，不过照样全部加载。

- 直接说：“用 test-runner 子智能体修复失败的测试”。Claude 通常会照办，但用不用还是由它决定。
- 输入 `@`，从联想列表里选中它，跟引用文件一样。这样运行的一定是你选的那个，不过整条消息仍然交给 Claude，任务提示词也由 Claude 来写。
- 用 `claude --agent code-reviewer` 启动会话，主线程就变成这个智能体，套用它的工具限制和模型。在 `.claude/settings.json` 里设置 `agent`，就能把它设成项目的默认值。

## 用子智能体还是技能，子智能体什么时候值得用

技能会[加载进你当前的对话](https://code.claude.com/docs/en/features-overview)，占用这段对话的上下文。技能是可以反复使用的内容，比如操作说明或参考资料。

子智能体的 `skills` 字段会预先载入所列[技能](https://mindket.com/cn/blog/what-are-agent-skills)的全文，设了 `context: fork` 的技能则会[放到子智能体里运行](https://code.claude.com/docs/en/skills)。

互不依赖、可以[同时进行](https://code.claude.com/docs/en/best-practices)的几件事，适合交给子智能体。整轮测试这类很长的输出也一样，交出去就不会堆进你的对话。代码评审是另一种用法：没写这段代码的智能体，不会带着你们对话里的那些预设去看它。

每个子智能体都单独发请求，和主对话共用同一份用量上限，所以主要开销是 token。新的子智能体还得重新收集主对话已经有的背景，比如把读过的文件再读一遍，所以可能比直接在主对话里做更慢。答案也不会更好：默认情况下，它就是同一个模型，或者更小的模型，在做同一件事。

要是你每次改完文档都派一个子智能体去查链接，交代的话也都一样，就把它存成示例那样的智能体文件。

**主对话还是子智能体：任务适合哪一种**

| | 主对话 | 子智能体 |
| --- | --- | --- |
| 需要频繁来回沟通，或者反复打磨 | ✓ 是 | ✗ 否 |
| 几个阶段共享大量上下文，比如规划、实现和测试 | ✓ 是 | ✗ 否 |
| 改动小而明确 | ✓ 是 | ✗ 否 |
| 在意延迟 | ✓ 是 | ✗ 否 |
| 会产生大量输出，而你的对话里不需要它们 | ✗ 否 | ✓ 是 |
| 需要自己的工具限制或权限 | ✗ 否 | ✓ 是 |
| 任务自成一体，能以摘要的形式交回 | ✗ 否 | ✓ 是 |

来源：[Claude Code 文档：创建自定义子智能体](https://code.claude.com/docs/en/sub-agents) (2026-11-03 查阅)

## 参考：智能体文件从哪里加载，以及默认上限

**Claude Code 给子智能体设的三条上限**

- **15,000** 个令牌：所有子智能体的描述加起来超过这个数，Claude Code 启动时会发出警告 (来源：[Claude Code 文档：创建自定义子智能体](https://code.claude.com/docs/en/sub-agents), 2026-11-03 查阅)
- **3** 层：默认情况下，主对话之下最多允许嵌套的子智能体层数 (来源：[Claude Code 文档：创建自定义子智能体](https://code.claude.com/docs/en/sub-agents), 2026-11-03 查阅)
- **20** 个：默认情况下，同时运行的子智能体达到这个数，新的就启动不了 (来源：[Claude Code 文档：创建自定义子智能体](https://code.claude.com/docs/en/sub-agents), 2026-11-03 查阅)

| 位置 | 范围 | 优先级 |
| --- | --- | --- |
| 组织托管设置 | 整个组织 | 1，最高 |
| `--agents` 参数，以 JSON 传入 | 只限当前会话，不会存到磁盘 | 2 |
| `.claude/agents/` | 当前项目 | 3 |
| `~/.claude/agents/` | 你的所有项目 | 4 |
| 插件的 `agents/` 文件夹 | 启用了该插件的地方 | 5，最低 |

> 这里的每个事实都来自下方来源里列出的 Anthropic 页面，阅读日期为 2026 年 11 月 2 日和 3 日。本文是对官方文档的解读，不是实际测试，Claude Code 的字段、默认值和命令也会随版本变化。

## 常见问题

### 子智能体能再启动自己的子智能体吗？

能，默认最多到主对话以下三层。到了这个深度，除了分叉（fork），Claude Code 会收回所有子智能体的 Agent 工具。最深的那一个只能自己完成任务，交回一份摘要。层数可以用 `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` 来改。数量另有上限：一个会话里已有 20 个子智能体在跑时，第 21 个会启动失败。

### 添加子智能体之后，要重启 Claude Code 吗？

一般不用。Claude Code 会监视 `.claude/agents/` 和 `~/.claude/agents/`，新建或修改的文件几秒钟内就会被发现，下一次委派任务时就能用上。要重启的情况只有三种：会话启动时还没有 agents 文件夹，智能体放在用 `--add-dir` 添加的目录下，或者会话是用 `--disable-slash-commands` 启动的。

### 子智能体和分叉（fork）有什么区别？

分叉会继承到目前为止的整段对话，普通子智能体则按自己的定义从零开始。分叉和主会话共用系统提示词、工具和模型，还能复用主会话的提示词缓存。需要相同背景的任务，交给分叉比交给新的子智能体更省。想自己开一个，输入 `/subtask` 再跟上任务。分叉不能再分叉。

### 怎样禁止 Claude 使用某个子智能体？

在权限设置的 `deny` 列表里加上 `Agent(name)`，比如 `Agent(Explore)`。内置和自定义的子智能体都适用。旧的 `Task(...)` 写法也照样有效：Claude Code v2.1.63 把 Task 工具改名为 Agent，旧名字留作别名。

### 子智能体能在不同会话之间记住东西吗？

能，在文件头里加一行，打开持久记忆就行。设为 `memory: user`，笔记存在 `~/.claude/agent-memory/` 下，所有项目通用。设为 `project`，笔记存在 `.claude/agent-memory/` 下，可以提交进仓库。设为 `local`，则存在 `.claude/agent-memory-local/` 下，不进版本控制。这和你自己的[自动记忆](https://code.claude.com/docs/en/memory)是两回事，普通子智能体不会加载它。

### 不写 model 字段，子智能体用哪个模型？

默认沿用主对话的模型。如果设置了 `CLAUDE_CODE_SUBAGENT_MODEL` 环境变量，就用它。Claude 针对某一次调用传入的模型别名，优先级比这两者都高。想让所有子智能体都用同一个模型，再加上 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`。这个变量要 Claude Code v2.1.257 或更高版本才支持。

### 别人写好的子智能体，去哪里找？

插件里会带，插件能把智能体连同技能、钩子和 MCP 服务器一起带过来。Mindket 的[套件](https://mindket.com/cn/kits)也能装智能体文件，套件是纯文本文件的压缩包，里面的东西不会自己运行。不是自己写的智能体文件，用之前先看一遍文件头。Mindket 的[智能体页](https://mindket.com/cn/agents)列的是另一种：交给浏览器智能体的指令，每个都完整列出，你先看清它会做什么，再交给智能体。

## 资料来源

- [Claude Code 文档：创建自定义子智能体](https://code.claude.com/docs/en/sub-agents) (2026-11-03 查阅)
- [Claude Code 文档：最佳实践](https://code.claude.com/docs/en/best-practices) (2026-11-02 查阅)
- [Claude Code 文档：扩展 Claude Code](https://code.claude.com/docs/en/features-overview) (2026-11-02 查阅)
- [Claude Code 文档：用技能扩展 Claude](https://code.claude.com/docs/en/skills) (2026-11-02 查阅)
- [Claude Code 文档：Claude 如何记住你的项目](https://code.claude.com/docs/en/memory) (2026-11-02 查阅)

[阅读 CLAUDE.md 指南](https://mindket.com/cn/blog/claude-md-file)