详细讲讲Subagent

在 OpenClaw 的多智能体协同体系中，Subagent（子智能体）绝对是提升效率、控制成本的核心角色——它就像主Agent的“后台分身”，能独立并行干活，不耽误主会话，还能精准拆分复杂任务。

今天就从定义、特性、架构、用法到最佳实践，一次性把 Subagent 讲透，新手也能快速上手～

一、先搞懂：什么是 Subagent？

一句话总结：Subagent 是主Agent派生的独立后台工作单元，在完全隔离的会话中执行任务，完成后自动把结果回传给主会话，不用主Agent一直等待。

核心定位很明确：解决“主Agent忙不过来、任务阻塞、成本过高”的问题，主打一个「并行干活、分工明确」。

补充一个小细节：Subagent 有专属的会话标识（格式：agent:<agentId>:subagent:<uuid>），和主会话完全隔离，不会互相干扰。

二、必记核心特性（7个关键点）

Subagent 的优势的都藏在这些特性里，记牢就能灵活用对：

非阻塞：主Agent调用后立即返回 runId，不用等待子代理完成，主会话可以继续响应用户。

会话隔离：有自己的独立上下文、独立工具权限、独立对话历史，互不干扰更安全。

上下文精简：只加载 AGENTS.md + TOOLS.md 两个核心文件，大大节省 Token 成本。

禁止嵌套扇出：默认嵌套深度（depth）=1，子代理不能再创建自己的子代理，避免资源浪费。

工具权限收紧：默认不继承主会话的工具，需要手动配置，安全可控。

自动通知：任务完成后，会通过 announce 功能自动把结果回传到主会话频道，不用手动查询。

成本优化：主Agent用贵模型（比如 Opus）做规划，子代理用便宜模型（比如 Haiku）执行，能省60%+成本。

三、核心架构：Subagent 的三层深度体系

OpenClaw 对 Subagent 的层级有明确限制，避免无限嵌套导致资源爆炸，三层体系如下：

Depth 0（主Agent）：顶层“大脑”，负责任务编排和决策，始终可以创建子代理（spawn）。

Depth 1（子代理）：中层“执行者/协调者”，可以做具体任务，也可以协调其他子代理；只有当配置 maxSpawnDepth≥2 时，才能再创建子代理。

Depth 2（孙代理）：底层“纯执行者”，只能做具体任务，永远不能再创建子代理。

结果回传逻辑也很清晰：孙代理 子代理 主Agent 用户，形成链式通告，确保结果不丢失。

四、完整生命周期：4步走完一个Subagent任务

从创建到完成，Subagent 的生命周期只有4步，流程简单且可控：

1. Spawn（创建）

主Agent调用 sessions_spawn 工具（或输入 /subagents spawn 命令），网关会生成一个专属会话ID，把任务加入 Subagent 专用队列，同时立即返回 runId，主会话继续正常响应。

2. Queue（排队）

任务会在专用队列中排队，并发数量受 maxConcurrent 控制（默认8个），不会影响主会话的调度速度。

3. Execute（执行）

Subagent 在独立会话中运行，加载精简版系统提示和必要文件，超时、重试、崩溃恢复等操作都独立管理，不影响主Agent。

4. Announce（通告）

任务完成后，自动把结果发回主会话频道；如果不需要回传，可以设置返回 ANNOUNCE_SKIP 跳过通告，结果默认保留60分钟后归档。

五、常用配置：一键复制就能用

Subagent 的配置主要在 agents.defaults.subagents 中，以下是最常用的配置模板，根据需求微调即可：

agents:defaults:   subagents:     enabled: true               # 启用子代理（必开）     model: claude-haiku-4       # 子代理默认模型（选便宜的更省成本）     maxConcurrent: 8            # 最大并发数（默认8，可按机器资源调整）     runTimeoutMinutes: 30        # 单任务超时时间（30分钟足够大多数任务）     archiveAfterMinutes: 60      # 结果保留时长（默认60分钟）     maxSpawnDepth: 1             # 嵌套深度（默认1，禁止子代理再 spawn）     tools: []                    # 子代理可用工具（默认空，按需添加）

六、两种使用方式：小白也能上手

Subagent 有两种常用使用场景，分别对应“用户直接操作”和“Agent内部调用”，按需选择即可。

1. 命令行方式（用户直接用）

适合手动触发子代理任务，复制命令修改参数即可：

# 后台创建子代理，执行数据分析任务/subagents spawn \ --name data_analyst \          # 子代理名称（自定义） --model claude-3-sonnet \      # 子代理使用的模型 --tools read,write,web_search  # 子代理可用工具 --task "分析 sales.csv 并生成报告"  # 具体任务

2. 代码/工具调用（Agent内部用）

适合Agent自动拆分任务时调用，用 JSON 格式传入参数：

{"type": "tool_use","name": "sessions_spawn","input": {   "task": "把 Python 代码转成 TypeScript",  # 任务描述   "model": "claude-3-sonnet",              # 模型   "label": "refactor-job",                 # 任务标签（自定义）   "tools": ["exec", "read"]                # 可用工具 }}

七、主Agent vs Subagent：一张表分清差异

很多人会混淆主Agent和Subagent，用这张表对比，一眼看清区别：

八、最佳实践：避坑+提效，少走弯路

掌握这些技巧，能让 Subagent 发挥最大价值，还能避免踩坑：

模型分层使用：主Agent用贵模型（Opus）做规划、综合决策，子代理用便宜模型（Haiku/Sonnet）做具体执行，能省60%+成本。

合理拆分任务：长任务、慢工具调用、可并行的任务，全部交给 Subagent，主会话只负责交互和任务编排。

权限最小化：子代理只给完成任务必需的工具，不继承主会话的敏感工具，降低安全风险。

控制嵌套深度：默认设置 maxSpawnDepth=1，避免无限嵌套导致资源爆炸，除非有特殊需求，否则不建议调高。

合理设置超时和并发：根据任务复杂度调整 runTimeout，maxConcurrent 匹配机器资源，避免队列拥堵。

及时保存重要结果：结果默认只保留60分钟，重要任务的结果要及时手动保存，避免丢失。

九、典型应用场景

Subagent 适合所有“不想阻塞主会话、需要并行执行”的场景，常见用法有：

并行数据爬取、数据分析

后台代码审查、代码重构

长文档摘要、批量翻译

批量文件处理（如格式转换）

慢 API/工具调用（不阻塞主聊天）

十、一句话总结

Subagent 是 OpenClaw 实现「多智能体并行、任务隔离、成本优化」的核心机制——主Agent做“大脑”负责规划，Subagent做“手脚”负责执行，各司其职，让多智能体协同更高效、更省钱。