156</Note>156</Note>
157 157
158<h2 id="configure-subagents">158<h2 id="configure-subagents">
159 配置 subagents159 配置子代理
160</h2>160</h2>
161 161
162一个 subagent 的文件位置决定了谁可以使用它，其 frontmatter 决定了它可以做什么。本节涵盖 subagent 文件的位置以及它们支持的每个字段。162子代理文件的位置决定了谁可以使用它，其 frontmatter 决定了它能做什么。本节介绍子代理文件的存放位置以及它们支持的所有字段。
163 163
164<h3 id="choose-the-subagent-scope">164<h3 id="choose-the-subagent-scope">
165 选择 subagent 范围165 选择子代理作用域
166</h3>166</h3>
167 167
168根据范围将 subagent 文件存储在不同的位置。当多个 subagents 共享相同的名称时，Claude Code 使用来自更高优先级位置的那个。168根据作用域将子代理文件存放在不同位置。当多个子代理同名时，Claude Code 使用优先级较高位置中的那个。
169 169
170| Location | Scope | Priority | 如何创建 |170| 位置 | 作用域 | 优先级 | 创建方式 |
171| :- | :- | :- | :- |171| :- | :- | :- | :- |
172| 托管设置 | 组织范围 | 1（最高） | 通过 [managed settings](/docs/zh-CN/settings) 部署 |172| 托管设置 | 整个组织 | 1（最高） | 通过[托管设置](/docs/zh-CN/settings)部署 |
173| `--agents` CLI 标志 | 当前会话 | 2 | 启动 Claude Code 时传递 JSON |173| `--agents` CLI 标志 | 当前会话 | 2 | 启动 Claude Code 时传入 JSON |
174| `.claude/agents/` | 当前项目 | 3 | 询问 Claude，或手动创建文件 |174| `.claude/agents/` | 当前项目 | 3 | 让 Claude 创建，或手动创建文件 |
175| `~/.claude/agents/` | 所有您的项目 | 4 | 询问 Claude，或手动创建文件 |175| `~/.claude/agents/` | 您的所有项目 | 4 | 让 Claude 创建，或手动创建文件 |
176| Plugin 的 `agents/` 目录 | 启用 plugin 的位置 | 5（最低） | 与 [plugins](/docs/zh-CN/plugins/overview) 一起安装 |176| 插件的 `agents/` 目录 | 启用插件的位置 | 5（最低） | 随[插件](/docs/zh-CN/plugins/overview)一起安装 |
177 177
178**项目 subagents**（`.claude/agents/`）非常适合特定于代码库的 subagents。将它们检入版本控制，以便您的团队可以协作使用和改进它们。178**项目子代理**（`.claude/agents/`）非常适合特定于某个代码库的子代理。将它们提交到版本控制中，以便您的团队可以协作使用和改进它们。
179 179
180项目 subagents 通过从当前工作目录向上遍历来发现，因此会扫描那里和存储库根目录之间的每个 `.claude/agents/`。当这些嵌套目录中的多个目录定义相同的 `name` 时，Claude Code 使用最接近工作目录的定义。180项目子代理的发现方式是从当前工作目录向上遍历，因此从该目录到仓库根目录之间的每个 `.claude/agents/` 都会被扫描。当这些嵌套目录中有多个定义了相同的 `name` 时，Claude Code 使用离工作目录最近的定义。
181 181
182使用 `--add-dir` 或 `/add-dir` 添加目录时，Claude Code 也会加载其 `.claude/agents/` 文件夹，与您的项目 subagents 一起。有关哪些其他配置类型从 `--add-dir` 加载，请参阅 [Additional directories](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。要在没有 `--add-dir` 的情况下跨项目共享 subagents，请使用 `~/.claude/agents/` 或 [plugin](/docs/zh-CN/plugins/overview)。182当您使用 `--add-dir` 或 `/add-dir` 添加目录时，Claude Code 也会加载该目录的 `.claude/agents/` 文件夹，与您的项目子代理一起使用。有关还有哪些其他配置类型会从 `--add-dir` 加载，请参阅[额外目录](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。若要在不使用 `--add-dir` 的情况下跨项目共享子代理，请使用 `~/.claude/agents/` 或[插件](/docs/zh-CN/plugins/overview)。
183 183
184**用户 subagents**（`~/.claude/agents/`）是在所有项目中可用的个人 subagents。184**用户子代理**（`~/.claude/agents/`）是在您所有项目中都可用的个人子代理。
185 185
186Claude Code 递归扫描 `.claude/agents/` 和 `~/.claude/agents/`，因此您可以将定义组织到子文件夹中，例如 `agents/review/` 或 `agents/research/`。子目录路径不会影响 subagent 的识别或调用方式，因为身份仅来自 `name` frontmatter 字段。186Claude Code 会递归扫描 `.claude/agents/` 和 `~/.claude/agents/`，因此您可以将定义组织到子文件夹中，例如 `agents/review/` 或 `agents/research/`。子目录路径不影响子代理的识别或调用方式，因为其身份仅来自 `name` frontmatter 字段。
187 187
188在整个目录树中保持 `name` 值唯一：如果同一 `.claude/agents/` 目录（包括其子文件夹）下的两个文件声明了相同的名称，Claude Code 只会加载其中一个，由文件系统读取顺序决定，而不是由有文档记录的优先级决定。在嵌套的项目目录之间，如上所述，最接近工作目录的定义优先。[`/doctor`](/docs/zh-CN/commands#all-commands) 设置检查会报告同一目录中同名的文件，并建议重命名或删除其中除一个之外的所有文件。188请在整个目录树中保持 `name` 值唯一：如果同一个 `.claude/agents/` 目录（包括其子文件夹）下的两个文件声明了相同的名称，Claude Code 只会加载其中一个，具体由文件系统读取顺序决定，而不是由文档规定的优先级决定。在嵌套的项目目录之间，如上所述，离工作目录最近的定义优先。[`/doctor`](/docs/zh-CN/commands#all-commands) 设置检查会报告同一目录中同名的文件，并建议重命名或删除多余的文件，只保留一个。
189 189
190Plugin `agents/` 目录也会被递归扫描。与项目和用户范围不同，plugin 的 `agents/` 目录内的子文件夹成为 [scoped identifier](#invoke-subagents-explicitly) 的一部分：plugin `my-plugin` 中位于 `agents/review/security.md` 的文件注册为 `my-plugin:review:security`。190插件的 `agents/` 目录也会被递归扫描。与项目和用户作用域不同，插件 `agents/` 目录中的子文件夹会成为[作用域标识符](#invoke-subagents-explicitly)的一部分：插件 `my-plugin` 中位于 `agents/review/security.md` 的文件注册为 `my-plugin:review:security`。
191 191
192**CLI 定义的 subagents** 在启动 Claude Code 时作为 JSON 传递。它们仅存在于该会话中，不会保存到磁盘，使其对快速测试或自动化脚本很有用。您可以在单个 `--agents` 调用中定义多个 subagents：192**CLI 定义的子代理**在启动 Claude Code 时以 JSON 形式传入。它们仅在该会话中存在，不会保存到磁盘，因此适用于快速测试或自动化脚本。您可以在一次 `--agents` 调用中定义多个子代理：
193 193
194<Tabs>194<Tabs>
195 <Tab title="macOS, Linux, WSL">195 <Tab title="macOS, Linux, WSL">
229 </Tab>229 </Tab>
230</Tabs>230</Tabs>
231 231
232在 [non-interactive mode](/docs/zh-CN/headless) 中，`--agents` 也接受保存相同对象的 JSON 文件的路径，用于定义太大而无法在命令行上传递的情况。例如，`claude -p --agents ./agents.json "Review my changes"` 从该文件读取定义。在交互式会话中，Claude Code 拒绝文件路径。文件形式需要 Claude Code v2.1.281 或更高版本。232在[非交互模式](/docs/zh-CN/headless)下，`--agents` 也接受一个包含相同对象的 JSON 文件路径，适用于定义过大而无法在命令行中传入的情况。例如，`claude -p --agents ./agents.json "Review my changes"` 会从该文件读取定义。在交互式会话中，Claude Code 会拒绝文件路径。文件形式需要 Claude Code v2.1.281 或更高版本。
233 233
234JSON 中的每个顶级键是代理的名称，其值是该代理的定义。不要以 `-` 开头的名称。定义采用这些字段：234JSON 中的每个顶层键都是一个 Agent 的名称，其值是该 Agent 的定义。名称不要以 `-` 开头。定义包含以下字段：
235 235
236* **`prompt`**：代理的系统提示，等同于基于文件的 subagents 中的 markdown 正文。`prompt` 可能为空。如果您选择一个具有空 `prompt` 且没有 `memory` 字段的代理作为会话的代理，使用 `--agent`，会话的系统提示保持不变。空 `prompt` 需要 Claude Code v2.1.281 或更高版本。236* **`prompt`**：Agent 的系统提示词，等同于基于文件的子代理中的 markdown 正文。`prompt` 可以为空。如果您使用 `--agent` 将一个 `prompt` 为空且没有 `memory` 字段的 Agent 选为会话的 Agent，会话的系统提示词将保持不变。空 `prompt` 需要 Claude Code v2.1.281 或更高版本。
237* **[Frontmatter 字段](#supported-frontmatter-fields)**：`description`、`tools`、`disallowedTools`、`model`、`permissionMode`、`mcpServers`、`hooks`、`maxTurns`、`autoCompactWindow`、`skills`、`initialPrompt`、`memory`、`effort`、`background`、`omitClaudeMd` 和 `isolation`。237* **[Frontmatter 字段](#supported-frontmatter-fields)**：`description`、`tools`、`disallowedTools`、`model`、`permissionMode`、`mcpServers`、`hooks`、`maxTurns`、`autoCompactWindow`、`skills`、`initialPrompt`、`memory`、`effort`、`background`、`omitClaudeMd` 和 `isolation`。
238* **忽略的字段**：`color` 和 `experimental` 在此处不被接受，被忽略而不是拒绝。238* **被忽略的字段**：`color` 和 `experimental` 在此处不被接受，会被忽略而不是被拒绝。
239 239
240有关 Claude Code 对无法加载的值的处理，以及跳过该检查的标志和环境变量，请参阅 [`Invalid --agents configuration`](/docs/zh-CN/errors#invalid-agents-configuration)。240有关 Claude Code 如何处理无法加载的值，以及跳过该检查的标志和环境变量，请参阅 [`Invalid --agents configuration`](/docs/zh-CN/errors#invalid-agents-configuration)。
241 241
242**托管 subagents** 由组织管理员部署。在 [managed settings directory](/docs/zh-CN/managed-settings#delivery-mechanisms) 内的 `.claude/agents/` 中放置 markdown 文件，使用与项目和用户 subagents 相同的 frontmatter 格式。托管定义优先于具有相同名称的项目和用户 subagents。242**托管子代理**由组织管理员部署。将 markdown 文件放在[托管设置目录](/docs/zh-CN/managed-settings#delivery-mechanisms)内的 `.claude/agents/` 中，使用与项目和用户子代理相同的 frontmatter 格式。托管定义优先于同名的项目和用户子代理。
243 243
244**Plugin subagents** 来自您已安装的 [plugins](/docs/zh-CN/plugins/overview)。它们与您的自定义 subagents 一起自动加载，并在 @-mention 类型提前中以其范围名称出现。有关创建 plugin subagents 的详细信息，请参阅 [plugin 组件参考](/docs/zh-CN/plugins/components#agents)。244**插件子代理**来自您已安装的[插件](/docs/zh-CN/plugins/overview)。它们会与您的自定义子代理一起自动加载，并以其作用域名称出现在 @ 提及的输入提示中。有关创建插件子代理的详细信息，请参阅[插件组件参考](/docs/zh-CN/plugins/components#agents)。
245 245
246<Note>246<Note>
247 出于安全原因，插件子代理不支持 `hooks`、`mcpServers` 或 `permissionMode` frontmatter 字段。从插件加载 Agent 时，这些字段会被忽略。如果您需要它们，请将 Agent 文件复制到 `.claude/agents/` 或 `~/.claude/agents/`。您也可以在 `settings.json` 或 `settings.local.json` 中向 [`permissions.allow`](/docs/zh-CN/settings-reference#permissions-allow) 添加规则，但这些规则适用于整个会话，而不仅仅是该插件子代理。247 出于安全原因，插件子代理不支持 `hooks`、`mcpServers` 或 `permissionMode` frontmatter 字段。从插件加载 Agent 时，这些字段会被忽略。如果您需要它们，请将 Agent 文件复制到 `.claude/agents/` 或 `~/.claude/agents/` 中。您也可以在 `settings.json` 或 `settings.local.json` 中向 [`permissions.allow`](/docs/zh-CN/settings-reference#permissions-allow) 添加规则，但这些规则适用于整个会话，而不仅仅是插件子代理。
248 248
249 如果您是插件的作者，请改为在插件的 [`hooks/hooks.json`](/docs/zh-CN/plugins/components#hooks) 中提供 hook，并在其 [`.mcp.json`](/docs/zh-CN/plugins/components#mcp-servers) 中提供 MCP 服务器。它们会在插件启用时始终生效，而不仅仅在子代理内部生效。249 如果您是插件的作者，请改为在插件的 [`hooks/hooks.json`](/docs/zh-CN/plugins/components#hooks) 中提供 hook，在其 [`.mcp.json`](/docs/zh-CN/plugins/components#mcp-servers) 中提供 MCP 服务器。它们会在插件启用时生效，而不仅仅在子代理内部生效。
250</Note>250</Note>
251 251
252您还可以将子代理定义复用为 [agent team](/docs/zh-CN/agent-teams) 的队友：在要求 Claude 生成队友时指定子代理类型，Claude Code 会将该定义的部分内容应用于该队友。[将子代理定义用于队友](/docs/zh-CN/agent-teams#use-subagent-definitions-for-teammates)说明了在每种显示模式下适用哪些作用域以及哪些部分。252您还可以将子代理定义复用为 [agent team](/docs/zh-CN/agent-teams) 的队友：在请求 Claude 生成队友时指定子代理类型，Claude Code 会将该定义的部分内容应用于该队友。[将子代理定义用于队友](/docs/zh-CN/agent-teams#use-subagent-definitions-for-teammates)说明了在每种显示模式下适用哪些作用域和哪些部分。
253 253
254<h3 id="write-subagent-files">254<h3 id="write-subagent-files">
255 编写 subagent 文件255 编写子代理文件
256</h3>256</h3>
257 257
258Subagent 文件使用 YAML frontmatter 进行配置，然后是 Markdown 中的系统提示：258子代理文件使用 YAML frontmatter 进行配置，随后是 Markdown 格式的系统提示词：
259 259
260<Note>260<Note>
261 Claude Code 监视 `~/.claude/agents/` 和 `.claude/agents/`。当您在磁盘上添加或编辑 subagent 文件，或要求 Claude 为您编写一个时，Claude Code 会在几秒内检测到更改，下一次委托使用更新的定义，无需重启。261 Claude Code 会监视 `~/.claude/agents/` 和 `.claude/agents/`。当您在磁盘上添加或编辑子代理文件，或让 Claude 为您编写一个时，Claude Code 会在几秒钟内检测到更改，下一次委派将使用更新后的定义，无需重启。
262 262
263 三种情况仍然需要重启：263 以下三种情况仍需要重启：
264 264
265 * 监视器仅涵盖会话启动时存在的目录，因此在新 `agents` 目录中创建范围的第一个代理文件后，重启以加载它。265 * 监视器只覆盖会话启动时已存在的目录，因此在新的 `agents` 目录中创建某个作用域的第一个 Agent 文件后，需要重启才能加载它。
266 * Claude Code 不监视通过 `--add-dir` 或 `/add-dir` 添加的目录内的 `.claude/agents/`，因此在那里添加或编辑 subagent 后，重启以加载更改。266 * Claude Code 不会监视通过 `--add-dir` 或 `/add-dir` 添加的目录中的 `.claude/agents/`，因此在那里添加或编辑子代理后，需要重启才能加载更改。
267 * 使用 `--disable-slash-commands` 启动的会话根本不监视这些目录。267 * 使用 `--disable-slash-commands` 启动的会话完全不会监视这些目录。
268</Note>268</Note>
269 269
270```markdown .claude/agents/code-reviewer.md theme={null}270```markdown .claude/agents/code-reviewer.md theme={null}
279specific, actionable feedback on quality, security, and best practices.279specific, actionable feedback on quality, security, and best practices.
280```280```
281 281
282Frontmatter 定义了 subagent 的元数据和配置。正文成为指导 subagent 行为的系统提示。Subagents 仅接收此系统提示加上基本环境详细信息（如工作目录），而不是 Claude Code 系统提示。282frontmatter 定义子代理的元数据和配置。正文成为指导子代理行为的系统提示词。子代理只接收此系统提示词以及基本的环境详细信息（如工作目录），而不接收 Claude Code 的系统提示词。
283 283
284在 [non-interactive mode](/docs/zh-CN/headless) 中，传递 [`--append-subagent-system-prompt`](/docs/zh-CN/cli-reference#cli-flags) 以将您的文本附加到每个 subagent 的系统提示末尾，包括嵌套 subagents，除了 [forked subagent](#fork-the-current-conversation)，它重用对话自己的提示。需要 Claude Code v2.1.205 或更高版本。如果您的文本太长而无法在命令行上传递，请将其保存到文件并使用 `--append-subagent-system-prompt-file` 传递路径。文件标志需要 Claude Code v2.1.261 或更高版本。284在[非交互模式](/docs/zh-CN/headless)下，传入 [`--append-subagent-system-prompt`](/docs/zh-CN/cli-reference#cli-flags) 可将您的文本追加到每个子代理（包括嵌套子代理）的系统提示词末尾，但[分叉子代理](#fork-the-current-conversation)除外，它复用对话自身的提示词。需要 Claude Code v2.1.205 或更高版本。如果您的文本太长而无法在命令行中传入，请将其保存到文件中，并改用 `--append-subagent-system-prompt-file` 传入路径。文件标志需要 Claude Code v2.1.261 或更高版本。
285 285
286一个 subagent 在主对话的当前工作目录中启动。在 subagent 中，`cd` 命令不会在 Bash 或 PowerShell 工具调用之间持续，也不会影响主对话的工作目录。要给 subagent 一个隔离的存储库副本，请改为设置 [`isolation: worktree`](#supported-frontmatter-fields)。286子代理在主对话的当前工作目录中启动。在子代理中，`cd` 命令不会在 Bash 或 PowerShell 工具调用之间保留，也不会影响主对话的工作目录。若要为子代理提供仓库的隔离副本，请设置 [`isolation: worktree`](#supported-frontmatter-fields)。
287 287
288具有 `isolation: worktree` 的子代理会在其 worktree 内运行 Bash 和 PowerShell 命令。如果某个命令的工作目录解析到了您的主检出，例如因为 worktree 目录在子代理运行期间被删除，该命令会失败并报错。288设置了 `isolation: worktree` 的子代理会在其 worktree 内运行 Bash 和 PowerShell 命令。如果某个命令的工作目录解析为您的主检出目录（例如因为 worktree 目录在子代理运行期间被删除），该命令会失败并报错。
289 289
290此工作目录检查涵盖包含您启动 Claude Code 的目录的整个存储库。当您的会话在其自己的链接 [worktree](/docs/zh-CN/worktrees) 中运行时，检查也涵盖该 worktree 链接的主检出。在 v2.1.210 之前，检查仅涵盖启动目录本身。一个工作目录解析到同一存储库中其他地方的命令，例如当您从 monorepo 子目录启动 Claude Code 时的存储库根目录，会在那里运行而不是失败。290此工作目录检查覆盖包含您启动 Claude Code 的目录的整个仓库。当您的会话本身运行在一个链接的 [worktree](/docs/zh-CN/worktrees) 中时，该检查还覆盖该 worktree 所链接的主检出目录。
291 291
292对于 Bash 命令，Claude Code 还以两种方式检查命令本身：292对于 Bash 命令，Claude Code 还会从两个方面检查命令本身：
293 293
294* 它阻止将 git 重定向到主检出的命令。294* 它会阻止将 git 重定向到主检出目录的命令。
295* 当它无法从命令文本验证命令运行的任何 git 都保留在 worktree 内时，它拒绝命令，例如当命令名称在运行时计算时。295* 当无法从命令文本中验证命令运行的任何 git 都停留在 worktree 内时（例如命令名称是在运行时计算的），它会拒绝该命令。
296 296
297重定向向量和形状规则列在 [How Claude Code enforces isolation](/docs/zh-CN/worktrees#how-claude-code-enforces-isolation) 下。PowerShell 命令仅获得工作目录检查。297重定向途径和形式规则列在[Claude Code 如何强制执行隔离](/docs/zh-CN/worktrees#how-claude-code-enforces-isolation)中。PowerShell 命令只进行工作目录检查。
298 298
299[Monitor](/docs/zh-CN/tools-reference#monitor-tool) 命令通过与 Bash 命令相同的工作目录和命令内容检查。299[Monitor](/docs/zh-CN/tools-reference#monitor-tool) 命令与 Bash 命令一样，会经过相同的工作目录和命令内容检查。
300 300
301当主对话本身在 worktree 中隔离运行时，Claude Code 对会话和它生成的每个 subagent 应用相同的检查，包括没有 `isolation: worktree` 的 subagents；请参阅 [How Claude Code enforces isolation](/docs/zh-CN/worktrees#how-claude-code-enforces-isolation)。301当主对话本身在 worktree 中隔离运行时，Claude Code 会对会话及其生成的每个子代理应用相同的检查，包括没有设置 `isolation: worktree` 的子代理；请参阅[Claude Code 如何强制执行隔离](/docs/zh-CN/worktrees#how-claude-code-enforces-isolation)。
302 302
303<h3 id="supported-frontmatter-fields">303<h3 id="supported-frontmatter-fields">
304 Frontmatter 参考304 Frontmatter 参考
305</h3>305</h3>
306 306
307配置一个 subagent 时，使用 YAML [frontmatter](/docs/zh-CN/glossary#frontmatter) 在其文件顶部的 `---` 标记之间，并在关闭 `---` 后将其系统提示写为 Markdown。只有 `name` 和 `description` 是必需的。307使用子代理文件顶部 `---` 标记之间的 YAML [frontmatter](/docs/zh-CN/glossary#frontmatter) 来配置子代理，并在结束的 `---` 之后以 Markdown 编写其系统提示词。只有 `name` 和 `description` 是必需的。
308 308
309多词字段名称使用 camelCase，例如 `maxTurns` 和 `disallowedTools`，并且必须与表格完全一致：Claude Code 会忽略它不识别的字段，且不报告错误。309多词字段名使用 camelCase，例如 `maxTurns` 和 `disallowedTools`，并且必须与表格完全一致：Claude Code 会忽略无法识别的字段，且不报告错误。
310 310
311* 要在已加载的子代理中查找拼写错误的字段，请在 shell 中运行 [`claude --debug`](/docs/zh-CN/cli-reference#cli-flags)，并在 `~/.claude/debug/<session-id>.txt` 的调试日志中搜索 `does not recognize or apply`。调试日志会列出子代理文件中 Claude Code 不识别的最多五个顶级字段，并在存在相近的受支持字段时给出可能想要的名称。需要 Claude Code v2.1.296 或更高版本。311* 若要在已加载的子代理中查找拼写错误的字段，请在 shell 中运行 [`claude --debug`](/docs/zh-CN/cli-reference#cli-flags)，并在 `~/.claude/debug/<session-id>.txt` 的调试日志中搜索 `does not recognize or apply`。调试日志会列出子代理文件中最多五个 Claude Code 无法识别的顶层字段，并在存在相近的受支持字段时给出可能想写的名称。需要 Claude Code v2.1.296 或更高版本。
312* 要了解子代理文件为何未加载，请参阅[Claude Code 跳过的子代理文件](#subagent-files-claude-code-skips)。312* 若要了解子代理文件为何未加载，请参阅 [Claude Code 跳过的子代理文件](#subagent-files-claude-code-skips)。
313 313
314| Field | 必需 | Description |314| 字段 | 必需 | 描述 |
315| :- | :- | :- |315| :- | :- | :- |
316| `name` | 是 | 最多 256 个字符的唯一标识符，例如 `code-reviewer` 或 `reviewer-v2`。[Hook](/docs/zh-CN/hooks#subagentstart) 以 `agent_type` 的形式接收此值。文件名不必与之一致。名称不能包含 `:`，该字符保留用于[插件作用域标识符](/docs/zh-CN/plugins/overview)，例如 `my-plugin:reviewer` |316| `name` | 是 | 最多 256 个字符的唯一标识符，例如 `code-reviewer` 或 `reviewer-v2`。[Hook](/docs/zh-CN/hooks#subagentstart) 以 `agent_type` 的形式接收此值。文件名不必与之匹配。名称不能包含 `:`，它保留给[插件作用域标识符](/docs/zh-CN/plugins/overview)，例如 `my-plugin:reviewer` |
317| `description` | 是 | Claude 何时应该委托给此 subagent |317| `description` | 是 | Claude 应在何时委派给此子代理 |
318| `tools` | 否 | [Tools](#available-tools) subagent 可以使用，作为逗号分隔的字符串，例如 `Read, Grep, Bash` 或 YAML 列表。如果省略，继承 subagents 可用的每个工具。如果列表中没有条目解析为工具，subagent 通常 [fails to launch](/docs/zh-CN/errors#agent-would-be-spawned-with-zero-tools) 并出现错误，命名条目。要将 Skills 预加载到上下文中，请使用 `skills` 字段而不是在此处列出 `Skill` |318| `tools` | 否 | 子代理可以使用的[工具](#available-tools)，可以是逗号分隔的字符串（如 `Read, Grep, Bash`）或 YAML 列表。省略时继承子代理可用的所有工具。如果列表中没有任何条目能解析为工具，子代理通常会[启动失败](/docs/zh-CN/errors#agent-would-be-spawned-with-zero-tools)，并报告列出这些条目的错误。若要将 skill 预加载到上下文中，请使用 `skills` 字段，而不是在此处列出 `Skill` |
319| `disallowedTools` | 否 | 要拒绝的工具，会从继承的或指定的列表中移除。格式与 `tools` 相同。带有说明符的条目（例如 `Bash(git push *)`）仍会[移除整个工具](#restrict-which-tools-a-subagent-can-use) |319| `disallowedTools` | 否 | 要拒绝的工具，从继承的或指定的列表中移除。格式与 `tools` 相同。带有说明符的条目（如 `Bash(git push *)`）仍会[移除整个工具](#restrict-which-tools-a-subagent-can-use) |
320| `model` | 否 | [Model](#choose-a-model) 使用：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（例如，`claude-opus-5-5`）或 `inherit`。当您省略它时，Claude Code 在 [subagent model order](#choose-a-model) 中选择模型 |320| `model` | 否 | 要使用的[模型](#choose-a-model)：`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（如 `claude-opus-5-5`）或 `inherit`。省略时，Claude Code 按照[子代理模型顺序](#choose-a-model)选择模型 |
321| `permissionMode` | 否 | [权限模式](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan`，或作为 `default` 别名的 `manual`。对[插件子代理](#choose-the-subagent-scope)会被忽略 |321| `permissionMode` | 否 | [权限模式](#permission-modes)：`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan`，或作为 `default` 别名的 `manual`。对[插件子代理](#choose-the-subagent-scope)忽略 |
322| `maxTurns` | 否 | subagent 停止前的最大代理轮数。当 subagent 达到限制时，Claude Code 返回其输出标记为部分，Claude 可以 [resume it](#resume-subagents) 继续。部分标记需要 Claude Code v2.1.246 或更高版本 |322| `maxTurns` | 否 | 子代理停止前的最大 Agent 轮次数。当子代理达到限制时，Claude Code 会返回其标记为部分结果的输出，Claude 可以[恢复它](#resume-subagents)以继续。部分结果标记需要 Claude Code v2.1.246 或更高版本 |
323| `autoCompactWindow` | 否 | 将此子代理的[自动压缩窗口](#subagent-auto-compact-window)降低到 `100000` 至 `1000000` 之间的 token 数。需要 Claude Code v2.1.296 或更高版本 |323| `autoCompactWindow` | 否 | 将此子代理的[自动压缩窗口](#subagent-auto-compact-window)降低到 `100000` 至 `1000000` 之间的 token 数。需要 Claude Code v2.1.296 或更高版本 |
324| `skills` | 否 | [Skills](/docs/zh-CN/skills) 在启动时预加载到 subagent 的上下文中。注入完整的技能内容，而不仅仅是描述。Subagents 仍然可以通过 Skill 工具调用未列出的项目、用户和 plugin 技能 |324| `skills` | 否 | 启动时预加载到子代理上下文中的 [skill](/docs/zh-CN/skills)。注入的是完整的 skill 内容，而不仅仅是描述。子代理仍可通过 Skill 工具调用未列出的项目、用户和插件 skill |
325| `mcpServers` | 否 | [MCP servers](/docs/zh-CN/mcp) 对此 subagent 可用。每个条目要么是引用已配置服务器的服务器名称（例如，`"slack"`），要么是内联定义，其中服务器名称为键，完整的 [MCP server config](/docs/zh-CN/mcp#installing-mcp-servers) 为值。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |325| `mcpServers` | 否 | 此子代理可用的 [MCP 服务器](/docs/zh-CN/mcp)。每个条目可以是引用已配置服务器的服务器名称（例如 `"slack"`），也可以是以服务器名称为键、以完整 [MCP 服务器配置](/docs/zh-CN/mcp#installing-mcp-servers)为值的内联定义。对[插件子代理](#choose-the-subagent-scope)忽略 |
326| `hooks` | 否 | [Lifecycle hooks](#define-hooks-for-subagents) 限定于此 subagent。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |326| `hooks` | 否 | 限定于此子代理的[生命周期 hook](#define-hooks-for-subagents)。对[插件子代理](#choose-the-subagent-scope)忽略 |
327| `memory` | 否 | [Persistent memory scope](#enable-persistent-memory)：`user`、`project` 或 `local`。启用跨会话学习 |327| `memory` | 否 | [持久记忆作用域](#enable-persistent-memory)：`user`、`project` 或 `local`。启用跨会话学习 |
328| `background` | 否 | 设置为 `true` 以即使 Claude 要求在前台运行也保持此 subagent 在后台。其中 [fork mode](#turn-fork-mode-on-or-off) 打开时，Claude Code 已经在 [background](#run-subagents-in-foreground-or-background) 中运行 Claude 生成的 subagents |328| `background` | 否 | 设置为 `true` 可使此子代理保持在后台运行，即使 Claude 要求等待它。默认情况下，Claude 从主对话生成的子代理已经会[在后台启动](#run-subagents-in-foreground-or-background) |
329| `omitClaudeMd` | 否 | 设置为 `true` 可使此子代理在启动时，其[初始上下文](#what-loads-at-startup)中不包含用户、项目和本地 CLAUDE.md 文件；[托管策略文件](/docs/zh-CN/memory#how-claude-md-files-load)仍会加载，但[托管子代理](#choose-the-subagent-scope)除外。适用于从委托提示词中获取所需一切的子代理。当该 Agent 通过 `--agent` 或 `agent` 设置作为主会话 Agent 运行时会被忽略。需要 Claude Code v2.1.271 或更高版本 |329| `omitClaudeMd` | 否 | 设置为 `true` 可使此子代理在启动时的[初始上下文](#what-loads-at-startup)中不包含用户、项目和本地 CLAUDE.md 文件；[托管策略文件](/docs/zh-CN/memory#how-claude-md-files-load)仍会加载，但[托管子代理](#choose-the-subagent-scope)除外。适用于从委派提示词中获取所需全部信息的子代理。当 Agent 通过 `--agent` 或 `agent` 设置作为主会话 Agent 运行时忽略。需要 Claude Code v2.1.271 或更高版本 |
330| `effort` | 否 | 此子代理活跃时的 effort 级别。覆盖会话的 effort 级别，但不覆盖 [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars#variables) 环境变量。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型。请参阅[选择 effort 级别](#choose-an-effort-level) |330| `effort` | 否 | 此子代理活动时的 effort 级别。覆盖会话的 effort 级别，但不覆盖 [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars#variables) 环境变量。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型。请参阅[选择 effort 级别](#choose-an-effort-level) |
331| `isolation` | 否 | 设置为 `worktree` 以在临时 [git worktree](/docs/zh-CN/worktrees) 中运行 subagent，为其提供存储库的隔离副本，默认从您的 [default branch](/docs/zh-CN/worktrees#choose-the-base-branch) 分支，而不是父会话的 `HEAD`。如果 subagent 不进行任何更改，worktree 会自动清理 |331| `isolation` | 否 | 设置为 `worktree` 可在临时 [git worktree](/docs/zh-CN/worktrees) 中运行子代理，为其提供仓库的隔离副本，默认从您的[默认分支](/docs/zh-CN/worktrees#choose-the-base-branch)而不是父会话的 `HEAD` 创建分支。如果子代理未做任何更改，worktree 会被自动清理 |
332| `color` | 否 | Subagent 在任务列表和转录中的显示颜色。接受 `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink` 或 `cyan` |332| `color` | 否 | 子代理在任务列表和会话记录中的显示颜色。接受 `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink` 或 `cyan` |
333| `initialPrompt` | 否 | 当此代理作为主会话代理运行时（通过 `--agent` 或 `agent` 设置），自动提交为第一个用户轮次。[Commands](/docs/zh-CN/commands) 和 [skills](/docs/zh-CN/skills) 被处理。前置于任何用户提供的提示。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |333| `initialPrompt` | 否 | 当此 Agent 作为主会话 Agent 运行时（通过 `--agent` 或 `agent` 设置），作为第一个用户轮次自动提交。会处理其中的[命令](/docs/zh-CN/commands)和 [skill](/docs/zh-CN/skills)。添加在任何用户提供的提示词之前。对[插件子代理](#choose-the-subagent-scope)忽略 |
334| `experimental` | 否 | 实验选项的映射。将其 `cacheTtl` 键设置为 `5m` 或 `1h` 以选择此 subagent 请求的 [prompt cache lifetime](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself)，在 frontmatter 的 [cache lifetime precedence](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself) 中的位置。Claude Code 忽略任何其他值，在您的 Claude 订阅使用使用额度时忽略 `1h`，并仅从 subagent 文件读取字段。需要 Claude Code v2.1.248 或更高版本 |334| `experimental` | 否 | 实验性选项的映射。将其 `cacheTtl` 键设置为 `5m` 或 `1h`，可为此子代理的请求选择[提示缓存生命周期](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself)，其优先级取决于 frontmatter 在[缓存生命周期优先级](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself)中的位置。Claude Code 会忽略任何其他值，在您的 Claude 订阅使用使用额度时忽略 `1h`，并且只从子代理文件中读取该字段。需要 Claude Code v2.1.248 或更高版本 |
335 335
336在 `experimental` 映射内写入 `cacheTtl`，而不是在 frontmatter 的顶级。336请将 `cacheTtl` 写在 `experimental` 映射内，而不是 frontmatter 的顶层。
337 337
338```yaml theme={null}338```yaml theme={null}
339---339---
345```345```
346 346
347<h4 id="subagent-files-claude-code-skips">347<h4 id="subagent-files-claude-code-skips">
348 Subagent 文件 Claude Code 跳过348 Claude Code 跳过的子代理文件
349</h4>349</h4>
350 350
351Claude Code 跳过项目、用户或托管 `agents` 目录中的文件，或在您使用 `--add-dir` 添加的目录下的文件，而不在会话中报告它，当 frontmatter 有以下任何问题时：351当项目、用户或托管 `agents` 目录中的文件，或您通过 `--add-dir` 添加的目录下的 `agents` 目录中的文件的 frontmatter 存在以下任一问题时，Claude Code 会跳过该文件，且不会在会话中报告：
352 352
353* **没有 `name`**：Claude Code 将文件视为保存在您的代理旁边的文档。353* **没有 `name`**：Claude Code 将该文件视为与您的 Agent 放在一起的文档。
354* **一个开始 `---` 不是文件的第一行**：Claude Code 读取文件为没有 frontmatter，并将其视为文档。354* **开头的 `---` 不在文件第一行**：Claude Code 认为该文件没有 frontmatter，并将其视为文档。
355* **`name` 以 `-` 开头、包含 `:` 或超过 256 个字符**：Claude Code 跳过该文件，并向调试日志写入一条错误。355* **`name` 以 `-` 开头、包含 `:` 或超过 256 个字符**：Claude Code 跳过该文件，并将错误写入调试日志。
356* **一个 `name` 但没有 `description`**：Claude Code 跳过文件并向调试日志写入原因。356* **有 `name` 但没有 `description`**：Claude Code 跳过该文件，并将原因写入调试日志。
357* **不解析的 YAML**：Claude Code 从文件读取没有字段，跳过它，并向调试日志写入解析错误。357* **YAML 无法解析**：Claude Code 不从该文件读取任何字段，跳过它，并将解析错误写入调试日志。
358 358
359要查看调试日志，使用 `--debug` 运行 Claude Code。359若要查看调试日志，请使用 `--debug` 运行 Claude Code。
360 360
361一个 [plugin subagent](/docs/zh-CN/plugins/components#agents)，其 frontmatter 没有 `name` 或不解析，仍然加载，在其文件名下。361如果[插件子代理](/docs/zh-CN/plugins/components#agents)的 frontmatter 没有 `name` 或无法解析，它仍会以其文件名加载。
362 362
363<h5 id="check-an-agents-directory-before-a-session">363<h5 id="check-an-agents-directory-before-a-session">
364 在会话前检查 `agents` 目录364 在会话开始前检查 `agents` 目录
365</h5>365</h5>
366 366
367要查找 `agents` 目录中 frontmatter 不解析的文件，针对目录运行 `claude plugin validate`，例如 `.claude/agents` 或 `~/.claude/agents`。Claude Code 仅检查 [您命名的目录](/docs/zh-CN/plugins/cli-reference#validate-a-directory)，并不标记 frontmatter 解析但没有 `name` 的文件。需要 Claude Code v2.1.233 或更高版本。367若要查找 `agents` 目录中 frontmatter 无法解析的文件，请针对该目录（例如 `.claude/agents` 或 `~/.claude/agents`）运行 `claude plugin validate`。Claude Code 只检查[您指定的目录](/docs/zh-CN/plugins/cli-reference#validate-a-directory)，并且不会标记 frontmatter 可解析但没有 `name` 的文件。需要 Claude Code v2.1.233 或更高版本。
368 368
369<h3 id="choose-a-model">369<h3 id="choose-a-model">
370 选择模型370 选择模型
371</h3>371</h3>
372 372
373`model` 字段控制 subagent 使用的模型：373`model` 字段控制子代理使用哪个模型：
374 374
375* **Model alias**：使用可用的别名之一：`sonnet`、`opus`、`haiku` 或 `fable`375* **模型别名**：使用可用别名之一：`sonnet`、`opus`、`haiku` 或 `fable`
376* **Full model ID**：使用完整的模型 ID，例如 `claude-opus-5-5` 或 `claude-sonnet-5`。接受与 `--model` 标志相同的值376* **完整模型 ID**：使用完整模型 ID，例如 `claude-opus-5-5` 或 `claude-sonnet-5`。接受与 `--model` 标志相同的值
377* **inherit**：使用与主对话相同的模型377* **inherit**：使用与主对话相同的模型
378 378
379当 Claude 调用 subagent 时，它也可以为该特定调用传递 `model` 参数。Claude Code 按以下顺序解析 subagent 的模型：379当 Claude 调用子代理时，它还可以为该次调用传入 `model` 参数。Claude Code 按以下顺序确定子代理的模型：
380 380
3811. 每次调用的 `model` 参数3811. 单次调用的 `model` 参数
3822. Subagent 定义的 `model` frontmatter，其中 `inherit` 选择主对话的模型3822. 子代理定义中的 `model` frontmatter，其中 `inherit` 选择主对话的模型
3833. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-CN/model-config#environment-variables) 环境变量，当您将其设置为模型别名或模型 ID 时3833. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-CN/model-config#environment-variables) 环境变量（当您将其设置为模型别名或模型 ID 时）
3844. 主对话的模型3844. 主对话的模型
385 385
386如果已安装的 [mod](/docs/zh-CN/plugins/mods/overview) 在其 [`agent.spawn`](/docs/zh-CN/plugins/mods/reference#subagents) hook 中设置了模型，Claude Code 会使用该模型来代替每次调用的参数。386如果已安装的 [mod](/docs/zh-CN/plugins/mods/overview) 在其 [`agent.spawn`](/docs/zh-CN/plugins/mods/reference#subagents) hook 中设置了模型，Claude Code 会使用该模型来代替单次调用的参数。
387 387
388在两种情况下，家族别名（例如 frontmatter 或每次调用的参数中的 `opus`）解析到主对话的模型，而不是 [alias points to](/docs/zh-CN/model-config#model-aliases) 的版本：388在两种情况下，单次调用参数或 frontmatter 中的系列别名（如 `opus`）会解析为主对话的模型，而不是[该别名指向的版本](/docs/zh-CN/model-config#model-aliases)：
389 389
390* **主对话的模型属于该家族**：subagent 在主对话的确切模型上运行，包括任何 `[1m]` 后缀，因此它获得与主对话相同的 [extended context](/docs/zh-CN/model-config#extended-context) 窗口。390* **主对话的模型属于该系列**：子代理在主对话的确切模型上运行，包括任何 `[1m]` 后缀，因此它获得与主对话相同的[扩展上下文](/docs/zh-CN/model-config#extended-context)窗口。
391* **Claude Code 无法告诉主对话的模型家族，在 [a provider other than the Anthropic API](/docs/zh-CN/third-party-integrations) 上**：这可能发生在 Amazon Bedrock 上的 [application inference profile ARN](/docs/zh-CN/amazon-bedrock#iam-configuration)，Claude Code 尚未解析为支持模型。这种情况仅涵盖 `opus` 别名，当您设置 [`ANTHROPIC_DEFAULT_OPUS_MODEL`](/docs/zh-CN/model-config#environment-variables) 时不适用，因为 `opus` 然后解析到您设置的模型。391* **在 [Anthropic API 以外的提供商](/docs/zh-CN/third-party-integrations)上，Claude Code 无法判断主对话的模型系列**：这可能发生在 Amazon Bedrock 上使用 Claude Code 尚未解析到后端模型的[应用推理配置文件 ARN](/docs/zh-CN/amazon-bedrock#iam-configuration) 时。这种情况仅涵盖 `opus` 别名，并且在您设置了 [`ANTHROPIC_DEFAULT_OPUS_MODEL`](/docs/zh-CN/model-config#environment-variables) 时不适用，因为此时 `opus` 会解析为您设置的模型。
392 392
393`CLAUDE_CODE_SUBAGENT_MODEL` 中的别名始终解析为该别名指向的版本，即使它指定的是主对话所属的系列。将该变量设置为 `inherit` 与不设置它相同。393`CLAUDE_CODE_SUBAGENT_MODEL` 中的别名始终解析为该别名指向的版本，即使它指向主对话的系列。将该变量设置为 `inherit` 等同于不设置它。
394 394
395设置 `CLAUDE_CODE_SUBAGENT_MODEL` 本身不会改变内置 Explore 和 Plan subagents 运行的模型。要改变它，请参阅 [Run every subagent on one model](#run-every-subagent-on-one-model)。395仅设置 `CLAUDE_CODE_SUBAGENT_MODEL` 不会改变内置 Explore 和 Plan 子代理所运行的模型。若要更改，请参阅[让所有子代理在同一模型上运行](#run-every-subagent-on-one-model)。
396 396
397在 v2.1.251 之前，`CLAUDE_CODE_SUBAGENT_MODEL` 在此顺序中排在第一位，并覆盖每次调用的参数和 frontmatter，包括 `model: inherit`。397在 v2.1.251 之前，`CLAUDE_CODE_SUBAGENT_MODEL` 在此顺序中排在首位，会覆盖单次调用参数和 frontmatter，包括 `model: inherit`。
398 398
399Claude Code 根据您组织的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表检查每次调用的参数、frontmatter 和环境变量值。对于被阻止的值，它替换另一个模型：399Claude Code 会根据您组织的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表检查单次调用参数、frontmatter 和环境变量的值。对于被阻止的值，它会替换为另一个模型：
400 400
401* 当被阻止的值是家族别名（例如 `opus`）时，Claude Code 在允许列表允许的该家族的最新版本上运行 subagent，遵循与 `/model` 相同的 [substitution rules and provider scope](/docs/zh-CN/model-config#restrict-model-selection)。在 v2.1.222 之前，Claude Code 也在继承的模型上为被阻止的家族别名运行 subagent。401* 当被阻止的值是系列别名（如 `opus`）时，Claude Code 会在允许列表允许的该系列最新版本上运行子代理，遵循与 `/model` 相同的[替换规则和提供商范围](/docs/zh-CN/model-config#restrict-model-selection)。在 v2.1.222 之前，对于被阻止的系列别名，Claude Code 同样会在继承的模型上运行子代理。
402* 对于任何其他被阻止的值，在该替换不运行的提供商上，或当允许列表允许该家族的没有版本时，Claude Code 改为在继承的模型上运行 subagent。如果您设置 `CLAUDE_CODE_SUBAGENT_MODEL`，Claude Code 首先尝试该模型，在这些相同的规则下。402* 对于任何其他被阻止的值、在该替换不起作用的提供商上，或者当允许列表不允许该系列的任何版本时，Claude Code 会改为在继承的模型上运行子代理。如果您设置了 `CLAUDE_CODE_SUBAGENT_MODEL`，Claude Code 会按照同样的规则首先尝试该模型。
403 403
404在交互式会话中，Claude Code 显示一个警告，命名请求的模型和 subagent 运行的模型，对于任一替换。404在交互式会话中，对于上述任一种替换，Claude Code 都会显示一条警告，列出请求的模型和子代理实际运行的模型。
405 405
406要检查子代理运行在哪个模型上，请运行 [`/tasks`](/docs/zh-CN/commands)。Claude Code 会在子代理所在行显示模型名称，并在为该子代理设置了 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)时一并显示。需要 Claude Code v2.1.242 或更高版本。406若要查看子代理正在哪个模型上运行，请运行 [`/tasks`](/docs/zh-CN/commands)。Claude Code 会在子代理所在行显示模型名称，并附上为该子代理设置的 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)（如果有）。需要 Claude Code v2.1.242 或更高版本。
407 407
408每次调用的 `model` 参数也适用于 subagent 何时 [resumed or sent a follow-up message](#resume-subagents)，因此 subagent 保持在该模型上。在 v2.1.211 之前，恢复删除了每次调用的值，subagent 恢复到其定义的 `model` 字段或，没有一个，主对话的模型。408当子代理被[恢复或收到后续消息](#resume-subagents)时，单次调用的 `model` 参数同样适用，因此子代理会保持在该模型上。
409 409
410从 v2.1.198 开始，subagents 也继承主对话的 [extended thinking](/docs/zh-CN/model-config#extended-thinking) 配置：如果在您的会话中启用了思考，对于 subagent 也启用，如果关闭，则保持关闭。没有每个 subagent 的思考设置。在 v2.1.198 之前，subagents 运行时禁用了扩展思考，无论主对话的设置如何。410从 v2.1.198 开始，子代理还会继承主对话的[扩展思考](/docs/zh-CN/model-config#extended-thinking)配置：如果您的会话中启用了思考，子代理也会启用；如果关闭，它也保持关闭。没有针对单个子代理的思考设置。在 v2.1.198 之前，无论主对话的设置如何，子代理都在禁用扩展思考的情况下运行。
411 411
412<h4 id="run-every-subagent-on-one-model">412<h4 id="run-every-subagent-on-one-model">
413 在一个模型上运行每个 subagent413 让所有子代理在同一模型上运行
414</h4>414</h4>
415 415
416`CLAUDE_CODE_SUBAGENT_MODEL` 是一个默认值，因此 subagent 的定义或 Claude 传递的模型仍然优先于它。要将一个模型应用于每个 subagent、[teammate](/docs/zh-CN/agent-teams#specify-teammates-and-models) 和 [workflow agent](/docs/zh-CN/workflows)，也设置 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` 为 `1`。需要 Claude Code v2.1.257 或更高版本。416`CLAUDE_CODE_SUBAGENT_MODEL` 是一个默认值，因此子代理的定义或 Claude 传入的模型仍优先于它。若要将同一模型应用于每个子代理、[队友](/docs/zh-CN/agent-teams#specify-teammates-and-models)和[工作流 Agent](/docs/zh-CN/workflows)，还需将 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` 设置为 `1`。需要 Claude Code v2.1.257 或更高版本。
417 417
418* 如果您设置两个变量，subagents 在 `CLAUDE_CODE_SUBAGENT_MODEL` 中的模型上运行。418* 如果同时设置了这两个变量，子代理会在 `CLAUDE_CODE_SUBAGENT_MODEL` 中的模型上运行。
419* 如果仅设置 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`，子代理将在主对话的模型上运行，但内置 Explore 子代理除外，它会在[内置子代理下为其列出的模型](#built-in-subagents)上运行。419* 如果只设置了 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`，子代理会在主对话的模型上运行，但内置 Explore 子代理除外，它在[内置子代理下为其列出的模型](#built-in-subagents)上运行。
420 420
421例如，要在 Haiku 上运行每个 subagent，在 [settings file](/docs/zh-CN/settings) 的 `env` 块中设置两个变量：421例如，若要让所有子代理都在 Haiku 上运行，请在[设置文件](/docs/zh-CN/settings)的 `env` 块中同时设置这两个变量：
422 422
423```json theme={null}423```json theme={null}
424{424{
429}429}
430```430```
431 431
432要检查设置是否生效，在 subagent 运行时运行 [`/tasks`](/docs/zh-CN/commands)。Subagent 的行显示它运行的模型。432若要检查设置是否生效，请在子代理运行时运行 [`/tasks`](/docs/zh-CN/commands)。子代理所在行会显示它所运行的模型。
433 433
434当 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` [启用](/docs/zh-CN/env-vars)时，Claude Code 会忽略子代理定义中的 `model` 字段，Claude 在启动子代理时也无法传递模型。以下子代理仍在主对话的模型上运行：434当 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` [启用](/docs/zh-CN/env-vars)时，Claude Code 会忽略子代理定义中的 `model` 字段，并且 Claude 在启动子代理时无法传入模型。以下子代理仍在主对话的模型上运行：
435 435
436* 一个 [fork](#fork-the-current-conversation)436* [分叉](#fork-the-current-conversation)
437* 一个 [skill that runs in a subagent](/docs/zh-CN/skills#run-skills-in-a-subagent)，带有 `model: inherit`437* 设置了 `model: inherit` 的[在子代理中运行的 skill](/docs/zh-CN/skills#run-skills-in-a-subagent)
438 438
439<h3 id="choose-an-effort-level">439<h3 id="choose-an-effort-level">
440 选择 effort 级别440 选择 effort 级别
441</h3>441</h3>
442 442
443要让子代理以其自身的 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)运行，请在其定义中设置 [`effort`](#supported-frontmatter-fields) 字段。443若要让子代理以其自己的 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)运行，请在其定义中设置 [`effort`](#supported-frontmatter-fields) 字段。
444 444
445当您要求 Claude 以特定 effort 级别运行非分叉子代理时，Claude 也可以为该次调用传递一个 `effort` 参数。该参数会覆盖 `effort` 字段，并在子代理被[恢复](#resume-subagents)时保持有效。[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars#variables) 环境变量优先于这两者。每次调用的参数需要 Claude Code v2.1.292 或更高版本。445当您要求 Claude 以特定 effort 级别运行非分叉子代理时，它还可以为该次调用传入 `effort` 参数。该参数会覆盖 `effort` 字段，并在子代理被[恢复](#resume-subagents)时保持有效。[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars#variables) 环境变量优先于这两者。单次调用参数需要 Claude Code v2.1.292 或更高版本。
446 446
447<h3 id="control-subagent-capabilities">447<h3 id="control-subagent-capabilities">
448 控制 subagent 能力448 控制子代理的能力
449</h3>449</h3>
450 450
451您可以通过工具访问、权限模式和条件规则来控制 subagents 可以做什么。451您可以通过工具访问、权限模式和条件规则来控制子代理能做什么。
452 452
453<h4 id="available-tools">453<h4 id="available-tools">
454 可用工具454 可用工具
455</h4>455</h4>
456 456
457Subagents 继承主对话中可用的 [built-in tools](/docs/zh-CN/tools-reference) 和 MCP 工具，由两个过滤器缩小：第一个从每个 subagent 删除工具的短列表，第二个为在 [background](#run-subagents-in-foreground-or-background) 中运行的 subagents 减少内置工具集，这是默认值。在 macOS、Linux 和 WSL 上，当主对话没有 Glob 和 Grep 工具时，subagent 也可以接收它们，如 [Glob tool behavior](/docs/zh-CN/tools-reference#glob-tool-behavior) 下所述。[Forks](#fork-the-current-conversation) 跳过两个过滤器并接收主对话的确切工具池。第一个过滤器删除这些工具，即使在 `tools` 字段中列出：457子代理继承主对话中可用的[内置工具](/docs/zh-CN/tools-reference)和 MCP 工具，并经过两个过滤器的缩减：第一个过滤器从每个子代理中移除少量工具，第二个过滤器为在[后台](#run-subagents-in-foreground-or-background)运行的子代理（默认情况）缩减内置工具集。在 macOS、Linux 和 WSL 上，当主对话没有 Glob 和 Grep 工具时，子代理也可以获得这些工具，如 [Glob 工具行为](/docs/zh-CN/tools-reference#glob-tool-behavior)中所述。[分叉](#fork-the-current-conversation)会跳过这两个过滤器，获得与主对话完全相同的工具池。第一个过滤器会移除以下工具，即使它们列在 `tools` 字段中：
458 458
459* `Agent`，当 subagent 在 [depth limit](#let-subagents-spawn-their-own-subagents)；在 [fork](#fork-the-current-conversation) 中工具保持列出但返回错误而不是生成459* `Agent`，当子代理达到[深度限制](#let-subagents-spawn-their-own-subagents)时；在[分叉](#fork-the-current-conversation)中，该工具仍会列出，但会返回错误而不是生成子代理
460* `AskUserQuestion`460* `AskUserQuestion`
461* `EndConversation`，只能结束主对话；请参阅 [EndConversation tool behavior](/docs/zh-CN/tools-reference#endconversation-tool-behavior)461* `EndConversation`，它只能结束主对话；请参阅 [EndConversation 工具行为](/docs/zh-CN/tools-reference#endconversation-tool-behavior)
462* `EnterPlanMode`462* `EnterPlanMode`
463* `ExitPlanMode`，除非 subagent 的 [`permissionMode`](#permission-modes) 是 `plan`463* `ExitPlanMode`，除非子代理的 [`permissionMode`](#permission-modes) 为 `plan`
464* `ScheduleWakeup`464* `ScheduleWakeup`
465* `WaitForMcpServers`465* `WaitForMcpServers`
466* `Workflow`466* `Workflow`
467 467
468第二个过滤器适用于在后台运行的 subagents。`Agent` 和 `ExitPlanMode` 无论 subagent 在哪里运行都遵循第一个过滤器的条件。除这两个工具外，后台 subagent 保留每个 MCP 工具，但内置工具仅保留这些：`Read`、`Grep`、`Glob`、`LSP`、`Bash`、`PowerShell`、`Edit`、`Write`、`NotebookEdit`、`WebFetch`、`WebSearch`、`TodoWrite`、`Skill`、`ToolSearch`、`EnterWorktree`、`ExitWorktree`、`Monitor`、`TaskStop`、`SendMessage` 和 `Artifact`，加上 [`SubagentHandback`](/docs/zh-CN/tools-reference) 用于通过它报告的 subagent。Claude Code 从后台 subagent 删除每个其他内置工具，无论继承还是在 `tools` 字段中列出，因此相同的定义可以在前台和后台解析为不同的工具。删除不会报告错误，除非它使 `tools` 列表[解析为空](/docs/zh-CN/errors#agent-would-be-spawned-with-zero-tools)。468第二个过滤器适用于在后台运行的子代理。除了 `Agent` 和 `ExitPlanMode`（无论子代理在何处运行，都遵循第一个过滤器的条件）之外，后台子代理保留所有 MCP 工具，但只保留以下内置工具：`Read`、`Grep`、`Glob`、`LSP`、`Bash`、`PowerShell`、`Edit`、`Write`、`NotebookEdit`、`WebFetch`、`WebSearch`、`TodoWrite`、`Skill`、`ToolSearch`、`EnterWorktree`、`ExitWorktree`、`Monitor`、`TaskStop`、`SendMessage` 和 `Artifact`，对于通过 [`SubagentHandback`](/docs/zh-CN/tools-reference) 报告的子代理，还保留该工具。Claude Code 会从后台子代理中移除所有其他内置工具，无论是继承的还是列在 `tools` 字段中的，因此同一定义在前台和后台可能解析为不同的工具。除非移除后 `tools` 列表[解析结果为空](/docs/zh-CN/errors#agent-would-be-spawned-with-zero-tools)，否则移除操作不会报告错误。
469 469
470在 v2.1.280 之前，后台 subagents 无法使用 `LSP`。470在 v2.1.280 之前，后台子代理无法使用 `LSP`。
471 471
472[`ListAgents`](/docs/zh-CN/cross-session-messaging) 遵循这些过滤器，如任何内置工具：前台 subagent 在启用跨会话消息的会话中继承它，后台 subagent 不保留它。472[`ListAgents`](/docs/zh-CN/cross-session-messaging) 与任何内置工具一样遵循这些过滤器：在启用了跨会话消息的会话中，前台子代理会继承它，而后台子代理不会保留它。
473 473
474[agent teams](/docs/zh-CN/agent-teams) 中的队友另外保留任务工具和 cron 工具：`TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`、`CronCreate`、`CronDelete` 和 `CronList`。474[agent team](/docs/zh-CN/agent-teams) 中的队友还会额外保留任务工具和 cron 工具：`TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`、`CronCreate`、`CronDelete` 和 `CronList`。
475 475
476在 [session without the Task tools](/docs/zh-CN/tools-reference#task-tool-availability) 中，Claude Code 也不向 subagents 提供任务工具，即使 subagent 运行不同的模型。进程内队友遵循您的会话相同的方式，而在其自己的 [split pane](/docs/zh-CN/agent-teams#choose-a-display-mode) 中的队友作为单独的 Claude Code 进程运行，因此其自己的模型决定。476在[没有 Task 工具的会话](/docs/zh-CN/tools-reference#task-tool-availability)中，Claude Code 也不会向子代理提供任务工具，即使子代理运行的是不同的模型。进程内队友同样遵循您的会话，而在其自己的[分割窗格](/docs/zh-CN/agent-teams#choose-a-display-mode)中的队友作为独立的 Claude Code 进程运行，因此由其自身的模型决定。
477 477
478<h4 id="restrict-which-tools-a-subagent-can-use">478<h4 id="restrict-which-tools-a-subagent-can-use">
479 限制子代理可以使用的工具479 限制子代理可以使用的工具
480</h4>480</h4>
481 481
482要限制工具，请使用 `tools` 字段作为允许列表，或使用 `disallowedTools` 字段作为拒绝列表。如果两者都设置了，会先应用 `disallowedTools`，然后针对剩余的工具池解析 `tools`。同时列在两者中的工具会被移除。482若要限制工具，请将 `tools` 字段用作允许列表，或将 `disallowedTools` 字段用作拒绝列表。如果两者都设置，会先应用 `disallowedTools`，然后根据剩余的工具池解析 `tools`。同时列在两者中的工具会被移除。
483 483
484此示例使用 `tools` 仅允许 Read、Grep、Glob 和 Bash。该子代理无法编辑文件、写入文件或使用任何 MCP 工具：484此示例使用 `tools` 只允许 Read、Grep、Glob 和 Bash。该子代理无法编辑文件、写入文件或使用任何 MCP 工具：
485 485
486```yaml theme={null}486```yaml theme={null}
487---487---
491---491---
492```492```
493 493
494此示例使用 `disallowedTools` 来继承 subagent 的工具池，除了 Write 和 Edit。Subagent 保留 Bash、MCP 工具和其他所有内容：494此示例使用 `disallowedTools` 继承子代理除 Write 和 Edit 之外的工具池。该子代理保留 Bash、MCP 工具及其工具池中的其余工具：
495 495
496```yaml theme={null}496```yaml theme={null}
497---497---
501---501---
502```502```
503 503
504当 `tools` 列表中没有任何内容解析为工具时，例如因为每个条目都拼写错误或命名了对 subagents 不可用的工具，Claude Code 通常拒绝启动 subagent，Agent 工具返回一个错误，命名未解析的条目；请参阅 [Agent would be spawned with zero tools](/docs/zh-CN/errors#agent-would-be-spawned-with-zero-tools) 了解消息和如何修复每个条目。在 v2.1.208 之前，该 subagent 启动时没有工具，可能返回空的或令人困惑的结果。504当 `tools` 列表中没有任何条目能解析为工具时（例如每个条目都拼写错误，或指向子代理不可用的工具），Claude Code 通常会拒绝启动子代理，并且 Agent 工具会返回一个列出未解析条目的错误；有关该消息以及如何修复每个条目，请参阅 [Agent would be spawned with zero tools](/docs/zh-CN/errors#agent-would-be-spawned-with-zero-tools)。
505 505
506`tools` 和 `disallowedTools` 字段也接受针对整个 MCP 服务器的条目：506`tools` 和 `disallowedTools` 字段还接受针对整个 MCP 服务器的条目：
507 507
508| 目标 | 字段 | 示例条目 |508| 目标 | 字段 | 示例条目 |
509| :- | :- | :- |509| :- | :- | :- |
510| 为子代理提供某个服务器的所有工具 | `tools` | `mcp__github__*` |510| 为子代理提供某个服务器的所有工具 | `tools` | `mcp__github__*` |
511| 排除某个服务器的工具 | `disallowedTools` | `mcp__github` 或 `mcp__github__*` |511| 排除某个服务器的工具 | `disallowedTools` | `mcp__github` 或 `mcp__github__*` |
512| 排除来自任何服务器的所有 MCP 工具 | `disallowedTools` | `mcp__*` |512| 排除所有服务器的所有 MCP 工具 | `disallowedTools` | `mcp__*` |
513 513
514此示例移除来自 `github` MCP 服务器的所有工具，同时保留子代理工具池中来自其他服务器的工具和内置工具：514此示例从子代理的工具池中移除 `github` MCP 服务器的所有工具，同时保留其他服务器的工具和内置工具：
515 515
516```yaml theme={null}516```yaml theme={null}
517---517---
521---521---
522```522```
523 523
524一个 `disallowedTools` 条目带有说明符，例如 `Bash(git push *)`，仍然从 subagent 删除整个工具，而不仅仅是匹配的命令。要保留 Bash 并阻止特定命令，请在您的设置中向 `permissions.deny` 添加 [Bash deny rule](/docs/zh-CN/permissions#bash)，例如 `Bash(git push *)`。该规则适用于主对话和 subagents。524带有说明符的 `disallowedTools` 条目（如 `Bash(git push *)`）仍会从子代理中移除整个工具，而不仅仅是匹配的命令。若要保留 Bash 并阻止特定命令，请在设置中向 `permissions.deny` 添加 [Bash 拒绝规则](/docs/zh-CN/permissions#bash)，例如 `Bash(git push *)`。该规则适用于主对话和子代理。
525 525
526<h4 id="restrict-which-subagents-can-be-spawned">526<h4 id="restrict-which-subagents-can-be-spawned">
527 限制可以生成哪些 subagents527 限制可以生成的子代理
528</h4>528</h4>
529 529
530当代理作为主线程运行时，使用 `claude --agent`，它可以使用 Agent 工具生成 subagents。要限制它可以生成的 subagent 类型，在 `tools` 字段中使用 `Agent(agent_type)` 语法。530当 Agent 通过 `claude --agent` 作为主线程运行时，它可以使用 Agent 工具生成子代理。若要限制它可以生成的子代理类型，请在 `tools` 字段中使用 `Agent(agent_type)` 语法。
531 531
532<Note>在版本 2.1.63 中，Task 工具被重命名为 Agent。设置和代理定义中的现有 `Task(...)` 引用仍然作为别名工作。</Note>532<Note>在 2.1.63 版本中，Task 工具被重命名为 Agent。设置和 Agent 定义中现有的 `Task(...)` 引用仍可作为别名使用。</Note>
533 533
534```yaml theme={null}534```yaml theme={null}
535---535---
539---539---
540```540```
541 541
542这是一个允许列表：只有 `worker` 和 `researcher` subagents 可以被生成。如果代理尝试生成任何其他类型，请求失败，代理在其提示中仅看到允许的类型。要在允许所有其他类型的同时阻止特定代理，请改用 [`permissions.deny`](#disable-specific-subagents)。542这是一个允许列表：只能生成 `worker` 和 `researcher` 子代理。如果 Agent 尝试生成任何其他类型，请求会失败，并且 Agent 在其提示词中只能看到允许的类型。若要阻止特定 Agent 同时允许所有其他 Agent，请改用 [`permissions.deny`](#disable-specific-subagents)。
543 543
544要允许生成任何 subagent 而不受限制，使用不带括号的 `Agent`：544若要允许不受限制地生成任何子代理，请使用不带括号的 `Agent`：
545 545
546```yaml theme={null}546```yaml theme={null}
547tools: Agent, Read, Bash547tools: Agent, Read, Bash
548```548```
549 549
550如果 `Agent` 完全从 `tools` 列表中省略，代理无法生成任何 subagents。550如果您在 `tools` 列表中完全省略 `Agent`，该 Agent 将无法使用 Agent 工具生成任何子代理。
551 551
552`Agent(agent_type)` 允许列表语法仅适用于作为主线程运行的代理，使用 `claude --agent`。在 subagent 定义中，在 `tools` 中列出 `Agent` 让该 subagent 生成自己的 subagents，同时 [depth limit](#let-subagents-spawn-their-own-subagents) 允许它，但括号内的任何类型列表都被忽略。552`Agent(agent_type)` 允许列表语法仅适用于通过 `claude --agent` 作为主线程运行的 Agent。在子代理定义中，在 `tools` 中列出 `Agent` 可让该子代理在[深度限制](#let-subagents-spawn-their-own-subagents)允许的范围内生成它自己的子代理，但括号内的任何类型列表都会被忽略。
553 553
554<h4 id="scope-mcp-servers-to-a-subagent">554<h4 id="scope-mcp-servers-to-a-subagent">
555 将 MCP 服务器限定于 subagent555 将 MCP 服务器限定于子代理
556</h4>556</h4>
557 557
558使用 `mcpServers` 字段为 subagent 提供对主对话中不可用的 [MCP](/docs/zh-CN/mcp) 服务器的访问。此处定义的内联服务器在 subagent 启动时连接，受 [trust rule for the agent file's folder](#inline-server-trust) 约束，并在完成时断开连接。字符串引用共享父会话的连接。558使用 `mcpServers` 字段为子代理提供对主对话中不可用的 [MCP](/docs/zh-CN/mcp) 服务器的访问权限。此处定义的内联服务器在子代理启动时连接（需符合[针对 Agent 文件所在文件夹的信任规则](#inline-server-trust)），并在其完成时断开连接。字符串引用共享父会话的连接。
559 559
560<Note>560<Note>
561 `mcpServers` 字段适用于代理文件可以运行的两个上下文：561 `mcpServers` 字段在 Agent 文件可以运行的两种情境中都适用：
562 562
563 * 作为 subagent，通过 Agent 工具或 @-mention 生成563 * 作为子代理，通过 Agent 工具或 @ 提及生成
564 * 作为主会话，使用 [`--agent`](#invoke-subagents-explicitly) 或 `agent` 设置启动564 * 作为主会话，通过 [`--agent`](#invoke-subagents-explicitly) 或 `agent` 设置启动
565 565
566 当代理是主会话时，内联服务器定义与来自 [`.mcp.json`](/docs/zh-CN/mcp) 和设置文件的服务器一起在启动时连接，在 [trust rule for the agent file's folder](#inline-server-trust) 下。在 `/mcp` 中，您之前使用过的远程（HTTP 或 SSE）服务器可以显示 [`cached` status](/docs/zh-CN/mcp#managing-your-servers) 而不是；Claude Code 在 Claude 首次调用其工具之一时连接它。566 当 Agent 是主会话时，内联服务器定义会在启动时与来自 [`.mcp.json`](/docs/zh-CN/mcp) 和设置文件的服务器一起连接，遵循相同的[针对 Agent 文件所在文件夹的信任规则](#inline-server-trust)。在 `/mcp` 中，您以前使用过的远程（HTTP 或 SSE）服务器可能会改为显示 [`cached` 状态](/docs/zh-CN/mcp#managing-your-servers)；Claude Code 会在 Claude 首次调用其某个工具时连接它。
567</Note>567</Note>
568 568
569列表中的每个条目要么是内联服务器定义，要么是引用会话中已配置的 MCP 服务器的字符串：569列表中的每个条目要么是内联服务器定义，要么是引用您会话中已配置的 MCP 服务器的字符串：
570 570
571```yaml theme={null}571```yaml theme={null}
572---572---
585Use the Playwright tools to navigate, screenshot, and interact with pages.585Use the Playwright tools to navigate, screenshot, and interact with pages.
586```586```
587 587
588内联定义使用与 `.mcp.json` 服务器条目相同的架构，由服务器名称键入，并支持 `stdio`、`http`、`sse` 和 `ws` 类型。588内联定义使用与 `.mcp.json` 服务器条目相同的 schema，以服务器名称为键，并支持 `stdio`、`http`、`sse` 和 `ws` 类型。
589 589
590要将 MCP 服务器保持在主对话之外，并避免其工具描述消耗那里的上下文，请在此处内联定义它，而不是在 `.mcp.json` 中。Subagent 获得工具；父对话不获得。590若要将某个 MCP 服务器完全排除在主对话之外，避免其工具描述占用主对话的上下文，请在此处以内联方式定义它，而不是在 `.mcp.json` 中定义。子代理会获得这些工具；父对话则不会。
591 591
592适用于主会话的 MCP 限制同样涵盖子代理 frontmatter 中声明的服务器：592适用于主会话的 MCP 限制同样覆盖在子代理 frontmatter 中声明的服务器：
593 593
594* [`--strict-mcp-config`](/docs/zh-CN/cli-reference) 和 [`--bare`](/docs/zh-CN/cli-reference)594* [`--strict-mcp-config`](/docs/zh-CN/cli-reference) 和 [`--bare`](/docs/zh-CN/cli-reference)
595* [企业托管 MCP 配置](/docs/zh-CN/managed-mcp)595* [企业托管 MCP 配置](/docs/zh-CN/managed-mcp)
596* [`allowedMcpServers` 和 `deniedMcpServers` 策略](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists)596* [`allowedMcpServers` 和 `deniedMcpServers` 策略](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists)
597 597
598当其中任一项阻止某个服务器时，Claude Code 会跳过它，并显示一条列出被阻止服务器的警告。598当其中之一阻止某个服务器时，Claude Code 会跳过它，并显示一条列出被阻止服务器的警告。
599 599
600托管设置限制适用于每个子代理，无论其如何定义。`--strict-mcp-config` 不会过滤您通过 `--agents` 或 SDK `agents` 选项内联传递的服务器，因为这些属于调用方的显式输入。600托管设置的限制适用于每个子代理，无论其定义方式如何。`--strict-mcp-config` 不会过滤您通过 `--agents` 或 SDK `agents` 选项以内联方式传入的服务器，因为这些属于调用方的明确输入。
601 601
602<h4 id="inline-server-trust">602<h4 id="inline-server-trust">
603 内联 MCP 服务器需要信任603 内联 MCP 服务器所需的信任
604</h4>604</h4>
605 605
606只有在您[信任 Agent 文件所在的文件夹](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)之后，Claude Code 才会从项目 `.claude/agents/` 目录或 `--add-dir` 目录的 `.claude/agents/` 中的 Agent 文件加载[内联 MCP 服务器](#scope-mcp-servers-to-a-subagent)。在 v2.1.238 之前，Claude Code 加载这些服务器时不检查信任。606对于您项目的 `.claude/agents/` 目录或 `--add-dir` 目录的 `.claude/agents/` 中的 Agent 文件，Claude Code 只有在您[信任该 Agent 文件所在的文件夹](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)之后，才会加载其中的[内联 MCP 服务器](#scope-mcp-servers-to-a-subagent)。在 v2.1.238 之前，Claude Code 加载这些服务器时不检查信任。
607 607
608* **不计数的信任**：父文件夹的信任，以及 `-p` 或 SDK 会话为 [hooks in settings files](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 获得的自动信任608* **不算数的信任**：父文件夹的信任，以及 `-p` 或 SDK 会话针对[设置文件中的 hook](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 获得的自动信任
609* **直到那时**：Claude Code 跳过该代理文件中的每个内联服务器，并将确切的 `projects["<path>"].hasTrustDialogAccepted` 键写入调试日志，用于 `~/.claude.json`609* **在此之前**：Claude Code 会跳过该 Agent 文件中的每个内联服务器，并将 `~/.claude.json` 中确切的 `projects["<path>"].hasTrustDialogAccepted` 键写入调试日志
610* **`--add-dir` 目录**：您受信任工作区的存储库外的目录需要其自己的信任条目，因为其 `.claude/agents/` 文件不继承您的工作区的信任610* **`--add-dir` 目录**：位于您受信任工作区仓库之外的目录需要其自己的信任条目，因为其 `.claude/agents/` 文件不会继承您工作区的信任
611 611
612Claude Code 加载两种服务器而不检查代理文件来自的文件夹的信任：612对于以下两种服务器，Claude Code 加载时不检查 Agent 文件所在文件夹的信任：
613 613
614* 一个引用您已配置的服务器的名称614* 引用您已配置的服务器的名称
615* 一个代理文件中的内联服务器，来自 `~/.claude/agents/`，在您使用 `--agents` 或 SDK `agents` 选项传递的一个中，或托管设置提供的一个中615* 来自 `~/.claude/agents/` 中的 Agent 文件、您通过 `--agents` 或 SDK `agents` 选项传入的 Agent 文件，或由托管设置提供的 Agent 文件中的内联服务器
616 616
617<h4 id="permission-modes">617<h4 id="permission-modes">
618 权限模式618 权限模式
619</h4>619</h4>
620 620
621设置 `permissionMode` 以选择 subagent 运行的权限模式。使用模式的配置值，因此手动模式是 `default`。如果您不设置它，subagent 继承主对话的 [permission mode](/docs/zh-CN/permission-modes)。621设置 `permissionMode` 以选择子代理运行时使用的权限模式。请使用模式的配置值，因此 Manual 模式为 `default`。如果不设置，子代理会继承主对话的[权限模式](/docs/zh-CN/permission-modes)。
622 622
623主对话的权限模式决定 Claude Code 是否使用您设置的值：623主对话的权限模式决定 Claude Code 是否使用您设置的值：
624 624
625* 当主对话在 `bypassPermissions`、`acceptEdits` 或 [auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 时，subagent 在该相同模式中运行，Claude Code 忽略您设置的 `permissionMode`。在自动模式下，分类器使用主对话的块和允许规则评估 subagent 的工具调用。当 subagent 完成时，分类器也会在报告被传递之前审查其工作和最终报告，如 [How auto mode handles subagents](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 所述。625* 当主对话处于 `bypassPermissions`、`acceptEdits` 或[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)时，子代理以相同模式运行，Claude Code 会忽略您设置的 `permissionMode`。在自动模式下，分类器使用主对话的阻止和允许规则评估子代理的工具调用。当子代理完成时，分类器还会在交付最终报告之前审查其工作和最终报告，如[自动模式如何处理子代理](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中所述。
626* 当主对话处于 `default`、`dontAsk` 或 `plan` 模式时，子代理会在您设置的权限模式下运行。在以下情况下，它会改为保持主对话的权限模式：626* 当主对话处于 `default`、`dontAsk` 或 `plan` 模式时，子代理以您设置的权限模式运行。在以下情况下，它会改为保持主对话的权限模式：
627 * 您设置了 `bypassPermissions`。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更高版本。627 * 您设置了 `bypassPermissions`。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更高版本。
628 * 您设置了 `auto`，但子代理[无法使用自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，例如某个设置文件设置了 [`disableAutoMode`](/docs/zh-CN/settings-reference#disableautomode)，或子代理的模型不支持自动模式。628 * 您设置了 `auto`，但子代理[无法使用自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，例如设置文件设置了 [`disableAutoMode`](/docs/zh-CN/settings-reference#disableautomode)，或子代理的模型不支持自动模式。
629 629
630`permissionMode` 接受这些值，以及 `manual` 作为 `default` 的别名：630`permissionMode` 接受以下值，以及作为 `default` 别名的 `manual`：
631 631
632| Mode | Behavior |632| 模式 | 行为 |
633| :- | :- |633| :- | :- |
634| `default` | 手动模式：提示权限 |634| `default` | Manual 模式：提示请求权限 |
635| `acceptEdits` | 自动接受文件编辑和工作目录或 `additionalDirectories` 中路径的常见文件系统命令 |635| `acceptEdits` | 对于工作目录或 `additionalDirectories` 中的路径，自动接受文件编辑和常见文件系统命令 |
636| `auto` | [Auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)：后台分类器审查命令和受保护目录的写入 |636| `auto` | [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)：后台分类器审查命令和对受保护目录的写入 |
637| `dontAsk` | 自动拒绝权限提示。显式允许的工具仍可使用；`AskUserQuestion`、标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具、[从网络路径读取](/docs/zh-CN/permissions#network-paths)，以及[您的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具（在该设置传达到 Claude Code 的会话中）会被拒绝，即使您已允许它们 |637| `dontAsk` | 自动拒绝权限提示。明确允许的工具仍可使用；`AskUserQuestion`、标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具、[从网络路径读取](/docs/zh-CN/permissions#network-paths)，以及在该设置能作用到 Claude Code 的会话中[您的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具，即使您已允许也会被拒绝 |
638| `bypassPermissions` | [Skip permission prompts](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)。Subagent 仅在主对话也这样做时在此模式中运行 |638| `bypassPermissions` | [跳过权限提示](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)。只有当主对话处于此模式时，子代理才会以此模式运行 |
639| `plan` | Plan mode（只读探索） |639| `plan` | 计划模式（只读探索） |
640 640
641<h4 id="preload-skills-into-subagents">641<h4 id="preload-skills-into-subagents">
642 将技能预加载到 subagents642 将 skill 预加载到子代理中
643</h4>643</h4>
644 644
645使用 `skills` 字段在启动时将技能内容注入到 subagent 的上下文中。这为 subagent 提供领域知识，而无需在执行期间发现和加载技能。645使用 `skills` 字段在启动时将 skill 内容注入子代理的上下文。这样子代理无需在执行期间发现和加载 skill 即可获得领域知识。
646 646
647```yaml theme={null}647```yaml theme={null}
648---648---
656Implement API endpoints. Follow the conventions and patterns from the preloaded skills.656Implement API endpoints. Follow the conventions and patterns from the preloaded skills.
657```657```
658 658
659每个列出的 skill 的完整内容会在启动时注入到子代理的上下文中，最多为列表中前 32 个不同的名称。此字段控制预加载哪些 skill，而不是子代理可以访问哪些 skill：即使没有此字段，子代理仍然可以在执行期间通过 Skill 工具发现和调用项目、用户和插件 skill。要完全阻止子代理调用 skill，请从 [`tools`](#available-tools) 列表中省略 `Skill`，或将其添加到 `disallowedTools`。659每个列出的 skill 的完整内容会在启动时注入子代理的上下文，最多为列表中前 32 个不同的名称。此字段控制预加载哪些 skill，而不是子代理可以访问哪些 skill：即使没有此字段，子代理在执行期间仍可通过 Skill 工具发现和调用项目、用户和插件 skill。若要完全阻止子代理调用 skill，请从 [`tools`](#available-tools) 列表中省略 `Skill`，或将其添加到 `disallowedTools`。
660 660
661您无法预加载设置了 [`disable-model-invocation: true`](/docs/zh-CN/skills#control-who-invokes-a-skill) 的 skill，因为预加载的来源与 Claude 可以调用的 skill 集合相同。这包括内置的 `/verify` skill，Claude 无法自行运行它。661您无法预加载设置了 [`disable-model-invocation: true`](/docs/zh-CN/skills#control-who-invokes-a-skill) 的 skill，因为预加载取自 Claude 可以调用的同一组 skill。这包括内置的 `/verify` skill，Claude 无法自行运行它。
662 662
663如果列出的技能缺失或被禁用，例如由您的组织的策略，Claude Code 会跳过它并向调试日志记录警告。663如果列出的某个 skill 缺失或被禁用（例如被您组织的策略禁用），Claude Code 会跳过它，并在调试日志中记录一条警告。
664 664
665<Note>665<Note>
666 这与 [running a skill in a subagent](/docs/zh-CN/skills#run-skills-in-a-subagent) 相反。使用 subagent 中的 `skills`，subagent 控制系统提示并加载技能内容。使用技能中的 `context: fork`，技能内容被注入到您指定的代理中。两者都使用相同的底层系统。666 这与[在子代理中运行 skill](/docs/zh-CN/skills#run-skills-in-a-subagent) 相反。在子代理中使用 `skills` 时，由子代理控制系统提示词并加载 skill 内容。在 skill 中使用 `context: fork` 时，skill 内容会被注入到您指定的 Agent 中。在这两种情况下，子代理启动时都不带有您的对话历史。
667</Note>667</Note>
668 668
669<h4 id="enable-persistent-memory">669<h4 id="enable-persistent-memory">
670 启用持久内存670 启用持久记忆
671</h4>671</h4>
672 672
673`memory` 字段为 subagent 提供一个在对话中幸存的持久目录。Subagent 使用此目录随时间积累知识，例如代码库模式、调试见解和架构决策。673`memory` 字段为子代理提供一个跨对话保留的持久目录。子代理使用此目录随时间积累知识，例如代码库模式、调试心得和架构决策。
674 674
675```yaml theme={null}675```yaml theme={null}
676---676---
683patterns, conventions, and recurring issues you discover.683patterns, conventions, and recurring issues you discover.
684```684```
685 685
686根据内存应该应用的广泛程度选择范围：686根据记忆应适用的范围选择作用域：
687 687
688| Scope | Location | 使用时机 |688| 作用域 | 位置 | 适用场景 |
689| :- | :- | :- |689| :- | :- | :- |
690| `user` | `~/.claude/agent-memory/<name-of-agent>/` | subagent 应该在所有项目中记住学习 |690| `user` | `~/.claude/agent-memory/<name-of-agent>/` | 子代理应在所有项目中记住所学内容 |
691| `project` | `.claude/agent-memory/<name-of-agent>/` | subagent 的知识是特定于项目的并可通过版本控制共享 |691| `project` | `.claude/agent-memory/<name-of-agent>/` | 子代理的知识特定于项目，并可通过版本控制共享 |
692| `local` | `.claude/agent-memory-local/<name-of-agent>/` | subagent 的知识是特定于项目的但不应检入版本控制 |692| `local` | `.claude/agent-memory-local/<name-of-agent>/` | 子代理的知识特定于项目，但不应提交到版本控制 |
693 693
694Subagent 内存是 [auto memory](/docs/zh-CN/memory#auto-memory) 的一部分：如果您关闭自动内存，使用 `autoMemoryEnabled` 设置或 `CLAUDE_CODE_DISABLE_AUTO_MEMORY`，`memory` 字段没有效果，subagent 启动时没有内存说明或下面描述的内存工具访问。694子代理记忆是[自动记忆](/docs/zh-CN/memory#auto-memory)的一部分：如果您通过 `autoMemoryEnabled` 设置或 `CLAUDE_CODE_DISABLE_AUTO_MEMORY` 关闭自动记忆，`memory` 字段将不起作用，子代理启动时不会带有下述记忆指令或记忆工具访问权限。
695 695
696启用内存时：696启用记忆后：
697 697
698* Subagent 的系统提示包括读取和写入内存目录的说明。698* 子代理的系统提示词包含读取和写入记忆目录的指令。
699* 子代理的系统提示词还包含记忆目录中 `MEMORY.md` 的前 200 行或前 25KB（以先达到者为准），以及在 `MEMORY.md` 超过该限制时对其进行整理的说明。699* 子代理的系统提示词还包含记忆目录中 `MEMORY.md` 的前 200 行或前 25KB（以先达到者为准），并附有在 `MEMORY.md` 超出该限制时对其进行整理的指令。
700* Read、Write 和 Edit 工具会自动启用，以便 subagent 可以管理其内存文件。700* Read、Write 和 Edit 工具会自动启用，以便子代理管理其记忆文件。
701 701
702<h5 id="persistent-memory-tips">702<h5 id="persistent-memory-tips">
703 持久内存提示703 持久记忆提示
704</h5>704</h5>
705 705
706* `project` 是推荐的默认范围。它使 subagent 知识可通过版本控制共享。706* `project` 是推荐的默认作用域。它使子代理的知识可以通过版本控制共享。
707* 要求 subagent 在开始工作前查阅其内存："Review this PR, and check your memory for patterns you've seen before."707* 让子代理在开始工作前查阅其记忆："Review this PR, and check your memory for patterns you've seen before."
708* 要求 subagent 在完成任务后更新其内存："Now that you're done, save what you learned to your memory." 随着时间的推移，这会建立一个知识库，使 subagent 更有效。708* 让子代理在完成任务后更新其记忆："Now that you're done, save what you learned to your memory." 随着时间推移，这会建立一个让子代理更高效的知识库。
709* 直接在 subagent 的 markdown 文件中包含内存说明，以便它主动维护自己的知识库：709* 直接在子代理的 markdown 文件中加入记忆指令，使其主动维护自己的知识库：
710 710
711 ```markdown theme={null}711 ```markdown theme={null}
712 Update your agent memory as you discover codepaths, patterns, library712 Update your agent memory as you discover codepaths, patterns, library
716 ```716 ```
717 717
718<h4 id="conditional-rules-with-hooks">718<h4 id="conditional-rules-with-hooks">
719 使用 hooks 的条件规则719 使用 hook 的条件规则
720</h4>720</h4>
721 721
722为了更动态地控制工具使用，使用 `PreToolUse` hooks 在执行前验证操作。当您需要允许工具的某些操作同时阻止其他操作时，这很有用。722若要对工具使用进行更动态的控制，请使用 `PreToolUse` hook 在操作执行前对其进行验证。当您需要允许某个工具的部分操作同时阻止其他操作时，这非常有用。
723 723
724此示例创建一个仅允许只读数据库查询的 subagent。`PreToolUse` hook 在每个 Bash 命令执行前运行 `command` 中指定的脚本：724此示例创建一个只允许只读数据库查询的子代理。`PreToolUse` hook 会在每个 Bash 命令执行前运行 `command` 中指定的脚本：
725 725
726```yaml theme={null}726```yaml theme={null}
727---727---
737---737---
738```738```
739 739
740Claude Code [通过 stdin 将 hook 输入作为 JSON 传递](/docs/zh-CN/hooks#pretooluse-input) 给 hook 命令。验证脚本读取此 JSON，提取 Bash 命令，并 [以代码 2 退出](/docs/zh-CN/hooks#exit-code-2-behavior-per-event) 以阻止写入操作：740Claude Code 通过 stdin [以 JSON 形式将 hook 输入传递](/docs/zh-CN/hooks#pretooluse-input)给 hook 命令。验证脚本读取此 JSON，提取 Bash 命令，并[以退出码 2 退出](/docs/zh-CN/hooks#exit-code-2-behavior-per-event)以阻止写入操作：
741 741
742```bash theme={null}742```bash theme={null}
743#!/bin/bash743#!/bin/bash
755exit 0755exit 0
756```756```
757 757
758在 macOS 和 Linux 上，使脚本可执行，否则 hook 失败而不是阻止任何内容：758在 macOS 和 Linux 上，请将脚本设为可执行，否则 hook 会失败而不是阻止任何操作：
759 759
760```bash theme={null}760```bash theme={null}
761chmod +x ./scripts/validate-readonly-query.sh761chmod +x ./scripts/validate-readonly-query.sh
762```762```
763 763
764要测试规则，要求 subagent 运行 `UPDATE` 语句：脚本以代码 2 退出，Claude Code 阻止命令，subagent 看到 `Blocked: Only SELECT queries are allowed` 消息。764若要测试该规则，请让子代理运行一条 `UPDATE` 语句：脚本以退出码 2 退出，Claude Code 阻止该命令，子代理会看到 `Blocked: Only SELECT queries are allowed` 消息。
765 765
766有关完整的输入架构，请参阅 [Hook input](/docs/zh-CN/hooks#pretooluse-input)，有关退出代码如何影响行为，请参阅 [exit codes](/docs/zh-CN/hooks#exit-code-output)。在 Windows 上，在 PowerShell 中编写 hook 脚本，并在 hook 条目中添加 `shell: powershell`，如 [running hooks in PowerShell](/docs/zh-CN/hooks#windows-powershell-tool) 中所示。766有关完整的输入 schema，请参阅 [Hook 输入](/docs/zh-CN/hooks#pretooluse-input)；有关退出码如何影响行为，请参阅[退出码](/docs/zh-CN/hooks#exit-code-output)。在 Windows 上，请使用 PowerShell 编写 hook 脚本，并按照[在 PowerShell 中运行 hook](/docs/zh-CN/hooks#windows-powershell-tool) 中所示，向 hook 条目添加 `shell: powershell`。
767 767
768<h4 id="disable-specific-subagents">768<h4 id="disable-specific-subagents">
769 禁用特定 subagents769 禁用特定子代理
770</h4>770</h4>
771 771
772您可以通过将 subagents 添加到您的 [settings](/docs/zh-CN/settings-reference#permission-settings) 中的 `deny` 数组来防止 Claude 使用特定 subagents。使用格式 `Agent(subagent-name)`，其中 `subagent-name` 与 subagent 的 name 字段匹配。772您可以将特定子代理添加到[设置](/docs/zh-CN/settings-reference#permission-settings)中的 `deny` 数组，以阻止 Claude 使用它们。使用 `Agent(subagent-name)` 格式，其中 `subagent-name` 与子代理的 name 字段匹配。
773 773
774```json theme={null}774```json theme={null}
775{775{
779}779}
780```780```
781 781
782这对内置和自定义 subagents 都有效。您也可以使用 `--disallowedTools` CLI 标志：782这同时适用于内置子代理和自定义子代理。您也可以使用 `--disallowedTools` CLI 标志：
783 783
784```bash theme={null}784```bash theme={null}
785claude --disallowedTools "Agent(Explore)"785claude --disallowedTools "Agent(Explore)"
786```786```
787 787
788有关权限规则的更多详细信息，请参阅 [Permissions documentation](/docs/zh-CN/permissions#tool-specific-permission-rules)。788有关权限规则的更多详细信息，请参阅[权限文档](/docs/zh-CN/permissions#tool-specific-permission-rules)。
789 789
790<h3 id="define-hooks-for-subagents">790<h3 id="define-hooks-for-subagents">
791 为 subagents 定义 hooks791 为子代理定义 hook
792</h3>792</h3>
793 793
794Subagents 可以定义在 subagent 的生命周期中运行的 [hooks](/docs/zh-CN/hooks)。有两种方式来配置 hooks：794子代理可以定义在子代理生命周期中运行的 [hook](/docs/zh-CN/hooks)。配置 hook 有两种方式：
795 795
796* **在 subagent 的 frontmatter 中**：定义仅在该 subagent 活跃时运行的 hooks796* **在子代理的 frontmatter 中**：定义仅在该子代理活动期间运行的 hook
797* **在 `settings.json` 中**：定义会话范围的 hooks，也在 subagents 内部触发。工具事件，例如 `PreToolUse` 和 `PostToolUse`，为 subagent 的工具调用触发，与它们在主对话中的方式相同，`SubagentStart` 和 `SubagentStop` 在 subagent 启动或完成时触发797* **在 `settings.json` 中**：定义也会在子代理内部触发的会话级 hook。`PreToolUse` 和 `PostToolUse` 等工具事件会像在主对话中一样针对子代理的工具调用触发，而 `SubagentStart` 和 `SubagentStop` 会在子代理启动或完成时触发
798 798
799来自 [settings files, managed policy settings, and plugins](/docs/zh-CN/hooks#hook-locations) 的 Hooks 都适用于 subagents 内部，因此 `settings.json` 中的 `PreToolUse` hook 也在 subagent 使用的每个工具之前运行。799来自[设置文件、托管策略设置和插件](/docs/zh-CN/hooks#hook-locations)的 hook 都会在子代理内部生效，因此 `settings.json` 中的 `PreToolUse` hook 也会在子代理使用每个工具之前运行。
800 800
801<h4 id="hooks-in-subagent-frontmatter">801<h4 id="hooks-in-subagent-frontmatter">
802 Subagent frontmatter 中的 Hooks802 子代理 frontmatter 中的 hook
803</h4>803</h4>
804 804
805直接在 subagent 的 markdown 文件中定义 hooks。这些 hooks 仅在该特定 subagent 活跃时运行，并在完成时清理。805直接在子代理的 markdown 文件中定义 hook。这些 hook 仅在该特定子代理活动期间运行，并在其完成时被清理。
806 806
807<Note>807<Note>
808 Frontmatter hooks 在代理通过 Agent 工具或 @-mention 作为 subagent 生成时触发，以及当代理通过 [`--agent`](#invoke-subagents-explicitly) 或 `agent` 设置作为主会话运行时触发。在主会话情况下，它们与在 [`settings.json`](/docs/zh-CN/hooks) 中定义的任何 hooks 一起运行。808 当 Agent 通过 Agent 工具或 @ 提及作为子代理生成时，以及当 Agent 通过 [`--agent`](#invoke-subagents-explicitly) 或 `agent` 设置作为主会话运行时，frontmatter hook 都会触发。在主会话的情况下，它们会与 [`settings.json`](/docs/zh-CN/hooks) 中定义的任何 hook 一起运行。
809</Note>809</Note>
810 810
811要让项目级 subagent 的 frontmatter hooks 运行，接受包含代理文件的文件夹的 [workspace trust dialog](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)。来自 `~/.claude/agents/` 中的用户级 subagents 的 Hooks 和来自您使用 `--agents` 传递的定义的 Hooks 无需此步骤即可运行。如果您从受信任工作区的存储库外使用 `--add-dir` 添加了文件夹，单独信任该文件夹：其 `.claude/agents/` hooks 不继承工作区的授予。811若要让项目级子代理的 frontmatter hook 运行，请为包含该 Agent 文件的文件夹接受[工作区信任对话框](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)。来自 `~/.claude/agents/` 中用户级子代理以及您通过 `--agents` 传入的定义的 hook 无需此步骤即可运行。如果您通过 `--add-dir` 添加了位于受信任工作区仓库之外的文件夹，请单独信任该文件夹：其 `.claude/agents/` 中的 hook 不会继承工作区的授权。
812 812
813直到您信任文件夹，subagent 仍然运行，但 Claude Code 跳过其 frontmatter hooks 并向调试日志记录错误，解释如何信任文件夹。这是比 settings 文件中的 hooks 的规则更严格的规则：信任父文件夹不够，`-p` 会话不计为受信任。[What runs before you trust a folder](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 比较两者。在 v2.1.218 之前，frontmatter hooks 可以从您未信任的文件夹运行，包括在非交互式会话中。813在您信任该文件夹之前，子代理仍会运行，但 Claude Code 会跳过其 frontmatter hook，并在调试日志中记录一条说明如何信任该文件夹的错误。这一规则比设置文件中 hook 的规则更严格：信任父文件夹是不够的，并且 `-p` 会话不算作受信任。[信任文件夹之前会运行什么](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)对这两者进行了比较。在 v2.1.218 之前，frontmatter hook 可以从您未信任的文件夹中运行，包括在非交互式会话中。
814 814
815所有 [hook events](/docs/zh-CN/hooks#hook-events) 都被支持。subagents 最常见的事件是：815支持所有 [hook 事件](/docs/zh-CN/hooks#hook-events)。子代理最常用的事件有：
816 816
817| Event | Matcher input | 何时触发 |817| 事件 | 匹配器输入 | 触发时机 |
818| :- | :- | :- |818| :- | :- | :- |
819| `PreToolUse` | Tool name | 在 subagent 使用工具之前 |819| `PreToolUse` | 工具名称 | 子代理使用工具之前 |
820| `PostToolUse` | Tool name | 在 subagent 使用工具之后 |820| `PostToolUse` | 工具名称 | 子代理使用工具之后 |
821| `Stop` | (none) | 当 subagent 完成时（在运行时转换为 `SubagentStop`） |821| `Stop` | （无） | 子代理完成时（在运行时转换为 `SubagentStop`） |
822 822
823此示例使用 `PreToolUse` hook 验证 Bash 命令，并在文件编辑后使用 `PostToolUse` 运行 linter：823此示例使用 `PreToolUse` hook 验证 Bash 命令，并使用 `PostToolUse` 在文件编辑后运行 linter：
824 824
825```yaml theme={null}825```yaml theme={null}
826---826---
840---840---
841```841```
842 842
843当代理作为 subagent 调用时，frontmatter 中的 `Stop` hooks 会自动转换为 `SubagentStop` 事件。843当 Agent 作为子代理被调用时，frontmatter 中的 `Stop` hook 会自动转换为 `SubagentStop` 事件。
844 844
845<h4 id="project-level-hooks-for-subagent-events">845<h4 id="project-level-hooks-for-subagent-events">
846 用于 subagent 事件的项目级 hooks846 针对子代理事件的项目级 hook
847</h4>847</h4>
848 848
849在 `settings.json` 中配置 hooks，以响应主会话中的 subagent 生命周期事件。849在 `settings.json` 中配置 hook，以响应主会话中的子代理生命周期事件。
850 850
851| Event | Matcher input | 何时触发 |851| 事件 | 匹配器输入 | 触发时机 |
852| :- | :- | :- |852| :- | :- | :- |
853| `SubagentStart` | Agent type name | 当 subagent 开始执行时 |853| `SubagentStart` | Agent 类型名称 | 子代理开始执行时 |
854| `SubagentStop` | Agent type name | 当 subagent 完成时 |854| `SubagentStop` | Agent 类型名称 | 子代理完成时 |
855 855
856两个事件都支持匹配器以按名称针对特定代理类型。匹配器值是项目级和用户级 subagents 的代理 frontmatter `name`，或 [plugin subagents](/docs/zh-CN/plugins/components#agents) 的 plugin 范围标识符，例如 `my-plugin:db-agent`。范围名称包含冒号，因此它被评估为 [unanchored regular expression](/docs/zh-CN/hooks#matcher-patterns)；使用 `^` 和 `$` 锚定它，如 `^my-plugin:db-agent$`，以仅匹配该代理。856这两个事件都支持匹配器，可按名称指定特定的 Agent 类型。对于项目级和用户级子代理，匹配器值是 Agent 的 frontmatter `name`；对于[插件子代理](/docs/zh-CN/plugins/components#agents)，则是插件作用域标识符，例如 `my-plugin:db-agent`。作用域名称包含冒号，因此会被作为[非锚定正则表达式](/docs/zh-CN/hooks#matcher-patterns)进行求值；请使用 `^` 和 `$` 对其进行锚定，如 `^my-plugin:db-agent$`，以仅匹配该 Agent。
857 857
858此示例仅在 `db-agent` subagent 启动时运行设置脚本，并在任何 subagent 停止时运行清理脚本：858此示例仅在 `db-agent` 子代理启动时运行设置脚本，并在任何子代理停止时运行清理脚本：
859 859
860```json theme={null}860```json theme={null}
861{861{
969* **前台子代理**会阻塞主对话直到完成。权限提示会在出现时传递给您。969* **前台子代理**会阻塞主对话直到完成。权限提示会在出现时传递给您。
970* **后台子代理**在您继续工作时并发运行。当后台子代理遇到需要权限的工具调用时，Claude Code 会在您的主会话中显示该提示，并指明发出请求的子代理。批准即可让子代理继续；按 Esc 则拒绝该单个工具调用，而不会停止子代理。970* **后台子代理**在您继续工作时并发运行。当后台子代理遇到需要权限的工具调用时，Claude Code 会在您的主会话中显示该提示，并指明发出请求的子代理。批准即可让子代理继续；按 Esc 则拒绝该单个工具调用，而不会停止子代理。
971 971
972对于 Claude 使用 Agent 工具生成的每个子代理，Claude Code 会按以下情况中第一个适用的情况来决定前台还是后台：972<h4 id="which-subagents-run-in-the-background">
973 哪些子代理在后台运行
974</h4>
975
976在未进行任何配置的情况下，Claude 从您的主对话生成的子代理会在后台启动。
973 977
974* 如果是进程内的 [agent team](/docs/zh-CN/agent-teams#limitations) 队友生成了该子代理，Claude Code 会在前台运行它。如果队友要生成的子代理的定义设置了 [`background: true`](#supported-frontmatter-fields)，Claude Code 会拒绝并报错。在 [fork 模式](#turn-fork-mode-on-or-off)关闭且您未[关闭后台任务](/docs/zh-CN/env-vars)的情况下，如果队友设置了 `run_in_background: true`，Claude Code 也会拒绝并报错。978* **`claude -p` 和 Agent SDK**：Claude 可以根据自己的判断或在您要求时等待。
975* 如果您将 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/zh-CN/env-vars) 设置为 `1`，Claude Code 会在前台运行子代理，适用于所有类型的会话，且无论 fork 模式是否开启。979* **交互式终端会话、VS Code 以及您本机上的桌面应用会话**：要让 Claude 等待子代理，请[关闭 fork 模式](#let-claude-wait-for-a-subagent)，该模式[默认开启](#turn-fork-mode-on-or-off)。
976* 当 [fork 模式](#turn-fork-mode-on-or-off)开启时（交互式会话中默认开启），Claude Code 会在后台运行子代理，fork 和非 fork 子代理都是如此，且 Claude 无法要求在前台运行。
977* 当 fork 模式关闭时，Claude 默认在后台运行子代理，并在需要先拿到结果才能继续时在前台运行。在使用 `-p` 的[非交互模式](/docs/zh-CN/headless)和 Agent SDK 中，fork 模式默认关闭，除非您将其开启。要让某个子代理即使在 Claude 需要其结果时也保持在后台运行，请将其 frontmatter 中的 [`background`](#supported-frontmatter-fields) 字段设置为 `true`。
978 980
979对于带有 `context: fork` 的 skill，Claude Code 改为遵循[在子代理中运行 skill](/docs/zh-CN/skills#run-skills-in-a-subagent) 中的规则，无论 fork 模式是否开启。981对于带有 `context: fork` 的 skill，Claude Code 改为遵循[在子代理中运行 skill](/docs/zh-CN/skills#run-skills-in-a-subagent) 中的规则，无论 fork 模式是否开启。
980 982
983<h4 id="let-claude-wait-for-a-subagent">
984 让 Claude 等待子代理
985</h4>
986
9871. 将 `CLAUDE_CODE_FORK_SUBAGENT` 设置为 `0` 以关闭 [fork 模式](#turn-fork-mode-on-or-off)，例如在 [`settings.json`](/docs/zh-CN/settings) 中：
988
989 ```json theme={null}
990 {
991 "env": {
992 "CLAUDE_CODE_FORK_SUBAGENT": "0"
993 }
994 }
995 ```
996
9972. 从 shell 中重新运行 `claude`，或打开一个新的 VS Code 对话。
998
9993. 当您需要先拿到结果时，请让 Claude 等待，例如"run the reviewer subagent and wait for its report"。
1000
1001要在 Claude 等待期间继续工作，请在终端中按 **Ctrl+B**，或在 VS Code 中点击 [**Run in background**](/docs/zh-CN/vs-code#move-a-running-command-or-subagent-to-the-background)。
1002
1003如果您不关闭 fork 模式，而是将 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/zh-CN/env-vars) 环境变量设置为 `1`，Claude 会等待每一个子代理，并且后台任务会被关闭，包括 **Ctrl+B**。
1004
1005<h4 id="tools-permissions-and-results-of-background-subagents">
1006 后台子代理的工具、权限和结果
1007</h4>
1008
981后台子代理使用的[内置工具集](#available-tools)比前台子代理更小，但对话 fork 和[已恢复](#resume-subagents)的前台子代理除外。1009后台子代理使用的[内置工具集](#available-tools)比前台子代理更小，但对话 fork 和[已恢复](#resume-subagents)的前台子代理除外。
982 1010
983后台子代理会在您的主会话中显示每一个权限提示。当您对其中某个提示所作的选择会在该次工具调用之后继续生效（例如在会话剩余时间内持续有效的授予）时，Claude Code 会将您的答复应用于整个会话，包括您的主对话。1011后台子代理会在您的主会话中显示每一个权限提示。当您对其中某个提示所作的选择会在该次工具调用之后继续生效（例如在会话剩余时间内持续有效的授予）时，Claude Code 会将您的答复应用于整个会话，包括您的主对话。
984 1012
985后台子代理可以让后台 [Bash 或 PowerShell 命令](/docs/zh-CN/tools-reference#background-commands)[在其轮次结束后继续运行](/docs/zh-CN/interactive-mode#how-backgrounding-works)。该命令结束时，Claude Code 会向该子代理发送通知。1013后台子代理可以让后台 [Bash 或 PowerShell 命令](/docs/zh-CN/tools-reference#background-commands)[在其轮次结束后继续运行](/docs/zh-CN/interactive-mode#how-backgrounding-works)。该命令结束时，Claude Code 会向该子代理发送通知。
986 1014
987后台子代理的结果会在之后的某个轮次中以完成通知的形式送达 Claude。Claude 会等待该通知后再报告子代理的结果；如果您先询问进度，它会告知子代理仍在运行。在 v2.1.211 之前，Claude 有时会报告尚未完成的后台子代理的结果。1015后台子代理的结果会在之后的某个轮次中以完成通知的形式送达 Claude。Claude 会等待该通知后再报告子代理的结果；如果您先询问进度，它会告知子代理仍在运行。
988 1016
989您也可以自行控制：1017<h4 id="finished-subagents-in-the-panel-and-task-list">
990 1018 面板和任务列表中已结束的子代理
991* 当 fork 模式关闭时，要求 Claude 在后台或前台运行任务1019</h4>
992* 按 **Ctrl+B** 将正在运行的任务转到后台
993 1020
994Claude Code 会以两种方式之一从输入框下方的子代理面板中清除后台子代理所在的行，具体取决于子代理的结束方式：1021Claude Code 会以两种方式之一从输入框下方的子代理面板中清除后台子代理所在的行，具体取决于子代理的结束方式：
995 1022
1036 1063
1037[后台子代理的报告](#run-subagents-in-foreground-or-background)会包含在完成通知中送达，该通知被标记为自动化事件，而不是来自您的消息。1064[后台子代理的报告](#run-subagents-in-foreground-or-background)会包含在完成通知中送达，该通知被标记为自动化事件，而不是来自您的消息。
1038 1065
1039<Note>
1040 子代理输出扫描需要 Claude Code v2.1.210 或更高版本。
1041</Note>
1042
1043<h3 id="common-patterns">1066<h3 id="common-patterns">
1044 常见模式1067 常见模式
1045</h3>1068</h3>
1109 1132
1110默认情况下，子代理可以生成自己的子代理，最多可达主对话之下三层。达到深度限制时，Claude Code 会从除 [fork](#fork-the-current-conversation) 之外的所有子代理中移除 `Agent` 工具，因此处于限制层级的子代理会自己完成委托的工作并返回一份摘要。处于限制层级的 fork 在其继承的工具列表中仍保留 `Agent`，但该工具会返回错误而不是生成子代理。1133默认情况下，子代理可以生成自己的子代理，最多可达主对话之下三层。达到深度限制时，Claude Code 会从除 [fork](#fork-the-current-conversation) 之外的所有子代理中移除 `Agent` 工具，因此处于限制层级的子代理会自己完成委托的工作并返回一份摘要。处于限制层级的 fork 在其继承的工具列表中仍保留 `Agent`，但该工具会返回错误而不是生成子代理。
1111 1134
1112嵌套子代理适用于本身可拆分为并行子任务的委托任务，例如一个审查子代理为每项发现分派一个验证者。在交互式会话中，只有顶层子代理的摘要会返回给您，中间输出不会进入您的主对话：启动后台子代理的子代理会等待它们的结果后再结束。在[非交互模式](/docs/zh-CN/headless)和 Agent SDK 中，发起启动的子代理不会等待，因此如果嵌套的后台子代理在其启动者结束后才完成，它会改为向您的主对话报告。1135嵌套子代理适用于本身可拆分为并行子任务的委托任务，例如一个审查子代理为每项发现分派一个验证者。默认情况下，发起启动的子代理会等待每个嵌套子代理的报告：
1136
1137* **交互式终端会话**：只有顶层子代理的摘要会返回给您，因为启动后台子代理的子代理会等待它们的结果后再结束。
1138* **`claude -p` 和 Agent SDK**：当 [fork 模式](#turn-fork-mode-on-or-off)开启时，发起启动的子代理会等待。如果您关闭 fork 模式，嵌套子代理会改为在[后台](#run-subagents-in-foreground-or-background)启动。发起启动的子代理不会等待后台嵌套子代理；如果该嵌套子代理在其启动者结束后仍在运行，它会向您的主对话报告。
1113 1139
1114要更改该限制，请将 [`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`](/docs/zh-CN/env-vars) 设置为您希望在主对话之下允许的子代理层数。例如，[`settings.json`](/docs/zh-CN/settings) 中的以下条目将嵌套限制为两层：1140要更改该限制，请将 [`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`](/docs/zh-CN/env-vars) 设置为您希望在主对话之下允许的子代理层数。例如，[`settings.json`](/docs/zh-CN/settings) 中的以下条目将嵌套限制为两层：
1115 1141
1277</h2>1303</h2>
1278 1304
1279<Note>1305<Note>
1280 使用 `/subtask` 运行分叉 subagent，需要 Claude Code v2.1.212 或更高版本。当[代理视图被关闭](/docs/zh-CN/agent-view#turn-off-agent-view)时，`/subtask` 不可用，`/fork` 启动分叉 subagent；否则 `/fork` 将整个会话复制到新的[后台会话](/docs/zh-CN/agent-view#from-inside-a-session)中。1306 当[Agent 视图被关闭](/docs/zh-CN/agent-view#turn-off-agent-view)时，`/subtask` 不可用，`/fork` 改为启动分叉子代理；否则 `/fork` 将整个会话复制到新的[后台会话](/docs/zh-CN/agent-view#from-inside-a-session)中。
1281</Note>1307</Note>
1282 1308
1283分叉是一个 subagent，它继承到目前为止的整个对话，而不是从头开始。这消除了 subagents 通常提供的输入隔离：分叉看到与主会话相同的系统提示、工具、模型和消息历史，因此您可以将其交给一个辅助任务而无需重新解释情况。分叉自己的工具调用仍然保持在您的对话之外，只有其最终结果返回，因此您的主 context window 保持干净。当任何其他 subagent 需要太多背景才能有用时，或当您想从相同的起点并行尝试多种方法时，使用分叉。1309分叉是一个 subagent，它继承到目前为止的整个对话，而不是从头开始。这消除了 subagents 通常提供的输入隔离：分叉看到与主会话相同的系统提示、工具、模型和消息历史，因此您可以将其交给一个辅助任务而无需重新解释情况。分叉自己的工具调用仍然保持在您的对话之外，只有其最终结果返回，因此您的主 context window 保持干净。当任何其他 subagent 需要太多背景才能有用时，或当您想从相同的起点并行尝试多种方法时，使用分叉。
1284 1310
1285Claude 通过 Agent 工具请求 `fork` subagent 类型来启动分叉。您可以通过[分叉模式](#turn-fork-mode-on-or-off)控制是否可以这样做，在交互式会话中默认启用。1311分叉模式启用时（默认即为启用），Claude 可以自行启动分叉。要停止分叉，请参阅[关闭分叉模式](#turn-fork-mode-on-or-off)。
1286 1312
1287您可以使用 `/subtask` 后跟任务自己启动分叉，无论分叉模式是否启用。在 v2.1.161 到 v2.1.211 版本中，命令是 `/fork`。Claude Code 从任务的前几个单词命名分叉。以下示例分叉对话以在您继续主会话中的实现时草拟测试用例：1313您可以使用 `/subtask` 后跟任务自己启动分叉，无论分叉模式是否启用。Claude Code 从任务的前几个单词命名分叉。以下示例分叉对话以在您继续主会话中的实现时草拟测试用例：
1288 1314
1289```text wrap theme={null}1315```text wrap theme={null}
1290/subtask draft unit tests for the parser changes so far1316/subtask draft unit tests for the parser changes so far
1327| 上下文 | 完整的对话历史 | 新鲜上下文，带有您传递的提示 |1353| 上下文 | 完整的对话历史 | 新鲜上下文，带有您传递的提示 |
1328| 系统提示和工具 | 与主会话相同 | 来自 subagent 的[定义文件](#write-subagent-files)，[为后台运行过滤](#available-tools) |1354| 系统提示和工具 | 与主会话相同 | 来自 subagent 的[定义文件](#write-subagent-files)，[为后台运行过滤](#available-tools) |
1329| 模型 | 与主会话相同 | 来自 subagent 的 `model` 字段 |1355| 模型 | 与主会话相同 | 来自 subagent 的 `model` 字段 |
1330| 权限 | 提示在您的终端中出现 | [提示在后台运行时在您的主会话中出现](#run-subagents-in-foreground-or-background) |
1331| Prompt cache | 与主会话共享 | 单独的缓存 |1356| Prompt cache | 与主会话共享 | 单独的缓存 |
1332 1357
1333因为分叉的系统提示词和工具定义与父级相同，其第一个请求重用父级的[提示缓存](/docs/zh-CN/prompt-caching#subagents-and-the-cache)。由于这种重用，对于需要相同上下文的任务，分叉的成本低于新的子代理。1358因为分叉的系统提示词和工具定义与父级相同，其第一个请求重用父级的[提示缓存](/docs/zh-CN/prompt-caching#subagents-and-the-cache)。由于这种重用，对于需要相同上下文的任务，分叉的成本低于新的子代理。
1335当 Claude 通过 Agent 工具生成分叉时，它可以传递 `isolation: "worktree"` 以便分叉的文件编辑被写入单独的 git worktree 而不是您的检出。分叉无法生成进一步的分叉。1360当 Claude 通过 Agent 工具生成分叉时，它可以传递 `isolation: "worktree"` 以便分叉的文件编辑被写入单独的 git worktree 而不是您的检出。分叉无法生成进一步的分叉。
1336 1361
1337<h3 id="turn-fork-mode-on-or-off">1362<h3 id="turn-fork-mode-on-or-off">
1338 打开或关闭分叉模式1363 关闭分叉模式
1339</h3>1364</h3>
1340 1365
1341Claude Code 在交互式会话中默认打开分叉模式，在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 和 Agent SDK 中默认关闭。交互式默认值需要 Claude Code v2.1.232 或更高版本。在早期版本中，设置 `CLAUDE_CODE_FORK_SUBAGENT` 为 `1` 以打开分叉模式。1366分叉模式允许 Claude 自行启动分叉。要阻止 Claude 启动分叉：
1342
1343您可以从 Claude Code 处理 Agent 工具的方式判断分叉模式是否打开：
1344
1345* Claude 可以通过请求 `fork` subagent 类型来生成分叉。当 Claude 不请求类型时，如果会话仍然有该类型，它会获得[通用](#built-in-subagents) subagent。从定义生成的 subagents，例如 Explore，照常工作。
1346* Claude Code 在后台运行 Claude 生成的 subagents，分叉和非分叉 subagents 都是如此，除了[保持在前台的情况](#run-subagents-in-foreground-or-background)。Claude Code 也会移除 Agent 工具的 `run_in_background` 参数，因此 Claude 无法请求前台。
1347
1348设置 [`CLAUDE_CODE_FORK_SUBAGENT`](/docs/zh-CN/env-vars) 环境变量以覆盖默认值：
1349 1367
1350* `1` 在非交互模式和 Agent SDK 中打开分叉模式1368* **仅停止分叉**：在您的[设置](#disable-specific-subagents)中将 `"Agent(fork)"` 添加到 `permissions.deny`。
1351* `0` 在每种会话中关闭分叉模式1369* **关闭分叉模式**：按照[让 Claude 等待子代理](#let-claude-wait-for-a-subagent)中的步骤，将 `CLAUDE_CODE_FORK_SUBAGENT` 设置为 `0`。
1352 1370
1353要保持分叉模式打开但阻止 Claude 生成分叉，使用 `Agent(fork)` 规则[禁用 `fork` subagent 类型](#disable-specific-subagents)。Claude Code 仍然在后台运行 Claude 生成的 subagents，除了相同的[保持在前台的情况](#run-subagents-in-foreground-or-background)。1371分叉模式启用时，在您本机上的交互式终端、VS Code 或桌面会话中，Claude 也无法[等待子代理](#run-subagents-in-foreground-or-background)。从 Claude Code v2.1.302 起默认启用分叉模式，而在交互式终端会话中则从 v2.1.232 起默认启用。
1354 1372
1355<h2 id="example-subagents">1373<h2 id="example-subagents">
1356 示例 subagents1374 示例 subagents
