OpenClaw 智能体集群（Agent Swarms）进阶指南：打造多智能体工作流

在 OpenClaw 2.7 版本中，我们推出了 智能体集群 (Agent Swarms)——这是一个强大的新原语，用于编排多个 AI 智能体协同解决复杂任务。与试图包揽所有工作的单个智能体不同，集群允许你定义专门的角色（如研究员、程序员、审核员），让它们自主协作。

本指南将带你构建第一个集群：一个 市场调研团队。

什么是集群 (Swarm)？

集群是一组具备以下特性的智能体集合：

专业指令：每个智能体都知道自己的具体职责。
交接协议：智能体可以在需要时将控制权转移给其他智能体。
共享上下文：记忆在整个集群会话中保持同步。

构建市场调研集群

我们将构建一个包含两个智能体的简单集群：

研究员 (Researcher)：搜索网络信息。
分析师 (Analyst)：将数据整理成报告。

第一步：定义智能体

首先，在你的 OpenClaw 工作区创建一个 swarm.config.ts 文件。

import { Agent, Swarm } from '@openclaw/core';

const researcher = new Agent({
  name: 'Researcher',
  instructions: '你是一名网络研究员。查找关于该主题的最新数据。',
  tools: ['web_search'],
});

const analyst = new Agent({
  name: 'Analyst',
  instructions: '你是一名数据分析师。阅读研究资料并进行总结。',
});

第二步：定义交接

现在，将它们连接起来。研究员需要将工作移交给分析师。

researcher.addHandoff('analysis_needed', analyst);

第三步：运行集群

const swarm = new Swarm({
  agents: [researcher, analyst],
  defaultAgent: researcher,
});

await swarm.run("调研 2025 年 AI 智能体的普及情况。");

为什么这很重要

单智能体系统往往会被过长的上下文或相互冲突的指令搞混。通过将任务分解为角色，你可以获得：

更高的准确性：智能体专注于一件事。
更好的调试：你可以确切地看到哪个智能体出了问题。
可扩展性：轻松添加更多智能体（例如“撰稿人”或“编辑”）。

什么场景最适合先上 Swarm

这篇指南最适合下面几类高意图场景：

你已经不是想做一次性问答，而是想把 research、coding、review 拆给不同角色
单个 agent 经常因为上下文过长、目标过杂而跑偏
你在做重复型工作流，比如调研、排障、内容生产、代码审查
你希望把“谁负责查资料、谁负责总结、谁负责最后把关”明确下来

如果你只是想先跑通 OpenClaw、确认 gateway 正常工作，或者只需要一个 agent 做单步任务，那就先别急着上 swarm，先把基础 setup 和单 agent 流程跑顺更划算。

常见搭建判断问题

什么时候两角色 swarm 就够了

如果你的目标还是线性的，例如“查资料 -> 总结输出”或“收集日志 -> 形成结论”，两角色通常已经够用：

一个 agent 负责采集
一个 agent 负责分析或收尾

不要一上来就堆 5 到 6 个角色，否则你很快会把问题从“任务太复杂”变成“编排太复杂”。

什么时候不该先优化 swarm，而该先优化单 agent

如果你现在遇到的是这些问题：

工具权限没配好
gateway 本身不稳定
模型或 API 经常超时
基础 prompt 都还没跑顺

那这些都不是 swarm 先解决的问题。先把单 agent 路径调通，再扩到多 agent，会更快得到稳定收益。

常见 swarm 设计误区

什么时候 swarm 带来的编排成本会超过收益

如果你的流程本身还没理清，就先把角色边界拆得很细，swarm 往往会开始拖慢效率。一个实用判断标准是，如果你不能用一句话说清“为什么这个 agent 现在要交给下一个 agent”，那这个集群大概率拆得过碎。最适合作为第一版的 swarm，应该是小而明确，并且只服务一个可重复结果。

把一个流程交给多个 agent 之前，最该先写清什么

在你把角色扩到两个以上之前，至少先写清这四件事：

每个 agent 负责什么，不负责什么
什么证据或条件会触发 handoff
最后一个 agent 必须输出什么格式
某个工具失败或某个角色无法完成时，应该怎么退回或兜底

这样做的好处是，后续排查时你能更快看出是哪一段出了问题，也能避免多个 agent 重复劳动，或者在角色之间来回踢皮球。

哪些场景不该一上来就用 Swarm

如果你符合下面任意一种情况，Swarm 往往不是第一步：

单 agent 版本都还没跑稳，因为编排层只会把基础问题藏起来，不会替你解决它。
任务几乎没有清晰交接边界，把它硬拆成多个角色，只会增加延迟和上下文漂移点。
你看不到中间产物，这样一旦结果变差，很难判断是 agent、handoff，还是任务设计本身出了问题。

这种情况下，先把单 agent 路径简化并测稳，再决定要不要升级成 swarm。

上线前常见运维判断问题

第一个最适合放进生产的 swarm 用例，应该长什么样？

优先挑那种每个 agent 都只负责一小段、而且中间结果可检查的流程，比如 research → synthesis，或者 triage → action drafting。先确保 handoff 可审计，再把这套模式带进更接近用户的回路。

什么时候 swarm 应该只留在内部使用，而不要直接触达用户？

当输出质量还不稳定、升级规则不清晰，或者任意一次 handoff 失真都可能直接伤到用户体验时，就先把 swarm 留在内部。面向用户的 swarm，应该建立在你已经信任这套协作模式之后。

哪些信号说明你的 swarm 边界终于划对了？

当 handoff 不再像“重新开一轮讨论”，而更像机械式交接时，通常就说明边界开始对了。更具体地说，就是每个 agent 都能产出一个小而可检查的中间结果，下一个 agent 不需要重新理解整道题，而且一旦失败，你能很快把问题归到某个角色，而不是整条工作流一起背锅。

在把两角色 swarm 扩成更大团队前，最该先测什么？

先测完成率、handoff 失败率、复审返工率，以及角色之间等待时间。如果两角色版本在这些指标上还不稳定，继续加角色通常只会更快放大噪音，而不是放大产出质量。

FAQ：什么样的 swarm 才算值得放进真实工作流？

swarm 角色拆得过多，最先暴露出来的信号是什么？

最先暴露出来的通常不是报错，而是犹豫。比如 agent 反复重述任务、追问本该已经明确的上下文，或者把任务交回去却没有产出任何可检查的中间结果，这通常说明角色边界已经被拆得超过了自然工作流本身。

什么时候该增加 reviewer 角色，而不是继续加长 prompt？

当一次错误的中间产物会明显放大下游损失时，就该考虑 reviewer。比如错误总结、错误代码改动、错误升级草稿都会直接影响后续动作，这时单独加一层 reviewer，往往比无止境地把同一个 agent 的 prompt 越写越长更稳。

在把 swarm 放进生产前，最该先记录哪些日志？

至少记录四类信号：handoff 是被什么证据触发的、每个角色产出了什么中间结果、角色之间等待了多久、以及人类最终是在什么节点介入的。没有这四类日志，团队后面通常只会围绕“这套 swarm 行不行”争论，而看不清真正失效的是哪一段。

从 Agent Swarms 流量转成接力边界设计

如果你是因为 “OpenClaw agent swarms” 或“多 agent 协作怎么落地”搜到这里，先不要急着增加 agent 数量。真正影响产出的不是 swarm 规模，而是每个 agent 的交接边界、验收证据和失败回退路径是否清楚。

最小落地方式是先定义一个主 agent、两个子 agent 和一条明确的 handoff contract：输入是什么、输出必须包含哪些证据、超时后谁接管、哪些信息禁止跨任务泄漏。这样页面承接的就不是概念流量，而是把高意图读者引向可审计的多 agent SOP。

面向搜索入口的 Agent Swarm 上线检查清单

如果你是搜“OpenClaw agent swarms”或“多个 OpenClaw agent 怎么安全协作”来到这篇指南，先把 swarm 当成生产工作流，而不是更大的 prompt。在让多个 agent 改代码或操作工具前，先确认这条顺序：

指定一个 owner agent 负责定范围、审子任务结果，并阻止重复工作；
给每个 child agent 明确窄任务、预期产物和停止条件；
除非任务确实需要，不要把共享凭据和可写工具放进 child context；
要求每个 child 返回证据，例如 diff、测试结果、公网检查或明确 blocker；
只有 owner 确认输出不冲突、没有重复覆盖同一表面后，再合并。

这段内容把“agent swarm”搜索流量转成更安全的运维模型：并行化调查、取证和草稿，但最终写入权限和部署判断仍集中在一个 owner 上。