In OpenClaw, how do you route a work Slack account to one agent and a family WhatsApp number to another?
answer
- two agents, two channel accounts
- agentId plus a match object
- channel required, accountId optional
- omitted accountId means default only
- verify with agents list --bindings
basics
~10 sDefine 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 sGive 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{
"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
Recall the two halves: agents under agents.entries and bindings that map a channel and account to an agentId.
Explain each match field, the accountId default-only rule versus the star wildcard, and the AND semantics when a binding sets several fields.
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.
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.