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, including explicit [parallel] phase barriers
• ACP-first execution — ACP is the only default-capable automated runner; capability-aware auto resolution
• Supervised autopilot — Deterministic control-plane ticks, optional watcher-driven 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 queued-task drain
• 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 (dev dependency baseline 2026.5.3-1; local mini smoke 2026.6.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 --sync --json

# 4. Dry-run with the resolved default runner
openclaw swarm run --project /path/to/your/project --sync-active --dry-run --json

# 5. Execute
openclaw swarm run --project /path/to/your/project --sync-active --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

Session Management

Runner Model

defaultRunner: "auto" resolves to acp when ACP automation is available, otherwise falls back to manual.

Autopilot Watcher Mode

Autopilot defaults to the existing polling loop. Version 0.5.4 adds optional filesystem watcher modes that can drive ticks from workflow-state changes while keeping polling as the rollback path.

{
  "autopilot": {
    "enabled": true,
    "watcherMode": "hybrid",
    "watcher": {
      "debounceMs": 100,
      "safetyTickMs": 300000,
      "library": "auto"
    }
  }
}

Use watcherMode: "watch" for event-driven operation, hybrid for watcher events plus low-frequency safety polling, and polling to return to the pre-0.5.4 behavior.

Development

npm run build          # TypeScript -> dist/
npm test               # Unit + e2e tests
npm run test:unit      # Unit tests only (428 tests, 62 files)
npm run test:e2e       # E2E tests only (26 tests, 20 files)
npm run test:watch     # Watch mode
npm run check:docs-redaction  # Verify docs do not contain local machine paths
npm run release:check         # Build + full regression + docs redaction + npm pack dry-run + ClawHub package prep

Current release validation also includes OpenClaw 2026.5.3-1 package-baseline coverage and local mini 2026.6.1 smoke coverage: plugin load, manifest contracts, openclaw-swarm-layer doctor checks, runtime health, node/parcel autopilot watcher smoke, and Daily Papers-style parallel workflow completion.

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.