OpenClaw 多Agent协作模式技术架构

OpenClaw 多Agent协作模式技术架构

核心问题：OpenClaw 采用”主Agent + N个子Agent”模式时，如何解决任务编排和Agent间通信问题？

---

OpenClaw 提供了两套互补的多Agent协作机制：

• 现有机制：sessions_spawn + sessions_send 子代理模式（树状层级通信）
• 未来机制：Agent Teams RFC（扁平化团队协作，开发中）

本文基于官方文档和 GitHub 源码，深入分析两种模式的设计理念、实现原理、适用场景与最佳实践。

---

一、多Agent协作的核心挑战

当采用”主Agent + N个子Agent”模式时，面临三大核心挑战：

1. 任务编排问题

• 如何将复杂任务分解为子任务？
• 如何确定子任务的执行顺序和依赖关系？
• 如何处理子任务的失败和重试？

2. Agent间通信问题

• 主Agent如何向子Agent下发指令？
• 子Agent如何向主Agent回报结果？
• 子Agent之间是否需要通信？如何实现？

3. 状态共享问题

• 多个Agent如何共享上下文信息？
• 如何避免状态不一致？
• 如何实现持久化和恢复？

---

二、Option A：sessions_spawn 树状层级模式

这是当前已实现的方案。

架构图

            ┌─────────────┐
            │  Main Agent │
            └──────┬──────┘
                   │ spawn
        ┌──────────┼──────────┐
        ▼          ▼          ▼
   ┌─────────┐ ┌─────────┐ ┌─────────┐
   │SubAgent1│ │SubAgent2│ │SubAgent3│
   └─────────┘ └─────────┘ └─────────┘

核心特性

特性	描述
通信拓扑	树状层级，子代理只能与父代理通信
生命周期	子代理完成任务后自动终止
结果回传	通过 announce 机制推送结果
隔离性	高，子代理之间完全隔离

通信模式

1. Fire-and-Forget

sessions_send(sessionId, message, { timeoutSeconds: 0 })
// 主代理发送后不等待，适合通知类任务

2. Wait for Reply

sessions_send(sessionId, message, { timeoutSeconds: 30 })
// 主代理等待子代理响应，适合需要确认的任务

3. Ping-Pong 模式

// 主代理发起查询 → 子代理响应 → 主代理继续
const reply = await sessions_send(subAgent, { type: 'query' }, { timeoutSeconds: 10 })

协作模式

模式	适用场景	实现方式
协调者-专家	复杂任务需要专家分工	主代理分配任务给专家子代理
并行执行	独立任务可同时执行	同时spawn多个子代理
共享文件	需要共享大量状态	使用workspace目录文件共享

优缺点

优点：

• ✅ 架构简单，易于理解
• ✅ 隔离性好，故障不传播
• ✅ 适合独立子任务
• ✅ 当前已实现，可立即使用

缺点：

• ❌ 子代理间无法直接通信
• ❌ 复杂协作需要绕道主代理
• ❌ 共享状态需要外部机制（文件）
• ❌ 不适合需要紧密协作的场景

---

三、Option B：Agent Teams 扁平化团队模式

这是未来的方案，目前处于 RFC 阶段。

架构图

    ┌────────────────────────────────┐
    │         Team Workspace         │
    │  ┌──────────────────────────┐  │
    │  │    Shared Task Queue     │  │
    │  └──────────────────────────┘  │
    └────────────────────────────────┘
           ▲    ▲    ▲    ▲
           │    │    │    │
    ┌──────┴────┴────┴────┴──────┐
    │                             │
    │  Agent1  Agent2  Agent3    │
    │                             │
    └─────────────────────────────┘

核心特性

特性	描述
通信拓扑	扁平化，同级Agent可直接通信
任务管理	共享任务列表，Agent主动领取
Mailbox	每个Agent有独立邮箱，接收消息
持久化	支持团队状态保存和恢复

通信机制

1. 同级通信

agent.send(targetAgent, message)
// Agent之间直接通信，无需通过协调者

2. 任务队列

team.tasks.add({ type: 'code-review', priority: 'high' })
agent.pickTask() // Agent主动领取任务

3. Mailbox

agent.mailbox.receive() // 接收发送给自己的消息
agent.mailbox.send(targetAgent, message) // 发送消息

优缺点

优点：

• ✅ 扁平化结构，通信灵活
• ✅ 支持同级Agent协作
• ✅ 内置状态共享机制
• ✅ 适合复杂协作场景

缺点：

• ❌ 目前处于RFC阶段，尚未实现
• ❌ 架构更复杂，学习成本高
• ❌ 隔离性相对较弱
• ❌ 上线时间不确定

---

四、推荐方案：混合模式过渡

推荐采用 Option C（混合模式）作为过渡，逐步迁移到 Option B（Agent Teams）。

架构图

            ┌─────────────────────────────┐
            │        Main Agent           │
            │    (Coordinator Role)       │
            └──────────────┬──────────────┘
                           │
            ┌──────────────┴──────────────┐
            │    Shared Workspace         │
            │  ┌───────────────────────┐  │
            │  │  State Files / Queue  │  │
            │  └───────────────────────┘  │
            └──────────────┬──────────────┘
                           │ spawn
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
   ┌─────────┐        ┌─────────┐        ┌─────────┐
   │SubAgent1│◄──────►│SubAgent2│◄──────►│SubAgent3│
   └─────────┘  文件   └─────────┘  文件   └─────────┘

实现要点

1. 协调者模式 + 共享文件

// 主代理作为协调者
const subAgents = await Promise.all([
  sessions_spawn({ role: 'backend' }),
  sessions_spawn({ role: 'frontend' }),
  sessions_spawn({ role: 'qa' })
])

// 通过共享文件传递状态
await writeFile('workspace/shared-state.json', { stage: 'development' })

2. 任务队列文件

// workspace/task-queue.json
{
  "tasks": [
    { "id": "t1", "type": "code", "status": "pending", "assignee": null },
    { "id": "t2", "type": "test", "status": "blocked", "depends_on": ["t1"] }
  ]
}

// 子代理轮询任务队列
const task = await pickTask('workspace/task-queue.json')

3. 事件通知文件

// workspace/events.jsonl
{"type": "task_complete", "taskId": "t1", "agentId": "sub1", "timestamp": "..."}
{"type": "task_started", "taskId": "t2", "agentId": "sub2", "timestamp": "..."}

// 主代理监听事件流
watchEvents('workspace/events.jsonl', (event) => {
  if (event.type === 'task_complete') {
    // 更新任务状态，通知相关Agent
  }
})

推荐理由

1. 技术可行性

• 混合模式可基于现有 sessions_spawn 立即实现
• 通过共享文件模拟 Agent Teams 的部分能力
• 无需等待 RFC 完成

2. 架构演进路径

Phase 1 (当前)     Phase 2 (3-6月)      Phase 3 (6-12月)
┌──────────────┐   ┌──────────────┐    ┌──────────────┐
│ sessions_    │   │ 混合模式     │    │ Agent Teams  │
│ spawn        │ → │ + 共享文件   │ → │ 正式版       │
│ 简单场景     │   │ 复杂协作     │    │ 全面协作     │
└──────────────┘   └──────────────┘    └──────────────┘

3. 场景适配

场景	推荐方案
简单独立任务	sessions_spawn 直接使用
中等复杂协作	混合模式（协调者+共享文件）
高度复杂协作	等待 Agent Teams

---

五、最佳实践建议

立即实施

• 使用 sessions_spawn 处理独立子任务
• 采用协调者模式管理复杂任务
• 使用 workspace 目录共享状态文件
• 实现简单的任务队列文件

短期准备

• 设计可迁移的任务队列格式
• 抽象Agent通信接口，便于切换
• 关注 Agent Teams RFC 进展

长期规划

• 评估 Agent Teams 适用性
• 制定迁移计划
• 保持架构灵活性

---

六、风险与缓解措施

风险	影响	缓解措施
Agent Teams 延期	无法使用扁平化协作	混合模式可长期使用
文件并发冲突	状态不一致	使用文件锁或原子操作
子代理故障	任务中断	实现超时和重试机制
性能瓶颈	大量文件IO	使用内存缓存层

---

总结

简单独立任务：使用 sessions_spawn

复杂协作：建议使用协调者模式配合共享文件

未来方向：推荐转向 Agent Teams 架构

通过合理选择协作模式，可以充分发挥多Agent系统的优势，实现高效、可靠的任务处理。