OpenClaw multi-agent

A single assistant is easy. The moment a household, a team or a small company shares one gateway, the question becomes how to keep personas, files and histories apart without running separate servers. OpenClaw answers it by letting one gateway process host several isolated agents, each with its own workspace, state directory and SQLite-backed session history, alongside multiple channel accounts such as two WhatsApp numbers. Inbound messages find the right agent through bindings, which map a channel account to one of those agents. Where that isolation holds and where it deliberately does not is the whole point of the page.

What one agent owns

• An agent is the full per-persona scope, so its workspace holds files, the AGENTS.md, SOUL.md and USER.md instruction files, local notes and persona rules, while its state directory holds auth profiles, the model registry and per-agent configuration.
• Each agent keeps chat history and routing state in its own per-agent SQLite session file inside that state directory, and auth profiles are read from the same file.
• Reusing one state directory across agents causes auth and session state collisions, and when a secondary agent local OAuth credential is expired or its refresh fails, OpenClaw reads through to the default agent credential for the same profile id and adopts whichever token is freshest, without copying the refresh token into the secondary store.
• A workspace is the default working directory rather than a hard sandbox, so relative paths resolve inside it while absolute paths can reach other host locations unless sandboxing is enabled.

If multiple bindings match within the same tier, the first one in config order wins.

How routing decides

Bindings are deterministic and the most specific rule wins, with a full tier order running from exact peer through parent peer, peer wildcard, guild with roles, guild, team, account and channel, down to the default agent. Within one tier, config order breaks the tie. A binding that sets several match fields, for example a peer and a guild id, requires all of the specified fields to match. A binding that omits an account id matches only the default account rather than every account, so a channel-wide fallback needs an explicit wildcard account and a single account needs its name, and adding the same binding again with an explicit account id upgrades the existing channel-only binding instead of duplicating it. Channels that support multiple accounts use an account id to identify each login, and each account id routes to its own agent, which is how one server hosts several phone numbers without mixing sessions. When the account is omitted, a configured default account is used, falling back to an account named default when present and otherwise the first configured account id in sorted order. For existing multi-agent configs, the doctor repair command materialises legacy ambient default routing into channel-wide bindings plus explicit heartbeat, Custodian and Talk targets, leaving single-agent configs unchanged. It also adds an account-scoped binding when an account has no fallback route but its matchable narrower bindings all name one configured agent, and it refuses to borrow ownership from another account or channel or to choose between conflicting owners.

Where isolation stops

• Cross-agent session access is on by default and governed by the agent to agent tool setting, so session visibility can be narrowed, agent pairs can be restricted and ordinary cross-agent access can be blocked, while separate gateways remain the answer for strict separation.
• Plugin-owned storage follows that plugin configuration, so adding a second agent does not automatically split every global plugin store, and Memory Wiki for instance uses one global vault until its vault scope is set to agent.
• The cross-agent memory search path was removed along with the rest of the QMD backend in v2026.8.1, so builtin memory does not search another agent transcript corpus and shared reference material belongs in an explicit shared extra search path.

Direct chats collapse to the agent main session key by default, so true isolation means one agent per person rather than one binding per person. See the agents command reference for creating and inspecting a roster from the command line, and session isolation and routing for isolation and routing at the session level.

Why bindings and not heuristics

The routing model is deliberately boring. Deterministic tiers with a documented order are easy to reason about at three in the morning, and they fail in predictable ways, which matters far more than cleverness when a message has been quietly answered by the wrong persona. The same preference for explicit state shows up in agent provenance, where OpenClaw records whether an agent was created by an operator, by the system agent or by a Claw install, retains the requesting agent id, and creates an agent-requested agent only after operator approval. It shows up again in the team preset, where a chief of staff discovers matching specialists, assigns bounded work, checks their artifacts and reports a coherent result, while specialists return artifacts and evidence without delegating further. Even the delegation preference is honest about its own limits, because it guides the coordinator to delegate suitable work and is prompt guidance rather than a scheduler. If you are designing a roster, read built-in memory search and agent workspaces and sandboxing before deciding how much these agents should share.

On Diali

On Diali each customer runs their own assistant, so the isolation question is settled at the boundary rather than inside a shared process. Channels are connected from the dashboard, the runtime configuration is generated from it and replaced at each release, and state lives on a persistent volume, with daily snapshots and one-click restore available through the Backups add-on (included on Max). See Hosted OpenClaw on Diali for what we host, and Diali security for how we treat that state.

• One gateway, several agents, each with its own workspace and session store.
• Bindings are deterministic: most specific wins, then config order.
• A workspace is a default working directory, not a hard sandbox.