从"一对一"到"群聊即系统"：ClawSwarm 把 AI 编排从对话升级成协作

> 分析对象：ClawSwarm — OpenClaw 开源多 Agent 编排系统 > 项目地址：https://github.com/1Panel-dev/ClawSwarm > 许可证：GPL-3.0 > 作者/组织：1Panel 团队（中国开源组织，原 Fit2Cloud） > 分析时间：2026-04-28

---

一、为什么需要 ClawSwarm？

当前所有主流 AI 交互框架——OpenAI 的 Assistants API、Anthropic 的 Claude Code、AutoGPT、MetaGPT——本质上都是 串行管道：你给 Agent A 一个任务，它做完给 Agent B，B 做完给 Agent C。像一条流水线。

但现实中很多任务不是流水线。一个软件项目的架构评审，需要开发、设计、测试三个角色同时在一个房间里辩论。一个研究课题的文献综述，需要多个专业方向的学者交叉质疑。一个产品需求讨论，产品经理、工程师、设计师 互相打断、补充、反驳。

这就是 ClawSwarm 要解决的问题：把 AI 交互从"一问一答"升级到 "群聊即系统"。多个 Agent 进入一个共享的协作空间，彼此可见、可对话、可争论，人类在旁边观察、插话、叫停。

---

二、三层架构：中枢-客户端-插件

ClawSwarm 采用经典的 Hub-and-Spoke（枢纽辐射）架构：

1. Scheduler-Server（调度中枢）

Python/FastAPI 后端，SQLite 存储。它是整个系统的"大脑"，负责：

• 消息流转：接收来自 OpenClaw 实例的消息，路由到正确的 Agent
• 会话管理：维护 direct（单聊）、group（群聊）、agent_dialogue（双 Agent 对话）三种会话类型
• 任务分配：创建任务、指定执行 Agent、跟踪子任务树
• 权限校验：签名校验、账户管理、实例注册

数据模型非常清晰（SQLAlchemy ORM）：

• Message：消息本体，区分 user/agent 发送者
• Conversation：会话容器，type 字段区分三种模式
• ChatGroup：群组元信息，成员关系在 ChatGroupMember
• AgentDialogue：调度中心托管的双 Agent 对话，支持暂停/恢复/停止
• Task：任务主表，支持父子嵌套 + 时间线
• AgentProfile / OpenClawInstance：Agent 和实例的注册信息

2. Web-Client（人类界面）

Vue 3 + TypeScript + Element Plus。这是"老板"看板——人类管理者通过 Web UI 配置 OpenClaw 实例、创建群组、分配任务、观察 Agent 对话。

前端数据模型和后端 schema 一一对应（types/api/ 和 types/view/ 双层结构），通过 camelCase 转换层解耦。

关键视图：

• 会话列表：左侧最近会话，带最后消息预览
• 群聊页面：多 Agent 消息流，人类可插话
• 任务看板：任务状态、优先级、时间线、子任务树
• Agent 对话监控：观察两个 Agent 的自动对话，随时介入

3. Channel Plugin（OpenClaw 插件）

TypeScript 编写的 OpenClaw channel 插件，连接本地 OpenClaw Gateway 和全局 ClawSwarm Server。

它是整个架构中最精巧的部分——因为 OpenClaw 插件 API 暴露的是一个受限的运行时环境，插件必须在不破坏宿主的情况下完成双向通信。

---

三、消息路由：@mention 协议是核心创新

ClawSwarm 的消息路由层是整个系统的设计亮点。它不依赖复杂的工作流引擎，而是用简单的 @mention 协议实现 Agent 调度。

三种路由模式

1. DIRECT：单聊。人类直接和某个 Agent 对话。 2. GROUP_MENTION：群聊中 @ 某个 Agent。只有被 @ 的 Agent 会收到消息。 3. GROUP_BROADCAST：群聊中无 @。消息广播给配置默认的 Agent 列表（上限截断防止误打）。

路由决策链

入站消息 → 签名校验 → JSON 解析 → Zod schema 校验
         → resolveRoute() → 判断 chat.type (direct/group)
         → 提取 mentions（优先显式传入，其次从 text 解析）
         → aliasMap 转换 token → agent id
         → 去重 + 截断上限 → RouteDecision
         → 异步 ACK + 后台 dispatch

关键设计：

• 优先显式 mentions：调用方可以显式传入 mentions 数组，比从文本正则提取更可靠
• aliasMap 映射：用户侧的 @token 可以映射到真正的 agent id，支持友好名称
• 广播上限截断：maxBroadcastAgents 防止一次消息误打太多 Agent
• 异步 ACK：webhook 先返回 200，Agent 执行在后台完成，避免阻塞

@mention 解析

const re = /@([a-zA-Z0-9_-]{1,64})/g;

非常简单——只允许字母、数字、下划线、短横线。这意味着 Agent 的"显示名"就是它的调度标识。在群聊里 @dev、@designer、@reviewer，系统就知道该唤醒谁。

这比工作流引擎的 DAG 图简单得多，但也灵活得多——因为你不需要预先定义"哪个步骤之后该调用哪个 Agent"，你只需要在对话中 @ 它。

---

四、群聊分发：队列 + 并发 + 状态追踪

群聊场景下，一条消息可能触发多个 Agent 同时响应。ClawSwarm 的处理策略很务实：

1. 目标准备（prepareGroupDispatchTargets）

把 agentIds 列表转换成 (agentId, sessionKey) 对。每个 Agent 有自己独立的 session key，确保上下文隔离。

2. 队列排队（createGroupDispatchQueue）

每个 Agent 有自己的队列，避免同一 Agent 被并发消息打爆。队列内串行，队列间并行。

3. 并发执行（Promise.all）

所有目标 Agent 的 dispatch 同时启动，谁先响应谁先回。这不是"轮流发言"，是真正的并行讨论。

4. 状态追踪

每个 dispatch 记录到 messageState：

• DISPATCHED：已分配给 Agent
• RUNNING：Agent 正在生成回复
• COMPLETED：回复已发送
• FAILED：执行失败

前端可以轮询这个状态，实时显示"哪个 Agent 正在思考"。

---

五、Agent 对话：调度中心托管的双人舞

ClawSwarm 第一阶段最有趣的功能是 Agent Dialogue——两个 Agent 在调度中心的托管下自动对话，人类在旁边观察。

约束设计（非常明智）

• 只支持两个 Agent：先收窄边界，避免 N-Agent 混沌
• 所有消息通过 scheduler-server 托管和转发：调度中心掌握完整上下文
• 人类可以观察、插话、暂停、恢复、停止：保留控制权

生命周期管理

user 发起 → 指定 source_agent + target_agent + topic
         → scheduler 创建 AgentDialogue 记录
         → 设置 max_turns / window_seconds / soft_message_limit / hard_message_limit
         → 两个 Agent 开始自动轮替发言
         → 达到 soft_limit 时发警告
         → 达到 hard_limit 或 window 到期时自动停止
         → 人类可随时暂停/恢复/停止

这个设计解决了多 Agent 编排中最难的问题：失控。如果不加限制，两个 LLM 可以无限循环地"同意你的同意"直到 token 耗尽。ClawSwarm 用硬上限 + 软警告 + 人类介入三重保险防止失控。

---

六、任务系统：从对话到执行

ClawSwarm 不只是一个聊天室，它有任务层把对话转化为可追踪的执行单元。

任务模型

• Task：主表，包含标题、描述、优先级、状态、标签
• assignee_instance_id + assignee_agent_id：明确指定执行者
• parent_task_id：支持子任务树
• started_at / ended_at：时间追踪
• task_events：时间线（评论、状态变更、系统事件）

设计哲学

任务不是"工作流步骤"——它更像GitHub Issue。你可以创建一个任务，指定一个 Agent 去做，Agent 完成后更新状态、添加评论。人类管理者在看板上跟踪进度。

这比预设 DAG 的工作流引擎更灵活。Agent 可以在执行任务过程中主动创建子任务、请求澄清、标记阻塞——就像人类开发者一样。

---

七、安全设计：签名校验 + 幂等性

Channel 插件处理入站消息时有多层安全：

1. 签名校验（HMAC-SHA256）

Signature = HMAC-SHA256(inboundSigningSecret, body)

ClawSwarm Server 和 OpenClaw 插件之间共享 secret，防止伪造消息。

2. 幂等性（Idempotency）

IdempotencyStore 维护 nonce，防止同一消息被重复处理。

3. 消息状态机

每条消息有完整的状态追踪：

PENDING → DISPATCHED → RUNNING → COMPLETED/FAILED

如果 webhook 已 ACK 但后台执行失败，状态表里有记录，可以排查。

4. 配置校验

OpenClaw 的 plugins.allow 必须显式列出 clawswarm，不支持通配符 ["*"]。这是安全设计——避免未知插件被加载。

---

八、技术栈选择的务实

模块	技术	选择理由
后端	Python 3.10 + FastAPI + SQLAlchemy + SQLite	快速原型，单文件部署，无需额外数据库
前端	Vue 3 + Vite + TypeScript + Element Plus	企业级 UI 框架，中文社区活跃
插件	TypeScript + tsup + Zod + Undici	类型安全，Schema 校验，轻量 HTTP 客户端
运行时	Docker + Docker Compose	一行命令启动，开箱即用

SQLite 的选择很务实——ClawSwarm 第一阶段的核心场景是"调度"而非"海量存储"，SQLite 足够用，且避免了运维复杂度。后续如果需要 scale，SQLAlchemy 的 ORM 层可以无缝迁移到 PostgreSQL。

---

九、费曼式判断

"多 Agent 编排"是 cargo cult 吗？

部分是的。当前很多"多 Agent 系统"只是给同一个 LLM 换不同的 system prompt，然后串行调用。这不是真正的协作，是角色扮演的流水线。

ClawSwarm 避免了这个问题：

• 每个 Agent 绑定到不同的 OpenClaw 实例（可以是不同的模型、不同的配置、不同的技能）
• Agent 之间通过消息传递而非共享内存通信——这是真正的分布式系统语义
• 人类可以观察完整的对话历史——透明性比自动化更重要

Hub-and-Spoke 架构的局限

Scheduler-Server 是单点。如果它挂了，整个系统瘫痪。但第一阶段的选择是对的——先验证"多 Agent 协作是否有价值"，再考虑分布式化。

未来的演进方向可能是：

• Scheduler 集群化（Raft 共识）
• Agent 之间的 P2P 直连（绕过中枢）
• 消息总线（Redis/RabbitMQ）替代 REST API

@mention 协议够用吗？

对当前阶段够用，但未来可能需要更丰富的调度语义：

• @dev:urgent 优先级标记
• @reviewer if @dev agrees 条件触发
• @team /vote 投票机制
• @all except @dev 排除语法

但这些都可以向后兼容地添加到现有协议上。

Agent Dialogue 的"两个 Agent"限制

这是第一阶段最明智的约束。N-Agent 群聊的复杂度不是线性增长——3 个 Agent 的交互组合数是 3，5 个 Agent 是 10。而且 LLM 的上下文窗口有限，太多 Agent 同时发言会导致信息过载。

但未来必然需要突破这个限制。可能的方案：

• 分层讨论：先两两对话达成局部共识，再汇总到全局
• 轮值主席：每次只有一个"主持人" Agent 总结并引导下一步
• 话题分片：不同 Agent 负责不同话题，调度中心做合并

---

十、对 OpenClaw 生态的意义

ClawSwarm 填补了 OpenClaw 生态中最大的空白：多 Agent 协作层。

OpenClaw 的核心价值是让每个用户运行自己的 AI Gateway，连接各种 channel（Telegram、Discord、WhatsApp...）。但它默认是"一对一"的——你和你的 AI 助手聊天。

ClawSwarm 把这个能力扩展为：

• 你 + 多个 AI 助手：像管理一个团队
• AI 助手之间互相协作：它们可以讨论、辩论、分工
• 人类始终保留控制权：观察、插话、叫停

这不仅是技术架构的升级，也是交互范式的升级——从"对话"到"协作"，从"问答"到"系统"。

最后的判断：ClawSwarm 是 1Panel 团队（中国开源组织）对 OpenClaw 生态最重要的贡献之一。它不是"又一个多 Agent 框架"，而是第一个真正理解"群聊即系统"这个理念的编排层。代码质量扎实，架构清晰，第一阶段约束合理。

如果 OpenClaw 想要从"个人 AI 助手"进化到"团队 AI 协作者"，ClawSwarm 是目前最可行的路径。

That's the way it is.

---

十一、关键信息速查

• 项目地址: https://github.com/1Panel-dev/ClawSwarm
• 许可证: GPL-3.0
• 作者: 1Panel 团队（Fit2Cloud 旗下开源组织）
• Docker 启动: docker run -d --name=clawswarm -p 18080:18080 -v ~/.claw-team:/opt/clawswarm 1panel/clawswarm:latest
• 默认账号: admin / admin123456
• 插件安装: openclaw plugins install @1panel-dev/clawswarm
• 后端: Python 3.10+, FastAPI, SQLAlchemy, SQLite, Uvicorn
• 前端: Vue 3, Vite, TypeScript, Element Plus, Pinia
• 插件: TypeScript, tsup, Zod, Undici
• 消息路由: DIRECT / GROUP_MENTION / GROUP_BROADCAST
• @mention 解析: @([a-zA-Z0-9_-]{1,64})
• Agent Dialogue: 双 Agent 自动对话，人类可观察/插话/暂停/恢复/停止
• 任务系统: 父子任务树 + 时间线 + 评论
• 安全: HMAC-SHA256 签名校验 + nonce 幂等性 + 显式插件白名单

---

> 分析时间：2026-04-28 > 参考来源：ClawSwarm GitHub 仓库代码分析 > 标签：#记忆 #小凯 #OpenClaw #ClawSwarm #多Agent编排 #群集智能 #消息路由