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

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 auto resolution
• 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 N and --all-ready batch 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.5.3-1)

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 (360 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

Current release validation also includes OpenClaw 2026.5.3-1 smoke coverage on the mini and Volcengine hosts: plugin load, manifest contracts, openclaw-swarm-layer doctor checks, and runtime health.

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

MIT

Contributing

See CONTRIBUTING.md.