OpenClaw实战教程系列第09篇 - 多 Agent 协作：让 AI 带团队

一个 AI 不够？让主 AI 当监工，派一群子 AI 并行干活。

---

开篇：一个 AI 的瓶颈

你有没有遇到过这种情况：给 AI 一个大任务，它一步一步慢慢做，你等了半小时，才做完一半？

这不是 AI 不够聪明，而是单线程工作的固有局限。

想象一下：你要优化 4 个网站的 SEO。

单 AI 方案：一个个优化，每个 30 分钟，总共需要 2 小时。

多 Agent 方案：主 AI 分析任务、拆成 4 个子任务，同时启动 4 个子 Agent 各负责一个网站，30 分钟后 4 个网站同时完成，主 AI 汇总结果。

效率提升 4 倍。

这就是 Sub-agent（子代理）的核心价值：并行处理、分工协作、效率倍增。

---

Sub-agent 核心概念

架构图

┌──────────────────────────────────────────────────────────┐
│                    主 Agent（你正在对话的）                 │
│                                                          │
│  "优化这 4 个网站的 SEO"                                   │
│                      │                                   │
│                      ▼                                   │
│           ┌─────────────────┐                           │
│           │  任务分解        │                           │
│           │ - 网站 A         │                           │
│           │ - 网站 B         │                           │
│           │ - 网站 C         │                           │
│           │ - 网站 D         │                           │
│           └────────┬────────┘                           │
│                    │                                     │
│    ┌───────────────┼───────────────┐                    │
│    ▼               ▼               ▼               ▼    │
│ ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐    │
│ │Agent │      │Agent │      │Agent │      │Agent │    │
│ │  A   │      │  B   │      │  C   │      │  D   │    │
│ └──┬───┘      └──┬───┘      └──┬───┘      └──┬───┘    │
│    │             │             │             │         │
│    ▼             ▼             ▼             ▼         │
│  执行           执行           执行           执行       │
│  任务A          任务B          任务C          任务D      │
│    │             │             │             │         │
│    └─────────────┴─────────────┴─────────────┘         │
│                      │                                   │
│                      ▼                                   │
│           ┌─────────────────┐                           │
│           │   结果汇总       │                           │
│           │ "4 个网站已完成  │                           │
│           │   共优化 23 处"  │                           │
│           └─────────────────┘                           │
└──────────────────────────────────────────────────────────┘

关键特性

特性	说明
独立 Session	每个子 Agent 有自己的上下文，互不干扰
并行执行	多个子 Agent 同时运行，加速任务完成
非阻塞启动	sessions_spawn 立即返回，主 Agent 不用等待
自动汇报	完成后自动通知主 Agent 所在的聊天渠道
灵活配置	可为不同任务选择不同模型、不同超时时间

重要限制（必读）

⚠️ 子 Agent 不能再派生子 Agent。官方默认 maxSpawnDepth: 1，即子 Agent 无法调用 sessions_spawn。这是安全设计，防止无限嵌套。

⚠️ 每个 Agent 最多同时 5 个子 Agent（maxChildrenPerAgent: 5）。超过这个数量的请求会被排队等待。

⚠️ 子 Agent 的 announce 是尽力而为。如果 Gateway 重启，待发送的“任务完成通知”可能丢失。

---

使用场景

场景 1：编码任务（最常用）

任务：开发一个新功能，需要同时修改前端、后端、数据库。

分工：
- 子 Agent 1（Claude Code）：写后端 API
- 子 Agent 2（Claude Code）：写前端组件
- 子 Agent 3：更新数据库 schema
- 主 Agent：审核代码、协调接口

场景 2：多语言翻译

任务：把一篇英文博客翻译成 5 种语言。

分工：
- 子 Agent 1：翻译成中文
- 子 Agent 2：翻译成日文
- 子 Agent 3：翻译成韩文
- 子 Agent 4：翻译成法文
- 子 Agent 5：翻译成西班牙文

优势：5 种语言同时翻译，总时间 = 翻译 1 种语言的时间

场景 3：数据采集

任务：采集 5 个网站的信息（注意：不超过 5 个并发限制）。

分工：
- 子 Agent 1-5：各负责 1 个网站
- 每个子 Agent 独立采集、解析、保存
- 主 Agent 汇总成统一格式

场景 4：报告生成

任务：生成本周工作总结报告。

分工：
- 子 Agent 1：整理本周完成的代码提交
- 子 Agent 2：整理本周的会议记录
- 子 Agent 3：整理本周解决的问题
- 主 Agent：综合三份材料，生成最终报告

---

sessions_spawn：启动子 Agent

基本语法

{
  "name": "sessions_spawn",
  "arguments": {
    "description": "写后端登录 API",
    "prompt": "详细的任务说明...",
    "model": "claude-3-5-sonnet",
    "runTimeoutSeconds": 600,
    "announce": "✓ 登录 API 完成"
  }
}

💡 非阻塞执行： sessions_spawn 调用后立即返回 { status: "accepted", runId, childSessionKey }，主 Agent 不会等待子 Agent 完成。子 Agent 在后台独立运行，完成后通过 announce 通知主 Agent 所在的聊天渠道。

关键参数

参数	说明	示例
description	任务简短描述（用于日志）	“写登录 API”
prompt	给子 Agent 的详细指令	完整任务说明
model	使用什么模型	"claude-3-5-sonnet"
runTimeoutSeconds	超时时间（秒）	600（10 分钟）
announce	完成后的通知消息	“✓ 任务完成”

模型选择建议

任务类型	推荐模型	理由
编码任务	Claude 3.5 Sonnet	代码能力强，能迭代
文案写作	Gemini 1.5 Pro	便宜，写作好
搜索总结	Gemini 2.0 Flash	最便宜，够用
复杂推理	Claude Opus	最强能力，关键任务

---

Claude Code：最强 Coding Sub-agent

什么是 Claude Code?

Claude Code 是 Anthropic 官方推出的 AI 编程助手，可以作为 OpenClaw 的子 Agent 使用。它和普通子 Agent 的核心区别在于迭代能力：

普通子 Agent 遇到报错：
子 Agent：npm install 报错！
（不会自己解决，超时后失败）

Claude Code 遇到报错：
Claude Code：npm install 报权限错误
Claude Code：检查 npm 配置，发现全局目录权限问题
Claude Code：修复 npm 权限，重新安装
Claude Code：安装成功，继续下一步

Claude Code 能做到：

• 看到报错，自己尝试解决

• 跑测试，看到失败自己修

• 安装依赖、配置环境

• 提交代码到 git

安装 Claude Code

# 安装
npm install -g @anthropic/claude-code

# 配置使用 Bedrock（推荐，稳定）
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

# 验证
claude --version

在 OpenClaw 中调用 Claude Code

{
  "name": "sessions_spawn",
  "arguments": {
    "description": "用 Claude Code 写登录功能",
    "prompt": "启动 Claude Code，执行以下任务：

1. 在 ~/workspace/auth/ 创建新项目
2. 初始化 npm 项目
3. 安装 express、jsonwebtoken、bcrypt
4. 创建用户登录 API（POST /api/login）
5. 写 3 个测试用例并运行，确保通过

完成后报告：
- 写了哪些文件
- 测试是否通过
- 如何使用这个 API",
    "model": "claude-3-5-sonnet",
    "runTimeoutSeconds": 900,
    "announce": "✓ 登录功能开发完成（详见 ~/workspace/auth/REPORT.md）"
  }
}

---

血泪经验：Sub-agent 避坑指南

坑 1：Sub-agent 会“摸鱼”

现象：

子 Agent：任务完成！

你去检查：代码在哪里？
（git log 没有任何提交）
（文件根本不存在）

原因： AI 产生幻觉以为自己做了；执行到一半失败但报告成功；超时后返回默认成功消息。

解决方案：主 Agent 必须验证结果，不能当传话筒！

❌ 不好的做法：
主 Agent：子 Agent 说完成了
你：好的

✅ 正确的做法：
主 Agent：子 Agent 说完成了，我来验证
主 Agent：（检查 git log）✓ 有 3 个提交
主 Agent：（运行测试）✓ 全部通过
主 Agent：（检查关键文件）✓ 代码正确
主 Agent：确实完成了！

代码类任务验收清单：

- [ ] git log 有提交记录（真的有提交？）
- [ ] 要求的文件都存在（ls -la）
- [ ] 运行测试通过（npm test / pytest）
- [ ] 代码审查（read 关键文件）
- [ ] 功能验证（curl API / 打开页面）

坑 2：任务太大导致超时

现象：

子 Agent：我要写 10 个页面...
（8 分钟后）
子 Agent：（超时，任务失败，所有工作丢失）

解决方案：任务拆分

❌ 不好的做法：
任务："重写整个网站"（太大，必然超时）

✅ 正确的做法：
任务 1："重写首页"（5-10 分钟）
任务 2："重写关于页面"（5-10 分钟）
任务 3："重写产品页面"（5-10 分钟）
...

时间预估原则：

• 每个子任务控制在 5-10 分钟能完成

• 设置 runTimeoutSeconds 为预估时间的 1.5 倍

• 复杂的编码任务给 15-20 分钟（900-1200 秒）

坑 3:Announce 消息撑爆 Context

现象：

子 Agent 完成，发送通知：
"任务完成！详细信息：
1. 我首先安装了依赖...
2. 然后创建了文件...
（5000 字详细报告）"

→ 主 Agent 上下文被撑满，后续对话受影响

解决方案：Announce 消息必须简短，详细报告写文件

❌ 不好的做法：
announce: "详细报告：blablabla...（5000 字）"

✅ 正确的做法：
announce: "✓ 登录功能完成（3 个文件，测试通过）"

详细报告写入文件：
write("~/workspace/auth/REPORT.md", "详细报告...")

规则：Announce 不超过 3 行，详情写文件。

坑 4：子 Agent 之间没有协调

现象：

子 Agent A：我要创建 users 表
子 Agent B：我也要创建 users 表
（冲突！数据库报错）

解决方案：任务要有明确边界

✅ 正确的分工：
子 Agent A：
- 职责：后端 API
- 输入：设计文档
- 输出：~/workspace/backend/
- 不碰：前端代码、数据库 schema

子 Agent B：
- 职责：前端组件
- 输入：API 文档（等 A 完成后读取）
- 输出：~/workspace/frontend/
- 不碰：后端代码

依赖管理：

阶段 1：A 和 B 可以并行（无依赖）
阶段 2：C 依赖 A 和 B（等它们完成后启动）
阶段 3：D 依赖 C（最后做）

坑 5：忘记并发限制导致任务排队

现象：同时派了 8 个子 Agent，但只有 5 个在跑，其余 3 个一直等待。

原因：官方默认 maxChildrenPerAgent: 5，超过限制的请求会排队。

解决方案：任务超过 5 个时，分批启动，等前一批完成后再启动下一批。

---

实战示例：完整的多 Agent 工作流

任务：开发一个博客系统

阶段 1：设计（主 Agent 与你确认）

你：开发一个博客系统，包括文章列表、文章详情、评论功能

主 Agent：分解任务：
1. 数据库 schema 设计
2. 后端 API（文章 CRUD、评论）
3. 前端页面（列表、详情）

技术栈：Node.js + Express + SQLite + React + Tailwind
测试框架：Jest

确认这个方案吗？

你：确认

阶段 2：并行开发（Sub-agents）

主 Agent：启动 3 个子 Agent 并行开发...

[子 Agent A - 数据库]
任务：设计数据库 schema
- 文章表（posts）：id, title, content, author, created_at
- 评论表（comments）：id, post_id, content, author, created_at
- 创建迁移文件

[子 Agent B - 后端 API]
任务：创建 REST API
- GET /api/posts（列表）
- GET /api/posts/:id（详情）
- POST /api/posts（创建）
- POST /api/posts/:id/comments（评论）

[子 Agent C - 前端]
任务：等待 B 完成后启动
- 文章列表页
- 文章详情页
- 评论组件

阶段 3：验收（主 Agent 主动验证）

[20 分钟后]

主 Agent：检查子 Agent A 结果...
✓ 数据库 schema 创建完成
✓ 迁移文件在 ~/blog/db/migrations/
✓ 验证：sqlite3 能连接

主 Agent：检查子 Agent B 结果...
✓ API 创建完成
✓ 所有路由可访问
✓ curl 测试通过

主 Agent：子 Agent C 依赖 B，现在启动...

[10 分钟后]

主 Agent：集成测试：
✓ 前端能调用后端 API
✓ 数据能正常显示
✓ 评论功能正常

总结：
- 代码行数：1200 行
- 测试覆盖率：85%
- 耗时：30 分钟
- 成本：$0.45

博客系统开发完成！🎉

---

高级：Agent 间通信（sessions_send）

除了父子关系（sessions_spawn），OpenClaw 还支持平级 Agent 之间直接通信（sessions_send）。

这允许你构建更复杂的多 Agent 架构：

# openclaw.json 配置示例
agents:
  list:
    - id: orchestrator
      default: true
      subagents:
        allowAgents: ["researcher", "coder"]
    - id: researcher
      workspace: ~/.openclaw/workspace-research
    - id: coder
      workspace: ~/.openclaw/workspace-code
  tools:
    agentToAgent:
      enabled: true
      allow: ["orchestrator", "researcher", "coder"]

架构图：

主 Orchestrator
├─ sessions_send → Researcher Agent（平级通信）
│  └─ sessions_spawn → 子 Agent（采集数据）
└─ sessions_send → Coder Agent（平级通信）
   └─ sessions_spawn → 子 Agent（写代码）

💡 这是绕过单层限制的方法：通过 sessions_send 委托给平级 Agent，平级 Agent 再用 sessions_spawn 派生子 Agent，实现三层协作。

---

管理和调试子 Agent

# 查看所有活跃的子 Agent
/subagents list

# 停止特定子 Agent（及其所有子孙）
/subagents kill <subagent-id>

# 停止主 Agent 及其所有子 Agent
/stop

# 查看子 Agent 日志
openclaw sessions history --session "agent:main:subagent:<id>"
</id></subagent-id>

💡 /stop 命令会级联停止所有子 Agent。如果你在聊天中发送 /stop，当前 session 和它派生的所有子 Agent 都会被终止。

---

故障排除

Q1：子 Agent 总是超时？

1. 增加 runTimeoutSeconds（编码任务建议 900-1200 秒）

2. 拆分任务，让子任务更小

3. 使用 Claude Code（有迭代能力，更高效）

Q2：怎么查看子 Agent 进度？

子 Agent 在后台运行，没有实时进度显示。可以：

• 在 prompt 中要求子 Agent 定期写进度文件（~/workspace/progress.md）

• 主 Agent 定期读取进度文件检查状态

• 等待 announce 通知

Q3：子 Agent 卡住了怎么办？

# 停止特定子 Agent
/subagents kill <subagent-id>

# 或者停止整个 session（包括所有子 Agent）
/stop
</subagent-id>

Q4：子 Agent 之间如何传递数据？

方式一：通过文件（推荐）

子 Agent A：写入 ~/workspace/shared/data.json
子 Agent B：读取 ~/workspace/shared/data.json

方式二：通过主 Agent 中转

子 Agent A：完成任务，通过 announce 报告给主 Agent
主 Agent：收到 A 的结果，启动子 Agent B 并传入 A 的结果
子 Agent B：开始工作

---

验证清单

确认多 Agent 协作正常工作：

• 成功启动过至少 1 个子 Agent（sessions_spawn）

• 子 Agent 完成了任务并通过 announce 汇报

• 主 Agent 主动验证了子 Agent 的结果（不是盲目相信）

• 尝试过并行启动多个子 Agent（注意 5 个并发限制）

• 配置过 Claude Code 作为 coding sub-agent

• 处理过子 Agent 失败的情况（超时、报错）

• Announce 消息保持简短（不超过 3 行）

---

本篇小结

核心要点：

1. Sub-agent 是并行加速的利器：把大任务拆成小任务，同时执行，效率倍增

2. sessions_spawn 是非阻塞的：调用后立即返回，主 Agent 继续工作，子 Agent 后台执行

3. 最多 5 个并发子 Agent：超过限制会排队，大批量任务需分批启动

4. 子 Agent 不能再派生子 Agent：单层限制，可通过 sessions_send + 平级 Agent 绕过

5. 验收是关键：主 Agent 必须主动验证结果，不能盲目相信子 Agent 的报告

---

下一步

多 Agent 让你能并行处理复杂任务，但不同任务适合不同模型。下一篇教你如何选择和切换模型：

→ 第 10 篇 | 多模型调度 — 穷鬼套餐、正常套餐、富哥套餐，各取所长又省钱。

---

💬 读者讨论

你最想用多 Agent 并行处理什么任务？
翻译？数据采集？还是别的什么？
欢迎在评论区分享！

---

📚 本系列目录

• 第 01 篇：OpenClaw 是什么？

• 第 02 篇：5 分钟安装指南

• 第 03 篇：连接你的第一个聊天渠道

• 第 04 篇：个性化你的 AI

• 第 05 篇：记忆系统

• 第 06 篇：工具调用与 Skills

• 第 07 篇：定时任务 Cron

• 第 08 篇：心跳机制 Heartbeat

• 第 09 篇：多 Agent 协作（你在这里）

• 第 10 篇：多模型调度

• 查看完整目录

---

下一篇预告：多模型调度策略——什么时候用便宜的 Gemini Flash，什么时候用强大的 Claude Opus，如何配置模型别名，以及成本控制技巧。