OpenClaw Swarm Layer

Spec-Driven Workflow Orchestration for AI Agent Swarms

Turn Markdown specs into executable task graphs. Dispatch through ACP automation, manual fallback, or legacy subagent bridge. 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
• 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
• 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.3.24)

Installation

From ClawHub (recommended)

clawhub install openclaw-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\|subagent] [--dry-run] | Execute the next runnable task | | swarm review --project <path> --task <id> --approve\|--reject | 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 |

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 | | subagent | Legacy bridge-backed opt-in | No | subagent.enabled=true + bridge.subagentEnabled=true |

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 (872 tests, 324 suites)
npm run test:e2e       # E2E tests only (68 tests, 104 suites)
npm run test:watch     # Watch mode

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

Operations:

• ACP Bridge Exit Gate — Bridge-free ACP floor, live smoke matrix, artifact expectations
• Operator Runbook — Install, smoke, upgrade, rollback, legacy bridge guidance
• 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.