Sub-agents 是 OpenClaw 的后台任务机制。它们运行在独立 session 中，可以并行处理研究、整理、长时间工具调用和慢任务，完成后把结果回传给发起者。
什么时候用 Sub-agent？
适合：
- 长时间资料搜索
- 多方向并行调研
- 大文件总结
- 后台生成报告
- 多个候选方案比较
- 不想阻塞主对话的慢任务
不适合：
- 调用 Codex、Claude Code、Gemini CLI 等外部编码 harness
- 需要完整 IDE/编码 harness 上下文的任务
- 简单一两步就能完成的工具调用
外部 coding harness 应使用 ACP Agents。
基本工作流
- 主 Agent 发起 sub-agent
- Sub-agent 在独立上下文中执行任务
- 完成后触发 announce
- 主会话收到结果并用正常语气转述给用户
这种隔离让主对话不会被大量搜索日志和中间推理淹没。
run 模式与 session 模式
默认是 run：一次性后台任务，完成就返回。
session 模式适合 thread-bound 场景：一个线程持续绑定到同一个 sub-agent，后续回复继续进入该 session。
经验规则：
- 一次性研究：run
- 持续项目线程：session
- 编码 harness：ACP，不用 sub-agent
结果回传：announce
Sub-agent 完成后不会把内部原始元数据直接发给用户，而是通过 announce 步骤把结果交回请求会话。主 Agent 应把结果改写成自然、可读的总结。
这避免了用户看到 runtime id、token stats、内部 transcript 等噪音。
线程绑定
支持线程绑定的渠道中，sub-agent 可以绑定到一个 thread：
- 线程里的后续消息继续路由给该 sub-agent
- 结果回到同一线程
- 可以用 unfocus/idle/max-age 机制解绑或过期
这适合团队协作：每个长期任务一个线程，不污染主频道。
嵌套 Sub-agent
OpenClaw 支持 orchestrator pattern：主 Agent 启动一个 orchestrator sub-agent，orchestrator 再启动多个 worker sub-agent。
适合：
- 多站点并行调研
- 多方案竞品分析
- 多文件批量审查
- 大规模信息汇总
注意控制并发和超时，避免成本失控。
成本与安全建议
- Sub-agent 有独立上下文，会产生额外 token 成本
- 大量并行任务应使用更便宜模型
- 对每个任务设置 runTimeoutSeconds
- 不要无限循环轮询状态
- 对外部输入保持隔离和不信任
- 完成后可自动归档或清理 session
来源：OpenClaw 官方文档 - Sub-agents | 整理：ClaudeEagle