Streaming and chunking

OpenClaw has two separate streaming layers:

• Block streaming (channels): emit completed blocks as the assistant writes. These are normal channel messages (not token deltas).
• Preview streaming (Telegram/Discord/Slack): update a temporary preview message while generating.

There is no true token-delta streaming to channel messages today. Preview streaming is message-based (send + edits/appends).

Block streaming (channel messages)

Block streaming sends assistant output in coarse chunks as it becomes available.

text
Copy
Model output
  └─ text_delta/events
       ├─ (blockStreamingBreak=text_end)
       │    └─ chunker emits blocks as buffer grows
       └─ (blockStreamingBreak=message_end)
            └─ chunker flushes at message_end
                   └─ channel send (block replies)

Legend:

• text

  Copy

  text_delta/events
  : model stream events (may be sparse for non-streaming models).
• text

  Copy

  chunker
  :
  text

  Copy

  EmbeddedBlockChunker
  applying min/max bounds + break preference.
• text

  Copy

  channel send
  : actual outbound messages (block replies).

Controls:

• text

  Copy

  agents.defaults.blockStreamingDefault
  :
  text

  Copy

  "on"
  /
  text

  Copy

  "off"
  (default off).
• Channel overrides:
  text

  Copy

  *.blockStreaming
  (and per-account variants) to force
  text

  Copy

  "on"
  /
  text

  Copy

  "off"
  per channel.
• text

  Copy

  agents.defaults.blockStreamingBreak
  :
  text

  Copy

  "text_end"
  or
  text

  Copy

  "message_end"
  .
• text

  Copy

  agents.defaults.blockStreamingChunk
  :
  text

  Copy

  { minChars, maxChars, breakPreference? }
  .
• text

  Copy

  agents.defaults.blockStreamingCoalesce
  :
  text

  Copy

  { minChars?, maxChars?, idleMs? }
  (merge streamed blocks before send).
• Channel hard cap:
  text

  Copy

  *.textChunkLimit
  (e.g.,
  text

  Copy

  channels.whatsapp.textChunkLimit
  ).
• Channel chunk mode:
  text

  Copy

  *.chunkMode
  (
  text

  Copy

  length
  default,
  text

  Copy

  newline
  splits on blank lines (paragraph boundaries) before length chunking).
• Discord soft cap:
  text

  Copy

  channels.discord.maxLinesPerMessage
  (default 17) splits tall replies to avoid UI clipping.

Boundary semantics:

• text

  Copy

  text_end
  : stream blocks as soon as chunker emits; flush on each
  text

  Copy

  text_end
  .
• text

  Copy

  message_end
  : wait until assistant message finishes, then flush buffered output.

still uses the chunker if the buffered text exceeds , so it can emit multiple chunks at the end.

Media delivery with block streaming

directives are normal delivery metadata. When block streaming sends a media block early, OpenClaw remembers that delivery for the turn. If the final assistant payload repeats the same media URL, the final delivery strips the duplicate media instead of sending the attachment again.

Exact duplicate final payloads are suppressed. If the final payload adds distinct text around media that was already streamed, OpenClaw still sends the new text while keeping the media single-delivery. This prevents duplicate voice notes or files on channels such as Telegram when an agent emits

during streaming and the provider also includes it in the completed reply.

Chunking algorithm (low/high bounds)

Block chunking is implemented by

:

• Low bound: don’t emit until buffer >=
  text

  Copy

  minChars
  (unless forced).
• High bound: prefer splits before
  text

  Copy

  maxChars
  ; if forced, split at
  text

  Copy

  maxChars
  .
• Break preference:
  text

  Copy

  paragraph
  →
  text

  Copy

  newline
  →
  text

  Copy

  sentence
  →
  text

  Copy

  whitespace
  → hard break.
• Code fences: never split inside fences; when forced at
  text

  Copy

  maxChars
  , close + reopen the fence to keep Markdown valid.

is clamped to the channel , so you can’t exceed per-channel caps.

Coalescing (merge streamed blocks)

When block streaming is enabled, OpenClaw can merge consecutive block chunks before sending them out. This reduces “single-line spam” while still providing progressive output.

• Coalescing waits for idle gaps (
  text

  Copy

  idleMs
  ) before flushing.
• Buffers are capped by
  text

  Copy

  maxChars
  and will flush if they exceed it.
• text

  Copy

  minChars
  prevents tiny fragments from sending until enough text accumulates (final flush always sends remaining text).
• Joiner is derived from
  text

  Copy

  blockStreamingChunk.breakPreference
  (
  text

  Copy

  paragraph
  →
  text

  Copy

  \n\n
  ,
  text

  Copy

  newline
  →
  text

  Copy

  \n
  ,
  text

  Copy

  sentence
  → space).
• Channel overrides are available via
  text

  Copy

  *.blockStreamingCoalesce
  (including per-account configs).
• Default coalesce
  text

  Copy

  minChars
  is bumped to 1500 for Signal/Slack/Discord unless overridden.

Human-like pacing between blocks

When block streaming is enabled, you can add a randomized pause between block replies (after the first block). This makes multi-bubble responses feel more natural.

• Config:
  text

  Copy

  agents.defaults.humanDelay
  (override per agent via
  text

  Copy

  agents.list[].humanDelay
  ).
• Modes:
  text

  Copy

  off
  (default),
  text

  Copy

  natural
  (800–2500ms),
  text

  Copy

  custom
  (
  text

  Copy

  minMs
  /
  text

  Copy

  maxMs
  ).
• Applies only to block replies, not final replies or tool summaries.

"Stream chunks or everything"

This maps to:

• Stream chunks:
  text

  Copy

  blockStreamingDefault: "on"
  +
  text

  Copy

  blockStreamingBreak: "text_end"
  (emit as you go). Non-Telegram channels also need
  text

  Copy

  *.blockStreaming: true
  .
• Stream everything at end:
  text

  Copy

  blockStreamingBreak: "message_end"
  (flush once, possibly multiple chunks if very long).
• No block streaming:
  text

  Copy

  blockStreamingDefault: "off"
  (only final reply).

Channel note: Block streaming is off unless

is explicitly set to . Channels can stream a live preview () without block replies.

Config location reminder: the

defaults live under , not the root config.

Preview streaming modes

Canonical key:

Modes:

• text

  Copy

  off
  : disable preview streaming.
• text

  Copy

  partial
  : single preview that is replaced with latest text.
• text

  Copy

  block
  : preview updates in chunked/appended steps.
• text

  Copy

  progress
  : progress/status preview during generation, final answer at completion.

Channel mapping

Slack-only:

• text

  Copy

  channels.slack.streaming.nativeTransport
  toggles Slack native streaming API calls when
  text

  Copy

  channels.slack.streaming.mode="partial"
  (default:
  text

  Copy

  true
  ).
• Slack native streaming and Slack assistant thread status require a reply thread target; top-level DMs do not show that thread-style preview.

Legacy key migration:

• Telegram: legacy
  text

  Copy

  streamMode
  and scalar/boolean
  text

  Copy

  streaming
  values are detected and migrated by doctor/config compatibility paths to
  text

  Copy

  streaming.mode
  .
• Discord:
  text

  Copy

  streamMode
  + boolean
  text

  Copy

  streaming
  auto-migrate to
  text

  Copy

  streaming
  enum.
• Slack:
  text

  Copy

  streamMode
  auto-migrates to
  text

  Copy

  streaming.mode
  ; boolean
  text

  Copy

  streaming
  auto-migrates to
  text

  Copy

  streaming.mode
  plus
  text

  Copy

  streaming.nativeTransport
  ; legacy
  text

  Copy

  nativeStreaming
  auto-migrates to
  text

  Copy

  streaming.nativeTransport
  .

Runtime behavior

Telegram:

• Uses
  text

  Copy

  sendMessage
  +
  text

  Copy

  editMessageText
  preview updates across DMs and group/topics.
• Sends a fresh final message instead of editing in place when a preview has been visible for about one minute, then cleans up the preview so Telegram's timestamp reflects reply completion.
• Preview streaming is skipped when Telegram block streaming is explicitly enabled (to avoid double-streaming).
• text

  Copy

  /reasoning stream
  can write reasoning to preview.

Discord:

• Uses send + edit preview messages.
• text

  Copy

  block
  mode uses draft chunking (
  text

  Copy

  draftChunk
  ).
• Preview streaming is skipped when Discord block streaming is explicitly enabled.
• Final media, error, and explicit-reply payloads cancel pending previews without flushing a new draft, then use normal delivery.

Slack:

• text

  Copy

  partial
  can use Slack native streaming (
  text

  Copy

  chat.startStream
  /
  text

  Copy

  append
  /
  text

  Copy

  stop
  ) when available.
• text

  Copy

  block
  uses append-style draft previews.
• text

  Copy

  progress
  uses status preview text, then final answer.
• Native and draft preview streaming suppress block replies for that turn, so a Slack reply is streamed by one delivery path only.
• Final media/error payloads and progress finals do not create throwaway draft messages; only text/block finals that can edit the preview flush pending draft text.

Mattermost:

• Streams thinking, tool activity, and partial reply text into a single draft preview post that finalizes in place when the final answer is safe to send.
• Falls back to sending a fresh final post if the preview post was deleted or is otherwise unavailable at finalize time.
• Final media/error payloads cancel pending preview updates before normal delivery instead of flushing a temporary preview post.

Matrix:

• Draft previews finalize in place when the final text can reuse the preview event.
• Media-only, error, and reply-target-mismatch finals cancel pending preview updates before normal delivery; an already-visible stale preview is redacted.

Tool-progress preview updates

Preview streaming can also include tool-progress updates — short status lines like "searching the web", "reading file", or "calling tool" — that appear in the same preview message while tools are running, ahead of the final reply. This keeps multi-step tool turns visually alive rather than silent between the first thinking preview and the final answer.

Supported surfaces:

• Discord, Slack, Telegram, and Matrix stream tool-progress into the live preview edit by default when preview streaming is active.
• Telegram has shipped with tool-progress preview updates enabled since
  text

  Copy

  v2026.4.22
  ; keeping them enabled preserves that released behavior.
• Mattermost already folds tool activity into its single draft preview post (see above).
• Tool-progress edits follow the active preview streaming mode; they are skipped when preview streaming is
  text

  Copy

  off
  or when block streaming has taken over the message. On Telegram,
  text

  Copy

  streaming.mode: "off"
  is final-only: generic progress chatter is also suppressed instead of being delivered as standalone "Working..." messages, while approval prompts, media payloads, and errors still route normally.
• To keep preview streaming but hide tool-progress lines, set
  text

  Copy

  streaming.preview.toolProgress
  to
  text

  Copy

  false
  for that channel. To disable preview edits entirely, set
  text

  Copy

  streaming.mode
  to
  text

  Copy

  off
  .

Example:

json
Copy
{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": false
        }
      }
    }
  }
}

Related

• Messages — message lifecycle and delivery
• Retry — retry behavior on delivery failure
• Channels — per-channel streaming support