Use this file to discover all available pages before exploring further.

Multi-agent routing

Run multiple isolated agents — each with its own workspace, state directory (

text

agentDir

), and session history — plus multiple channel accounts (e.g. two WhatsApps) in one running Gateway. Inbound messages are routed to the right agent through bindings.

An agent here is the full per-persona scope: workspace files, auth profiles, model registry, and session store.

text

agentDir

is the on-disk state directory that holds this per-agent config at

text

~/.openclaw/agents/<agentId>/

. A binding maps a channel account (e.g. a Slack workspace or a WhatsApp number) to one of those agents.

What is "one agent"?

An agent is a fully scoped brain with its own:

Workspace (files, AGENTS.md/SOUL.md/USER.md, local notes, persona rules).
State directory (
text
agentDir
) for auth profiles, model registry, and per-agent config.
Session store (chat history + routing state) under
text
~/.openclaw/agents/<agentId>/sessions
.

Auth profiles are per-agent. Each agent reads from its own:


text
~/.openclaw/agents/<agentId>/agent/auth-profiles.json

note

`sessions_history` is the safer cross-session recall path here too: it returns a bounded, sanitized view, not a raw transcript dump. Assistant recall strips thinking tags, `` scaffolding, plain-text tool-call XML payloads (including `...`, `...`, `...`, `...`, and truncated tool-call blocks), downgraded tool-call scaffolding, leaked ASCII/full-width model control tokens, and malformed MiniMax tool-call XML before redaction/truncation.

warning

Never reuse `agentDir` across agents (it causes auth/session collisions). Agents can read through to the default/main agent's auth profiles when they do not have a local profile, but OpenClaw does not clone OAuth refresh tokens into the secondary agent store. If you want an independent OAuth account, sign in from that agent; if you copy credentials manually, copy only portable static `api_key` or `token` profiles.

Skills are loaded from each agent workspace plus shared roots such as

text

~/.openclaw/skills

, then filtered by the effective agent skill allowlist when configured. Use

text

agents.defaults.skills

for a shared baseline and

text

agents.list[].skills

for per-agent replacement. See Skills: per-agent vs shared and Skills: agent skill allowlists.

The Gateway can host one agent (default) or many agents side-by-side.

note

**Workspace note:** each agent's workspace is the **default cwd**, not a hard sandbox. Relative paths resolve inside the workspace, but absolute paths can reach other host locations unless sandboxing is enabled. See [Sandboxing](/gateway/sandboxing).

Paths (quick map)

Config:
text
~/.openclaw/openclaw.json
(or
text
OPENCLAW_CONFIG_PATH
)
State dir:
text
~/.openclaw
(or
text
OPENCLAW_STATE_DIR
)
Workspace:
text
~/.openclaw/workspace
(or
text
~/.openclaw/workspace-<agentId>
)
Agent dir:
text
~/.openclaw/agents/<agentId>/agent
(or
text
agents.list[].agentDir
)
Sessions:
text
~/.openclaw/agents/<agentId>/sessions

Single-agent mode (default)

If you do nothing, OpenClaw runs a single agent:

text
agentId
defaults to
text
main
.
Sessions are keyed as
text
agent:main:<mainKey>
.
Workspace defaults to
text
~/.openclaw/workspace
(or
text
~/.openclaw/workspace-<profile>
when
text
OPENCLAW_PROFILE
is set).
State defaults to
text
~/.openclaw/agents/main/agent
.

Agent helper

Use the agent wizard to add a new isolated agent:


bash
openclaw agents add work

Then add

text

bindings

(or let the wizard do it) to route inbound messages.

Verify with:


bash
openclaw agents list --bindings

Quick start

Create each agent workspace

Use the wizard or create workspaces manually:


text
```bash}
openclaw agents add coding
openclaw agents add social
```

Each agent gets its own workspace with `SOUL.md`, `AGENTS.md`, and optional `USER.md`, plus a dedicated `agentDir` and session store under `~/.openclaw/agents/<agentId>`.

Create channel accounts

Create one account per agent on your preferred channels:


text
* Discord: one bot per agent, enable Message Content Intent, copy each token.
* Telegram: one bot per agent via BotFather, copy each token.
* WhatsApp: link each phone number per account.

```bash}
openclaw channels login --channel whatsapp --account work
```

See channel guides: [Discord](/channels/discord), [Telegram](/channels/telegram), [WhatsApp](/channels/whatsapp).

Add agents, accounts, and bindings

Add agents under `agents.list`, channel accounts under `channels..accounts`, and connect them with `bindings` (examples below).

Restart and verify

```bash} openclaw gateway restart openclaw agents list --bindings openclaw channels status --probe ```

Multiple agents = multiple people, multiple personalities

With multiple agents, each

text

agentId

becomes a fully isolated persona:

Different phone numbers/accounts (per channel
text
accountId
).
Different personalities (per-agent workspace files like
text
AGENTS.md
and
text
SOUL.md
).
Separate auth + sessions (no cross-talk unless explicitly enabled).

This lets multiple people share one Gateway server while keeping their AI "brains" and data isolated.

Cross-agent QMD memory search

If one agent should search another agent's QMD session transcripts, add extra collections under

text

agents.list[].memorySearch.qmd.extraCollections

. Use

text

agents.defaults.memorySearch.qmd.extraCollections

only when every agent should inherit the same shared transcript collections.


json5
{
  agents: {
    defaults: {
      workspace: "~/workspaces/main",
      memorySearch: {
        qmd: {
          extraCollections: [{ path: "~/agents/family/sessions", name: "family-sessions" }],
        },
      },
    },
    list: [
      {
        id: "main",
        workspace: "~/workspaces/main",
        memorySearch: {
          qmd: {
            extraCollections: [{ path: "notes" }], // resolves inside workspace -> collection named "notes-main"
          },
        },
      },
      { id: "family", workspace: "~/workspaces/family" },
    ],
  },
  memory: {
    backend: "qmd",
    qmd: { includeDefaultMemory: false },
  },
}

The extra collection path can be shared across agents, but the collection name stays explicit when the path is outside the agent workspace. Paths inside the workspace remain agent-scoped so each agent keeps its own transcript search set.

One WhatsApp number, multiple people (DM split)

You can route different WhatsApp DMs to different agents while staying on one WhatsApp account. Match on sender E.164 (like

text

+15551234567

) with

text

peer.kind: "direct"

. Replies still come from the same WhatsApp number (no per-agent sender identity).

note

Direct chats collapse to the agent's **main session key**, so true isolation requires **one agent per person**.

Example:


json5
{
  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"],
    },
  },
}

Notes:

DM access control is global per WhatsApp account (pairing/allowlist), not per agent.
For shared groups, bind the group to one agent or use Broadcast groups.

Routing rules (how messages pick an agent)

Bindings are deterministic and most-specific wins:

peer match

Exact DM/group/channel id.

parentPeer match

Thread inheritance.

guildId + roles

Discord role routing.

guildId

Discord.

teamId

Slack.

accountId match for a channel

Per-account fallback.

Channel-level match

`accountId: "*"`.

Default agent

Fallback to `agents.list[].default`, else first list entry, default: `main`.

Multiple accounts / phone numbers

Channels that support multiple accounts (e.g. WhatsApp) use

text

accountId

to identify each login. Each

text

accountId

can be routed to a different agent, so one server can host multiple phone numbers without mixing sessions.

If you want a channel-wide default account when

text

accountId

is omitted, set

text

channels.<channel>.defaultAccount

(optional). When unset, OpenClaw falls back to

text

default

if present, otherwise the first configured account id (sorted).

Common channels supporting this pattern include:

text
whatsapp
,
text
telegram
,
text
discord
,
text
slack
,
text
signal
,
text
imessage
text
irc
,
text
line
,
text
googlechat
,
text
mattermost
,
text
matrix
,
text
nextcloud-talk
text
bluebubbles
,
text
zalo
,
text
zalouser
,
text
nostr
,
text
feishu

Concepts

text
agentId
: one "brain" (workspace, per-agent auth, per-agent session store).
text
accountId
: one channel account instance (e.g. WhatsApp account
text
"personal"
vs
text
"biz"
).
text
binding
: routes inbound messages to an
text
agentId
by
text
(channel, accountId, peer)
and optionally guild/team ids.
Direct chats collapse to
text
agent:<agentId>:<mainKey>
(per-agent "main";
text
session.mainKey
).

Platform examples

Common patterns

Split by channel: route WhatsApp to a fast everyday agent and Telegram to an Opus agent.


text
```json5}
{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-6",
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.openclaw/workspace-opus",
        model: "anthropic/claude-opus-4-6",
      },
    ],
  },
  bindings: [
    { agentId: "chat", match: { channel: "whatsapp" } },
    { agentId: "opus", match: { channel: "telegram" } },
  ],
}
```

Notes:

* If you have multiple accounts for a channel, add `accountId` to the binding (for example `{ channel: "whatsapp", accountId: "personal" }`).
* To route a single DM/group to Opus while keeping the rest on chat, add a `match.peer` binding for that peer; peer matches always win over channel-wide rules.

Keep WhatsApp on the fast agent, but route one DM to Opus:


text
```json5}
{
  agents: {
    list: [
      {
        id: "chat",
        name: "Everyday",
        workspace: "~/.openclaw/workspace-chat",
        model: "anthropic/claude-sonnet-4-6",
      },
      {
        id: "opus",
        name: "Deep Work",
        workspace: "~/.openclaw/workspace-opus",
        model: "anthropic/claude-opus-4-6",
      },
    ],
  },
  bindings: [
    {
      agentId: "opus",
      match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551234567" } },
    },
    { agentId: "chat", match: { channel: "whatsapp" } },
  ],
}
```

Peer bindings always win, so keep them above the channel-wide rule.

Bind a dedicated family agent to a single WhatsApp group, with mention gating and a tighter tool policy:


text
```json5}
{
  agents: {
    list: [
      {
        id: "family",
        name: "Family",
        workspace: "~/.openclaw/workspace-family",
        identity: { name: "Family Bot" },
        groupChat: {
          mentionPatterns: ["@family", "@familybot", "@Family Bot"],
        },
        sandbox: {
          mode: "all",
          scope: "agent",
        },
        tools: {
          allow: [
            "exec",
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"],
        },
      },
    ],
  },
  bindings: [
    {
      agentId: "family",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "120363999999999999@g.us" },
      },
    },
  ],
}
```

Notes:

* Tool allow/deny lists are **tools**, not skills. If a skill needs to run a binary, ensure `exec` is allowed and the binary exists in the sandbox.
* For stricter gating, set `agents.list[].groupChat.mentionPatterns` and keep group allowlists enabled for the channel.

Per-agent sandbox and tool configuration

Each agent can have its own sandbox and tool restrictions:


js
{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: {
          mode: "off",  // No sandbox for personal agent
        },
        // No tool restrictions - all tools available
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: {
          mode: "all",     // Always sandboxed
          scope: "agent",  // One container per agent
          docker: {
            // Optional one-time setup after container creation
            setupCommand: "apt-get update && apt-get install -y git curl",
          },
        },
        tools: {
          allow: ["read"],                    // Only read tool
          deny: ["exec", "write", "edit", "apply_patch"],    // Deny others
        },
      },
    ],
  },
}

note

`setupCommand` lives under `sandbox.docker` and runs once on container creation. Per-agent `sandbox.docker.*` overrides are ignored when the resolved scope is `"shared"`.

Benefits:

Security isolation: restrict tools for untrusted agents.
Resource control: sandbox specific agents while keeping others on host.
Flexible policies: different permissions per agent.

note

`tools.elevated` is **global** and sender-based; it is not configurable per agent. If you need per-agent boundaries, use `agents.list[].tools` to deny `exec`. For group targeting, use `agents.list[].groupChat.mentionPatterns` so @mentions map cleanly to the intended agent.

See Multi-agent sandbox and tools for detailed examples.

ACP agents — running external coding harnesses
Channel routing — how messages route to agents
Presence — agent presence and availability
Session — session isolation and routing
Sub-agents — spawning background agent runs

OpenClaw Docs

Multi-agent routing

What is "one agent"?

note

warning

note

Paths (quick map)

Single-agent mode (default)

Agent helper

Quick start

Create each agent workspace

Create channel accounts

Add agents, accounts, and bindings

Restart and verify

Multiple agents = multiple people, multiple personalities

Cross-agent QMD memory search

One WhatsApp number, multiple people (DM split)

note

Routing rules (how messages pick an agent)

peer match

parentPeer match

guildId + roles

guildId

teamId

accountId match for a channel

Channel-level match

Default agent

Multiple accounts / phone numbers

Concepts

Platform examples

Common patterns

Per-agent sandbox and tool configuration

note

note

Related