使用子智能体

版本号与默认值以官方为准。

自动委派

Claude 根据你请求里的任务描述、子智能体配置的 description 字段和当前上下文自动委派。想鼓励主动委派，就在 description 里写「use proactively」之类的话。描述要简短：所有子智能体的描述合计超过 15,000 token 时启动会警告，但仍会加载全部子智能体。随插件分发的子智能体，可以用 claude plugin eval 在一批真实提示上度量委派的可靠度（有无该插件各跑一遍并评分）。

显式调用

从一次性建议到会话级默认，有三种方式：

• 自然语言：在提示里点名子智能体，Claude 决定是否委派，例如「Use the test-runner subagent to fix failing tests」。
• @ 提及：保证本次任务运行该子智能体。输入 @ 从补全里选，写法如 @"code-reviewer (agent)" look at the auth changes。你的完整消息仍交给 Claude，由它写子智能体的任务提示——@ 提及控制调用哪个子智能体，不控制它收到什么提示。插件子智能体以带作用域的名字出现（my-plugin:code-reviewer）；也可以手动输入 @agent-<名称>，插件的写成 @agent-my-plugin:code-reviewer（输入这种形式时补全显示文件，但提交时仍会解析）；正在运行的具名后台子智能体也出现在补全里并显示状态。
• 会话级：claude --agent code-reviewer 让主线程自己承担该子智能体的工具限制和模型。除非该智能体的 prompt 为空，自定义子智能体的系统提示会完全替换默认的 Claude Code 系统提示（与 --system-prompt 相同）；CLAUDE.md 和项目记忆仍通过正常消息流加载，即使定义里设了 omitClaudeMd。启动标题里显示 @<名称> 以便确认。选择在恢复会话时保留（工具限制和模型一并恢复）；若该智能体已不存在，会话以默认工具继续并显示点名该智能体的警告。插件提供的子智能体可只传名字，重名时传带作用域的名字（my-plugin:security-reviewer，子文件夹里的写 my-plugin:review:security）。

想让项目里每个会话都默认如此，在 .claude/settings.json 里设 "agent": "code-reviewer"；命令行标志优先于该设置。

前台与后台

• 前台子智能体阻塞主对话直到完成，权限提示传给你。
• 后台子智能体与你的工作并发运行；遇到需要权限的工具调用时，Claude Code 在主会话里弹出提示并点名是哪个子智能体在请求。批准则继续，按 Esc 只拒绝那一次工具调用而不停止子智能体。

对 Claude 用 Agent 工具生成的每个子智能体，Claude Code 按下列第一条适用的规则决定前台还是后台：

1. 若是进程内智能体团队的队友生成了它，则前台运行；队友生成的子智能体定义里设了 background: true 会报错拒绝；fork 模式关闭且你没有关闭后台任务时，队友设 run_in_background: true 同样报错。
2. 设了 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1：所有会话里都前台运行，无论是否 fork 模式。
3. fork 模式开启（交互会话默认如此）：fork 与非 fork 子智能体一律后台运行，Claude 不能要求前台。
4. fork 模式关闭：默认后台，Claude 需要结果才能继续时前台。非交互 -p 与 Agent SDK 默认关闭 fork 模式；想让某个子智能体即使 Claude 要结果也留在后台，设前置信息 background: true。

带 context: fork 的 Skill 遵循「在子智能体里运行 Skill」的规则。后台子智能体使用比前台更小的内置工具集（对话 fork 和已恢复的前台子智能体除外）。后台子智能体的每个权限提示都显示在主会话里；你以持续超过那一次调用的选择回答（如本会话余下时间的授权）时，答案应用到整个会话，包括主对话。后台子智能体可以让后台 Bash 或 PowerShell 命令在其回合结束后继续运行，命令结束时 Claude Code 向它发通知。后台子智能体的结果以后续回合里的完成通知到达 Claude；Claude 会等通知再汇报结果，你先问进度时它会说仍在运行（v2.1.211 之前 Claude 有时会汇报尚未完成的后台子智能体的结果）。

你也可以自己调节：fork 模式关闭时，请 Claude 在后台或前台运行某任务；按 Ctrl+B 把运行中的任务放到后台。子智能体面板（提示输入下方）清除一行有两种方式：成功完成则立即移除该行，并（屏幕阅读器模式除外）在页脚显示 30 秒的 /tasks to see subagents，这 30 秒内运行 /tasks 并在该子智能体上按 Enter 可打开它的转录；失败或被你停止的保留该行 30 秒，选中后按 x 可提前清除。完成的后台子智能体在 /tasks 里同样保留 30 秒（标记为完成并排在运行中的任务之后，详情视图保持打开）；失败或被停止的离开列表。

子智能体名称

Claude 可以在 Agent 工具调用里传 name 参数给子智能体命名，且可能不问你就这么做。名称让子智能体可寻址：Claude 可以在它结束后按名称给它发消息或恢复它。启用了智能体团队的交互会话里，Claude 从主对话以 name 生成的子智能体会作为队友启动，除非该调用是 fork 或在调用上自己传了 isolation（定义前置信息里的 isolation 值不能阻止这点，此时队友运行在主会话的工作目录）。

子智能体里的 API 错误

流式响应中途被切断、部分响应含文本但没有工具调用时，Claude Code 会提示子智能体继续而不是结束运行（交互会话里也如此），续写次数用完才以错误结束。自 v2.1.199 起，运行以 API 错误结束的子智能体（如用量上限或反复的服务器错误）把失败汇报给 Claude，而不是把错误文本当作子智能体的发现返回：前台时，若限流、过载或服务器错误切断了已产出文本的子智能体，Agent 工具返回该部分输出并注明被切断、未完成任务；什么都没产出或只有工具调用的，以 Agent terminated early due to an API error 失败并附错误详情。后台时子智能体被标记为失败，Claude 收到的结束消息点名该 API 错误并包含最后的输出，部分工作不丢。若你配置了回退模型链，且子智能体遇到该链所覆盖的失败（如其模型不可用），Claude Code 把子智能体切到链里第一个接受请求的模型。API 错误恢复后，让 Claude 重试任务或恢复该子智能体。

输出扫描

Claude Code 在 Claude 读取之前扫描每个子智能体的最终报告，因为子智能体可能读过你没审阅的文件、网页或命令输出，其中的文字可能带有针对主对话的指令。扫描从不删除或改写内容，只做两种你可能注意到的改动：插入反斜杠——对模仿 Claude Code 自身输出的文本（如 <system-reminder> 标签、以 Human: 或 Assistant: 开头的行）插入反斜杠，让模仿读作普通文本；前置标记行——报告模仿类似 <system-reminder> 的标签、或提到 bypassPermissions、--dangerously-skip-permissions 这样的权限设置时，前置一行以 [harness: subagent output matched instruction-shaped pattern(s): 开头的标记（权限设置的提及只加标记行，文本保持原样）。扫描不判断内容是否恶意，也不改变报告里的指令能做什么：Claude 因报告而发起的工具调用仍要过会话的权限检查和沙箱，它不能替代限制子智能体能触及的范围。作为子智能体结果返回的报告还带有一个标明「子智能体输出」的头，声明报告里的指令或批准声明只是子智能体的话，不代表你的授权；后台子智能体的报告在被标为自动事件（而非你的消息）的完成通知里到达。需要 v2.1.210+。

常见模式

• 隔离高产出操作：跑测试、取文档、处理日志会消耗大量上下文；交给子智能体后，冗长输出留在其上下文里，只有相关摘要返回主对话。例如「Use a subagent to run the test suite and report only the failing tests with their error messages」。
• 并行研究：对相互独立的调查，生成多个子智能体同时工作，各自探索后由 Claude 综合，例如「Research the authentication, database, and API modules in parallel using separate subagents」。研究路径互不依赖时最好用。注意：子智能体完成后结果返回主对话，许多子智能体各返回详细结果会占用大量上下文，且每个子智能体运行时自己也花 token。需要持续并行或装不进一个上下文窗口的工作，用独立会话并让 Claude 在它们之间传递发现。
• 串联子智能体：多步工作流让 Claude 依次使用子智能体，每个完成后把结果返回 Claude，再由它把相关上下文传给下一个，例如「Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them」。

子智能体还是主对话

用主对话：任务需要频繁往返或迭代细化；多个阶段共享大量上下文（规划、实现、测试）；做快速的针对性修改；延迟很重要（非 fork 子智能体从头开始，可能需要时间收集上下文）。用子智能体：任务产出你不需要留在主上下文里的冗长输出；想强制特定的工具限制或权限；工作自成一体、可以返回摘要。想要在主对话上下文里运行的可复用提示或工作流，考虑 Skill。问对话里已有内容的问题，用 /btw：它能看到完整上下文但没有工具访问，答案不进入历史。

嵌套子智能体

默认子智能体可以生成自己的子智能体，主对话之下最多三层。到达深度上限时，Claude Code 对除 fork 之外的每个子智能体不提供 Agent 工具，所以处于上限的子智能体自己完成委派的工作并返回一份摘要（上限处的 fork 在继承的工具列表里保留 Agent，但调用时报错而不生成）。嵌套适合本身可拆成并行子任务的委派，比如一个审查子智能体为每条发现派一个验证者。交互会话里只有顶层子智能体的摘要返回给你，中间输出不进入主对话：启动了后台子智能体的子智能体会等它们的结果再结束；非交互模式和 Agent SDK 里启动者不等待，所以在启动者结束后才完成的嵌套后台子智能体会向主对话报告。

用环境变量 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 设置主对话之下的子智能体层数，如在 settings.json 的 env 里设为 "2"，则你的子智能体可以委派给第二层，第二层不能再往下；设 1 关闭嵌套。嵌套子智能体的配置和作用域解析与顶层相同；想让某个子智能体（比如应保持只读的审查者）不生成子智能体，从其 tools 列表省略 Agent，或加入 disallowedTools。终端里嵌套子智能体在提示输入下方的面板里显示为一棵树，仍有后代的行标 (+N)，打开一行可看到它的兄弟和直接子级以及回到 main 的路径。

早期版本的默认不同：v2.1.172 到 v2.1.216 默认可嵌套至五层且不能改；v2.1.217 到 v2.1.218 默认限制为一，v2.1.219 起默认三。

并发上限

两个限制各有变量：并发上限在运行中的子智能体过多时阻止 Claude 再生成，深度上限限制嵌套多深；一次会话里能生成的子智能体总数没有限制。默认当会话里 20 个子智能体在运行时，再用 Agent 工具生成会以 Concurrent subagent limit reached 失败，错误告诉 Claude 不要重试；运行数降到上限之下后生成再次成功。用 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS（任意正整数）改上限；启用 ultracode 的会话不受此限（需要 v2.1.217+）。这个限制只阻止 Claude 用 Agent 工具生成的子智能体，但其他运行占用同样的名额：你用 /subtask 启动的会话内 fork 在运行时占一个名额且永不被限制阻止；恢复已完成的子智能体占新名额但不检查上限，所以恢复可以把运行数推过上限。其他功能运行的智能体（如工作流智能体和智能体团队队友）遵循各自的限制。

管理子智能体的上下文

启动时加载什么

每个子智能体从一个全新的、隔离的上下文窗口开始：看不到你的对话历史、你已调用的 Skill 或 Claude 已读的文件；Claude 写一条委派消息概述任务，子智能体据此工作。例外是 fork，它继承父对话。非 fork 子智能体的初始上下文包含：

• 系统提示：智能体自己的提示加上 Claude Code 附加的环境细节，不是 Claude Code 系统提示；自定义子智能体在 Markdown 正文或 prompt 字段里定义，内置智能体有预定义提示。
• 任务消息：Claude 交接工作时写的委派提示。
• CLAUDE.md 文件：主对话加载的每一层级的 CLAUDE.md 层级——~/.claude/CLAUDE.md、项目规则、CLAUDE.local.md、托管策略文件，以及作为项目指令加载的 AGENTS.md；内置 Explore 和 Plan 跳过它们。设了 omitClaudeMd 的子智能体只加载托管策略文件（来自托管设置的定义则一个也不加载）。
• Git 状态：子智能体启动时从仓库读取的快照；不在 Git 仓库里或快照被关闭（见 includeGitInstructions 设置）时没有；Explore 和 Plan 无论如何都跳过。
• 预载 Skill：skills 字段指名的 Skill 的完整内容；内置智能体不预载 Skill。
• 同伴名册：一条系统提醒，列出 main 和会话里每个其他具名智能体，每一项都是 SendMessage 的有效 to 值（需要 v2.1.206+）；只在子智能体工具包含 SendMessage 且至少一个其他智能体有名字时出现，是启动时的快照，之后命名的智能体不出现。

主对话读取这些子智能体的结果时仍拥有完整的 CLAUDE.md，所以多数规则不必传给子智能体本身；某条规则必须传到时（如「忽略 vendor/ 目录」），在委派时给 Claude 的提示里重述。你不能改变哪些子智能体接收 git 状态，只有 Explore 和 Plan 跳过。有些主对话状态永远到不了非 fork 子智能体：输出风格（子智能体运行自己的系统提示，除 fork 外你的输出风格不塑造其回答）；自动记忆（主对话的自动记忆不加载，要给子智能体自己的持久记忆用 memory 字段）；上下文窗口大小（由子智能体自己的模型决定，委派给窗口较小的模型就得到较小的窗口）。

恢复子智能体

每次调用子智能体都会创建新实例而不是延续旧的。想接着已有子智能体的工作，就请 Claude 恢复它。恢复的子智能体保留完整的对话历史（所有先前的工具调用、结果和推理；若它生成过自己的后台子智能体，历史里包括它们在运行期间交付的结果），从停下的地方继续。要点：

• 子智能体完成时 Claude 收到它的智能体 ID；内置 Explore 和 Plan 是一次性的、不返回 ID，Claude 无法恢复，需要继续工作时用 general-purpose 或自定义子智能体。
• 子智能体在 maxTurns 上限停止时，返回输出被标为部分；对返回 ID 的子智能体，结果里还注明 Claude 可以给它发消息从停下处继续。
• Claude 用 SendMessage 工具，以智能体 ID 或名称作 to 恢复它。SendMessage 不要求启用智能体团队，只有 shutdown_request、plan_approval_response 这类结构化团队协议消息才要求；在启用了跨会话消息的会话里，Claude 还能用同一工具给你本机或其他机器上的其他 Claude Code 会话发消息。
• 例如先「Use the code-reviewer subagent to review the authentication module」，完成后再说「Continue that code review and now analyze the authorization logic」，Claude 就带着先前对话的完整上下文恢复子智能体。
• Claude 给已完成的子智能体发 SendMessage 时，它在后台恢复，无需新的 Agent 调用；被 Claude 用 TaskStop 停止的子智能体，在其停止的运行退出后同样适用。恢复的运行保留首次运行时的工具集，并能继续读取原运行预热的提示缓存。
• 带有 SendMessage 工具的子智能体也能发这种消息；交互会话里被恢复的智能体向恢复它的子智能体汇报，而不是你的主对话，那个子智能体等结果再结束自己的工作；子智能体给自己汇报的对象（如它的启动者）发消息时，Claude Code 恢复该智能体但不重定向其结果。
• 你自己停止的子智能体（在 /tasks 里按 x 或 SDK 的 stop_task 请求）不会自动恢复：Claude 给它发消息会被拒绝，并告知该智能体已被取消。它的行还在子智能体面板里时，可在其转录里输入来自己恢复它，之后 Claude 的消息又能自动恢复它。
• 恢复在同一 ID 下启动新运行，所以已失败或完成的子智能体在任务列表和 Agent SDK 的任务事件里重新显示为运行中（v2.1.205 之前仍显示先前的失败或完成状态）。
• 自 v2.1.199 起，SendMessage 会检查某个名称仍指向对话里先前触达的同一个智能体；若更新的智能体占用了该名称（如重新生成的后台智能体复用了名字），Claude Code 拒绝发送以免误投，错误里报告该名称现在指向哪个智能体以便 Claude 重新定位；要触达仍在运行的较早智能体，Claude 用生成它时收到的智能体 ID。检查范围限于当前对话，/clear 后重置。
• 自 v2.1.198 起，子智能体把启动它的智能体发来的消息当作正常的任务指示（含任务中途的纠正），在自己的权限设置内行动。无论发送者是谁，两条限制仍然成立：任何智能体的消息都不算你对待处理权限提示的批准；任何智能体消息都不能改变子智能体的权限设置、CLAUDE.md 或配置。只有权限系统或你自己的消息能给出批准。

需要引用 ID 时可以问 Claude，也可在转录文件 ~/.claude/projects/{project}/{sessionId}/subagents/ 里找到，每份转录存为 agent-{agentId}.jsonl。子智能体转录独立于主对话持久：主对话压缩时子智能体转录不受影响（存在单独的文件里）；在其会话内持久，重启 Claude Code 后恢复同一会话即可再次恢复子智能体；在 cleanupPeriodDays 保留期（默认 30 天）之后被自动清理。

自动压缩

子智能体用与主对话相同的逻辑支持自动压缩，触发条件相同，CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 也适用于子智能体（何时生效见环境变量参考）。压缩事件记在子智能体转录文件里，如 {"type":"system","subtype":"compact_boundary","compactMetadata":{"trigger":"auto","preTokens":167189}}，其中 preTokens 是压缩前使用的 token 数。