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.

What It Does

• - Spec-driven planning — Write a Markdown spec with goals and phased tasks → generates a dependency-ordered task graph
• Multi-runner execution — Manual (operator-driven safe fallback) and ACP (default-capable automation path)
• Session management — Persistent sessions with binding-key reuse, thread-bound follow-up, and steering messages
• Review gates — Tasks require explicit approve/reject; structured quality rubrics for weighted multi-dimension scoring
• Sprint contracts — Negotiated verifiable acceptance criteria per task with automated evaluator injection (GAN-inspired pattern)
• Cross-session continuity — Progress summary synthesis, bootstrap startup sequence, harness assumption tracking
• Protective guardrails — Task field immutability guard, session budget control (duration + retries)
• Automatic retry — Configurable per-task retry policy with dead letter tracking for exhausted tasks
• 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
• Autopilot control plane — Supervised status/start/pause/resume/stop/tick flows with lease-backed decisions and degraded-mode holds
• Operator reports — Status snapshots, run logs, review logs, spec archives, completion summaries → local + Obsidian sync

What It Does NOT Do

• - Not a distributed multi-node orchestrator — single machine, single project
• Not a CI/CD pipeline — no git push, PR creation, or deployment automation
• Not an autonomous PR factory — operator stays in the loop for review decisions

Install

Three installation paths:

ClawHub (skill only):
CODEBLOCK0

ClawHub package (full plugin):
CODEBLOCK1

npm (full plugin):
CODEBLOCK2

GitHub (source):
CODEBLOCK3

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

End-to-End Example

CODEBLOCK4

Links

• - GitHub: https://github.com/xucheng/openclaw-swarm-layer
• npm: https://www.npmjs.com/package/openclaw-swarm-layer
• Docs: https://github.com/xucheng/openclaw-swarm-layer/tree/main/docs
• Issues: https://github.com/xucheng/openclaw-swarm-layer/issues
• ClawHub: https://clawhub.ai/skills/swarm-layer

---

Module Router

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

User Intent	Module	Key Commands
Install, configure, initialize	Setup	INLINECODE5, doctor, INLINECODE7
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

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

Flow

1. Prerequisites

CODEBLOCK5

2. Install Plugin

CODEBLOCK6

3. Configure ACP Public Path

CODEBLOCK7

4. Verify

CODEBLOCK8

5. Initialize Project

CODEBLOCK9

6. Optional: Obsidian Sync + Journal

CODEBLOCK10

Setup Troubleshooting

• - Plugin not loading → INLINECODE19
• ACP unavailable → openclaw swarm doctor --json, confirm public ACP export readiness and runner resolution
• Legacy bridge config warning → remove bridge.acpFallbackEnabled after confirming ACP public path is ready

---

Operate

When to Use

Plan and execute workflows, manage sessions, complete review cycles.

Core Loop

CODEBLOCK11

Write a Spec

CODEBLOCK12

Plan → Run → Review

CODEBLOCK13

Autopilot Control Plane

CODEBLOCK14

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

Runner	Use When
INLINECODE24	Safe explicit fallback when ACP automation is unavailable or not desired
INLINECODE25

Default-capable automation path through the public ACP control-plane |

Session Operations

CODEBLOCK15

Session Policies

Policy	Behavior
INLINECODE26	New session each run (default)
INLINECODE27

Creates reusable persistent session |

| reuse_if_available | Reuse idle persistent session if match found | | require_existing | Fail if no matching session exists |

Harness Enhancement (GAN-Inspired Patterns)

Enable advanced harness features for long-running agent orchestration:

CODEBLOCK16

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:
CODEBLOCK17

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

• - functionality (0.3) / correctness (0.3) / design (0.2) / craft (0.2)
• Weighted total >= 6.0 → approve; < 6.0 → reject

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

User Says	Do This
"start a new workflow"	Help write spec → plan → INLINECODE47
"run the next task"

status → dry-run → run |

| "what's happening?" | status → session status for running tasks | | "approve everything" | List review queue → approve each | | "enable harness mode" | Add evaluator + immutability + bootstrap config | | "something is stuck" | → Diagnose module |

---

Diagnose

When to Use

Tasks stuck, ACP readiness failures, sessions not updating, dead letters, orphans.

Diagnostic Flow

CODEBLOCK18

Doctor Severity

Severity	Meaning	Action
INLINECODE52	All good	None
INLINECODE53

Works but risky | Address warnings when convenient |

| blocked | Cannot execute | Follow remediation immediately |

Issue Resolution

Legacy bridge compatibility warning:

• - doctor --json → check warnings / INLINECODE58
• Common: remove stale bridge.acpFallbackEnabled, or clean up old versionAllow/openclawRoot metadata

Stuck running task:
CODEBLOCK19

Dead letter task (retries exhausted):

• - swarm status → find dead_letter tasks
• Fix root cause → manually reset task to INLINECODE64

Orphaned sessions (stale active):
CODEBLOCK20

Version drift (after OpenClaw upgrade):

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

---

Report

When to Use

Check progress, generate reports, understand session inventory.

Quick Check

CODEBLOCK22

Report Sections

Section	Content
Attention	Items needing action: review / blocked / running / dead_letter
Tasks

All tasks with current status |

| Review Queue | Tasks awaiting approve/reject | | Highlights | Notable terminal events (completed/failed/cancelled) | | Recommended Actions | What to do next | | Recent Runs | Last 5 runs | | Sessions | Last 5 sessions with state | | Session Reuse Candidates | Which tasks can reuse which sessions |

Report Files

File	Trigger	Mode
INLINECODE65	Every operation	Overwrite
INLINECODE66

swarm run | Append |

| review-log.md | swarm review | Append | | specs/<specId>.md | swarm plan | Create once | | completion-summary.md | All tasks done | Overwrite |

Local: <project>/.openclaw/swarm/reports/ (always)
Obsidian: <obsidianRoot>/<project>/ (optional async mirror)

Conversational Patterns

User Says	Do This
"what's the status?"	INLINECODE75 → summarize counts + attention
"show me the report"

report → read and present key sections |

| "what needs attention?" | status → focus on attention array | | "how are sessions?" | status → show session counts + recent |

---

Tools Reference

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

Tool	Parameters	Purpose
INLINECODE81	INLINECODE82	Workflow status with attention items
INLINECODE83

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 |