.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
OpenClaw supports running multiple agents inside one Gateway process, and each one can behave like its own assistant with its own files, memory, auth and tools.
This guide is about multi-agent setup in practical terms. You’ll see two patterns that are easy to confuse:
- Persistent agents that live “forever” and usually map to a channel, a bot account or a household member
- Sub-agents that run in the background for a specific task then auto-archive
You can run both together. A common setup is a main “orchestrator” agent that handles your primary chat and it spawns sub-agents for parallel tasks. At the same time you can keep other persistent agents bound to separate channels so they do their own thing independently.
What “multi-agent” means in OpenClaw
OpenClaw can run multiple fully isolated agents inside one Gateway process. “Isolated” here is not marketing language. Each agent can have its own:
- workspace directory and local files like SOUL.md and AGENTS.md
- memory storage
- session history
- auth profiles for model providers and skills
- skills list and skill overrides
- model selection and defaults
- optional Docker sandbox settings
They still share the same server process and the same main config file, so you don’t run ten gateways. You run one gateway and multiple “brains” inside it.
If you are currently running a single assistant across a few channels, you might not need multi-agent. A well configured single agent can handle Slack and Telegram and Discord and keep context fine. Multi-agent starts being useful when you need real isolation, different tool policies or separate memories that should never mix.
Two multi-agent patterns that solve different problems
Persistent agents
Persistent agents are the long-lived ones. You define them in config or you create them using the agent wizard. These are the ones you bind to channels and chats.
Examples that make sense:
- a work assistant bound to Slack
- a family assistant bound to a WhatsApp account with strict tool restrictions
- a coding assistant bound to Discord that can access repos and run commands
- a social agent that only writes drafts and never has exec enabled
Sub-agents
Sub-agents are background workers spawned from a running conversation. They run in their own session, do their job and post back a result. OpenClaw documents this in two places that are worth reading once:
- sessions_spawn in the session tools concept page OpenClaw session tools
- /subagents spawn in the sub-agents tool page OpenClaw sub-agents
Sub-agents are great for parallel research and slow tool tasks. They are also great for cost control if your main agent uses an expensive model and your sub-agents use a cheaper model or a local model.
When multiple agents are actually worth it
Multi-agent is not a checkbox you need to tick. It adds moving parts. The trick is to add agents for clear reasons.
Different tool policies for safety
This is the biggest reason. For example, you want your personal assistant to have exec and filesystem access. You do not want your public Discord bot to have exec. With separate agents you can enforce this with per-agent tool allow and deny lists.
If you need security context for OpenClaw deployments, use OpenClaw security best practices.
Separate memories and tone
Memory is useful but it also creates “bleed”. If your work assistant learns one set of preferences and your personal assistant learns another, you will eventually get weird crossovers in tone, reminders or details. Separate agents prevent that.
If you haven’t dug into memory yet, read OpenClaw memory explained.
Different models and cost profiles
Some people want a fast model for casual chat and a slower stronger model for deep work. Multi-agent makes this clean because each agent can have its own default model. Sub-agents can also use a separate model by default which is an easy cost win.
If you need help choosing between Claude and OpenAI models in OpenClaw, we have a guide here: Claude vs OpenAI model choice for OpenClaw.
Persistent agents setup
What “one agent” includes on disk
OpenClaw stores agent-specific state separately. Even if you only run one agent today, it still helps to understand the layout because it makes debugging easier.
- Workspace holds files and per-agent skills in
<workspace>/skills/ - Agent directory holds auth profiles and per-agent config state
- Session store holds the chat history and routing state
Most of the time you only interact with the workspace. That’s where you tune SOUL.md and AGENTS.md and where you keep small helper files.
Single-agent mode and why it works for most people
In single-agent mode, OpenClaw defaults to a main agent and a default workspace. That is enough for a lot of setups. You can connect multiple channels to the same agent and it will behave consistently.
Before you build a “team” of agents, I’d recommend that you get one agent stable across your channels. If you run OpenClaw on WhatsApp, read OpenClaw WhatsApp production setup. If you use multiple channels, this helps a lot: OpenClaw multi-channel setup.
Create agents using the wizard
The agent wizard is the easiest path because it scaffolds the workspace and it creates a clean agent directory. It also reduces the risk of “two agents sharing a directory by accident” which can break auth and session history.
openclaw agents add work
openclaw agents add coding
openclaw agents add alertsThen list them:
openclaw agents list --bindingsThat --bindings flag is useful because routing bugs are usually binding bugs.
Manual agents config example
If you prefer writing config directly, a minimal example looks like this. Keep it boring and explicit. It will save you later.
agents: {
list: [
{
id: "main",
default: true,
name: "Personal Assistant",
workspace: "~/.openclaw/workspace",
},
{
id: "coding",
name: "Coding Agent",
workspace: "~/.openclaw/workspace-coding",
model: { primary: "anthropic/claude-sonnet-4-5" },
},
{
id: "alerts",
name: "Alerts",
workspace: "~/.openclaw/workspace-alerts",
model: { primary: "openai/gpt-5.2-mini" },
},
],
}After editing config, restart the gateway then run openclaw agents list --bindings again.
Bindings and routing messages to agents
Bindings are the deterministic routing rules that tell OpenClaw which agent should handle an incoming message. The binding match rules are strict and they usually follow a “most specific wins” concept, which is what you want.
The common binding fields you will care about:
- channel like whatsapp, telegram, discord, slack
- accountId which is useful when you run multiple bot accounts on the same channel type
- peer which targets a specific DM or group or channel
- guildId and roles for Discord routing if you want that complexity
The general rule that avoids surprises is: put the most specific bindings first. If you define “all WhatsApp goes to main” and you also define “this specific group goes to work” then put the group binding above the channel-wide binding.
WhatsApp with two accounts bound to two agents
This is a clean pattern if you have a personal number and a business number.
openclaw channels login --channel whatsapp --account personal
openclaw channels login --channel whatsapp --account bizagents: {
list: [
{ id: "home", default: true, name: "Home", workspace: "~/.openclaw/workspace-home" },
{ id: "work", name: "Work", workspace: "~/.openclaw/workspace-work" },
],
},
bindings: [
{ agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
{ agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
]If you want one special group on your personal account to route to work, add a peer binding above the channel-wide one.
WhatsApp with one number and multiple people split by DM
This is a surprisingly common household setup. You bind each DM peer ID to a separate agent so each person gets isolated memory.
agents: {
list: [
{ id: "alex", workspace: "~/.openclaw/workspace-alex" },
{ id: "mia", workspace: "~/.openclaw/workspace-mia" },
],
},
bindings: [
{ agentId: "alex", match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } } },
{ agentId: "mia", match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } } },
],
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15551230001", "+15551230002"],
},
}The allowlist is important. Without it you are basically running a public bot on a personal number. That gets weird fast.
Telegram with two bots and two agents
Telegram is a good fit for a split between “chat” and “alerts” because bot tokens are cheap to manage and the routing is simple.
channels: {
telegram: {
accounts: {
default: { botToken: "123456:ABC...", dmPolicy: "pairing" },
alerts: { botToken: "987654:XYZ...", dmPolicy: "allowlist", allowFrom: ["tg:123456789"] },
},
},
},
bindings: [
{ agentId: "main", match: { channel: "telegram", accountId: "default" } },
{ agentId: "alerts", match: { channel: "telegram", accountId: "alerts" } },
]If you need help setting up Telegram itself, these two are useful together: connect OpenClaw to Telegram BotFather and BotFather commands for OpenClaw.
Discord with separate bot accounts per agent
Discord multi-agent usually means multiple bot tokens. It’s cleaner than trying to route everything inside one bot because you get separation at the channel account level.
If you want the Discord channel basics, this guide is a good starting point: connect OpenClaw to Discord.
Conceptually the config looks like this:
agents: {
list: [
{ id: "main", workspace: "~/.openclaw/workspace-main" },
{ id: "coding", workspace: "~/.openclaw/workspace-coding" },
],
},
bindings: [
{ agentId: "main", match: { channel: "discord", accountId: "default" } },
{ agentId: "coding", match: { channel: "discord", accountId: "coding" } },
],
channels: {
discord: {
accounts: {
default: { token: "DISCORD_BOT_TOKEN_MAIN" },
coding: { token: "DISCORD_BOT_TOKEN_CODING" },
},
},
}Then you scope allowed guilds and channels per bot account. That way your coding bot only sees coding rooms. It is a simple security win.
Slack as a “work agent” boundary
Slack is a natural place to bind a work-only agent because you can keep it professional, keep its memory strictly work-related and lock down its tools. If you haven’t connected Slack before, use OpenClaw Slack integration.
Per-agent tools and sandbox settings
Per-agent tool restrictions are the feature that makes multi-agent worth it for a lot of people. It lets you say “this agent can read and summarize” and “this agent can run commands” without mixing them.
Per-agent config usually looks like this:
agents: {
list: [
{
id: "personal",
workspace: "~/.openclaw/workspace-personal",
sandbox: { mode: "off" },
},
{
id: "family",
name: "Family Bot",
workspace: "~/.openclaw/workspace-family",
sandbox: {
mode: "all",
scope: "agent",
docker: {
setupCommand: "apt-get update && apt-get install -y git curl",
},
},
tools: {
allow: ["read", "exec"],
deny: ["write", "edit", "apply_patch", "browser", "cron"],
},
},
],
}Three practical notes:
- deny wins. If a tool is both allowed and denied, denied wins. This is what you want.
- Docker sandboxing can make tool execution safer, but it can also be annoying if you forgot to mount a directory or install a binary inside the container.
- If an agent is public-facing, default to fewer tools. Add tools only when you can explain why the agent needs them.
Agent-to-agent communication
Persistent agents can talk to each other if you enable agent-to-agent tools. This is not “multi-agent” by default. It’s opt-in. That’s a good design choice because otherwise agents can become accidental data bridges.
When enabled, the main building blocks are sessions_send for ping-pong communication and allow lists so you restrict which agent IDs can be targeted. A community discussion on agent messaging mentions that agent-to-agent is capped to a small number of turns by default and it is controlled by allow lists. community discussion on multi-agent messaging.
Example:
tools: {
agentToAgent: {
enabled: true,
allow: ["home", "work", "coding"],
},
}My advice here is simple. Enable this only when you have a clear workflow that needs it. For most setups, sub-agents are enough.
Sub-agents and parallel work
Sub-agents are background runs spawned from a persistent agent. They run in an isolated session and post their result back when done. That behavior is documented in the session tools page for sessions_spawn. OpenClaw session tools.
OpenClaw also documents the user-facing command for this as /subagents spawn and it clarifies that it starts a background sub-agent and it sends a final completion update back to the requester. OpenClaw sub-agents.
Use cases that fit sub-agents
- parallel research for a report
- log analysis while you keep chatting
- batch file processing that would spam the main session
- running slow web lookups on a separate model
One thing I like about sub-agents is that they keep your main session clean. If a sub-agent produces noise, that noise stays inside its own transcript.
Spawn a sub-agent from chat
This is the “manual” version. It is useful when you want to direct work to a specialist.
/subagents spawn main "Summarize the last 7 days of changelog entries and propose release notes"If your sub-agent command supports model overrides in your environment, you can set a cheaper model for the run. The session tools docs list model and related parameters for sessions_spawn. OpenClaw session tools.
Spawn a sub-agent automatically using sessions_spawn
This is how the orchestrator pattern works. The agent decides to spawn workers. In config and tooling this is represented by the sessions_spawn tool. The docs describe it as spawning a sub-agent run in an isolated session and announcing back to the requester channel. OpenClaw session tools.
Conceptually it looks like this:
sessions_spawn({
task: "Analyze disk usage logs and find anomalies for the past 24 hours",
label: "Disk analysis",
model: "anthropic/claude-sonnet-4-5",
thinking: "medium",
runTimeoutSeconds: 300
})If you are doing this in production, set timeouts. A runaway sub-agent that loops on tool calls is both annoying and expensive.
Sub-agent context rules that surprise people
Sub-agents do not always inherit everything you expect. In many setups they get a smaller context set than the main agent. Practically that means: if you rely on personality rules or long preference files, you should either put the essentials into AGENTS.md or include them in the sub-agent task prompt.
This is also why I like having an orchestrator agent whose job is “break down tasks and spawn workers” and it keeps a short set of instructions about what workers need in AGENTS.md. It becomes predictable.
Nesting and the orchestrator pattern
Some users want pipelines like main → writer → checker → rewriter. The common surprise is that sub-agents cannot always spawn other sub-agents by default. A recent community thread describes this exact limitation and why it happens. multi agent spawn challenges discussion.
OpenClaw can support limited nesting when configured. If you enable a max depth of 2 you can have a depth-1 orchestrator that spawns depth-2 workers. Going deeper than that usually increases complexity without making results better.
A common defaults block looks like this:
agents: {
defaults: {
subagents: {
maxSpawnDepth: 2,
maxChildrenPerAgent: 5,
maxConcurrent: 8,
},
},
}Keep concurrency conservative at first. It is easy to create a bottleneck on your gateway CPU, your local model runtime or your provider rate limits.
Cost control with multi-agent
If you run a premium model as your main agent and you spawn cheaper workers, costs drop fast. The main agent does planning and synthesis. Workers do parallel grunt work.
A basic pattern:
agents: {
defaults: {
subagents: {
model: "anthropic/claude-sonnet-4-5",
thinking: "low",
},
},
list: [
{
id: "main",
model: { primary: "anthropic/claude-opus-4-6" },
},
],
}If you run local models, sub-agents can run on Ollama while the main agent stays on a cloud model for the tough reasoning. We already covered local model setup in a separate guide so I won’t repeat it here.
Great architecture patterns (in my opinion)
Domain specialists with channel routing
Each agent owns a domain and you route messages by channel or account. This is the easiest to reason about because you can point at a message and explain why it routed where it did.
agents: {
list: [
{ id: "main", default: true, workspace: "~/.openclaw/workspace" },
{ id: "coding", workspace: "~/.openclaw/workspace-coding" },
{ id: "writing", workspace: "~/.openclaw/workspace-writing" },
],
},
bindings: [
{ agentId: "coding", match: { channel: "discord", accountId: "coding-bot" } },
{ agentId: "writing", match: { channel: "telegram", accountId: "writer-bot" } },
{ agentId: "main", match: { channel: "whatsapp" } },
]Premium orchestrator with cheap workers
One agent talks to you. It spawns sub-agents to do parallel work. This is the pattern people end up with when they want speed and they also want cost control.
It is also the pattern where you need to think about boundaries. If the orchestrator can spawn workers with broader tools than it has, you can create accidental privilege escalation. The Cloud Security Alliance recently published a threat model discussion that includes risks around multi-agent collusion and tool boundaries. OpenClaw threat model analysis.
You don’t need to panic about that. You do need to design your tool policies carefully.
Direct agent calls without an orchestrator
This is a “boring but good” option. Route each channel to a specialist agent and do not let agents message each other. If you ever need another agent, you message it by switching channel or bot account.
It is slower for complex jobs but it is very easy to debug.
Thread-bound sessions on Discord
Discord threads are a nice fit for long-running work because you can bind a sub-agent run to a thread and keep follow-ups inside that thread. It stops a busy server channel from becoming a wall of logs.
This depends on Discord thread binding settings and it also depends on your channel configuration. If you run Discord heavily, it’s worth setting up properly early.
Common failure modes and fixes
Messages route to the wrong agent
This is almost always a binding specificity issue. List agents with bindings, then reorder bindings so the most specific peer rules come before broad channel rules.
openclaw agents list --bindingsTwo agents share auth or session state
This happens when people copy agent directories around manually. Don’t reuse agent state directories. Use the wizard or create distinct workspaces and let OpenClaw create separate agent directories.
Sub-agent results never show up
Sub-agents announce results back to the requester. If announce is skipped or delivery fails you will see missing results. The sub-agents docs describe that a sub-agent sends a final completion update back to the requester chat. OpenClaw sub-agents.
If delivery is flaky, check:
- the channel connection
- rate limits
- session timeouts
- any tool denies applied to sub-agents
Sub-agents try to use session tools and fail
This can be a version mismatch or a tool binding limitation. There is an open issue discussing cases where sub-agents see session tool names in prompt text but they are not actually bound for tool use. GitHub issue on sub-agents and session tools.
If you hit this, upgrade OpenClaw first. If it persists, avoid designing sub-agents that require session introspection and keep them as one-shot workers.
Security notes for multi-agent deployments
Multi-agent makes isolation easier but it also increases surface area. You have more bot tokens, more skills, more auth profiles. The usual “review third-party skills” advice still applies and it matters more here because you can accidentally install a skill into a shared directory that becomes eligible for every agent.
Security reporting in early 2026 covered malicious skills in public registries and why reviewing SKILL.md and scripts is non-negotiable. One example is the OpenClaw skills malware reporting by Tom’s Hardware. Malicious skill reporting.
On the LumaDock side, we treat public-facing agents as untrusted surfaces. Lock down tools, lock down channels and keep an audit trail of what you enabled.
Practical setup checklist
- start with one agent and get your channels stable
- add a second agent only when you can explain the isolation need
- set bindings so peer rules are above channel-wide rules
- use per-agent tool deny lists for public-facing agents
- use sub-agents for parallel work instead of creating more persistent agents
- set a cheaper model for sub-agents if you care about spend
- keep max sub-agent nesting depth low
- run
openclaw agents list --bindingsafter every routing change
