文章目录

1. OpenClaw 多 Agent 协作开发实战：从原理到实践

OpenClaw 多 Agent 协作开发实战：从原理到实践

前言

在多 Agent 系统（Multi-Agent System）越来越受关注的今天，如何在实际项目中高效地协调多个 AI Agent 协作完成任务，是一个值得深入探讨的话题。本文将分享我在使用 OpenClaw 进行多 Agent 开发的一些想法，从架构原理到实战案例，深入了解一下多Agent设计思路。这篇文章主要是AI写的，节约了不少时间。

一、OpenClaw 的架构设计

1.1 核心概念

OpenClaw 的架构可以用三层模型来理解：

┌─────────────────────────────────────────┐
│  用户界面层 (WebChat / CLI / API)        │
│  - 人类与系统交互的入口                   │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│  OpenClaw Gateway (Node.js)             │
│  - Session 管理器                        │
│  - 每个 Session = 独立对话上下文         │
│  - 支持多 Session 并行                   │
└──────────────┬──────────────────────────┘
               │
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌───────┐  ┌───────┐  ┌───────┐
│Agent 1│  │Agent 2│  │Agent 3│
│Session│  │Session│  │Session│
└───┬───┘  └───┬───┘  └───┬───┘
    │          │          │
    └──────────┼──────────┘
               ▼
    ┌─────────────────────┐
    │  AI Provider        │
    │  (Kimi/Claude/GPT)  │
    └─────────────────────┘

关键理解：

Agent 不是独立的 AI 实例，而是带有特定上下文的 Session
所有 Agent 共享同一个 AI Provider，但通过不同的 Session 隔离上下文
每个 Session 有自己的历史记录、系统提示词（System Prompt）、标签（Label）

二、多 Agent 协作的核心机制

2.1 Agent 的创建与管理

创建子 Agent 使用 sessions_spawn 工具（这个工具就是调用大模型API的时候注入到tools工具链里面的函数）：

// 创建设计师 Agent
{
  "tool": "sessions_spawn",
  "parameters": {
    "agentId": "main",              // 使用哪个基础配置
    "label": "snake-designer",      // 给 Session 打标签
    "runTimeoutSeconds": 300,       // 超时时间（重要！）
    "task": "你是产品设计师，负责...", // 系统提示 + 任务
    "thinking": "high"              // 思考深度
  }
}

返回结果：

{
  "childSessionKey": "agent:main:subagent:605eea7d-434d-456c-b1be-f985d6dc2e74",
  "runId": "c6e34f28-ae3e-4a28-97f5-69b4cd1a369c",
  "status": "accepted",
  "note": "auto-announces on completion"
}

2.2 Agent 间通信

Agent 之间的通信有两种方式：

方式一：直接消息传递（`sessions_send`）

// 给设计师 Agent 发消息
{
  "tool": "sessions_send",
  "sessionKey": "agent:main:subagent:605eea7d...",
  "message": "请修改设计，改为赛博朋克风格...",
  "timeoutSeconds": 300
}

注意： timeoutSeconds 必须设置足够长（建议 180-300 秒），因为 AI 需要时间来：

理解请求
调用工具（读写文件）
生成回复

方式二：文件驱动协作（推荐）

这是我们在实战中发现的最佳实践：

Agent 1 (Designer)          Agent 2 (Developer)          Agent 3 (Tester)
     │                            │                            │
     │  写入 design.md            │                            │
     ├────────────────────────────┼────────────────────────────┤
     │                            │  读取 design.md            │
     │                            │  写入 snake.html           │
     │                            ├────────────────────────────┤
     │                            │                            │  读取 snake.html
     │                            │                            │  写入 test_report.md

优势：

不依赖实时通信
任务解耦，可异步执行
产出物持久化，可追溯

三、实战案例：贪吃蛇游戏开发

3.1 项目背景

用 3 个 Agent 协作开发一个赛博朋克风格的贪吃蛇 Web 游戏，并添加道具系统。

3.2 Agent 分工

Agent	角色	职责	产出物
Designer	产品设计师	界面设计、配色方案、交互设计	`design.md`
Developer	前端工程师	编写 HTML/CSS/JS 代码	`snake.html`
Tester	测试工程师	功能测试、Bug 发现、性能测试	`test_report.md`

3.3 主 Agent 的协调控制机制

核心架构：主从协作模式

在多 Agent 系统中，主 Agent（Main Agent）扮演着协调者（Orchestrator）的角色，负责管理子 Agent 的生命周期、任务分配和结果汇总。

┌─────────────────────────────────────────────────────────┐
│                    主 Agent (Q)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │  Task Queue │  │ State Mgr   │  │ Result Coll │     │
│  │  任务队列   │  │ 状态管理    │  │ 结果汇总    │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │
│         │                │                │            │
│  ┌──────▼────────────────▼────────────────▼──────┐     │
│  │           Coordinator 协调器                   │     │
│  │  1. 创建子 Agent → 分配任务 → 监控进度            │     │
│  │  2. 收集结果 → 质量检查 → 决定是否迭代             │     │
│  │  3. 异常处理 → 重试/换人 → 错误上报               │     │
│  └──────┬────────────┬────────────┬──────────-───┘     │
└─────────┼────────────┼────────────┼───────────────────-┘
          │            │            │
          ▼            ▼            ▼
    ┌─────────┐  ┌─────────┐  ┌─────────┐
    │Designer │  │Developer│  │ Tester  │
    │子Agent  │  │子Agent   │  │子Agent  │
    └────┬────┘  └────┬────┘  └────┬────┘
         │            │            │
         └────────────┴────────────┘
                      │
              ┌───────▼────────┐
              │  共享工作区      │
              │  design.md     │
              │  snake.html    │
              │  test_report.md│
              └────────────────┘

主 Agent 的核心职责：

职责	说明	实现方式
任务分解	将大任务拆分为可并行/串行的子任务	人工分析 + AI 辅助
生命周期管理	创建、监控、终止子 Agent	`sessions_spawn` / `subagents`
状态同步	跟踪每个子 Agent 的工作状态	文件状态检查 + 心跳检测
结果聚合	收集各子 Agent 产出，整合最终成果	读取文件 + 质量评估
异常处理	处理超时、错误、质量不达标等情况	重试、重新分配、降级

协调流程示例（带状态检查）：

// 主 Agent 协调伪代码
async function coordinateGameDevelopment() {
  const results = {};
  
  // Phase 1: 并行启动设计和开发（如果设计文档已存在）
  // 或者先启动设计，等设计完成后再启动开发
  
  // 步骤1：创建设计师
  const designer = await sessions_spawn({
    label: "snake-designer",
    task: "设计赛博朋克风格贪吃蛇游戏...",
    runTimeoutSeconds: 300
  });
  
  // 步骤2：等待设计完成（阻塞等待）
  // OpenClaw 的 sessions_spawn 是异步的，通过返回的 childSessionKey 后续检查
  results.designer = { sessionKey: designer.childSessionKey, status: "running" };
  
  // 步骤3：轮询检查设计是否完成（通过检查文件是否存在）
  while (!await fileExists("snake/design.md")) {
    await sleep(5000); // 每5秒检查一次
    // 检查是否超时或失败
    const status = await checkSessionStatus(designer.childSessionKey);
    if (status === "failed") {
      // 重试或报错
      throw new Error("Designer failed");
    }
  }
  
  // 步骤4：设计完成，创建开发者
  const developer = await sessions_spawn({
    label: "snake-developer",
    task: "根据 design.md 编写代码...",
    runTimeoutSeconds: 600
  });
  results.developer = { sessionKey: developer.childSessionKey, status: "running" };
  
  // 步骤5：等待开发完成
  while (!await fileExists("snake/snake.html")) {
    await sleep(5000);
  }
  
  // 步骤6：开发完成，创建测试员
  const tester = await sessions_spawn({
    label: "snake-tester",
    task: "测试 snake.html 并生成报告...",
    runTimeoutSeconds: 300
  });
  results.tester = { sessionKey: tester.childSessionKey, status: "running" };
  
  // 步骤7：等待测试完成，收集结果
  while (!await fileExists("snake/test_report.md")) {
    await sleep(5000);
  }
  
  // 步骤8：评估测试结果
  const report = await readFile("snake/test_report.md");
  if (report.includes("FAIL")) {
    // 测试失败，决定是修复还是重新开发
    await sessions_send({
      sessionKey: results.developer.sessionKey,
      message: "根据测试报告修复问题..."
    });
  }
  
  return results;
}

关键协调策略：

串行依赖管理
- 开发依赖设计（必须等 design.md 完成）
- 测试依赖开发（必须等 snake.html 完成）
- 主 Agent 通过文件存在性检查实现流程控制

状态监控机制

// 检查子 Agent 状态
subagents({ action: "list" })
// 返回每个子 Agent 的活跃状态、token 使用量、最后更新时间

质量门禁（Quality Gate）
- 每个阶段产出必须经过检查才能进入下一阶段
- 检查方式：文件内容审查、自动测试、人工确认

异常恢复策略

异常情况	处理策略
子 Agent 超时	发送继续指令或重新创建
产出质量不达标	打回重做，附带具体修改意见
子 Agent 崩溃	重新 spawn，继承相同任务
循环依赖/死锁	人工介入，调整任务拆分

3.4 第一轮开发：基础游戏

工作流程：

// 1. 创建设计师
sessions_spawn({
  label: "snake-designer",
  task: "设计贪吃蛇游戏界面..."
})
// 产出：design.md（现代简洁风格）

// 2. 创建开发者（需等待设计完成）
sessions_spawn({
  label: "snake-developer", 
  task: "根据设计文档编写代码..."
})
// 产出：snake.html（可运行的游戏）

// 3. 创建测试员（需等待开发完成）
sessions_spawn({
  label: "snake-tester",
  task: "测试游戏功能..."
})
// 产出：test_report.md

3.5 第二轮迭代：赛博朋克风格改造

工作流程：

// 1. 给设计师发消息要求改版
sessions_send({
  sessionKey: "designer-session-key",
  message: "改为赛博朋克霓虹风格..."
})
// 产出：更新的 design.md

// 2. 给开发者发消息要求重写代码
sessions_send({
  sessionKey: "developer-session-key",
  message: "根据新设计重写代码..."
})
// 产出：更新的 snake.html（霓虹效果）

// 3. 给测试员发消息要求重新测试
sessions_send({
  sessionKey: "tester-session-key", 
  message: "重新测试新版本..."
})
// 产出：更新的 test_report.md

3.6 项目产出

最终产出文件：

snake/
├── design.md              # 完整设计文档（含道具系统）
├── snake.html             # 可运行的赛博朋克贪吃蛇
├── test_report.md         # 原始测试报告
├── test_report_cyberpunk.md  # 赛博朋克版测试报告  
└── test_report_powerup.md    # 道具系统测试报告

四、遇到的问题与解决方案

4.1 问题一：Session 发送超时

现象：

{
  "status": "timeout",
  "error": "Request timed out"
}

原因： timeoutSeconds 设置太短（120秒），AI 需要时间思考 + 执行工具 + 回复。

解决： 设置 timeoutSeconds: 300（5分钟）或更长。

4.2 问题二：Channel 访问限制

现象：

{
  "status": "forbidden",
  "error": "Session send visibility is restricted to the current session tree"
}

原因： WebChat 渠道对跨 Session 通信有限制。

解决：

使用文件驱动协作（推荐）
或在同一 Session 树内通信

五、多 Agent 协作的最佳实践

5.1 工作流设计原则

单一职责：每个 Agent 只做一件事（设计/开发/测试）
文件驱动：通过共享文件传递信息
标签管理：给 Agent 打有意义的 label（snake-designer）
超时设置：预留足够时间（300秒以上）

5.2 推荐的协作模式

串行模式（适合有依赖关系的任务）：

需求分析 → 架构设计 → 模块开发 → 集成测试

并行模式（适合独立子任务）：

        ┌→ 前端开发 ┐
架构设计 ┼→ 后端开发 ┼→ 集成测试
        └→ 文档编写 ┘

混合模式（实际项目推荐）：

需求 → 设计 ┬→ 前端Dev ┬→ 集成 → 测试
             └→ 后端Dev ┘

5.3 会话管理建议

// 查看所有子 Agent
subagents({ action: "list" })

// 查看 Session 历史
sessions_history({
  sessionKey: "agent:main:subagent:xxx",
  limit: 10
})

// 终止不再需要的 Agent
subagents({ 
  action: "kill",
  target: "agent:main:subagent:xxx"
})

六、总结与展望

6.1 核心收获

通过本次实战，我们验证了：

✅ 多 Agent 协作完全可行 - 3 个 Agent 成功协作完成游戏开发
✅ 文件驱动高效 - 无需实时通信，异步协作效果好
✅ 适合复杂任务 - 每个 Agent 专注自己的领域，质量更高

6.2 适用场景

OpenClaw 多 Agent 协作特别适合：

🎮 游戏开发 - 设计 + 开发 + 测试并行
📝 文档编写 - 大纲 + 正文 + 校对分工
🎨 创意设计 - 概念 + 细化 + 评审
💻 软件开发 - 架构 + 编码 + 测试 + 文档

6.3 未来展望

多 Agent 系统的发展方向：

更智能的调度 - AI 自动决定创建哪些 Agent
Agent 间直接通信 - 无需通过父 Agent 中转
长期记忆共享 - 所有 Agent 访问共同的知识库
可视化监控 - 实时查看各 Agent 状态

附录：完整 API 参考

创建子 Agent

sessions_spawn({
  agentId?: string,          // 基础 Agent 配置
  label?: string,            // Session 标签
  runTimeoutSeconds?: number, // 超时时间（秒）
  task: string,              // 任务描述
  thinking?: "low" | "medium" | "high"  // 思考深度
})

发送消息

sessions_send({
  sessionKey: string,        // 目标 Session
  message: string,           // 消息内容
  timeoutSeconds?: number    // 等待回复的超时
})

管理子 Agent

// 列出所有子 Agent
subagents({ action: "list" })

// 查看历史
sessions_history({
  sessionKey: string,
  limit?: number
})

// 终止 Agent
subagents({
  action: "kill",
  target: string
})

C的博客

不识庐山真面目,只缘身在此山中.

OpenClaw多Agent协作开发实践：从原理到实践

OpenClaw 多 Agent 协作开发实战：从原理到实践

前言

一、OpenClaw 的架构设计

1.1 核心概念

二、多 Agent 协作的核心机制

2.1 Agent 的创建与管理

2.2 Agent 间通信

方式一：直接消息传递（`sessions_send`）

方式二：文件驱动协作（推荐）

三、实战案例：贪吃蛇游戏开发

3.1 项目背景

3.2 Agent 分工

3.3 主 Agent 的协调控制机制

3.4 第一轮开发：基础游戏

3.5 第二轮迭代：赛博朋克风格改造

3.6 项目产出

四、遇到的问题与解决方案

4.1 问题一：Session 发送超时

4.2 问题二：Channel 访问限制

五、多 Agent 协作的最佳实践

5.1 工作流设计原则

5.2 推荐的协作模式

5.3 会话管理建议

六、总结与展望

6.1 核心收获

6.2 适用场景

6.3 未来展望

附录：完整 API 参考

创建子 Agent

发送消息

管理子 Agent

OpenClaw 多 Agent 协作开发实战：从原理到实践

前言

一、OpenClaw 的架构设计

1.1 核心概念

二、多 Agent 协作的核心机制

2.1 Agent 的创建与管理

2.2 Agent 间通信

方式一：直接消息传递（sessions_send）

方式二：文件驱动协作（推荐）

三、实战案例：贪吃蛇游戏开发

3.1 项目背景

3.2 Agent 分工

3.3 主 Agent 的协调控制机制

3.4 第一轮开发：基础游戏

3.5 第二轮迭代：赛博朋克风格改造

3.6 项目产出

四、遇到的问题与解决方案

4.1 问题一：Session 发送超时

4.2 问题二：Channel 访问限制

五、多 Agent 协作的最佳实践

5.1 工作流设计原则

5.2 推荐的协作模式

5.3 会话管理建议

六、总结与展望

6.1 核心收获

6.2 适用场景

6.3 未来展望

附录：完整 API 参考

创建子 Agent

发送消息

管理子 Agent

方式一：直接消息传递（`sessions_send`）