Five OpenClaw agents wrote an 88,000-word book in 48 hours. Fourteen chapters, 42 diagrams, all coordinated through OpenClaw's sub-agent system. That project showed up in a GitHub discussion last month and it captures what multi-agent orchestration looks like when it works.
Most OpenClaw users run a single agent. It handles messages, runs MCP tools, and gets the job done. But the platform supports three separate multi-agent patterns, each designed for different problems. The documentation is split across multiple pages and the configuration defaults are easy to miss.
This guide covers all three patterns with the actual configs, explains how MCP servers work across multiple agents, and tells you when multi-agent is worth the complexity. And when a single agent with good skills does the job better.
If you are new to OpenClaw, start with our what is OpenClaw guide first.
Three ways to run multiple agents
OpenClaw runs as a single Gateway process. Every message from WhatsApp, Telegram, Discord, and Slack flows through it. That single Gateway supports three distinct patterns for running multiple agents.
1. Sub-agents are background workers spawned from your main agent. They run in parallel, finish their task, and report back. Best for long-running research, batch processing, and code review.
2. Multi-agent routing puts separate, independent agents on one Gateway. Each is bound to different channels or users. Best for home/work separation, security isolation, and different personas.
3. Agent teams are community-built orchestration systems (SWAT, OpenMOSS, Mission Control) that add structured coordination on top of OpenClaw. Best for complex pipelines with review loops and 24/7 operations.
These are not the same thing. Sub-agents share a parent. Routed agents are fully independent. Agent teams add an orchestration layer on top. Picking the wrong pattern creates unnecessary complexity without improving results.
Sub-agents: the parallel workers you probably want first
This is the most common multi-agent pattern. Your main agent spawns background workers that run independently and announce results when done.
Sub-agents are spawned via the sessions_spawn tool or the /subagents spawn command. The call is non-blocking: it returns a run ID immediately and your main agent keeps working. When the sub-agent finishes, its results appear in the parent's context.
Three settings control the system:
| Setting | Default | Range | What it controls |
|---|---|---|---|
| maxSpawnDepth | 1 | 1-5 | How deep agents can nest (orchestrator pattern needs 2) |
| maxConcurrent | 8 | - | Global parallel sub-agent limit |
| maxChildrenPerAgent | 5 | 1-20 | Per-session fan-out cap |
Tool access works through inheritance with one important restriction. Sub-agents get all tools except session and system tools by default. This prevents sub-agents from spawning more sub-agents unless you set maxSpawnDepth to 2 or higher.
Model inheritance follows the parent unless overridden. A common cost optimization: run the orchestrator on Claude Opus and the workers on Claude Sonnet. The orchestrator handles planning and synthesis while workers handle the grunt work at a lower per-token cost.
Config for an orchestrator pattern where sub-agents can themselves spawn workers:
{
"agents": {
"defaults": {
"subagents": {
"maxSpawnDepth": 2,
"maxConcurrent": 8,
"maxChildrenPerAgent": 5,
"model": "sonnet"
}
}
}
}Results flow upward through the hierarchy. Depth-2 workers announce to depth-1 orchestrators, which synthesize the results and announce to the main agent. Each level can filter, summarize, or transform what gets passed up.
Tip: The 88K-word book project used 5 parallel sub-agents, each assigned specific chapters. The orchestrator agent managed the outline and ensured cross-chapter consistency by reading all sub-agent results before publishing. Sub-agents ran on Sonnet while the orchestrator used Opus for the synthesis work.
Multi-agent routing: separate agents on one Gateway
When sub-agents are not enough because you need fully isolated agents with separate credentials, memory, and tool access, you move to multi-agent routing.
Each routed agent is what the docs call a "fully scoped brain." It gets its own workspace files (SOUL.md, AGENTS.md, USER.md), its own auth profiles, and its own session store at ~/.openclaw/agents/<agentId>/sessions. No shared state between agents unless you explicitly set it up.
Routing uses deterministic bindings with an 8-level priority hierarchy:
- Specific peer matches (DMs and groups)
- Parent peer (thread inheritance)
- Discord roles + guild ID
- Guild ID alone
- Team ID (Slack)
- Account ID
- Channel-level fallback
- Default agent
In practice: a home agent on personal WhatsApp handles groceries and scheduling. A work agent on Slack handles code reviews and deployments. Each with different MCP servers, different permissions, different personalities defined in its own SOUL.md.
Since v2026.1.6, OpenClaw supports per-agent sandbox modes and tool restrictions. One agent can run unrestricted while another operates in a sandboxed container with read-only filesystem access. This matters when you give one agent access to production systems and want to keep another agent safely contained.
A warning from the docs: never reuse agentDir across agents. It causes auth and session collisions that are painful to debug.
{
"agents": {
"home": {
"bindings": [{"channel": "whatsapp", "accountId": "personal-number"}],
"agentDir": "~/.openclaw/agents/home"
},
"work": {
"bindings": [{"channel": "slack", "teamId": "T0123WORK"}],
"agentDir": "~/.openclaw/agents/work"
}
}
}Agent teams: SWAT, OpenMOSS, and the Lobster pipeline
The community has built structured orchestration systems on top of OpenClaw's primitives. These add structure that sub-agents and routing do not provide on their own.
SWAT (from GitHub Discussion #41068) is a markdown-driven squad orchestration system. Squads are defined in MANIFEST.md, task state is tracked in OPERATION.md, and accumulated learnings go into INTEL.md. It is pure prompt engineering with no custom code. An MCP bridge handles cross-squad task dispatch. If you can describe a workflow as produce, evaluate, iterate, SWAT can run it.
OpenMOSS (GitHub) is a self-organizing multi-agent collaboration platform. Agents plan, execute, review, and patrol tasks with zero human intervention. It is more autonomous than SWAT and suited for workflows where you want to step away entirely.
Mission Control (GitHub) is the operations dashboard approach. It manages agents, assigns tasks, and coordinates collaboration via the OpenClaw Gateway. The difference is approval-driven governance: humans review and approve before agents act on high-stakes tasks.
The Lobster dev pipeline is a deterministic code-review-test pipeline built by a community member using three agents: Programmer (Claude Opus), Reviewer (Claude Sonnet), and Tester. The pipeline follows a strict sequence: code, review (max 3 iterations), test, done. Lobster controls the workflow transitions through deterministic YAML, not through the LLMs. Agents do what LLMs are good at (writing and analyzing code). Lobster does what code is good at (sequencing, counting, routing, retrying). Source: DEV Community article.
openclaw-agents (GitHub) offers 9 pre-configured specialist agents with one-command setup and group routing. If you want to try multi-agent without building anything from scratch, this is the fastest starting point.
How MCP servers work across multiple agents
MCP servers are configured in openclaw.json at the Gateway level. By default, every agent on the Gateway can access every MCP server. That is convenient for getting started but becomes a problem as you add agents with different security requirements.
The primary isolation mechanism is per-agent tool allow/deny lists. You control which MCP tools each agent can use. Sub-agents inherit MCP tools from their parent unless explicitly restricted via the tools.subagents.tools config.
A practical example: a research agent gets Brave Search MCP and Firecrawl MCP for web research. A code agent gets GitHub MCP and Desktop Commander for development. Neither can access the other's tools.
{
"agents": {
"researcher": {
"tools": {
"allow": ["brave-search", "firecrawl"]
}
},
"coder": {
"tools": {
"allow": ["github", "desktop-commander"]
}
}
}
}Composio MCP integration adds over 1,000 app connections for multi-agent workflows. It turns each external app into an MCP tool your agents can call directly.
One thing to know: the official sub-agent docs do not explicitly cover MCP server isolation. The tool allow/deny system works, but it is documented separately from the sub-agent page. If you are setting up sub-agents with restricted tool access, you need to read both docs pages.
For MCP setup details, see our guide to connecting MCP servers. For server recommendations, check the best MCP servers in 2026 list.
Memory boundaries and agent communication
Each sub-agent gets its own context window. There is no automatic memory sharing between parallel sub-agents. This is by design, not a bug. Shared mutable state between concurrent agents creates race conditions that are hard to debug.
OpenClaw's memory system has two layers. Daily logs live at memory/YYYY-MM-DD.md, are append-only, and the agent reads today's plus yesterday's log at session start. Durable facts go into MEMORY.md for long-term persistence across sessions.
When a session approaches auto-compaction (the context window getting full), OpenClaw triggers a silent agentic turn. This reminds the model to persist important findings to MEMORY.md before the context is cleared. Source: OpenClaw memory docs.
Agent-to-agent communication uses three mechanisms:
sessions_sendfor fire-and-forget messaging between agentsagentToAgenttool for cross-agent calls that wait for a response- Peer messaging through addressable session keys using the pattern
pipeline:<project>:<role>
What works in practice: the orchestrator reads all sub-agent results and writes shared findings to MEMORY.md. Sub-agents read MEMORY.md at startup to get shared context. It is not real-time, but it works for most workflows where eventual consistency is acceptable.
The tradeoff: no native shared memory between parallel sub-agents. Each agent operates in its own context bubble. The orchestrator is the bridge. If your workflow requires real-time data sharing between workers, you need an external store (a database MCP server works well for this).
When multi-agent is worth it (and when it is not)
Start with a single agent. Most users and small teams do not need multi-agent. A single agent with good skills and MCP servers handles most workflows. Adding agents adds complexity, and complexity has a cost in debugging time and token spend.
Scale to sub-agents when a task blocks your main agent for minutes at a time. Long research tasks, batch file processing, running test suites. Sub-agents handle the slow work while you keep chatting with the main agent.
Scale to multi-agent routing when you need platform separation (personal vs work), security isolation (sandboxed agent for untrusted tasks), or very different agent personalities that would confuse a single agent's system prompt.
Scale to agent teams when you have complex pipelines with review loops, need 24/7 autonomous operations, or want structured produce-evaluate-iterate cycles that go beyond what a single orchestrator can manage.
The honest gotchas:
maxConcurrentof 8 is a hard ceiling and you will hit it faster than you expect when running multiple projects.- Coordination overhead is real. Every message between agents burns tokens.
- Debugging multi-agent issues is harder than single-agent debugging by an order of magnitude. When something goes wrong, you have to trace through multiple context windows.
How does OpenClaw compare to other multi-agent frameworks? CrewAI excels at role-based crew structures for team workflows. AutoGen (Microsoft) focuses on conversational agent coordination. LangGraph offers graph-based workflow routing with fine-grained state control. OpenClaw's advantage is that it is a full platform with messaging, scheduling, memory, and MCP built in, not just an orchestration library you bolt onto your own infrastructure.
Tip: If you can describe your workflow as "do A, then B, then C" with no branching, a single agent with skills handles it better than a multi-agent setup. Multi-agent shines when tasks can run in parallel or when isolation is a requirement.
Start simple, then scale
The 88K-word book project and the Lobster dev pipeline prove what becomes possible when you move beyond single-agent thinking. But the right starting point for most people is /subagents spawn for their next long-running task, not a full multi-agent routing setup.
Start simple. Spawn a sub-agent for background research during your next coding session. If that goes well, try routing separate agents to different platforms. Save agent teams for when you have a pipeline complex enough to justify the overhead.
For getting MCP servers connected to your agents, see our MCP connection guide. For picking the right servers, check best MCP servers in 2026. If you need a custom tool, our Python MCP server tutorial covers building one from scratch. And before granting multi-agent access to sensitive systems, read through OpenClaw MCP security.
What would you build with five agents running at once?