Subagent（子智能体）

子智能体（Subagent） 是由主智能体为一个边界明确的子任务启动的独立智能体线程。它在自己的上下文中探索、执行或审查，只把浓缩结果返回主线程。这个术语已被多个 Agent 产品和框架使用；本文重点记录 Codex 与 Claude Code 的官方实现。

子智能体工作流通常对应 Agentic System Patterns（智能体设计模式）中的 Orchestrator-Workers（编排者-执行者） 模式：

flowchart LR
    U["用户目标"] --> M["主智能体\n分解与编排"]
    M --> E["Explorer\n探索"]
    M --> R["Reviewer\n审查"]
    M --> D["Docs Researcher\n核对文档"]
    E --> M
    R --> M
    D --> M
    M --> O["汇总结果"]

为什么使用子智能体

子智能体主要解决两个问题：

隔离上下文噪声：搜索记录、测试日志、堆栈和大文件分析留在子线程，主线程只接收结论与证据。这能缓解 Context Rot（上下文腐烂），让需求、约束和关键决策不被中间输出淹没。
并行处理独立任务：代码路径探索、安全审查、测试缺口分析和文档核对可以同时执行，缩短等待时间。

它不是无成本加速器。每个子智能体都独立消耗模型推理和工具调用预算；并行写同一批文件还会制造冲突。适合优先委派的是只读、彼此独立、输出可压缩的工作，例如探索、分类、测试、日志分析和专项审查。写密集型工作需要更明确的文件所有权，必要时配合 Agent Worktree（Agent 工作树）隔离。

Codex 中的触发与编排

Codex 默认提供子智能体能力，但不会自行启动子智能体。用户需要显式提出“使用子智能体”“并行委派”或“每个检查点启动一个 Agent”等要求。主智能体负责：

启动和停止子智能体线程
向运行中的线程追加或修正指令
等待多个结果完成
汇总各线程返回的结论

CLI 中可用 /agent 切换和检查各个 Agent 线程。当前官方文档说明，子智能体活动可在 Codex App 和 CLI 中查看。

一个有效的委派指令应同时说明如何拆分、是否等待全部完成、每个 Agent 返回什么格式。例如：让一个 Agent 检查安全风险、一个检查测试缺口、一个检查可维护性，等待三者完成后按类别汇总，并附文件位置。

内置角色与自定义 Agent

Codex 内置三个角色：

角色	用途
`default`	通用后备角色
`worker`	实现和修复
`explorer`	只读代码库探索

可在项目的 .codex/agents/ 或个人目录 ~/.codex/agents/ 中放置独立 TOML 文件定义自定义角色。必填字段是 name、description 和 developer_instructions；模型、推理力度、沙箱、MCP 服务器和 Skill 配置等字段可覆盖父线程配置。

name = "reviewer"
description = "检查正确性、安全风险与缺失测试。"
model = "gpt-5.5"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
先报告可复现的实质问题，并提供文件与符号位置。
忽略不影响正确性的纯风格意见。
"""

自定义 Agent 应当角色窄、边界清楚、工具权限与任务匹配。例如文档核对者只需只读沙箱和文档 MCP；实现者才需要工作区写权限。用 nickname_candidates 可以给同类实例分配易辨认的显示昵称，但昵称不改变其底层角色。

Claude Code 中的定义与作用域

Claude Code 把自定义 subagent 定义为带 YAML frontmatter 的 Markdown 文件：frontmatter 配置身份、模型和能力，正文作为该 subagent 的系统提示词。name 与 description 必填，其中 description 直接参与自动委派判断，因此应该写清楚“何时使用”，而不只是角色名称。

---
name: code-reviewer
description: 审查代码质量、安全性和可维护性。代码修改后主动使用。
tools: Read, Grep, Glob, Bash
model: inherit
permissionMode: plan
---

你是一名只读代码审查者。优先报告可复现的正确性与安全问题，
按严重度输出证据、文件位置和修复建议。

定义位置决定作用域和覆盖优先级：

位置	作用域	优先级
托管设置目录中的 `.claude/agents/`	组织	最高
`--agents` CLI 参数	当前会话	次高
项目 `.claude/agents/`	当前项目，可提交到版本库	3
`~/.claude/agents/`	当前用户的所有项目	4
Plugin 的 `agents/`	启用该插件的环境	最低

项目与用户目录会递归扫描，身份只由 frontmatter 的 name 决定。项目内存在嵌套 .claude/agents/ 时，离当前工作目录更近的同名定义优先；同一作用域内的重名则应通过 /doctor 检查。首次创建一个此前不存在的 agents 目录通常需要重启当前会话，此后编辑已有目录中的定义会被文件监听器自动发现。

可配置能力

Claude Code 的 subagent frontmatter 将“做什么”和“能做什么”分开：

tools 是工具白名单，disallowedTools 是拒绝列表；可精确限制文件读写、Shell、MCP 和继续派生其他 Agent。
model、effort、maxTurns 控制单次任务的推理资源与轮数。
permissionMode 控制审批行为；父会话的 bypassPermissions、acceptEdits 或 Auto Mode 可能优先于子定义。
mcpServers 可只给该 subagent 接入特定 MCP 服务，避免工具描述占用主会话上下文。
skills 在启动时把指定 Skill（技能）全文预载到上下文；它控制预加载，不等于限制该 Agent 只能使用这些 Skill。
memory: user | project | local 启用跨会话记忆，并自动允许读写对应记忆目录。
hooks 为该角色声明 PreToolUse、PostToolUse、Stop 等生命周期约束。
background: true 固定后台运行，isolation: worktree 则把文件修改放进独立 Agent Worktree（Agent 工作树）。

Plugin 提供的 subagent 出于安全原因会忽略 hooks、mcpServers 和 permissionMode；需要这些能力时，应把定义复制到项目或用户作用域。

Claude Code 中的上下文与生命周期

普通 subagent 启动时获得一个全新的独立上下文窗口。它不会看到父对话历史、父线程已读文件或已经调用过的 Skill；父 Agent 需要在委派消息中重新说明任务。它会加载自己的系统提示、委派任务、环境信息、项目的 CLAUDE.md/记忆层级、会话启动时的 Git 状态，以及 skills 字段指定的完整 Skill。内置 Explore 和 Plan 为追求轻量，不加载 CLAUDE.md 与 Git 状态。

flowchart LR
    P["父会话\n需求、约束、决策"] -->|"委派摘要"| S["Subagent 独立上下文"]
    D["Agent 定义\n系统提示与权限"] --> S
    C["CLAUDE.md / Memory\n预载 Skills"] --> S
    S --> T["搜索、日志、工具调用"]
    S -->|"仅返回结论"| P

可通过自然语言点名、@ 提及或让 Claude 自动匹配 description 来委派；@ 提及保证指定角色运行。claude --agent <name> 则不是启动一个旁支，而是让整个主会话直接采用该 Agent 的系统提示、工具限制和模型；项目也可在 .claude/settings.json 用 agent 指定默认角色。

后台 subagent 允许主线程继续工作，权限请求仍会回到主会话。一个实例结束后可以按 Agent ID 或名称继续发送消息来恢复原上下文，而不是创建新的实例；Explore 和 Plan 是一次性内置角色，不能恢复。subagent 会独立自动压缩，其 transcript 也独立于主会话保存。

Claude Code 还支持两种更强的上下文组织方式：

嵌套 subagent：subagent 可继续派生下级 Agent，深度最多五层；从 tools 中移除 Agent 可禁止递归委派。
Fork：继承父会话当时的完整历史、系统提示、工具和模型，适合无法用简短委派消息重建背景的旁支任务。它复用父会话的提示缓存，但失去普通 subagent 的输入隔离。

Claude Agent SDK把同一类能力暴露到 Python / TypeScript：开发者可以用 AgentDefinition 定义专职 subagent，并把 Agent 放进 allowed_tools，让主 Agent 在 SDK run 中委派任务。这样 subagent 不只服务于交互式 Claude Code，也可以嵌入 CI、内部自动化和产品工作流。

Deep Agents 中的单次委派

Deep Agents用内置 task 工具启动临时子智能体。每次调用创建一个全新实例，在独立上下文中自主运行到完成，然后只返回一份最终报告；它不支持与主 Agent 多轮通信，也不保留可继续对话的子线程状态。因此它比 Codex / Claude Code 的可恢复线程更接近无状态函数调用：适合边界清楚、最终结果可压缩的子任务，不适合需要频繁协商的协作。

默认 general-purpose 角色开箱可用，也可配置专项 subagent。Deep Agents 的事件流会为每个委派创建独立 handle，使调用方仍能观察该子任务的消息、工具调用和嵌套委派；“只向主 Agent handoff 一次”不代表运行过程不可观测。

何时使用

适合 subagent 的任务有三个共同特征：输出量大、边界明确、结果可以压缩。例如代码搜索、测试日志分析、文档核对、专项审查和彼此独立的并行研究。主会话更适合频繁来回澄清、多个阶段共享大量上下文、延迟敏感或只需改一处的小任务。

不要把“可以委派”误解为“应该委派”。每个 subagent 都要重新建立任务背景并消耗独立推理预算；并行实例返回过多细节，同样会重新挤占主会话。有效编排的关键不是 Agent 数量，而是把高噪声过程隔离出去，只让可行动结论回来。

Codex 的并发、嵌套与批处理

全局配置位于 config.toml 的 [agents]：

[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800

max_threads 限制同时打开的 Agent 线程数，默认值为 6。
max_depth 限制递归委派深度，默认值为 1：根 Agent 可以启动直接子 Agent，但子 Agent 不能继续向下派生。
job_max_runtime_seconds 是 CSV 批处理 Worker 的默认单任务超时。

提高嵌套深度会放大 Token、延迟、协调和本地资源开销，不能用线程上限消除这些成本。除非任务确实需要递归分解，否则保持浅层编排更容易预测。

Codex 还实验性提供 spawn_agents_on_csv：把 CSV 每一行映射为一个同构子任务，并在所有 Worker 完成后导出合并 CSV。它适合按文件、服务、事故或迁移目标批量审计；每个 Worker 必须按固定 schema 报告一次结果。由于该能力仍属实验性，不应把当前接口视为稳定协议。

权限边界

子智能体继承当前会话的沙箱与审批策略，父线程本轮设置的运行时覆盖也会重新应用到子线程。自定义 Agent 可以进一步收紧权限，例如把探索者设为只读。

交互式 CLI 可以展示非当前线程发起的审批请求；无法展示新审批的非交互任务会失败，并把错误返回父工作流。这意味着子智能体不会绕过 Agent Sandbox（Agent 沙箱）：委派扩大了并行度，不应扩大授权范围。

在 Claude Code 的 Auto Mode 中，subagent 还有额外的 handoff 检查。委派出去之前，handoff classifier 会检查“这个子任务是否真由用户授权”，因为一旦进入子线程，orchestrator 的委派消息会变成 subagent 的用户指令，看起来天然合法。subagent 返回时，另一个 handoff classifier 会检查它的完整动作历史；若发现风险，结果仍返回给主 Agent，但会附带安全警告而不是直接丢弃。这把多 Agent 编排中的权限判断前移到委派边界，避免主 Agent 通过“让子 Agent 去做”绕过动作前审查。

多 Agent 系统还有一类相反风险：subagent 可以隔离不可信内容，只把结构化事实返回主线程；但如果主线程把“来自我们自己的 subagent 的总结”看得比原始工具输出更可信，攻击者就可能通过污染 subagent 的输出完成 trust escalation。设计上应明确 subagent 输出的信任级别，不要因为它经过了内部 Agent 改写，就自动高于网页、文件或 MCP tool result。