Channel routing

Channels & routing

OpenClaw routes replies back to the channel where a message came from. The model does not choose a channel; routing is deterministic and controlled by the host configuration.

Key terms

• Channel:
  text

  Copy

  telegram
  ,
  text

  Copy

  whatsapp
  ,
  text

  Copy

  discord
  ,
  text

  Copy

  irc
  ,
  text

  Copy

  googlechat
  ,
  text

  Copy

  slack
  ,
  text

  Copy

  signal
  ,
  text

  Copy

  imessage
  ,
  text

  Copy

  line
  , plus plugin channels.
  text

  Copy

  webchat
  is the internal WebChat UI channel and is not a configurable outbound channel.
• AccountId: per‑channel account instance (when supported).
• Optional channel default account:
  text

  Copy

  channels.<channel>.defaultAccount
  chooses which account is used when an outbound path does not specify
  text

  Copy

  accountId
  .
  • In multi-account setups, set an explicit default (
    text

    Copy

    defaultAccount
    or
    text

    Copy

    accounts.default
    ) when two or more accounts are configured. Without it, fallback routing may pick the first normalized account ID.
• AgentId: an isolated workspace + session store (“brain”).
• SessionKey: the bucket key used to store context and control concurrency.

Session key shapes (examples)

Direct messages collapse to the agent’s main session by default:

• text

  Copy

  agent:<agentId>:<mainKey>
  (default:
  text

  Copy

  agent:main:main
  )

Even when direct-message conversation history is shared with main, sandbox and tool policy use a derived per-account direct-chat runtime key for external DMs so channel-originated messages are not treated like local main-session runs.

Groups and channels remain isolated per channel:

• Groups:
  text

  Copy

  agent:<agentId>:<channel>:group:<id>
• Channels/rooms:
  text

  Copy

  agent:<agentId>:<channel>:channel:<id>

Threads:

• Slack/Discord threads append
  text

  Copy

  :thread:<threadId>
  to the base key.
• Telegram forum topics embed
  text

  Copy

  :topic:<topicId>
  in the group key.

Examples:

• text

  Copy

  agent:main:telegram:group:-1001234567890:topic:42
• text

  Copy

  agent:main:discord:channel:123456:thread:987654

Main DM route pinning

When

is , direct messages may share one main session. To prevent the session’s from being overwritten by non-owner DMs, OpenClaw infers a pinned owner from when all of these are true:

• text

  Copy

  allowFrom
  has exactly one non-wildcard entry.
• The entry can be normalized to a concrete sender ID for that channel.
• The inbound DM sender does not match that pinned owner.

In that mismatch case, OpenClaw still records inbound session metadata, but it skips updating the main session

.

Guarded inbound recording

Channel plugins can mark an inbound session record as

when a guarded path must not create a new OpenClaw session. In that mode, OpenClaw may update metadata and for an existing session, but it does not create a route-only session entry just because a message was observed.

Routing rules (how an agent is chosen)

Routing picks one agent for each inbound message:

1. Exact peer match (
   text

   Copy

   bindings
   with
   text

   Copy

   peer.kind
   +
   text

   Copy

   peer.id
   ).
2. Parent peer match (thread inheritance).
3. Guild + roles match (Discord) via
   text

   Copy

   guildId
   +
   text

   Copy

   roles
   .
4. Guild match (Discord) via
   text

   Copy

   guildId
   .
5. Team match (Slack) via
   text

   Copy

   teamId
   .
6. Account match (
   text

   Copy

   accountId
   on the channel).
7. Channel match (any account on that channel,
   text

   Copy

   accountId: "*"
   ).
8. Default agent (
   text

   Copy

   agents.list[].default
   , else first list entry, fallback to
   text

   Copy

   main
   ).

When a binding includes multiple match fields (

, , , ), all provided fields must match for that binding to apply.

The matched agent determines which workspace and session store are used.

Broadcast groups (run multiple agents)

Broadcast groups let you run multiple agents for the same peer when OpenClaw would normally reply (for example: in WhatsApp groups, after mention/activation gating).

Config:

json5
Copy
{
  broadcast: {
    strategy: "parallel",
    "120363403215116621@g.us": ["alfred", "baerbel"],
    "+15555550123": ["support", "logger"],
  },
}

See: Broadcast Groups.

Config overview

• text

  Copy

  agents.list
  : named agent definitions (workspace, model, etc.).
• text

  Copy

  bindings
  : map inbound channels/accounts/peers to agents.

Example:

json5
Copy
{
  agents: {
    list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }],
  },
  bindings: [
    { match: { channel: "slack", teamId: "T123" }, agentId: "support" },
    { match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" },
  ],
}

Session storage

Session stores live under the state directory (default

):

• text

  Copy

  ~/.openclaw/agents/<agentId>/sessions/sessions.json
• JSONL transcripts live alongside the store

You can override the store path via

and templating.

Gateway and ACP session discovery also scans disk-backed agent stores under the default

root and under templated roots. Discovered stores must stay inside that resolved agent root and use a regular file. Symlinks and out-of-root paths are ignored.

WebChat behavior

WebChat attaches to the selected agent and defaults to the agent’s main session. Because of this, WebChat lets you see cross‑channel context for that agent in one place.

Reply context

Inbound replies include:

• text

  Copy

  ReplyToId
  ,
  text

  Copy

  ReplyToBody
  , and
  text

  Copy

  ReplyToSender
  when available.
• Quoted context is appended to
  text

  Copy

  Body
  as a
  text

  Copy

  [Replying to ...]
  block.

This is consistent across channels.

Related

• Groups
• Broadcast groups
• Pairing