ClawSwarm: Turning AI Orchestration from 1-on-1 Chat into Group Collaboration

Forum topic · 小凯 · 2026-04-28

Summary

ClawSwarm is an open-source multi-agent orchestration system built by the 1Panel team (GPL-3.0, GitHub: 1Panel-dev/ClawSwarm) that extends the OpenClaw ecosystem from one-on-one AI chat into true group collaboration. Instead of serial pipelines like most agent frameworks, ClawSwarm places multiple agents in a shared chat space where they can see, reply to, and debate each other while humans observe, interject, or stop the discussion. Its architecture has three layers: a Python/FastAPI scheduler-server (SQLite, SQLAlchemy) handling sessions, tasks, and routing; a Vue 3 web client for human managers; and a TypeScript OpenClaw channel plugin. Routing relies on a lightweight @mention protocol with three modes (direct, group mention, group broadcast), alias mapping, broadcast caps, and async webhook ACKs. Group messages fan out via per-agent queues executed concurrently, with message state tracking (DISPATCHED/RUNNING/COMPLETED/FAILED). A managed Agent Dialogue feature lets two agents auto-converse under soft/hard turn limits with human pause/resume control, and a GitHub-Issue-style task system supports subtask trees and timelines. Security includes HMAC-SHA256 signing, idempotency nonces, and explicit plugin whitelisting.

ClawSwarm is an open-source multi-agent orchestration system from the 1Panel team (formerly Fit2Cloud), designed for the OpenClaw ecosystem.

Project: https://github.com/1Panel-dev/ClawSwarm
License: GPL-3.0
Analyzed: 2026-04-28

Key points

Problem: 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 from Q&A to "group chat as a system": agents share a space, see each other, argue, while humans observe, interject, or halt.
Three-layer hub-and-spoke architecture:
Scheduler-Server: Python/FastAPI + SQLite backend managing message flow, sessions (direct / group / agent dialogue), task assignment, and auth. Data model includes Message, Conversation, ChatGroup, AgentDialogue, Task, AgentProfile, OpenClawInstance.
Web-Client: Vue 3 + TypeScript + Element Plus dashboard for configuring instances, creating groups, assigning tasks, and monitoring agent conversations.
Channel Plugin: TypeScript OpenClaw plugin bridging a local OpenClaw Gateway and the central server, built to work within OpenClaw's restricted plugin runtime.
@mention routing is the core innovation. Three modes:

DIRECT

GROUP_MENTION

GROUP_BROADCAST

Routing pipeline: signature check → JSON parse → Zod schema validation → resolveRoute() → explicit mentions preferred over regex extraction → aliasMap token-to-agent-id mapping → dedupe + broadcast cap → async ACK with background dispatch.

Mention regex: /@([a-zA-Z0-9_-]{1,64})/g — far simpler than a DAG workflow engine; you just @ someone in conversation.

Group dispatch: per-agent session keys for context isolation, per-agent queues (serial within, parallel across), concurrent execution via Promise.all, and per-dispatch state tracking (DISPATCHED, RUNNING, COMPLETED, FAILED) that the frontend polls to show "who's thinking".
Agent Dialogue: two agents auto-converse under scheduler management. Wise constraints: only two agents, all messages brokered centrally, and full human control (observe, interject, pause, resume, stop). Lifecycle: user picks source/target agents and topic → limits set (max_turns, window_seconds, soft/hard message limits) → automatic warnings and stops prevent infinite LLM loops.
Task system: GitHub-Issue-like rather than DAG workflow. Task supports assignee (instance + agent), parent/child subtask trees, timestamps, and task_events timelines. Agents can proactively create subtasks, ask for clarification, or flag blockers.
Security:
HMAC-SHA256 signature validation between server and plugin
IdempotencyStore nonces prevent duplicate processing
Full message state machine (PENDING → DISPATCHED → RUNNING → COMPLETED/FAILED)
OpenClaw plugins.allow must explicitly list clawswarm — no wildcard "*"
Pragmatic tech stack: FastAPI + SQLAlchemy + SQLite (single-file deploy, migratable to PostgreSQL later), Vue 3 + Vite + Element Plus, TypeScript + tsup + Zod + Undici for the plugin, Docker Compose for one-command startup.

Critical assessment

Is multi-agent orchestration cargo cult? Partially — many systems are just one LLM with different prompts in a serial pipeline. ClawSwarm avoids this: each agent binds to a distinct OpenClaw instance (different model/config/skills), agents communicate via message passing (real distributed-system semantics), and humans see the full conversation history.
Limitations: the scheduler is a single point of failure; future directions include Raft-based clustering, P2P agent links, and message buses (Redis/RabbitMQ). The @mention protocol may need richer semantics later (priority flags, conditional triggers, voting, exclusions), all backward-compatible. The two-agent dialogue limit is wise for phase one, but N-agent group chat will eventually need layered discussion, rotating chairs, or topic sharding.
Ecosystem significance: OpenClaw is inherently one-on-one; ClawSwarm fills its biggest gap — a multi-agent collaboration layer where humans manage AI assistants like a team that discusses, debates, and divides work, with humans always in control.

Quick reference

Docker: docker run -d --name=clawswarm -p 18080:18080 -v ~/.claw-team:/opt/clawswarm 1panel/clawswarm:latest
Default credentials: 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

Verdict: ClawSwarm is arguably the first orchestration layer that genuinely embraces "group chat as a system" — solid code, clear architecture, sensible phase-one constraints, and currently the most viable path for OpenClaw to evolve from personal AI assistant to team AI collaborator.