文档来源：https://code.claude.com/docs/en/sub-agents & /en/agent-teams

更新时间：2026.04.08（Claude Code v2.1.32+）

Claude Code 在最新版本中引入了一套完整的多 Agent 协作体系：从单会话内的 Subagent（子代理）到跨会话的 Agent Teams（代理团队）。这套架构的设计选择与 OpenAI 的 Harness Engineering 理念、以及 OpenClaw 自身的调度模型高度呼应。核心洞察都是：好的 Agent 系统不是训练一个更强的模型，而是设计一套更好的协作架构。

Subagent：单会话内的并行执行

Subagent 是运行在独立上下文窗口中的专用 AI 助手。当主 Agent 遇到匹配子代理描述的任务时，它会委托给子代理，子代理独立工作并返回结果。

三个内置子代理

  • Explore（探索者）：使用 Haiku 模型，只读权限，专注于代码搜索和分析。支持三级深度（quick/medium/very thorough）。主 Agent 需要理解代码但不修改时，自动委托给它。
  • Plan（规划者）：继承主对话模型，只读权限，用于 Plan Mode 下收集上下文。关键设计：禁止嵌套（子代理不能再派生子代理），避免无限递归。
  • General-purpose（通用）：继承主对话模型，全工具权限，用于需要探索+修改的复杂多步任务。

自定义子代理的架构

子代理是带 YAML frontmatter 的 Markdown 文件，支持以下配置维度：

  • 作用域分级：Organization > CLI > Project（.claude/agents/） > User（~/.claude/agents/） > Plugin
  • 工具限制：可以精确控制子代理能用哪些工具（如 Explore 只给读权限）
  • 模型选择：可以让子代理用更快更便宜的模型（如 Haiku），控制成本
  • 持久记忆：可选开启 Auto Memory，子代理跨会话积累洞察
  • Hooks：可以挂载自定义脚本在子代理生命周期的特定节点执行
关键设计洞察：子代理的核心价值不是「并行」，而是「上下文隔离」。每个子代理有自己的上下文窗口，探索过程中产生的大量中间信息不会污染主 Agent 的上下文。这和 Harness Engineering 的「渐进式披露」理念完全一致——只把结果带回主上下文，过程留在自己的窗口里。

Agent Teams：跨会话的团队协作

Agent Teams 是更进一步的多 Agent 架构——多个 Claude Code 实例作为「队友」协作，每个都有完全独立的上下文窗口和会话。这是实验性功能，需要设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 启用。

Subagent vs Agent Teams 架构对比

  • Subagent：主 Agent 派生子代理，子代理完成工作，结果汇报给主 Agent。子代理之间不通信。
  • Agent Teams：Lead 创建队友，共享任务列表，队友之间直接通信，自主协调。
  • 通信模式：Subagent 是星型拓扑（只和主 Agent 通信），Agent Teams 是全连接拓扑（队友间直接通信）。
  • 成本：Subagent 结果摘要后回到主上下文（较省），Agent Teams 每个队友都是独立 Claude 实例（较贵）。

Agent Teams 的关键能力

  • 共享任务列表：Lead 创建任务，队友自行认领，自协调工作分配。
  • 直接通信：队友之间可以互相发消息、分享发现、挑战对方的结论。
  • 显示模式：In-process（同一终端内切换）或 Split panes（tmux/iTerm2 分屏）。
  • 计划审批：可以要求队友先做规划，Lead 审批通过后再执行。这不就是 Harness Engineering 的 Plan Mode 在多 Agent 场景的推广吗？
  • 模型指定：每个队友可以使用不同的模型（如 Explore 用 Haiku，Architecture 用 Opus）。

最佳使用场景

  • 研究与评审：多个队友同时调查问题的不同方面，然后分享和挑战彼此的发现。
  • 新模块开发：每个队友独立负责一个模块，互不干扰。
  • 调试竞争假设：队友并行测试不同的理论，更快收敛到正确答案。
  • 跨层协调：前端、后端、测试各自有队友负责，减少上下文切换。

与 OpenClaw 调度模型的对照

OpenClaw 的 sessions_spawn/subagent 机制与 Claude Code 的 Subagent 架构在理念上高度一致：

  • 独立上下文：OpenClaw 的 isolated session 和 Claude Code 的 subagent 都拥有独立上下文窗口，避免主会话被中间过程污染。
  • 任务委托：OpenClaw 通过 sessions_spawn 派发任务，Claude Code 通过自然语言委托——两条路线，同一目标。
  • 结果汇报：OpenClaw 通过事件回流获取结果（push-based），Claude Code 也是子代理完成后主动汇报。
  • 并行拆分：OpenClaw 的 AGENTS.md 明确偏好「能拆就拆，能并行就并行」，Claude Code 的 Agent Teams 将这一理念产品化。

差异在于成熟度：Claude Code 的 Agent Teams 还是实验性功能（需要手动启用），而 OpenClaw 的 cron + session 模型已经是生产级架构。但在多 Agent 直接通信方面，Claude Code 的 Agent Teams 走得更远。

Harness Engineering 视角的四个关键启示

  1. 上下文隔离 > 模型能力：Subagent 的核心价值是隔离探索过程，不是并行加速。一个用 Haiku 的 Explore 子代理比用 Opus 的主 Agent 直接探索更高效，因为 Haiku 够快且不会污染主上下文。
  2. 知识进版本库 > 对话记忆：子代理配置（.claude/agents/*.md）入 git，团队共享。这和 CLAUDE.md 入版本库是同一逻辑——知识结构化持久化，不靠对话记忆。
  3. 环境约束 > prompt 叮嘱：子代理可以通过 tools 配置精确限制能做什么（Explore 只读，不能写）。这比在 prompt 里说「不要修改文件」可靠一万倍。
  4. 自协调 > 中心调度：Agent Teams 的共享任务列表加队友间直接通信，比 Lead 一个人分配所有任务更灵活。这启发了 OpenClaw 未来的多 Agent 协作模式——从「中心化调度」走向「市场化自协调」。

对工程实践的具体建议

  • 在 CLAUDE.md 中定义项目级 Subagent：比如一个只读的 code-reviewer、一个只做测试的 tester。入版本库，团队共享。
  • 给 Subagent 用便宜模型：Explore 用 Haiku，Plan 用 Sonnet，只有 Implement 用 Opus。成本降低 60-80%。
  • 用 Agent Teams 做设计评审：创建 3 个队友分别扮演「实现者」「评审者」「魔鬼代言人」，并行探索不同角度。
  • 给 Subagent 开启持久记忆：让 code-reviewer 积累代码库的常见问题模式，每次评审都比上次更精准。

相关阅读

  • Claude Code Subagents 文档：https://code.claude.com/docs/en/sub-agents
  • Claude Code Agent Teams 文档：https://code.claude.com/docs/en/agent-teams
  • OpenClaw 调度模型：sessions_spawn + cron + isolated session
  • Harness Engineering：环境设计 > 模型能力

逍遥云初 | 2026.04.08