OpenClaw 串流與分塊設定指南：優化訊息輸出效能

每次在開發聊天機器人時，最讓人頭痛的就是等待模型生成回應的那幾秒鐘。如果讓使用者盯著空白螢幕看，他們很快就會失去耐心。但要在 Telegram、Discord 或 Slack 這些平台上實現流暢的串流體驗，其實比想像中複雜，因為每個平台對訊息長度和頻率的限制都不一樣。

OpenClaw 設計了兩層獨立的串流機制，幫你優化這種等待體驗。這篇文章會帶你了解如何設定這些功能，讓你的機器人回話更像真人，也更即時。

Streaming + chunking

OpenClaw 有兩層獨立的串流層：

區塊串流 (Block streaming/channels)： 在 Assistant 寫作時，發送已完成的區塊 (blocks)。這些是正常的 channel 訊息（不是 token deltas）。
預覽串流 (Preview streaming/Telegram/Discord/Slack)： 在生成過程中，更新一個暫時性的預覽訊息。

目前 OpenClaw 對 channel 訊息沒有真正的 token-delta 串流。預覽串流是基於訊息的（發送 + 編輯/追加）。

區塊串流 (Channel 訊息)

區塊串流會在 Assistant 輸出可用時，以粗顆粒度的區塊發送內容。

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)

圖例：

text_delta/events：模型串流事件（對於非串流模型，這些事件可能很稀疏）。
chunker：EmbeddedBlockChunker 會套用最小/最大邊界以及換行偏好。
channel send：實際發出的訊息（區塊回覆）。

控制選項：

agents.defaults.blockStreamingDefault："on"/"off"（預設為 off）。
Channel 覆寫：透過 *.blockStreaming（以及每個帳號的變體）來強制設定每個 channel 的 "on"/"off"。
agents.defaults.blockStreamingBreak："text_end" 或 "message_end"。
agents.defaults.blockStreamingChunk：{ minChars, maxChars, breakPreference? }。
agents.defaults.blockStreamingCoalesce：{ minChars?, maxChars?, idleMs? }（在發送前合併串流區塊）。
Channel 硬限制：*.textChunkLimit（例如 channels.whatsapp.textChunkLimit）。
Channel 分段模式：*.chunkMode（預設為 length，newline 會在長度分段前先按空行/段落邊界拆分）。
Discord 軟限制：channels.discord.maxLinesPerMessage（預設為 17）會拆分過高的回覆以避免 UI 裁切。

邊界語義：

text_end：一旦 chunker 產生區塊就立即串流發送；在每個 text_end 時清空緩衝。
message_end：等待 Assistant 訊息全部完成後，再清空緩衝發送輸出。

即使使用 message_end，如果緩衝的文字超過 maxChars，chunker 仍會運作，因此最後可能會發出多個區塊。

分段演算法 (低/高邊界)

區塊分段是由 EmbeddedBlockChunker 實作的：

低邊界 (Low bound)： 除非強制執行，否則在緩衝區 >= minChars 之前不發送。
高邊界 (High bound)： 優先在 maxChars 之前拆分；如果被強制執行，則在 maxChars 處拆分。
換行偏好 (Break preference)： paragraph → newline → sentence → whitespace → 硬拆分。
程式碼區塊 (Code fences)： 絕對不在 code fences 內部拆分；如果被迫在 maxChars 處拆分，會關閉並重新開啟 fence 以保持 Markdown 格式正確。

maxChars 會被限制在 channel 的 textChunkLimit 之內，所以你不會超過每個 channel 的上限。

合併處理 (合併串流區塊)

當啟用區塊串流時，OpenClaw 可以在發送前合併連續的區塊。這能減少「單行洗版」的情況，同時仍能提供漸進式的輸出。

合併處理會等待閒置間隔 (idleMs) 後才清空緩衝。
緩衝區受 maxChars 限制，超過時會自動發送。
minChars 可以防止發送微小的碎片，直到累積足夠的文字（最後一次清空總是會發送剩餘文字）。
連接符號取決於 blockStreamingChunk.breakPreference (paragraph → \n\n, newline → \n, sentence → 空格)。
可以透過 *.blockStreamingCoalesce 進行 channel 覆寫（包括每個帳號的配置）。
對於 Signal/Slack/Discord，預設的合併 minChars 會提升至 1500，除非另有設定。

區塊間的人性化停頓

啟用區塊串流後，你可以在區塊回覆之間（從第一個區塊之後開始）加入隨機停頓。這讓多氣泡回覆感覺更自然。

配置：agents.defaults.humanDelay（可透過 agents.list[].humanDelay 為每個 agent 覆寫）。
模式：off（預設）、natural (800–2500ms)、custom (minMs/maxMs)。
僅適用於區塊回覆，不適用於最終回覆或工具摘要。

「分段串流」或「一次發送」

這對應到以下設定：

分段串流 (Stream chunks)： blockStreamingDefault: "on" + blockStreamingBreak: "text_end"（邊寫邊發）。非 Telegram 的 channel 還需要設定 *.blockStreaming: true。
最後一次發送全部 (Stream everything at end)： blockStreamingBreak: "message_end"（一次清空，如果內容很長可能會分成多個區塊）。
不使用區塊串流 (No block streaming)： blockStreamingDefault: "off"（只發送最終回覆）。

Channel 注意事項： 除非 *.blockStreaming 明確設為 true，否則區塊串流是關閉的。Channel 可以只串流即時預覽 (channels.<channel>.streaming) 而不使用區塊回覆。

配置位置提醒：blockStreaming* 的預設值位於 agents.defaults 下，而不是根配置。

預覽串流模式

標準 Key：channels.<channel>.streaming

模式：

off：停用預覽串流。
partial：單一預覽訊息，會被最新文字替換。
block：預覽訊息以區塊/追加的方式更新。
progress：生成期間顯示進度/狀態預覽，完成後顯示最終答案。

Channel 映射

Channel	`off`	`partial`	`block`	`progress`
Telegram	✅	✅	✅	映射至 `partial`
Discord	✅	✅	✅	映射至 `partial`
Slack	✅	✅	✅	✅

僅限 Slack：

當 streaming=partial 時，channels.slack.nativeStreaming 可切換是否使用 Slack 原生串流 API 呼叫（預設：true）。

舊版 Key 遷移：

Telegram：streamMode + 布林值 streaming 會自動遷移至 streaming 列舉。
Discord：streamMode + 布林值 streaming 會自動遷移至 streaming 列舉。
Slack：streamMode 自動遷移至 streaming 列舉；布林值 streaming 自動遷移至 nativeStreaming。

執行階段行為

Telegram：

在私訊、群組和主題中使用 sendMessage + editMessageText 進行預覽更新。
當明確啟用 Telegram 區塊串流時，會跳過預覽串流（以避免雙重串流）。
/reasoning stream 可以將推理過程寫入預覽。

Discord：

使用發送 + 編輯預覽訊息。
block 模式使用草稿分段 (draftChunk)。
當明確啟用 Discord 區塊串流時，會跳過預覽串流。

Slack：

當可用時，partial 可以使用 Slack 原生串流 (chat.startStream/append/stop)。
block 使用追加風格的草稿預覽。
progress 使用狀態預覽文字，然後發送最終答案。

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。