Master OpenClaw Message Routing and Debouncing

Ever felt like your bot is drowning in a flood of messages? Dealing with duplicate pings, rapid-fire texts, or keeping track of who said what in a group chat can get messy fast. OpenClaw handles the heavy lifting of message management so you can focus on building the actual logic.

This guide explains how OpenClaw manages the journey of a message from the moment it hits the gateway until a reply is sent back to the user.

Message flow (high level)

At its core, OpenClaw follows a specific path to ensure messages are processed in order and routed to the right place. Here is the high-level flow:

Inbound message
  -> routing/bindings -> session key
  -> queue (if a run is active)
  -> agent run (streaming + tools)
  -> outbound replies (channel limits + chunking)

You can find the main “knobs” for this process in your configuration:

• messages.* handles prefixes, queueing, and how groups behave.
• agents.defaults.* manages block streaming and how chunks are handled.
• Channel overrides (like channels.whatsapp.* or channels.telegram.*) let you set specific caps or toggle streaming for individual platforms.

Check out the Configuration page for the full schema.

Inbound dedupe

Sometimes channels redeliver the same message after a connection drop. To prevent your agent from responding twice to the same prompt, OpenClaw uses a short-lived cache. This cache is keyed by the channel, account, peer, session, and message ID. If a duplicate delivery shows up, OpenClaw identifies it and ensures it doesn’t trigger another agent run.

Inbound debouncing

If a user sends four messages in quick succession, you probably don’t want four separate agent turns. OpenClaw can batch these into a single turn using messages.inbound. This debouncing happens per channel and conversation, using the most recent message for threading and IDs.

Here is how you configure it (using global defaults or per-channel overrides):

{
  messages: {
    inbound: {
      debounceMs: 2000,
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500,
      },
    },
  },
}

A few things to keep in mind:

• Debouncing only applies to text-only messages. Media and attachments are flushed immediately.
• Control commands bypass this delay so they stay responsive.

Sessions and devices

In OpenClaw, sessions belong to the gateway, not the individual clients.

• Direct chats are collapsed into the main session key for the agent.
• Groups and channels receive their own unique session keys.
• All session stores and transcripts are kept on the gateway host.

You can have multiple devices or channels mapping to the same session. However, history isn’t always fully synced back to every single client. It is usually best to use one primary device for long conversations so you don’t end up with divergent context. If you need the source of truth, the Control UI and TUI always show the full gateway-backed transcript.

For more, see Session management.

Inbound bodies and history context

OpenClaw makes a distinction between the prompt body and the command body to give the agent the best possible context:

• Body: This is the actual prompt text sent to the agent. It might include channel envelopes or history wrappers.
• CommandBody: This is the raw text from the user, used for parsing directives or commands.
• RawBody: This is a legacy alias for CommandBody that we keep for compatibility.

When a channel provides history, it uses a specific wrapper format:

• [Chat messages since your last reply - for context]
• [Current message - respond to this]

In group chats or channels, the current message body is prefixed with a sender label. This ensures that real-time messages and queued history messages look consistent to the agent.

History buffers are pending-only. They include group messages that didn’t trigger a run (like messages where the bot wasn’t mentioned) but exclude anything already saved in the session transcript.

Directive stripping only happens on the “current message” section to keep the history context intact. If a channel wraps history, it should set CommandBody to the original text while keeping Body as the combined prompt. You can configure these buffers via messages.groupChat.historyLimit or per-channel overrides.

Queueing and followups

If your agent is already busy with a run, new inbound messages don’t just disappear. They can be queued, steered into the current active run, or saved for a followup turn.

• You can configure this behavior via messages.queue and messages.queue.byChannel.
• Available modes include interrupt, steer, followup, and collect, along with backlog variants.

Check the Queueing documentation for the specifics.

Streaming, chunking, and batching

Block streaming allows the gateway to send partial replies as the model generates text. OpenClaw handles chunking to respect channel text limits while making sure it doesn’t break fenced code blocks.

Key settings you should know:

• agents.defaults.blockStreamingDefault (on|off, default off)
• agents.defaults.blockStreamingBreak (text_end|message_end)
• agents.defaults.blockStreamingChunk (minChars|maxChars|breakPreference)
• agents.defaults.blockStreamingCoalesce (batching based on idle time)
• agents.defaults.humanDelay (adds a natural pause between block replies)
• Channel overrides: Use *.blockStreaming and *.blockStreamingCoalesce. Note that non-Telegram channels usually need *.blockStreaming: true set explicitly.

See Streaming + chunking for more details.

Reasoning visibility and tokens

You can choose whether to show or hide the model’s internal reasoning process:

• Use /reasoning on|off|stream to control what is visible.
• Even if reasoning is hidden, those tokens still count toward your usage.
• On Telegram, reasoning can be streamed directly into the draft bubble.

Read more in Thinking + reasoning directives and Token use.

Prefixes, threading, and replies

Formatting for outbound messages is managed centrally in the messages config:

• You can set prefixes at the global level (messages.responsePrefix), the channel level, or even the specific account level.
• WhatsApp uses a specific channels.whatsapp.messagePrefix for inbound messages.
• Reply threading is handled via replyToMode and per-channel defaults.

See the Configuration Reference and individual channel docs for more.

Related

• Streaming — real-time message delivery
• Retry — message delivery retry behavior
• Queue — message processing queue
• Channels — messaging platform integrations

Next Steps

• Set up your first channel in the Channels section.
• Fine-tune your agent’s response style in Configuration.

Need help getting started? Try the AI Setup Assistant.