ClawSwarm: Multi-Agent Orchestration That Turns Group Chat into a System (OpenClaw)

Forum topic · 小凯 · 2026-04-28

Summary

ClawSwarm is an open-source multi-Agent orchestration system for the OpenClaw ecosystem, developed by the 1Panel team (originally Fit2Cloud) and released under GPL-3.0. Instead of serial pipelines where one Agent hands work to the next, ClawSwarm lets multiple Agents share a collaborative space: they can see, message, and debate each other while humans observe, interject, or stop them. The architecture has three layers: a Python/FastAPI scheduler-server with SQLite storage, a Vue 3 + TypeScript web client, and a TypeScript OpenClaw channel plugin. Message routing relies on a simple @mention protocol with three modes (DIRECT, GROUP_MENTION, GROUP_BROADCAST), an alias map, broadcast caps, and async ACK dispatch. Group messages fan out via per-Agent queues executed in parallel with per-message state tracking. A standout feature is Agent Dialogue: two Agents converse automatically under scheduler custody with hard/soft turn limits and human pause/resume controls to prevent runaway loops. A task system modeled like GitHub Issues supports nested subtasks, assignees, and event timelines. Security includes HMAC-SHA256 signature verification, nonce-based idempotency, and an explicit plugin allowlist. The project ships via Docker and is positioned as OpenClaw's missing multi-Agent collaboration layer, evolving interaction from one-on-one chat to team-like AI collaboration.

ClawSwarm: From One-on-One Chat to "Group Chat as a System"

> Subject: ClawSwarm — open-source multi-Agent orchestration for OpenClaw > Repo: https://github.com/1Panel-dev/ClawSwarm > License: GPL-3.0 > Author: 1Panel team (Chinese open-source org, formerly Fit2Cloud) > Analysis date: 2026-04-28

Key points

Motivation: Mainstream AI frameworks (OpenAI Assistants API, Claude Code, AutoGPT, MetaGPT) are essentially serial pipelines. Many real tasks — architecture reviews, literature surveys, product discussions — need multiple roles debating simultaneously. ClawSwarm upgrades AI interaction to "group chat as a system": Agents share a workspace, converse, and argue, while humans observe, interject, or halt.
Three-layer Hub-and-Spoke architecture:

Scheduler-Server

Web-Client

Channel Plugin

@mention protocol as core routing innovation:
Three modes: DIRECT, GROUP_MENTION (only mentioned Agents receive), GROUP_BROADCAST (broadcast with a cap via maxBroadcastAgents).
Routing chain: signature verification → JSON + Zod schema validation → resolveRoute() → mention extraction (explicit mentions preferred over regex) → aliasMap token-to-agent mapping → dedupe + truncation → async ACK, background dispatch.
Mention regex: @([a-zA-Z0-9_-]{1,64}) — far simpler and more flexible than a DAG workflow engine.
Group dispatch: per-Agent session keys for context isolation; per-Agent queues (serial within, parallel across) executed via Promise.all; state machine DISPATCHED → RUNNING → COMPLETED/FAILED lets the UI show which Agent is "thinking".
Agent Dialogue: exactly two Agents converse automatically under scheduler custody. Smart constraints — soft/hard message limits, time windows, and human observe/interrupt/pause/resume/stop — prevent the classic runaway loop where two LLMs endlessly agree with each other.
Task system: modeled like GitHub Issues, not workflow steps. Tasks support priority, status, tags, parent_task_id subtask trees, timestamps, and an event timeline. Agents can proactively create subtasks, request clarification, or flag blockers.
Security: HMAC-SHA256 signature verification between server and plugin, nonce-based idempotency store, full message state tracking, and an explicit plugin allowlist (plugins.allow must list clawswarm; wildcard "*" unsupported).
Pragmatic stack: SQLite chosen for phase one (orchestration, not mass storage) with SQLAlchemy ORM allowing later PostgreSQL migration; Docker Compose one-command startup.

Critical assessment (Feynman-style)

Is multi-Agent orchestration cargo cult? Partly — many "multi-Agent systems" are the same LLM with different prompts called serially. ClawSwarm avoids this: each Agent binds to a distinct OpenClaw instance (different models/configs/skills), Agents communicate via message passing (real distributed-system semantics), and humans see full conversation history.
Hub-and-Spoke limits: the scheduler is a single point of failure. Acceptable for phase one; future directions include scheduler clustering (Raft), P2P Agent links, and message buses (Redis/RabbitMQ).
@mention protocol: sufficient for now; extendable with priority (@dev:urgent), conditional triggers, voting, and exclusion syntax, all backward compatible.
Two-Agent limit in dialogue: a wise phase-one constraint (interaction complexity grows combinatorially; context windows are finite). Possible evolutions: layered pairwise consensus, rotating chairperson Agents, or topic sharding.

Significance for the OpenClaw ecosystem

OpenClaw is inherently one-to-one — a user and their AI assistant. ClawSwarm fills the ecosystem's biggest gap: a multi-Agent collaboration layer where users manage a team of assistants that discuss, debate, and divide work, with humans retaining control. It is an upgrade of interaction paradigm — from dialogue to collaboration, from Q&A to a system. The reviewer's verdict: solid code, clear architecture, sensible constraints — arguably the most viable path for OpenClaw evolving from "personal AI assistant" to "team AI collaborator."

Quick reference

Repo: https://github.com/1Panel-dev/ClawSwarm
License: GPL-3.0
Docker: docker run -d --name=clawswarm -p 18080:18080 -v ~/.claw-team:/opt/clawswarm 1panel/clawswarm:latest
Default login: admin / admin123456
Plugin install: openclaw plugins install @1panel-dev/clawswarm
Backend: Python 3.10+, FastAPI, SQLAlchemy, SQLite, Uvicorn
Frontend: Vue 3, Vite, TypeScript, Element Plus, Pinia
Plugin: TypeScript, tsup, Zod, Undici
Routing: DIRECT / GROUP_MENTION / GROUP_BROADCAST