Swarm Layer

OpenClaw Swarm Layer

Turn workflow specifications into executable task graphs. Dispatch tasks through manual fallback or ACP automation. Supervise execution through an optional autopilot control plane. Track execution via persistent sessions with reuse and thread binding. Gate completion with review approval. Auto-retry on failure. Generate reports to local disk and Obsidian.

Current release baseline: openclaw-swarm-layer@0.5.3, validated on OpenClaw 2026.5.3-1 with startup tool contracts, plugin doctor checks, and runtime health smoke.

What It Does

What It Does NOT Do

Install

Three installation paths:

ClawHub (skill only):

openclaw skills install swarm-layer

ClawHub package (full plugin):

openclaw plugins install clawhub:openclaw-swarm-layer

npm (full plugin):

npm install openclaw-swarm-layer
openclaw plugins install -l node_modules/openclaw-swarm-layer

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

After install, verify: openclaw plugins info openclaw-swarm-layer should show Status: loaded.

End-to-End Example

# 1. Initialize
openclaw swarm init --project /tmp/my-project
2. Write a spec
cat > /tmp/my-project/SPEC.md << 'EOF'
Feature Build
Goals
Implement and test the new feature
Phases
Implement
Write the core logic
Test
Run unit tests
EOF
3. Plan
openclaw swarm plan --project /tmp/my-project --spec /tmp/my-project/SPEC.md
→ specId: feature-build, taskCount: 2
4. Execute first task
openclaw swarm run --project /tmp/my-project --runner acp
→ action: dispatched, runId: implement-task-1-run-...
5. Poll until complete
openclaw swarm session status --project /tmp/my-project --run 
→ status: completed
6. Approve
openclaw swarm review --project /tmp/my-project --task  --approve
→ status: done
7. Execute next task, repeat steps 4-6
8. View report
openclaw swarm report --project /tmp/my-project

Links

Module Router

Determine which module to use based on what the user needs:

| User Intent | Module | Key Commands | |------------|--------|-------------| | Install, configure, initialize | Setup | plugins install, doctor, init | | Plan, execute, review, session ops | Operate | plan, run, review, session * | | Supervised automation control | Operate | autopilot status/start/pause/resume/stop/tick | | Something broken, stuck, or failing | Diagnose | doctor, session status/cancel/cleanup | | Check progress, read reports | Report | status, report, session list/inspect |

When unsure, start with openclaw swarm status --project . to assess the situation.

Setup

When to Use

Flow

1. Prerequisites

node --version     # >= 22
openclaw --version # >= 2026.3.22

The 0.5.3 release was smoke-tested on OpenClaw 2026.5.3-1.

2. Install Plugin

openclaw plugins install clawhub:openclaw-swarm-layer   # Published package
openclaw plugins install -l /path/to/openclaw-swarm-layer
openclaw plugins info openclaw-swarm-layer   # Should show Status: loaded

3. Configure ACP Public Path

{
  "plugins": { "entries": { "openclaw-swarm-layer": { "config": {
    "defaultRunner": "auto",
    "acp": {
      "enabled": true,
      "defaultAgentId": "codex",
      "allowedAgents": ["codex"],
      "defaultMode": "run"
    }
  }}}}
}

4. Verify

openclaw swarm doctor --json
severity should be "healthy" or "warning", not "blocked"

5. Initialize Project

openclaw swarm init --project .

6. Optional: Obsidian Sync + Journal

{
  "obsidianRoot": "/path/to/vault/reports",
  "journal": {
    "enableRunLog": true,
    "enableReviewLog": true,
    "enableSpecArchive": true,
    "enableCompletionSummary": true
  }
}

Setup Troubleshooting

Operate

When to Use

Core Loop

Write Spec → Plan → Status → Run → Poll Session → Review → Repeat

Write a Spec

# My Workflow
Goals
What to achieve
Phases
Phase 1
Task A
Task B

Plan → Run → Review

openclaw swarm plan --project . --spec SPEC.md      # Import and generate tasks
openclaw swarm status --project .                     # See what's ready
openclaw swarm run --project . --dry-run              # Preview
openclaw swarm run --project . --runner acp           # Execute (acp/manual)
openclaw swarm run --project . --parallel 3           # Dispatch up to 3 ready tasks
openclaw swarm run --project . --all-ready             # Fill all available concurrency slots
openclaw swarm session status --project . --run   # Poll until complete
openclaw swarm review --project . --task  --approve
openclaw swarm review --project . --task  --reject --retry-now  # Reject and force retry

Autopilot Control Plane

openclaw swarm autopilot status --project .           # Health + last decision
openclaw swarm autopilot start --project .            # Start supervised loop
openclaw swarm autopilot pause --project . --reason "operator review"
openclaw swarm autopilot resume --project .
openclaw swarm autopilot tick --project . --dry-run   # Inspect next actions without mutating state
openclaw swarm autopilot stop --project . --mode graceful

Use autopilot when you want the workflow to keep progressing under policy control instead of manually calling run, session status, and recovery commands one by one.

Runner Selection

Session Operations

session list --project .                                    # List all
session inspect --project . --session                   # Details
session follow-up --project . --session  --task   # Inject task
session steer --project . --session  --message    # Redirect
session cancel --project . --run                        # Abort
session cleanup --project . --stale-minutes 60              # Clean orphans

Session Policies

Harness Enhancement (GAN-Inspired Patterns)

Enable advanced harness features for long-running agent orchestration:

{
  "enforceTaskImmutability": true,
  "bootstrap": { "enabled": true },
  "evaluator": { "enabled": true, "autoInjectAfter": ["coding"] }
}

Sprint Contracts — Add Acceptance Criteria to your spec. plan auto-generates a SprintContract with verifiable criteria attached to coding tasks.

Evaluator Injection — When evaluator.enabled, each coding task gets an auto-injected -eval task that validates the contract. Dependency chains adjust automatically:

coding-task → coding-task-eval → next-task

Quality Rubrics — Replace binary approve/reject with 4-dimension weighted scoring:

Cross-Session Progress — progress.json auto-updated after each run and review. Bootstrap sequence loads progress on startup: verify env → load progress → select task → verify baseline.

Task Immutability — When enforceTaskImmutability is enabled, agents cannot mutate task definitions (title, deps, runner, etc.). Only status, review.status, and contract.criteria[].passes are mutable.

Session Budget — Set runner.budget.maxDurationSeconds and runner.budget.maxRetries per task. Exceeded budgets annotate [BUDGET EXCEEDED] on run records.

Assumption Tracking — WorkflowState.assumptions tracks model capability, environment, tooling, and workflow structure assumptions with validation lifecycle.

Conversational Patterns

Diagnose

When to Use

Diagnostic Flow

1. openclaw swarm doctor --json      → Check ACP readiness and bridge-exit health
2. openclaw swarm status --project . → Find abnormal tasks/sessions
3. Investigate specific issue (see below)

Doctor Severity

Issue Resolution

Legacy bridge compatibility warning:

Stuck running task:

swarm session status --project . --run    # Check if session died
swarm session cancel --project . --run    # Force cancel if hung

Dead letter task (retries exhausted):

Orphaned sessions (stale active):

swarm session cleanup --project . --stale-minutes 60

Version drift (after OpenClaw upgrade):

swarm doctor --json
Remove stale bridge metadata if present → rerun doctor → verify runner resolution

Report

When to Use

Quick Check

openclaw swarm status --project .  # Structured summary
openclaw swarm report --project .  # Full Markdown report

Report Sections

Report Files

Local: /.openclaw/swarm/reports/ (always) Obsidian: // (optional async mirror)

Conversational Patterns

Tools Reference

For AI tool calling. All tools accept --json for structured output.

| Tool | Parameters | Purpose | |------|-----------|---------| | swarm_status | project | Workflow status with attention items | | swarm_task_plan | project, spec | Import spec, generate task graph | | swarm_run | project, task?, dryRun?, parallel?, allReady? | Dispatch runnable tasks (single or batch) | | swarm_review_gate | project, task, approve?, reject?, note? | Approve/reject review (reject returns to ready by default) | | swarm_session_status | project, run | Poll session status | | swarm_session_cancel | project, run, reason? | Cancel session | | swarm_session_close | project, run, reason? | Close session |

First-time install, ACP configuration, project initialization, or config troubleshooting.