OpenClaw Swarm Layer
Spec-Driven Workflow Orchestration for AI Agent Swarms
Turn Markdown specs into executable task graphs. Dispatch through ACP automation or manual fallback. Supervise progress with a control plane. Track with persistent sessions. Gate with review approval.
Quick Start · Installation · CLI Reference · Configuration · Docs
</div>Features
- Spec-driven planning — Markdown spec with goals and phased tasks → dependency-ordered task graph
- ACP-first execution — ACP is the only default-capable automated runner; capability-aware
autoresolution - Supervised autopilot — Deterministic control-plane tick, lease-backed service loop, and operator-visible start/pause/resume/stop controls
- Persistent sessions — Reuse, thread binding, follow-up, steer, cancel, and close flows
- Review gates — Explicit approve/reject with structured quality rubrics (weighted multi-dimension scoring)
- Sprint contracts — Verifiable acceptance criteria per task with GAN-inspired evaluator injection
- Cross-session continuity — Progress synthesis, bootstrap startup sequence, harness assumption tracking
- Automatic retry — Configurable per-task retry policy with dead letter tracking and signal-based auto-retry
- Concurrency protection — ACP session concurrency limits with queued task scheduling (FIFO)
- Reject-retry workflow — Review rejections return tasks to ready for re-run; configurable retry limits
- Parallel dispatch —
--parallel Nand--all-readybatch dispatch with concurrency-aware slot management - Operator reporting — Status snapshots, run/review logs, spec archives, completion summaries → local + Obsidian sync
- Runtime diagnostics —
swarm doctor,swarm status, and workflow reports surface ACP bridge-exit gate directly
Prerequisites
- Node.js >= 22
- OpenClaw >= 2026.3.22 (tested against
2026.4.8)
Installation
From ClawHub (recommended)
openclaw plugins install clawhub:openclaw-swarm-layer
Skill From ClawHub
openclaw skills install swarm-layer
From npm
npm install -g openclaw-swarm-layer
openclaw plugins install openclaw-swarm-layer
From source
git clone https://github.com/xucheng/openclaw-swarm-layer.git
cd openclaw-swarm-layer
npm install && npm run build
openclaw plugins install -l /path/to/openclaw-swarm-layer
Quick Start
# 1. Initialize a project
openclaw swarm init --project /path/to/your/project
# 2. Import a spec and build the workflow
openclaw swarm plan --project /path/to/your/project --spec SPEC.md
# 3. Inspect runtime posture before execution
openclaw swarm doctor --json
openclaw swarm status --project /path/to/your/project --json
# 4. Dry-run with the resolved default runner
openclaw swarm run --project /path/to/your/project --dry-run --json
# 5. Execute
openclaw swarm run --project /path/to/your/project --json
# 6. Review and report
openclaw swarm review --project /path/to/your/project --task <taskId> --approve --json
openclaw swarm report --project /path/to/your/project --json
CLI Commands
Core Workflow
| Command | Description |
|---|---|
swarm init --project <path> | Initialize swarm state for a project |
swarm plan --project <path> --spec <path> | Import a spec and build task graph |
swarm run --project <path> [--runner acp|manual] [--dry-run] [--parallel N] [--all-ready] | Execute runnable tasks (single or batch) |
swarm review --project <path> --task <id> --approve|--reject [--retry-now] | Approve or reject a task |
swarm report --project <path> | Generate a workflow report |
swarm status --project <path> | Show workflow status, runtime posture, and bridge-exit gate |
swarm doctor | Diagnose ACP readiness and bridge-exit gate status |
swarm autopilot status --project <path> | Inspect autopilot health, lease state, and last decision |
swarm autopilot start/pause/resume/stop --project <path> | Control the supervised autopilot service state |
swarm autopilot tick --project <path> [--dry-run] | Sync active runs, review state, and queue pressure through the supervised control plane |
Session Management
| Command | Description |
|---|---|
swarm session list --project <path> | List known sessions |
swarm session inspect --project <path> --session <id> | Inspect a session |
swarm session status --project <path> --run <id> | Poll session status |
swarm session cancel --project <path> --run <id> | Cancel an active session |
swarm session close --project <path> --run <id> | Close a session |
swarm session follow-up --project <path> --session <id> --task <desc> | Inject a follow-up task |
swarm session steer --project <path> --session <id> --message <text> | Send a steering message |
swarm session cleanup --project <path> [--stale-minutes <n>] | Clean up orphaned sessions |
Runner Model
| Runner | Role | Default-capable | Requirements |
|---|---|---|---|
acp | Primary automation path | Yes | ACP enabled, public control-plane available |
manual | Operator-driven safe fallback | Always available | None |
defaultRunner: "auto" resolves to acp when ACP automation is available, otherwise falls back to manual.
Development
npm run build # TypeScript -> dist/
npm test # Unit + e2e tests
npm run test:unit # Unit tests only (354 tests, 59 files)
npm run test:e2e # E2E tests only (25 tests, 19 files)
npm run test:watch # Watch mode
npm run release:check # Build + full regression + npm pack dry-run + ClawHub package prep
Documentation
User Guides:
- User Manual — Install, configuration, daily workflow, and troubleshooting
- Configuration Reference — Config schema, defaults, examples, and journaling
- Skills Guide — Unified skill usage modules
- Release Runbook — npm, GitHub release, ClawHub package, and ClawHub skill publishing steps
Operations:
- ACP Bridge Exit Gate — Bridge-free ACP floor, live smoke matrix, artifact expectations
- Operator Runbook — Install, smoke, upgrade, rollback, and ACP control-plane operations
- Migration Checklist — Staged bridge replacement planning
- Testing Strategy — Unit, e2e, and smoke verification rules
Project History:
- Changelog — Release notes
- Roadmap — Milestone structure and delivery history
- Milestones — Definition of done per milestone
License
Contributing
See CONTRIBUTING.md.