Messages

OpenClaw handles inbound messages through a pipeline of session resolution, queueing, streaming, tool execution, and reasoning visibility. This page maps the path from inbound message to reply.

Message flow (high level)

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

Key knobs live in configuration:

• text

  Copy

  messages.*
  for prefixes, queueing, and group behavior.
• text

  Copy

  agents.defaults.*
  for block streaming and chunking defaults.
• Channel overrides (
  text

  Copy

  channels.whatsapp.*
  ,
  text

  Copy

  channels.telegram.*
  , etc.) for caps and streaming toggles.

See Configuration for full schema.

Inbound dedupe

Channels can redeliver the same message after reconnects. OpenClaw keeps a short-lived cache keyed by channel/account/peer/session/message id so duplicate deliveries do not trigger another agent run.

Inbound debouncing

Rapid consecutive messages from the same sender can be batched into a single agent turn via

. Debouncing is scoped per channel + conversation and uses the most recent message for reply threading/IDs.

Config (global default + per-channel overrides):

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

Notes:

• Debounce applies to text-only messages; media/attachments flush immediately.
• Control commands bypass debouncing so they remain standalone — except when a channel explicitly opts in to same-sender DM coalescing (e.g. BlueBubbles
  text

  Copy

  coalesceSameSenderDms
  ), where DM commands wait inside the debounce window so a split-send payload can join the same agent turn.

Sessions and devices

Sessions are owned by the gateway, not by clients.

• Direct chats collapse into the agent main session key.
• Groups/channels get their own session keys.
• The session store and transcripts live on the gateway host.

Multiple devices/channels can map to the same session, but history is not fully synced back to every client. Recommendation: use one primary device for long conversations to avoid divergent context. The Control UI and TUI always show the gateway-backed session transcript, so they are the source of truth.

Details: Session management.

Tool result metadata

Tool result

is the model-visible result. Tool result is runtime metadata for UI rendering, diagnostics, media delivery, and plugins.

OpenClaw keeps that boundary explicit:

• text

  Copy

  toolResult.details
  is stripped before provider replay and compaction input.
• Persisted session transcripts keep only bounded
  text

  Copy

  details
  ; oversized metadata is replaced with a compact summary marked
  text

  Copy

  persistedDetailsTruncated: true
  .
• Plugins and tools should put text the model must read in
  text

  Copy

  content
  , not only in
  text

  Copy

  details
  .

Inbound bodies and history context

OpenClaw separates the prompt body from the command body:

• text

  Copy

  BodyForAgent
  : primary model-facing text for the current message. Channel plugins should keep this focused on the sender's current prompt-bearing text.
• text

  Copy

  Body
  : legacy prompt fallback. This may include channel envelopes and optional history wrappers, but current channels should not rely on it as the primary model input when
  text

  Copy

  BodyForAgent
  is available.
• text

  Copy

  CommandBody
  : raw user text for directive/command parsing.
• text

  Copy

  RawBody
  : legacy alias for
  text

  Copy

  CommandBody
  (kept for compatibility).

When a channel supplies history, it uses a shared wrapper:

• text

  Copy

  [Chat messages since your last reply - for context]
• text

  Copy

  [Current message - respond to this]

For non-direct chats (groups/channels/rooms), the current message body is prefixed with the sender label (same style used for history entries). This keeps real-time and queued/history messages consistent in the agent prompt.

History buffers are pending-only: they include group messages that did not trigger a run (for example, mention-gated messages) and exclude messages already in the session transcript.

Directive stripping only applies to the current message section so history remains intact. Channels that wrap history should set

(or ) to the original message text and keep as the combined prompt. Structured history, reply, forwarded, and channel metadata are rendered as user-role untrusted context blocks during prompt assembly. History buffers are configurable via (global default) and per-channel overrides like or (set to disable).

Queueing and followups

If a run is already active, inbound messages can be queued, steered into the current run, or collected for a followup turn.

• Configure via
  text

  Copy

  messages.queue
  (and
  text

  Copy

  messages.queue.byChannel
  ).
• Default mode is
  text

  Copy

  steer
  , with a 500ms followup debounce when steering falls back to queued followup delivery.
• Modes:
  text

  Copy

  steer
  ,
  text

  Copy

  followup
  ,
  text

  Copy

  collect
  ,
  text

  Copy

  steer-backlog
  ,
  text

  Copy

  interrupt
  , and the legacy one-at-a-time
  text

  Copy

  queue
  mode.

Details: Command queue and Steering queue.

Channel run ownership

Channel plugins may preserve ordering, debounce input, and apply transport backpressure before a message enters the session queue. They should not impose a separate timeout around the agent turn itself. Once a message is routed to a session, long-running work is governed by the session, tool, and runtime lifecycle so all channels report and recover from slow turns consistently.

Streaming, chunking, and batching

Block streaming sends partial replies as the model produces text blocks. Chunking respects channel text limits and avoids splitting fenced code.

Key settings:

• text

  Copy

  agents.defaults.blockStreamingDefault
  (
  text

  Copy

  on|off
  , default off)
• text

  Copy

  agents.defaults.blockStreamingBreak
  (
  text

  Copy

  text_end|message_end
  )
• text

  Copy

  agents.defaults.blockStreamingChunk
  (
  text

  Copy

  minChars|maxChars|breakPreference
  )
• text

  Copy

  agents.defaults.blockStreamingCoalesce
  (idle-based batching)
• text

  Copy

  agents.defaults.humanDelay
  (human-like pause between block replies)
• Channel overrides:
  text

  Copy

  *.blockStreaming
  and
  text

  Copy

  *.blockStreamingCoalesce
  (non-Telegram channels require explicit
  text

  Copy

  *.blockStreaming: true
  )

Details: Streaming + chunking.

Reasoning visibility and tokens

OpenClaw can expose or hide model reasoning:

• text

  Copy

  /reasoning on|off|stream
  controls visibility.
• Reasoning content still counts toward token usage when produced by the model.
• Telegram supports reasoning stream into the draft bubble.

Details: Thinking + reasoning directives and Token use.

Prefixes, threading, and replies

Outbound message formatting is centralized in

:

• text

  Copy

  messages.responsePrefix
  ,
  text

  Copy

  channels.<channel>.responsePrefix
  , and
  text

  Copy

  channels.<channel>.accounts.<id>.responsePrefix
  (outbound prefix cascade), plus
  text

  Copy

  channels.whatsapp.messagePrefix
  (WhatsApp inbound prefix)
• Reply threading via
  text

  Copy

  replyToMode
  and per-channel defaults

Details: Configuration and channel docs.

Silent replies

The exact silent token

/ means “do not deliver a user-visible reply”. When a turn also has pending tool media, such as generated TTS audio, OpenClaw strips the silent text but still delivers the media attachment. OpenClaw resolves that behavior by conversation type:

• Direct conversations disallow silence by default and rewrite a bare silent reply to a short visible fallback.
• Groups/channels allow silence by default.
• Internal orchestration allows silence by default.

OpenClaw also uses silent replies for internal runner failures that happen before any assistant reply in non-direct chats, so groups/channels do not see gateway error boilerplate. Direct chats show compact failure copy by default; raw runner details are shown only when

is or .

Defaults live under

and ; and can override them per surface.

When the parent session has one or more pending spawned subagent runs, bare silent replies are dropped on all surfaces instead of being rewritten, so the parent stays quiet until the child completion event delivers the real reply.

Related

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