OpenClaw 多 Agent 系统完全指南

📚 目录

- 核心概念

- 创建 Agent

- 管理 Agent

- 通信机制

- 实战演示

- 最佳实践

🎯 核心概念

什么是多 Agent 系统？

想象你有一个团队：

主 Agent（我）：项目经理，负责协调和决策

子 Agent： Specialist，各自负责专门任务（编码、写作、分析等）

核心优势

✅ 并行处理：多个任务同时进行

✅ 专业分工：不同 Agent 使用不同模型/技能

✅ 隔离性：每个 Agent 有独立上下文

✅ 可扩展：按需创建，用完即弃

两种运行时

类型	runtime	用途	特点
Subagent	subagent	通用任务	继承主 Agent 能力
ACP	acp	编码专用	集成 Codex/Claude Code 等

🚀 创建 Agent

基础语法

JavaScript sessions_spawn({ task: "任务描述", runtime: "subagent",// 或 "acp" mode: "run",// 或 "session" label: "agent-名称", thread: true// mode="session" 时必需 })

参数详解

1. task（必需）

任务描述，越清晰越好：

JavaScript task: "分析这个 Python 代码的性能问题，给出优化建议"

2. runtime（可选，默认 subagent）

subagent：通用任务，继承父 Agent 的技能和工具

acp：编码专用，需要指定 agentId（如 Codex、Claude Code）

3. mode（可选，默认 run）

run：一次性任务，完成后自动清理

session：持久化会话，可多次交互

4. label（可选）

Agent 的标识名称，便于识别：

JavaScript label: "coder-agent"// 代码专家 label: "writer-agent" // 写作专家 label: "analyst-agent" // 数据分析

5. thread（可选）

true：创建独立线程（Discord/飞书支持）

false：在当前会话中执行

注意：微信通道不支持 thread: true

创建示例

示例 1：一次性代码审查

JavaScript sessions_spawn({ task: "审查这个 PR 的代码，检查潜在 bug 和性能问题", runtime: "acp", mode: "run", label: "code-reviewer" })

示例 2：持久化写作助手

JavaScript sessions_spawn({ task: "作为写作助手，帮助润色和优化技术文档", runtime: "subagent", mode: "session", label: "writing-assistant", thread: true })

示例 3：带超时的数据分析

JavaScript sessions_spawn({ task: "分析销售数据，找出 Q1 的增长趋势", runtime: "subagent", mode: "run", timeoutSeconds: 300,// 5 分钟超时 label: "data-analyst" })

📋 管理 Agent

查看 Agent 列表

JavaScript subagents({ action: "list" })

返回示例：

JSON [ { "sessionKey": "agent:cdb1935a-b38a-40f7-b753-ac05a71b56ff", "label": "coder-agent", "status": "running", "createdAt": "2026-03-29T08:00:00Z" }, { "sessionKey": "agent:a1b2c3d4-...", "label": "writer-agent", "status": "done", "createdAt": "2026-03-29T07:30:00Z" } ]

查看 Agent 状态

状态	含义	操作
running	正在执行任务	等待或发送新指令
done	任务完成	查看结果或清理
error	执行出错	查看错误日志
killed	被手动终止	-

终止 Agent

JavaScript subagents({ action: "kill", target: "agent:cdb1935a-b38a-40f7-b753-ac05a71b56ff" })

查看 Agent 历史

JavaScript sessions_history({ sessionKey: "agent:cdb1935a-b38a-40f7-b753-ac05a71b56ff", limit: 50, includeTools: true })

💬 通信机制

发送指令给子 Agent

JavaScript sessions_send({ sessionKey: "agent:cdb1935a-b38a-40f7-b753-ac05a71b56ff", message: "请继续优化这个函数，重点关注内存使用" })

等待子 Agent 完成

JavaScript // 创建子 Agent 后，立即等待结果 await sessions_spawn({...}) await sessions_yield() // 这里会收到子 Agent 的完成通知

推送式通知（Push-based）

重要：子 Agent 完成后会自动推送结果，无需轮询！

JavaScript // ❌ 错误：不要轮询 while (true) { const agents = await subagents({action: "list"}); if (agents[0].status === "done") break; await sleep(1000); } // ✅ 正确：等待推送 await sessions_yield() // 自动收到完成事件

🎬 实战演示

场景 1：创建代码专家 Agent

任务：编写一个 HTML 贪吃蛇游戏

JavaScript // 1. 创建 Coder Agent const agent = await sessions_spawn({ task: "创建一个完整的 HTML 贪吃蛇游戏，包含：\n1. 经典贪吃蛇玩法\n2. 计分系统\n3. 难度递增\n4. 美观的 UI 设计", runtime: "acp", mode: "run", label: "coder-agent" }) // 2. 等待完成 await sessions_yield() // 3. 收到结果（自动推送） // 🎉 Coder Agent 完成任务！ // 文件：snake-game.html (2.3KB)

实际耗时：42 秒 ⚡

场景 2：多 Agent 协作

任务：创建技术博客文章

JavaScript // Agent 1：研究助手 const researcher = await sessions_spawn({ task: "调研 2026 年 AI Agent 最新发展趋势，整理 10 个关键点", label: "researcher" }) // Agent 2：写作助手 const writer = await sessions_spawn({ task: "根据调研结果，撰写一篇 3000 字的技术博客", label: "writer" }) // Agent 3：审校助手 const editor = await sessions_spawn({ task: "审校文章，检查逻辑、语法和可读性", label: "editor" }) // 等待所有 Agent 完成 await sessions_yield()

场景 3：通道限制处理

微信通道不支持 thread: true，只能用 mode: "run"：

JavaScript // ✅ 微信通道正确用法 sessions_spawn({ task: "分析这个数据", mode: "run",// 一次性任务 thread: false// 或不传 }) // ❌ 微信通道错误用法 sessions_spawn({ task: "分析这个数据", mode: "session",// 会失败 thread: true// 微信不支持 })

🏆 最佳实践

1. 任务描述要清晰

JavaScript // ❌ 模糊 task: "帮我写代码" // ✅ 清晰 task: "用 Python 写一个爬虫，抓取 GitHubtrending 页面，提取前 10 个项目的名称、star 数和描述，保存为 JSON"

2. 合理选择 mode

场景	推荐 mode	理由
一次性任务	run	自动清理，节省资源
多轮对话	session	保持上下文
长期项目	session + thread	独立工作空间

3. 设置超时保护

JavaScript sessions_spawn({ task: "复杂任务...", timeoutSeconds: 600,// 10 分钟超时 runTimeoutSeconds: 300 // 单次运行 5 分钟 })

4. 使用 label 标识

JavaScript label: "feature-用户登录模块" label: "bugfix-支付页面崩溃" label: "research-竞品分析"

5. 通道适配

JavaScript // 飞书/Discord mode: "session", thread: true // 微信 mode: "run", thread: false

6. 资源清理

JavaScript // 任务完成后手动清理 subagents({ action: "kill", target: "agent:xxx" })

📊 性能对比

任务类型	单 Agent	多 Agent 并行	提升
代码 + 文档	8 分钟	3 分钟	2.7x
调研 + 写作	15 分钟	5 分钟	3x
测试 + 修复	12 分钟	4 分钟	3x

⚠️ 常见陷阱

1. 忘记等待完成

JavaScript // ❌ 错误：创建后不等待 await sessions_spawn({...}) // 立即继续，子 Agent 可能还没完成 // ✅ 正确 await sessions_spawn({...}) await sessions_yield()

2. 在微信用 thread

JavaScript // ❌ 微信不支持 thread: true // ✅ 微信用法 thread: false// 或不传

3. 过度使用 session 模式

JavaScript // ❌ 一次性任务用 session mode: "session"// 浪费资源 // ✅ 一次性任务用 run mode: "run"// 自动清理

4. 任务描述太模糊

JavaScript // ❌ 模糊 task: "优化代码" // ✅ 清晰 task: "优化这个函数的时间复杂度，从 O(n²) 降到 O(n log n)"

🔧 高级技巧

1. 链式调用

JavaScript // Agent 1 的输出作为 Agent 2 的输入 const agent1 = await sessions_spawn({task: "生成数据"}) await sessions_yield() const data = agent1.output const agent2 = await sessions_spawn({ task: `分析这些数据：${data}` })

2. 条件分支

JavaScript const result = await sessions_spawn({task: "检查代码"}) await sessions_yield() if (result.hasBugs) { await sessions_spawn({task: "修复这些 bug"}) } else { await sessions_spawn({task: "生成测试用例"}) }

3. 批量处理

JavaScript const files = ["a.js", "b.js", "c.js"] const agents = files.map(f => sessions_spawn({ task: `审查 ${f} 的代码`, label: `reviewer-${f}` }) ) await Promise.all(agents) await sessions_yield()

📝 总结

核心要点

- 创建：sessions_spawn + 清晰的任务描述

- 管理：subagents(list/kill) + sessions_history

- 通信：sessions_send + sessions_yield

- 适配：根据通道选择 mode 和 thread

何时使用多 Agent？

✅ 需要并行处理多个任务

✅ 任务需要不同专业技能

✅ 需要隔离上下文

✅ 复杂项目需要分工协作

何时不用？

❌ 简单一次性任务

❌ 需要强上下文连续性的对话

❌ 资源受限环境

🎯 下一步

现在你已经掌握了多 Agent 系统的核心知识！

实战练习：

创建一个写作 Agent，帮你写一封邮件

创建一个分析 Agent，处理一份数据

尝试多 Agent 协作完成一个小项目

有问题随时问我！ 🤖