AI agent swarm: how to run OpenClaw Swarm without a coordination mess

An AI agent swarm is useful when one task can be split into independent pieces, each with a clear result and a bounded tool surface. It becomes expensive theater when several agents are given the same vague objective and their outputs are stapled together at the end.

OpenClaw Swarm makes that distinction concrete. It runs concurrent collector sub-agents, returns structured results, reports progress, and keeps limits around the group. In v2026.9.2, Swarm is enabled by default for eligible agents, while Code Mode remains a separate opt-in and normal tool policy still applies. The practical question is no longer whether agents can fan out. It is whether the parent has designed work that is worth fanning out.

Table of contents

• When an AI agent swarm earns its cost
• What OpenClaw Swarm changes
• A safe pattern for concurrent sub-agents
• Limits and permissions are part of the design
• How to handle partial failure
• Where Swarm fits in OpenClaw
• FAQ

When an AI agent swarm earns its cost

Use an AI agent swarm when the work has independent lanes. A release review is a good example: one child checks configuration changes, another checks security-impacting defaults, and a third checks migration notes. The parent then compares evidence and writes the decision.

Do not use a swarm just because the task sounds large. A single task with a shared dependency chain, such as editing one source file through several passes, often benefits more from one agent plus deterministic checks. Anthropic makes the same tradeoff explicit: agentic systems add latency and cost, so teams should start with the simplest solution that can do the job.

Good fit for concurrent children	Poor fit for concurrent children
Independent research questions	One file with tightly coupled edits
Separate review dimensions	A task that needs a single evolving plan
Parallel evidence gathering	A workflow with ambiguous acceptance criteria
Multiple candidate solutions to compare	Work that triggers the same external side effect

The division of work should be visible in the prompt. “Research the release” gives every child the same job. “Return one configuration change, the exact source link, and one operator impact” produces results the parent can compare.

What OpenClaw Swarm changes

OpenClaw describes Swarm as an experimental collector model. The orchestration is ordinary JavaScript or TypeScript, not a graph DSL: a Code Mode script can use Promise.all, Promise.allSettled, loops, and conditionals to launch child work and collect it.

That choice matters because the parent can keep the control flow close to the task. The child API accepts a label, model choices, an optional target agent, a phase, and a JSON Schema for the response. With a schema, the parent receives structured output rather than hoping every child wrote compatible prose.

OpenClaw’s release notes also make an important boundary clear. Enabling Swarm does not grant tools or bypass policy. Code Mode is still separately opt-in, and a child target must be configured and allowed by the requester’s subagents.allowAgents policy. That is the right default for an AI agent swarm: more workers should not silently expand what the system can touch.

A safe pattern for concurrent sub-agents

Start with a parent that owns the plan and has no reason to let children decide the next external action. Give each child a small contract, then reconcile the results after every lane has settled.

const reviewSchema = {
  type: "object",
  properties: {
    finding: { type: "string" },
    evidence: { type: "array", items: { type: "string" } },
    confidence: { type: "number" },
  },
  required: ["finding", "evidence", "confidence"],
  additionalProperties: false,
};

const topics = ["permissions", "recovery", "migration"];
const outcomes = await Promise.allSettled(
  topics.map((topic) =>
    agents.run(`Review ${topic}. Return one finding with source evidence.`, {
      label: `review-${topic}`,
      schema: reviewSchema,
    }),
  ),
);

This pattern gives the parent four useful properties:

1. Each child has a named scope.
2. The response shape is known before synthesis begins.
3. A failing child remains visible instead of being replaced by a plausible paragraph.
4. The parent can decide whether evidence is strong enough to continue.

The choice of Promise.allSettled is deliberate. Promise.all stops on the first rejection, which can hide successful work that finished in other lanes. OpenClaw’s Swarm guidance recommends keeping completed results, recording failures, and avoiding an automatic respawn of the entire batch.

Limits and permissions are part of the design

An AI agent swarm needs more than a parallel loop. It needs a ceiling. OpenClaw’s documented defaults are 8 concurrent children, 50 live children per group, 200 total children over a group’s lifetime, and a maximum agents_wait timeout of 600 seconds. Extra accepted children queue in submission order.

Those defaults are not a throughput target. They are a safety rail. Pick a lower maxConcurrent when workers share a rate-limited API, a small local model, a browser profile, or a database with a narrow write path. Raise it only after measuring the bottleneck and confirming that the downstream system can absorb simultaneous calls.

Use targeted permissions too. A lean worker agent can have a smaller model, fewer tools, and a tighter sandbox than the parent. OpenClaw permits a per-agent Swarm setting, so an agent can be allowed to run as a worker but prevented from starting its own top-level swarm. This keeps the hierarchy flat and prevents accidental recursion.

For broader product context, read how OpenClaw works and why OpenClaw. If your workflow needs visible ownership and review states, the AI agent workboard guide covers the complementary coordination layer.

How to handle partial failure

A finished batch is not necessarily a successful batch. Child runs can time out, be killed, fail schema validation, or return a result before a later provider failure. The parent should preserve the terminal status and decide whether the remaining evidence is sufficient.

A practical policy is simple:

• Continue when the successful lanes answer independent parts of a low-risk question.
• Retry one failed lane only when the failure was transient and the retry budget is explicit.
• Stop for human review when a failed lane owned a required check, an approval, or an external write.
• Keep the failure record in the final response, task, or log. A summary that omits failed lanes makes the system look more reliable than it was.

This is also where a swarm differs from a room full of chat agents. The parent is accountable for the acceptance rule. It should not treat a majority of fluent answers as proof.

Where Swarm fits in OpenClaw

Swarm is a concurrency primitive, not a replacement for the rest of the system. It sits alongside the agent’s tools, model selection, sandbox policy, session rules, and review process. The what is OpenClaw overview explains the broader self-hosted agent stack; Swarm is one way to split work inside that stack.

The v2026.9.2 release also changed cross-agent session access defaults. Installations with several agents should review conversation visibility before upgrading, especially where users or agents are not mutually trusted. The release documentation points to tools.sessions.visibility for narrowing the setting. That is separate from Swarm, but the two changes belong in the same operator checklist: concurrency only stays manageable when each worker’s data access is intentional.

For an AI agent swarm, the durable operating model is modest: fan out only independent work, give each child a narrow contract, require structured evidence, cap concurrency, and expose failures to the parent. The result is less dramatic than a fully autonomous swarm demo. It is much easier to operate.

FAQ

What is an AI agent swarm?

An AI agent swarm is a parent agent coordinating multiple sub-agents on separate parts of a task. It is useful when the work can be split into independent lanes and the parent can combine their results under a clear acceptance rule.

Is OpenClaw Swarm enabled by default?

OpenClaw documents Swarm as enabled by default for eligible agents, with an explicit opt-out. Code Mode remains separately opt-in, and Swarm still follows the active tool, sandbox, provider, and sub-agent policies.

How many OpenClaw Swarm children can run at once?

The documented default is 8 concurrent collector children per group. The default group caps are 50 live children and 200 total children over the group’s lifetime. Operators can tune those limits within the documented bounds.

Should every multi-agent workflow use Promise.allSettled?

No. Use it when partial results are meaningful and the parent needs a complete record of successful and failed lanes. If every child must succeed before any output is valid, fail fast may be appropriate, but the failure should still be recorded.

Does enabling Swarm give sub-agents more permissions?

No. OpenClaw states that enabling Swarm does not grant tools or bypass policy. Each child still operates under configured tool, sandbox, provider, and sub-agent restrictions.

Sources: OpenClaw Swarm documentation, OpenClaw v2026.9.2 release notes, Anthropic: Building effective agents, OpenAI Agents SDK: handoffs