OpenClaw Swarm

Swarm is how an OpenClaw agent fans work out across many sub-agents from a Code Mode script. The docs are emphatic about the shape: normal JavaScript or TypeScript control flow, Promise.all, while and if, with no graph DSL and no separate workflow format, and what Swarm adds is awaitable collector children, structured results, bounded concurrency and progress reporting. It is enabled by default with an explicit opt-out. Here is when to reach for it, the limits, the guest API, how collector children behave, and how to observe or stop a run.

When and how

• Use an ordinary announcing spawn for one or a few children; reserve Swarm for large parallel fan-out, several similar children, about five or more, typically driven by the run call inside Promise.all.
• It needs Code Mode enabled and Swarm left on; the guest globals, run, phase and log, appear only when the catalog contains the native spawn tool and the execution allowlist permits it, and an MCP tool with the same name does not qualify.
• The defaults: eight collector children running concurrently per group with the rest queued in order, fifty live children per group, two hundred over a group’s lifetime as the runaway backstop, a wait timeout of at most six hundred seconds with thirty as the call default, and an optional default agent for children.
• Opt out with the swarm key set to false, or per agent, where a limits-only object inherits global enablement and never re-enables a global off.

There is no graph DSL and no separate workflow format. The program is the orchestration.

The guest API

The run call takes a prompt and options, label, model, thinking, fast mode, agent id, schema and phase. Without a schema it resolves to the child’s final text; with a JSON Schema it resolves to the value the child submitted through a synthetic structured-output tool, with one corrective nudge for an invalid payload and the raw text plus a schema error otherwise. A failed, killed, timed-out or schema-invalid child rejects with an error whose name, run id, status and message identify it. The docs’ fan-out example uses Promise.allSettled rather than Promise.all, because allSettled preserves partial results while all rejects on the first failure, and the rule that follows is to keep completed work, report failed lanes, and never respawn the batch automatically. A decision-gate loop must be bounded; the lifetime cap is a safety backstop, not a stopping condition. Promise.race reacts to the first child to finish.

Collector children

• They are ordinary isolated sub-agent sessions with a different completion path: they write a durable collector result for the parent to await, send no completion notification and cannot be steered; the target agent resolves from the call, then the configured default, then the requesting agent.
• Approvals fail closed: a child never opens an operator approval prompt, an action that would need one is denied, and the child can report the denial in its result. A dedicated lean worker agent, configured by you since none ships built in, and hardened with Swarm off in its own config, is the docs’ suggested target.
• Keep groups flat: nested collector children are discouraged, the caps and observability assume flat groups, and a spawn depth of one enforces it. Announce children use the per-agent child budget of five; collector children use only the group caps.

OpenClaw subagents is the policy layer these children run under, and OpenClaw sandboxing explained the isolation each one gets.

Watching, stopping, other harnesses

Keep the parent session open: the Control UI and the native apps show a progress widget with queued, running, completed and failed counts, expandable child details, up to four active groups plus the latest completed one, and counts that survive a reload because they come from retained collector records. Stop in the parent chat cancels the collector children and their descendants; if it reports incomplete cancellation, the Tasks page is where the rest is retried. Without Code Mode, the same core tools work from any harness: spawn with collect and drain with bounded wait calls that accept up to a thousand run ids and return completed, pending and error arrays, bounded long polling rather than a busy loop. The limits are one-shot children, no stateful multi-turn worker API, the local Gateway’s lane only, and no saved workflow definitions. OpenClaw usage tracking is where the spend of a wide fan-out shows up.

On Diali

On Diali the sub-agent lane runs inside the assistant’s own isolated instance, and the model spend of a fan-out lands on the assistant’s credit balance, which is the number to size before writing a loop. Hosted OpenClaw on Diali is the assistant and AI credit calculator turns a planned fan-out into credits.

• The program is the orchestration.
• Eight at a time, fifty live, two hundred per group.
• Collector children fail closed and are never respawned automatically.