OpenClaw channel routing

Where does a reply go, and which brain writes it? In OpenClaw both answers are deterministic and owned by the host configuration: replies go back to the channel the message came from, the model does not choose a channel, and under the default DM scope direct messages from every channel converge on the agent’s main session. Here are the terms, the target-prefix rule, the session key shapes and scopes, the pinning and guarded-recording rules, the ordered routing that picks one agent, how broadcast groups sit on top, the config shape, storage, and what WebChat and reply context add.

Terms and targets

• A channel is a channel plugin such as Discord, Google Chat, iMessage, IRC, LINE, Signal, Slack, Telegram or WhatsApp, with WebChat as the internal UI channel that is not a configurable outbound channel; an account id is a per-channel account instance, and a channel default account picks which one is used when an outbound path names none, which multi-account setups should set explicitly rather than let fallback routing pick the first normalised id.
• An agent id is an isolated workspace plus session store, a brain; a session key is the bucket that stores context and controls concurrency.
• Explicit outbound targets may carry a provider prefix such as a Telegram prefix before an id; core treats it as a channel-selection hint only when the selected channel is last or unresolved and only when the loaded plugin advertises that prefix, and if a channel was already selected the prefix must match it, so a WhatsApp delivery to a Telegram-prefixed id fails before any plugin normalisation. Target-kind and service prefixes such as channel, user, room, thread, iMessage handle or SMS number stay inside the selected channel’s grammar and never select the provider.
• Session keys: direct messages collapse to the agent’s main key by default; a DM scope setting can keep DMs per peer, per channel and peer, or per account, channel and peer, and a route binding can override the scope for its matched peers. Even when DM history is shared with main, sandbox and tool policy use a derived per-account direct-chat runtime key for external DMs so channel messages are not treated like local main-session runs.

The model does not choose a channel; routing is deterministic and controlled by the host configuration.

Groups, pinning, the routing order

With the default per-group scope, groups and channels stay isolated per channel with group and channel keys, Slack and Discord threads append a thread suffix and Telegram forum topics embed a topic id; a main group scope routes all non-direct peers into the main session, globally or per binding, changing shared context only while mention gating and replies still use the originating room. When the DM scope is main, OpenClaw infers a pinned owner from the allow-from list when it has exactly one non-wildcard entry that normalises to a concrete sender id, and a DM from anyone else still records inbound metadata but does not overwrite the main session’s last route. Channel plugins can mark an inbound record as create-if-missing false so a guarded path updates an existing session without creating a route-only entry just because a message was observed. Ordinary routing then picks one agent in order: exact peer match, parent peer match for thread inheritance, peer wildcard, Discord guild plus roles, Discord guild, Slack team, account match, channel match with any account, and finally a fallback owner supplied by the caller or the sole configured agent; multiple agents without an owner require a matching binding, and routing never picks the first roster entry. A binding with several match fields applies only when all of them match, and the matched agent determines the workspace and session store.

Broadcast, config, storage

• Agent group threads use the top-level broadcast config to run several agents on one admitted message, with a qualified channel-and-peer key taking precedence over an unqualified WhatsApp key; ordinary routing still provides the conversation route, the coordinator gives each participant its own session, qualified entries default to explicit mention selection with one round and one turn per agent, channel allowlists still apply, and configured ACP bindings remain exclusive and bypass fan-out.
• The config has two parts: named agent definitions under the agent entries, and bindings that map channels, accounts and peers to agents, optionally with a session scope override; the docs’ example binds a Slack team and a specific Slack channel to a support agent, the latter with the main group scope.
• Runtime session rows and transcripts live in each agent’s SQLite database under the state directory; older installs with JSONL transcripts and a JSON session store must stop the Gateway, back up and run the doctor fix before restarting, because startup does not import legacy files and refuses readiness when it finds one. The store path supports agent-id templating, discovered store files must be regular files inside the resolved agent root, and ACP session discovery reads SQLite metadata and joins it to session entries.

OpenClaw sessions explains the keys these shapes are built from, and OpenClaw multi-user setups the setups where scopes and pinning decide who shares what.

WebChat and reply context

WebChat attaches to the selected agent and defaults to its main session, which is why it shows cross-channel context for that agent in one place. Inbound replies include the replied-to id, body and sender when available, and quoted context is appended to the body as a replying-to block, consistently across channels. OpenClaw broadcast groups covers the fan-out that layers on top of this routing, and OpenClaw doctor the migration that moves legacy session files into SQLite.

On Diali

On Diali the same rule holds: a message on WhatsApp is answered on WhatsApp, a Telegram thread on Telegram, and the dashboard chat is the WebChat view of the assistant’s main session. Hosted OpenClaw on Diali is the assistant and Connect your first channel in five minutes how the channels that feed this routing are linked.

• Replies return to their channel; the model never picks one.
• Nine ordered matches choose one agent.
• Prefixes are hints, never a way to hop providers.