Messages

This page ties together how OpenClaw handles inbound messages, sessions, queueing, streaming, und reasoning visibility.

Message flow (high level)

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:

• messages.* for prefixes, queueing, und group behavior.
• agents.defaults.* for block streaming und chunking defaults.
• Channel overrides (channels.whatsapp.*, channels.telegram.*, etc.) for caps und streaming toggles.

Siehe 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 messages.inbound. Debouncing is scoped per channel + conversation and uses the most recent message for reply threading/IDs.Config (global default + per-channel overrides):

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

Hinweise:

• Debounce applies to text-only messages; media/attachments flush immediately.
• Control commands bypass debouncing so they remain standalone.

Sitzungen und 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 und 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 und TUI always show the gateway-backed session transcript, so they are the Quelle der Wahrheit.Details: Sitzungsverwaltung.

Inbound bodies und history context

OpenClaw separates the prompt body from the command body:

• Body: prompt text sent to the agent. This may include channel envelopes and optional history wrappers.
• CommandBody: raw user text for directive/command parsing.
• RawBody: legacy alias for CommandBody (kept for compatibility).

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

• [Chat messages since your last reply - for context]
• [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 und 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) und 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 CommandBody (or RawBody) to the original message text und keep Body as the combined prompt. History buffers are configurable via messages.groupChat.historyLimit (global default) und per-channel overrides like channels.slack.historyLimit or channels.telegram.accounts.<id>.historyLimit (set 0 to disable).

Queueing und 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 messages.queue (and messages.queue.byChannel).
• Modes: interrupt, steer, followup, collect, plus backlog variants.

Details: Queueing.

Streaming, chunking, und batching

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

• agents.defaults.blockStreamingDefault (on|off, default off)
• agents.defaults.blockStreamingBreak (text_end|message_end)
• agents.defaults.blockStreamingChunk (minChars|maxChars|breakPreference)
• agents.defaults.blockStreamingCoalesce (idle-based batching)
• agents.defaults.humanDelay (human-like pause between block replies)
• Channel overrides: *.blockStreaming und *.blockStreamingCoalesce (non-Telegram channels require explicit *.blockStreaming: true)

Details: Streaming + chunking.

Reasoning visibility und tokens

OpenClaw can expose or hide model reasoning:

• /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 und Token use.

Prefixes, threading, und replies

Outbound message formatting is centralized in messages:

• messages.responsePrefix (outbound prefix) und channels.whatsapp.messagePrefix (WhatsApp inbound prefix)
• Reply threading via replyToMode und per-channel defaults

Details: Configuration und channel docs.