从"一对一"到"群聊即系统"：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 暴露的是一个**受限的运行时环境**，插件必须在不破坏宿主的情况下完成双向通信。 --- ## 三、消息路由：<span class="mention-invalid">@mention</span> 协议是核心创新 ClawSwarm 的消息路由层是整个系统的设计亮点。它不依赖复杂的工作流引擎，而是用**简单的 <span class="mention-invalid">@mention</span> 协议**实现 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 映射**：用户侧的 <span class="mention-invalid">@token</span> 可以映射到真正的 agent id，支持友好名称 - **广播上限截断**：`maxBroadcastAgents` 防止一次消息误打太多 Agent - **异步 ACK**：webhook 先返回 200，Agent 执行在后台完成，避免阻塞 ### <span class="mention-invalid">@mention</span> 解析 ```typescript const re = /@([a-zA-Z0-9_-]{1,64})/g; ``` 非常简单——只允许字母、数字、下划线、短横线。这意味着 Agent 的"显示名"就是它的调度标识。在群聊里 <span class="mention-invalid">@dev</span>、<span class="mention-invalid">@designer</span>、<span class="mention-invalid">@reviewer</span>，系统就知道该唤醒谁。 这比工作流引擎的 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 **<span class="mention-invalid">@mention</span> 协议够用吗？** 对当前阶段够用，但未来可能需要更丰富的调度语义： - `@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 - **<span class="mention-invalid">@mention</span> 解析**: `@([a-zA-Z0-9_-]{1,64})` - **Agent Dialogue**: 双 Agent 自动对话，人类可观察/插话/暂停/恢复/停止 - **任务系统**: 父子任务树 + 时间线 + 评论 - **安全**: HMAC-SHA256 签名校验 + nonce 幂等性 + 显式插件白名单 --- > 分析时间：2026-04-28 > 参考来源：ClawSwarm GitHub 仓库代码分析 > 标签：#记忆 #小凯 #OpenClaw #ClawSwarm #多Agent编排 #群集智能 #消息路由