Streaming and chunking

Streaming and chunking 문서는 OpenClaw 공식 문서(concepts/streaming)를 한국어로 정리한 가이드입니다. Streaming + chunking behavior (block replies, channel preview streaming, mode mapping) 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Streaming + chunking behavior (block replies, channel preview streaming, mode mapping)

한국어 가이드 범위: concepts/streaming 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Control UI startup status
Block streaming (channel messages)
Media delivery with block streaming
Chunking algorithm (low/high bounds)
Coalescing (merge streamed blocks)
Human-like pacing between blocks
"Stream chunks or everything"
Preview streaming modes
Channel mapping
Legacy key migration
Runtime behavior
Telegram
Discord
Slack
Mattermost
Matrix
Tool-progress preview updates
Progress draft rendering
Commentary progress lane
관련 문서

상세 내용

본문

OpenClaw has two independent streaming layers, and there is no true token-delta streaming to channel messages today:

주요 항목:

Block streaming (channels): emit completed blocks as the assistant
Preview streaming (Telegram/Discord/Slack/Matrix/Mattermost/MS Teams):

Control UI startup status

After chat.send acknowledges an active run, the Gateway can send a typed, coarse startup status before assistant text or tool activity is visible. The Control UI shows this status beside the working indicator, with stages for workspace preparation, environment provisioning, context preparation, and model startup.

Block streaming (channel messages)

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

주요 항목:

text_delta/events: model stream events (may be sparse for non-streaming models).
chunker: EmbeddedBlockChunker applying min/max bounds + break preference.
channel send: actual outbound messages (block replies).
text_end: stream blocks as soon as the chunker emits; flush on each text_end.
message_end: wait until the assistant message finishes, then flush buffered

Key	Values / shape	Default
`blockStreamingDefault`	`"on"` / `"off"`	`"off"`
`blockStreamingBreak`	`"text_end"` / `"message_end"`	-
`blockStreamingChunk`	`{ minChars, maxChars, breakPreference? }`	-
`blockStreamingCoalesce`	`{ minChars?, maxChars?, idleMs? }` (merge streamed blocks before send)	-
`*.streaming.block.enabled` (channel override)	`true` / `false`, forces block streaming per channel (and per account)	-
`*.textChunkLimit` (e.g. `channels.whatsapp.textChunkLimit`)	number, hard cap	4000
`*.streaming.chunkMode`	`"length"` / `"newline"`	`"length"`
`channels.discord.maxLinesPerMessage`	number, soft line cap that splits tall replies to avoid UI clipping	17

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)

Media delivery with block streaming

Streaming media must use structured payload fields such as mediaUrl or mediaUrls; streamed text is not parsed as an attachment command. When block streaming sends media early, OpenClaw remembers that delivery for the turn. If the final assistant payload repeats the same media URL, final delivery strips the duplicate media instead of sending the attachment again.

Chunking algorithm (low/high bounds)

Block chunking is implemented by EmbeddedBlockChunker:

주요 항목:

Low bound: don't emit until buffer >= minChars (unless forced).
High bound: prefer splits before maxChars; if forced, split at maxChars.
Break preference chain: paragraph -> newline -> sentence ->
Code fences: never split inside fences; when forced at maxChars, close

Coalescing (merge streamed blocks)

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

주요 항목:

Coalescing waits for idle gaps (idleMs) before flushing.
Buffers are capped by maxChars and flush if they exceed it.
minChars prevents tiny fragments from sending until enough text accumulates
Joiner is derived from blockStreamingChunk.breakPreference: paragraph ->
Channel overrides are available via *.streaming.block.coalesce (including
Discord, Signal, and Slack default coalesce to { minChars: 1500, idleMs: 1000 }

Human-like pacing between blocks

When block streaming is enabled, add a randomized pause between block replies, after the first block, so multi-bubble responses feel more natural.

`agents.defaults.humanDelay.mode`	Behavior
`off` (default)	No pause
`natural`	800-2500ms random pause
`custom`	`minMs`/`maxMs`

"Stream chunks or everything"

(emit as you go). Non-Telegram channels also need *.streaming.block.enabled: true.

주요 항목:

Stream chunks: blockStreamingDefault: "on" + blockStreamingBreak: "text_end"
Stream everything at end: blockStreamingBreak: "message_end" (flush
No block streaming: blockStreamingDefault: "off" (only final reply).

Preview streaming modes

Canonical key: channels..streaming (nested { mode, ... }; legacy top-level boolean/string spellings are rewritten by openclaw doctor --fix).

Mode	Behavior
`off`	Disable preview streaming
`partial`	Single preview replaced with latest text
`block`	Preview updates in chunked/appended steps
`progress`	Progress/status preview during generation, final answer at completion

Channel mapping

Preview chunk config (streaming.preview.chunk.*, e.g. under channels.discord.streaming or channels.telegram.streaming) defaults to minChars: 200, maxChars: 800 (clamped to the channel textChunkLimit), and breakPreference: "paragraph".

주요 항목:

channels.slack.streaming.nativeTransport toggles Slack native streaming API
Slack native streaming and Slack assistant thread status require a reply

Channel	`off`	`partial`	`block`	`progress`
Telegram	Yes	Yes	Yes	editable progress draft
Discord	Yes	Yes	Yes	editable progress draft
Slack	Yes	Yes	Yes	Yes
Mattermost	Yes	Yes	Yes	Yes
MS Teams	Yes	Yes	Yes	native progress stream

Legacy key migration

Channel	Legacy keys	Status
Telegram	`streamMode`, scalar/boolean `streaming`	Rewritten to `streaming.mode` by `openclaw doctor --fix`; not read at runtime
Discord	`streamMode`, boolean `streaming`	Rewritten to `streaming.mode` by `openclaw doctor --fix`; not read at runtime
Slack	`streamMode`; boolean `streaming`; legacy `nativeStreaming`	Rewritten to `streaming.mode` (and `streaming.nativeTransport` for the boolean/legacy forms) by `openclaw doctor --fix`; not read at runtime
Matrix	scalar/boolean `streaming`	Rewritten to `streaming.mode` (including Matrix's `"quiet"` mode) by `openclaw doctor --fix`; not read at runtime
Feishu	boolean `streaming`	Rewritten to `streaming.mode` by `openclaw doctor --fix`; not read at runtime
QQ Bot	boolean `streaming`; `streaming.c2cStreamApi`	Rewritten to `streaming.mode` (and `streaming.nativeTransport` for the boolean/`c2cStreamApi` forms) by `openclaw doctor --fix`; not read at runtime

Runtime behavior

이 섹션의 세부 항목은 공식 문서 Runtime behavior를 참고하세요.

group/topics; final text edits the active preview in place. Telegram ephemeral 30-second "typing" drafts (sendMessageDraft) are not used for answer streaming.

주요 항목:

Uses sendMessage + editMessageText preview updates across DMs and
Short initial previews are still debounced for push-notification UX, but
Long finals reuse the preview message for the first chunk and send only the
block mode rotates the preview into a new message at
progress mode keeps tool progress in an editable status draft, materializes
If the final edit fails before the completed text is confirmed, OpenClaw uses
Preview streaming is skipped when Telegram block streaming is explicitly
/reasoning stream can write reasoning to a transient preview that is
Telegram selected quote replies are an exception: when replyToMode is not

Discord

counts and elapsed time) to the final answer and deletes the status draft once that answer is delivered, so busy channels keep no orphaned tool log above the reply. Error finals keep the draft as the record of the failed turn.

주요 항목:

Uses send + edit preview messages.
block mode uses draft chunking (draftChunk).
Preview streaming is skipped when Discord block streaming is explicitly
progress mode appends a small -# activity receipt (thought/tool-call
Final media, error, and explicit-reply payloads cancel pending previews

Slack

Slack reply is streamed by one delivery path only.

주요 항목:

partial can use Slack native streaming (chat.startStream/append/stop)
block uses append-style draft previews.
progress uses status preview text, then the final answer.
Top-level DMs without a reply thread use draft preview posts and edits
Native and draft preview streaming suppress block replies for that turn, so a
Final media/error payloads and progress finals do not create throwaway draft

Mattermost

preview post that finalizes in place when the final answer is safe to send.

주요 항목:

In partial mode, streams thinking and partial reply text into a single draft
In progress mode, streams thinking and tool activity into a single status
In block mode, rotates between completed text and tool-activity posts;
Falls back to sending a fresh final post if the preview post was deleted or
Final media/error payloads cancel pending preview updates before normal

Matrix

updates before normal delivery; an already-visible stale preview is redacted.

주요 항목:

Draft previews finalize in place when the final text can reuse the preview
Media-only, error, and reply-target-mismatch finals cancel pending preview

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. In Codex app-server mode, Codex preamble/commentary messages use this same preview path, so short "I am checking..." progress notes can stream into the editable draft without becoming part of the final answer. This keeps multi-step tool turns visually alive instead of silent between the first thinking preview and the final answer.

주요 항목:

Discord, Slack, Telegram, and Matrix stream tool-progress and
Telegram has shipped with tool-progress preview updates enabled since
Mattermost folds tool activity into one preview post in partial and
Tool-progress edits follow the active preview streaming mode; they are
To keep preview streaming but hide tool-progress lines, set

Progress draft rendering

Progress-mode drafts (streaming.progress.*) are bounded and configurable per channel:

Key	Default	Behavior
`streaming.progress.maxLines`	`8`	Max compact progress lines kept below the draft label
`streaming.progress.maxLineChars`	`120`	Max characters per compact line before truncation (word-aware)
`streaming.progress.label`	`"auto"`	Draft title; a custom string, or `false` to hide it
`streaming.progress.labels`	built-in pool	Candidate labels used when `label: "auto"`

Commentary progress lane

Beyond tool-progress, the compact progress renderer can surface one more lane in the draft:

주요 항목:

streaming.progress.commentary - render the model's pre-tool

{
  "channels": {
    "discord": {
      "streaming": { "mode": "progress", "progress": { "commentary": true } }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/streaming
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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)

{
  "channels": {
    "discord": {
      "streaming": { "mode": "progress", "progress": { "commentary": true } }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

Streaming and chunking

핵심 요약

Streaming + chunking behavior (block replies, channel preview streaming, mode mapping)

한국어 가이드 범위: concepts/streaming 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Control UI startup status
Block streaming (channel messages)
Media delivery with block streaming
Chunking algorithm (low/high bounds)
Coalescing (merge streamed blocks)
Human-like pacing between blocks
"Stream chunks or everything"
Preview streaming modes
Channel mapping
Legacy key migration
Runtime behavior
Telegram
Discord
Slack
Mattermost
Matrix
Tool-progress preview updates
Progress draft rendering
Commentary progress lane
관련 문서

상세 내용

본문

OpenClaw has two independent streaming layers, and there is no true token-delta streaming to channel messages today:

주요 항목:

Block streaming (channels): emit completed blocks as the assistant
Preview streaming (Telegram/Discord/Slack/Matrix/Mattermost/MS Teams):

Control UI startup status

Block streaming (channel messages)

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

주요 항목:

text_delta/events: model stream events (may be sparse for non-streaming models).
chunker: EmbeddedBlockChunker applying min/max bounds + break preference.
channel send: actual outbound messages (block replies).
text_end: stream blocks as soon as the chunker emits; flush on each text_end.
message_end: wait until the assistant message finishes, then flush buffered

Key	Values / shape	Default
`blockStreamingDefault`	`"on"` / `"off"`	`"off"`
`blockStreamingBreak`	`"text_end"` / `"message_end"`	-
`blockStreamingChunk`	`{ minChars, maxChars, breakPreference? }`	-
`blockStreamingCoalesce`	`{ minChars?, maxChars?, idleMs? }` (merge streamed blocks before send)	-
`*.streaming.block.enabled` (channel override)	`true` / `false`, forces block streaming per channel (and per account)	-
`*.textChunkLimit` (e.g. `channels.whatsapp.textChunkLimit`)	number, hard cap	4000
`*.streaming.chunkMode`	`"length"` / `"newline"`	`"length"`
`channels.discord.maxLinesPerMessage`	number, soft line cap that splits tall replies to avoid UI clipping	17

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)

Media delivery with block streaming

Chunking algorithm (low/high bounds)

Block chunking is implemented by EmbeddedBlockChunker:

주요 항목:

Low bound: don't emit until buffer >= minChars (unless forced).
High bound: prefer splits before maxChars; if forced, split at maxChars.
Break preference chain: paragraph -> newline -> sentence ->
Code fences: never split inside fences; when forced at maxChars, close

Coalescing (merge streamed blocks)

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

주요 항목:

Coalescing waits for idle gaps (idleMs) before flushing.
Buffers are capped by maxChars and flush if they exceed it.
minChars prevents tiny fragments from sending until enough text accumulates
Joiner is derived from blockStreamingChunk.breakPreference: paragraph ->
Channel overrides are available via *.streaming.block.coalesce (including
Discord, Signal, and Slack default coalesce to { minChars: 1500, idleMs: 1000 }

Human-like pacing between blocks

When block streaming is enabled, add a randomized pause between block replies, after the first block, so multi-bubble responses feel more natural.

`agents.defaults.humanDelay.mode`	Behavior
`off` (default)	No pause
`natural`	800-2500ms random pause
`custom`	`minMs`/`maxMs`

"Stream chunks or everything"

(emit as you go). Non-Telegram channels also need *.streaming.block.enabled: true.

주요 항목:

Stream chunks: blockStreamingDefault: "on" + blockStreamingBreak: "text_end"
Stream everything at end: blockStreamingBreak: "message_end" (flush
No block streaming: blockStreamingDefault: "off" (only final reply).

Preview streaming modes

Canonical key: channels..streaming (nested { mode, ... }; legacy top-level boolean/string spellings are rewritten by openclaw doctor --fix).

Mode	Behavior
`off`	Disable preview streaming
`partial`	Single preview replaced with latest text
`block`	Preview updates in chunked/appended steps
`progress`	Progress/status preview during generation, final answer at completion

Channel mapping

주요 항목:

channels.slack.streaming.nativeTransport toggles Slack native streaming API
Slack native streaming and Slack assistant thread status require a reply

Channel	`off`	`partial`	`block`	`progress`
Telegram	Yes	Yes	Yes	editable progress draft
Discord	Yes	Yes	Yes	editable progress draft
Slack	Yes	Yes	Yes	Yes
Mattermost	Yes	Yes	Yes	Yes
MS Teams	Yes	Yes	Yes	native progress stream

Legacy key migration

Channel	Legacy keys	Status
Telegram	`streamMode`, scalar/boolean `streaming`	Rewritten to `streaming.mode` by `openclaw doctor --fix`; not read at runtime
Discord	`streamMode`, boolean `streaming`	Rewritten to `streaming.mode` by `openclaw doctor --fix`; not read at runtime
Slack	`streamMode`; boolean `streaming`; legacy `nativeStreaming`	Rewritten to `streaming.mode` (and `streaming.nativeTransport` for the boolean/legacy forms) by `openclaw doctor --fix`; not read at runtime
Matrix	scalar/boolean `streaming`	Rewritten to `streaming.mode` (including Matrix's `"quiet"` mode) by `openclaw doctor --fix`; not read at runtime
Feishu	boolean `streaming`	Rewritten to `streaming.mode` by `openclaw doctor --fix`; not read at runtime
QQ Bot	boolean `streaming`; `streaming.c2cStreamApi`	Rewritten to `streaming.mode` (and `streaming.nativeTransport` for the boolean/`c2cStreamApi` forms) by `openclaw doctor --fix`; not read at runtime

Runtime behavior

이 섹션의 세부 항목은 공식 문서 Runtime behavior를 참고하세요.

group/topics; final text edits the active preview in place. Telegram ephemeral 30-second "typing" drafts (sendMessageDraft) are not used for answer streaming.

주요 항목:

Uses sendMessage + editMessageText preview updates across DMs and
Short initial previews are still debounced for push-notification UX, but
Long finals reuse the preview message for the first chunk and send only the
block mode rotates the preview into a new message at
progress mode keeps tool progress in an editable status draft, materializes
If the final edit fails before the completed text is confirmed, OpenClaw uses
Preview streaming is skipped when Telegram block streaming is explicitly
/reasoning stream can write reasoning to a transient preview that is
Telegram selected quote replies are an exception: when replyToMode is not

Discord

주요 항목:

Uses send + edit preview messages.
block mode uses draft chunking (draftChunk).
Preview streaming is skipped when Discord block streaming is explicitly
progress mode appends a small -# activity receipt (thought/tool-call
Final media, error, and explicit-reply payloads cancel pending previews

Slack

Slack reply is streamed by one delivery path only.

주요 항목:

partial can use Slack native streaming (chat.startStream/append/stop)
block uses append-style draft previews.
progress uses status preview text, then the final answer.
Top-level DMs without a reply thread use draft preview posts and edits
Native and draft preview streaming suppress block replies for that turn, so a
Final media/error payloads and progress finals do not create throwaway draft

Mattermost

preview post that finalizes in place when the final answer is safe to send.

주요 항목:

In partial mode, streams thinking and partial reply text into a single draft
In progress mode, streams thinking and tool activity into a single status
In block mode, rotates between completed text and tool-activity posts;
Falls back to sending a fresh final post if the preview post was deleted or
Final media/error payloads cancel pending preview updates before normal

Matrix

updates before normal delivery; an already-visible stale preview is redacted.

주요 항목:

Draft previews finalize in place when the final text can reuse the preview
Media-only, error, and reply-target-mismatch finals cancel pending preview

Tool-progress preview updates

주요 항목:

Discord, Slack, Telegram, and Matrix stream tool-progress and
Telegram has shipped with tool-progress preview updates enabled since
Mattermost folds tool activity into one preview post in partial and
Tool-progress edits follow the active preview streaming mode; they are
To keep preview streaming but hide tool-progress lines, set

Progress draft rendering

Progress-mode drafts (streaming.progress.*) are bounded and configurable per channel:

Key	Default	Behavior
`streaming.progress.maxLines`	`8`	Max compact progress lines kept below the draft label
`streaming.progress.maxLineChars`	`120`	Max characters per compact line before truncation (word-aware)
`streaming.progress.label`	`"auto"`	Draft title; a custom string, or `false` to hide it
`streaming.progress.labels`	built-in pool	Candidate labels used when `label: "auto"`

Commentary progress lane

Beyond tool-progress, the compact progress renderer can surface one more lane in the draft:

주요 항목:

streaming.progress.commentary - render the model's pre-tool

{
  "channels": {
    "discord": {
      "streaming": { "mode": "progress", "progress": { "commentary": true } }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/streaming
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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)

{
  "channels": {
    "discord": {
      "streaming": { "mode": "progress", "progress": { "commentary": true } }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

Streaming and chunking

핵심 요약

문서 구성

상세 내용

본문

Control UI startup status

Block streaming (channel messages)

Media delivery with block streaming

Chunking algorithm (low/high bounds)

Coalescing (merge streamed blocks)

Human-like pacing between blocks

"Stream chunks or everything"

Preview streaming modes

Channel mapping

Legacy key migration

Runtime behavior

Telegram

Discord

Slack

Mattermost

Matrix

Tool-progress preview updates

Progress draft rendering

Commentary progress lane

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Streaming and chunking

핵심 요약

문서 구성

상세 내용

본문

Control UI startup status

Block streaming (channel messages)

Media delivery with block streaming

Chunking algorithm (low/high bounds)

Coalescing (merge streamed blocks)

Human-like pacing between blocks

"Stream chunks or everything"

Preview streaming modes

Channel mapping

Legacy key migration

Runtime behavior

Telegram

Discord

Slack

Mattermost

Matrix

Tool-progress preview updates

Progress draft rendering

Commentary progress lane

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드