skip to content

Multi-Agent Routing

One Gateway can host several isolated agents, each with its own workspace and state, and bindings decide which one answers a message. Interviewers ask how routing rules are matched.

part ofAI coding toolsread it →
on this pageshow

explore

questions

5

In OpenClaw, how do you route a work Slack account to one agent and a family WhatsApp number to another?

level: middleimportance: must knowfreq 12%

answer

  1. two agents, two channel accounts
  2. agentId plus a match object
  3. channel required, accountId optional
  4. omitted accountId means default only
  5. verify with agents list --bindings

basics

~10 s

Define both agents under agents.entries, log in a Slack account and a WhatsApp account, then add bindings whose match names the channel and accountId for each. Verify with openclaw agents list --bindings.

solid answer

~40 s

Give each persona its own agent under `agents.entries` (for example `coding` and `home`, each with its own workspace), make sure each channel account exists under `channels.<channel>.accounts`, then add one entry per route to the top-level `bindings` array: `agentId` plus a `match` with `channel` and `accountId`. Every binding needs `agentId` and `match.channel`; leaving out `accountId` matches only that channel's default account, while `"*"` matches all of them. Bindings only choose an agent for messages the channel has already admitted, so pairing and allowlists stay separate. Binding edits apply under the default `hybrid` reload mode. Check the result with `openclaw agents list --bindings` and `openclaw channels status --probe`.

code

json · 13 lines
json
{
  "agents": {
    "ownership": "explicit",
    "entries": {
      "coding": { "workspace": "~/.openclaw/workspace-coding" },
      "home": { "workspace": "~/.openclaw/workspace-home" }
    }
  },
  "bindings": [
    { "agentId": "coding", "match": { "channel": "slack", "accountId": "work" } },
    { "agentId": "home", "match": { "channel": "whatsapp", "accountId": "family" } }
  ]
}

go deeper

for a junior

Recall the two halves: agents under agents.entries and bindings that map a channel and account to an agentId.

for a middle

Explain each match field, the accountId default-only rule versus the star wildcard, and the AND semantics when a binding sets several fields.

for a senior

Diagnose a binding that never fires: wrong or missing accountId, an account the channel never admitted, or an unbound channel ending in AGENT_SELECTION_REQUIRED.

for a principal

Argue for account-scoped bindings plus an explicit channel-wide fallback as the team convention, so adding a login later never silently changes who answers.

## The goal One household server runs one OpenClaw Gateway. The owner wants their work Slack answered by a terse coding agent and the family's WhatsApp number answered by a friendly home agent, with no mixing of persona, history or credentials. OpenClaw expresses this as **agents** (who answers) plus **bindings** (which inbound traffic goes to whom). ## Step 1: define the agents Agents live in `~/.openclaw/openclaw.json` under the keyed roster `agents.entries`. Each key is the agent id; each entry can set its own `workspace`, `agentDir`, `model`, `identity`, tools and sandbox. Two practical routes: - **CLI:** `openclaw agents add coding --workspace ~/.openclaw/workspace-coding --bind slack:work` creates the agent and its binding in one step. `--bind` takes `<channel[:accountId]>` and can be repeated. - **Config:** write the entries yourself, as in the example below. In 2026.9.9 a roster with more than one agent must declare how ownership works: either `agents.ownership: "explicit"` or exactly one legacy `default: true` marker on an entry. Config validation rejects a multi-agent roster with neither, and rejects the two together. Older configs used an `agents.list` array; `openclaw doctor --fix` migrates it to the keyed `agents.entries`. ## Step 2: make sure the channel accounts exist A binding points at an account the channel already knows. Channels that support several logins, Slack and WhatsApp among them, keep them under `channels.<channel>.accounts.<accountId>`. A binding aimed at an account the channel never accepts does nothing. Logging the accounts in is a channel task, outside this question. ## Step 3: write the bindings Each entry in the top-level `bindings` array has: | Field | Required | Meaning | |---|---|---| | `agentId` | yes | an id from `agents.entries` | | `match.channel` | yes | `slack`, `whatsapp`, `telegram`, and so on | | `match.accountId` | no | one account id; omitted means the channel's default account only; `"*"` means every account | | `match.peer` | no | `{ kind, id }` with kind `direct`, `group` or `channel`, for one conversation | | `match.guildId` / `teamId` / `roles` | no | Discord guild and roles, Slack team | | `session.dmScope` / `session.groupScope` | no | session-scope override for matched conversations | When one binding sets several match fields, **all** of them must match. ## The accountId trap The most common mistake is omitting `accountId` and expecting the binding to cover every account on that channel. It does not: - omitted or blank `accountId` matches only the literal `default` account key; - `accountId: "*"` is the explicit channel-wide fallback; - `accountId: "work"` matches that one account and is more specific than `"*"`. If the family WhatsApp login is named `family`, a binding of just `{ channel: "whatsapp" }` never fires for it. ## Bindings are not access control A binding is consulted only after the channel has admitted the message through pairing, `dmPolicy`, group policy and allowlists. It decides who answers, never who may talk. Configure access on the channel account separately. ## Doing the same from the CLI 1. `openclaw agents add coding --workspace ~/.openclaw/workspace-coding --bind slack:work` creates the agent with an account-scoped binding. 2. `openclaw agents add home --workspace ~/.openclaw/workspace-home --bind whatsapp:family` does the same for the family number. 3. `openclaw agents bind --agent home --bind whatsapp:*` would add a channel-wide WhatsApp fallback to the home agent, still outranked by account-specific bindings; `openclaw agents unbind --agent home --bind whatsapp:family` removes one route. Two CLI details differ from hand-written config. `--bind <channel>` without an account lets the CLI resolve the account from plugin setup hooks or the channel's configured account count, whereas a stored binding with no `accountId` always means the `default` account. And binding the same agent again with an explicit account upgrades its existing channel-only binding in place instead of adding a duplicate. ## Step 4: apply and verify 1. Save the config. Binding changes apply automatically under the default `hybrid` reload mode; with `gateway.reload.mode` set to `off`, run `openclaw gateway restart`. 2. Run `openclaw agents list --bindings` to see every agent with its full routing rules. 3. Run `openclaw channels status --probe` to confirm each account is live. 4. Send a test message on each account and confirm the right persona answers. If some other channel, say Telegram, has no binding at all, an explicit multi-agent roster has no owner for it. Routing then falls back only to an owner it can resolve, such as the sole configured agent or a legacy `default: true` marker, and otherwise reports `AGENT_SELECTION_REQUIRED` and asks you to add a binding.

  • The family WhatsApp login is named `family`, and the binding is `{ "channel": "whatsapp" }` with no accountId. Why does the home agent never answer?
    A binding without `accountId` matches only the channel's literal `default` account, not every account. Messages on `family` skip it and fall through to whatever owner routing can resolve. Set `accountId: "family"`, or `"*"` for every WhatsApp account. With the CLI, `openclaw agents bind --agent home --bind whatsapp:family` adds the scoped binding.
  • Can a binding stop a stranger from messaging the coding agent on Slack?
    No. Bindings choose an agent for messages the channel has already admitted. Whether a sender gets in is decided by the channel account's pairing, `dmPolicy`, group policy and allowlists, which apply before routing and are configured separately from bindings.
  • Do binding edits in `openclaw.json` need a Gateway restart?
    Not under the default `hybrid` reload mode, where valid binding changes apply automatically. If `gateway.reload.mode` is `off`, restart with `openclaw gateway restart`. Either way, confirm the effective routing with `openclaw agents list --bindings`.

  • A binding without accountId covers every account on that channel.
  • Bindings decide who may message the bot, so no DM policy is needed.
  • The model reads the message and picks which agent should answer.
  • Agents are routed by naming the channel inside each agent's SOUL.md.
  • Every binding change requires a full Gateway restart to take effect.

Assumes OpenClaw 2026.9.9: the roster is the keyed agents.entries with agents.ownership set to explicit or one legacy default marker; older configs used an agents.list array that doctor migrates.

open as a page

In OpenClaw, what does each agent on a multi-agent Gateway own separately, and what does it still share?

level: juniorimportance: should knowfreq 11%

basics

~20 s

Each OpenClaw agent owns a workspace (AGENTS.md, SOUL.md, notes), an agentDir with its auth profiles and model registry, and its own session store. It still shares the Gateway process, channel access policy and, by default, session-tool reach.

open as a page

Two OpenClaw bindings cover one WhatsApp group: a channel-wide rule listed first, a rule for that group listed second — which agent answers, and why?

level: seniorimportance: should knowfreq 7%

basics

~20 s

The agent bound to that group answers, provided that binding covers the message's account. OpenClaw ranks bindings by specificity tier, with exact peer matches above account and channel-wide matches; config order only breaks ties inside one tier.

open as a page

When should you add another agent to one OpenClaw Gateway rather than run a separate Gateway, and what decides it?

level: principalimportance: should knowfreq 6%

basics

~20 s

Add an agent when everyone involved trusts each other and only persona, credentials and history need separating. Run a separate Gateway, ideally under another OS user or host, when people must not reach each other's tools, files or sessions.

open as a page

In OpenClaw, why can't a per-agent `tools.allow` bring back a tool that the global `tools.deny` removes?

level: seniorimportance: nice to knowfreq 5%

basics

~10 s

OpenClaw filters tools through a chain (profile, global allow/deny, provider, per-agent, sandbox, subagent) where each layer can only narrow the set. A per-agent allow cannot re-grant a globally denied tool; deny always wins.

open as a page