流式传输与分块 - OpenClaw 中文文档

OpenClaw 有两层独立的流式传输机制：

区块流式传输（频道）： 在助手写作时发出已完成的区块。这些是普通频道消息（不是 token 增量）。
预览流式传输（Telegram/Discord/Slack）： 在生成过程中更新一条临时 预览消息。

目前没有真正的 token 增量流式传输到频道消息。预览流式传输是基于消息的（发送 + 编辑/追加）。

区块流式传输（频道消息）

区块流式传输会在助手输出可用时，以较粗粒度的块发送。

模型输出
  └─ text_delta/events
       ├─ (blockStreamingBreak=text_end)
       │    └─ chunker 随着缓冲区增长发出区块
       └─ (blockStreamingBreak=message_end)
            └─ chunker 在 message_end 时刷新
                   └─ 频道发送（区块回复）

图例：

text_delta/events：模型流事件（对于非流式模型可能很稀疏）。
chunker：EmbeddedBlockChunker，应用最小/最大边界 + 断点偏好。
channel send：实际的外发消息（区块回复）。

控制项：

agents.defaults.blockStreamingDefault："on"/"off"（默认关闭）。
频道覆盖：*.blockStreaming（以及按账户的变体），用于按频道强制 "on"/"off"。
agents.defaults.blockStreamingBreak："text_end" 或 "message_end"。
agents.defaults.blockStreamingChunk：{ minChars, maxChars, breakPreference? }。
agents.defaults.blockStreamingCoalesce：{ minChars?, maxChars?, idleMs? }（在发送前合并已流式输出的区块）。
频道硬上限：*.textChunkLimit（例如 channels.whatsapp.textChunkLimit）。
频道分块模式：*.chunkMode（length 为默认值，newline 会先按空白行（段落边界）拆分，再进行长度分块）。
Discord 软上限：channels.discord.maxLinesPerMessage（默认 17），会拆分过长回复以避免 UI 裁切。

边界语义：

text_end：chunker 一旦发出区块就立即流式发送；每次 text_end 都刷新。
message_end：等待助手消息结束，然后刷新已缓冲输出。

如果缓冲文本超过 maxChars，message_end 仍会使用 chunker，因此它可能在结束时发出多个分块。

使用区块流式传输的媒体投递

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, 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.

分块算法（低/高边界）

区块分块由 EmbeddedBlockChunker 实现：

低边界： 除非被强制，否则在缓冲区达到 minChars 之前不发出。
高边界： 优先在 maxChars 之前切分；如果被强制，则在 maxChars 处切分。
断点偏好： paragraph → newline → sentence → whitespace → hard break.
代码围栏： 不会在围栏内部拆分；如果在 maxChars 处被强制拆分，会先关闭再重新打开围栏，以保持 Markdown 有效。

maxChars 会被限制到频道的 textChunkLimit，因此无法超过每个频道的上限。

合并（合并已流式区块）

当启用区块流式传输时，OpenClaw 可以在发送前合并连续的区块片段 。这可以减少“单行刷屏”，同时仍提供渐进式输出。

合并会等待 空闲间隔（idleMs）后再刷新。
缓冲区受 maxChars 限制，超过时会刷新。
minChars 会阻止过小片段发送，直到积累到足够文本（最终刷新总会发送剩余文本）。
连接符由 blockStreamingChunk.breakPreference 决定（paragraph → \n\n，newline → \n，sentence → 空格）。
可通过 *.blockStreamingCoalesce 使用频道覆盖（包括按账户配置）。
默认的合并 minChars 对 Signal/Slack/Discord 会提升到 1500，除非被覆盖。

区块之间的人类化节奏

启用区块流式传输时，你可以在区块回复之间加入 随机暂停（首个区块之后）。这会让多气泡回复显得更自然。

配置：agents.defaults.humanDelay（可通过 agents.list[].humanDelay 按 agent 覆盖）。
模式：off（默认）、natural（800-2500ms）、custom（minMs/maxMs）。
仅适用于区块回复，不适用于最终回复或工具摘要。

“流式分块还是一次全部输出”

对应如下：

流式分块： blockStreamingDefault: "on" + blockStreamingBreak: "text_end"（边生成边发出）。非 Telegram 频道还需要 *.blockStreaming: true。
在末尾一次性流式输出全部： blockStreamingBreak: "message_end"（刷新一次，如内容很长则可能分成多个区块）。
不进行区块流式传输： blockStreamingDefault: "off"（仅最终回复）。

频道说明： 区块流式传输默认是关闭的，除非 *.blockStreaming 被显式设为 true。频道可以流式显示实时预览（channels.<channel>.streaming），而无需区块回复。配置位置提醒：blockStreaming* 默认值位于 agents.defaults 下，而不是根配置。

预览流式模式

规范键：channels.<channel>.streaming 模式：

off：禁用预览流式传输。
partial：单个预览，会被最新文本替换。
block：预览按分块/追加步骤更新。
progress：生成期间显示进度/状态预览，完成时显示最终答案。

streaming.mode: "block" 是适用于 Discord 和 Telegram 等可编辑频道的预览流式模式。它并不会在那里启用频道区块投递。若你想要正常的区块回复，请使用 streaming.block.enabled 或旧版 blockStreaming 频道键。Microsoft Teams 是个例外：它没有草稿预览区块传输，因此 streaming.mode: "block" 会映射到 Teams 的区块投递，而不是原生的 partial/progress 流式传输。

频道映射

Channel	`off`	`partial`	`block`	`progress`
Telegram	✅	✅	✅	可编辑的进度草稿
Discord	✅	✅	✅	可编辑的进度草稿
Slack	✅	✅	✅	✅
Mattermost	✅	✅	✅	✅
MS Teams	✅	✅	✅	原生进度流

仅限 Slack：

当 channels.slack.streaming.mode="partial" 时，channels.slack.streaming.nativeTransport 会切换 Slack 原生流式 API 调用（默认：true）。
Slack 原生流式传输和 Slack 助手线程状态都需要一个回复线程目标。顶层 DM 不会显示那种线程式预览，但仍然可以使用 Slack 草稿预览发布和编辑。

旧键迁移：

Telegram：旧版 streamMode 和标量/布尔类型的 streaming 值会被 doctor/config 兼容路径检测并迁移到 streaming.mode。
Discord：streamMode + 布尔类型 streaming 仍然是 streaming 枚举的运行时别名；运行 openclaw doctor --fix 可重写持久化配置。
Slack：streamMode 仍然是 streaming.mode 的运行时别名；布尔类型 streaming 仍然是 streaming.mode 加上 streaming.nativeTransport 的运行时别名；旧版 nativeStreaming 仍然是 streaming.nativeTransport 的运行时别名。运行 openclaw doctor --fix 可重写持久化配置。

运行时行为

Telegram：

使用 sendMessage + editMessageText 在私聊和群组/话题中更新预览。
最终文本会就地编辑当前预览；较长的最终内容会将该消息复用为第一个分块，并且只发送剩余分块。
progress 模式会把工具进度保留在可编辑的状态草稿中，完成时清除该草稿，并通过正常投递发送最终答案。
如果在完成文本被确认之前最终编辑失败，OpenClaw 会改用正常的最终投递并清理过时的预览。
当显式启用 Telegram 区块流式传输时，会跳过预览流式传输（以避免双重流式传输）。
/reasoning stream 可以把推理写入一个临时预览，该预览会在最终投递后被删除。

Discord：

使用发送 + 编辑预览消息。
block 模式使用草稿分块（draftChunk）。
当 Discord 区块流式传输被显式启用时，会跳过预览流式传输。
最终媒体、错误和显式回复载荷会取消待处理的预览，而不会刷新新草稿，然后使用正常投递。

Slack：

partial 在可用时可以使用 Slack 原生流式传输（chat.startStream/append/stop）。
block 使用追加式草稿预览。
progress 先使用状态预览文本，然后显示最终答案。
没有回复线程的顶层 DM 会使用草稿预览发布和编辑，而不是 Slack 原生流式传输。
原生和草稿预览流式传输会抑制该轮次的区块回复，因此 Slack 回复只通过一种投递路径流式传输。
最终媒体/错误载荷和进度最终结果不会创建一次性草稿消息；只有能够编辑预览的文本/区块最终结果才会刷新待处理的草稿文本。

Mattermost：

将思考、工具活动和部分回复文本流式写入同一条草稿预览帖子，并在最终答案可以安全发送时原地定稿。
如果预览帖子已被删除或在最终定稿时不可用，则回退为发送一条新的最终帖子。
最终媒体/错误载荷会在正常投递前取消待处理的预览更新，而不是刷新一个临时预览帖子。

Matrix：

当最终文本可以复用预览事件时，草稿预览会原地定稿。
仅媒体、错误以及回复目标不匹配的最终结果会在正常投递前取消待处理的预览更新；已经可见的陈旧预览会被遮蔽。

工具进度预览更新

Preview streaming 也可以包含 工具进度 更新——例如“正在搜索网页”“正在读取文件”或“正在调用工具”之类的简短状态行——它们会在工具运行时显示在同一条预览消息中，并早于最终回复。在 Codex app-server 模式下，Codex 的前言/注释消息使用同一条预览路径，因此简短的“我正在检查……”进度说明可以流式进入可编辑草稿，而不会成为最终答案的一部分。这样可以让多步骤工具轮次在视觉上保持“活跃”，而不是在第一条思考预览和最终答案之间沉默。 Long-running tools may emit typed progress before they return. For example, web_fetch arms a five-second timer when it starts: if the fetch is still pending, the preview can show Fetching page content...; if the fetch finishes or is canceled before then, no progress line is emitted. The later final tool result is still delivered normally to the model. Supported surfaces:

Discord、Slack、Telegram 和 Matrix 会在预览流式传输激活时，默认将工具进度和 Codex 前言更新流式写入实时预览编辑。Microsoft Teams 在个人聊天中使用其原生进度流。
Telegram 自 v2026.4.22 起已启用工具进度预览更新；保持启用可保留该已发布行为。
Mattermost 已经会将工具活动折叠进其单一草稿预览帖子中（见上文）。
工具进度编辑会遵循当前活动的预览流式模式；当预览流式为 off，或区块流式已接管该消息时，会跳过这些更新。在 Telegram 上，streaming.mode: "off" 是仅最终结果模式：通用进度闲聊也会被抑制，而不是作为独立状态消息投递；不过审批提示、媒体载荷和错误仍会正常路由。
若要保留预览流式传输但隐藏工具进度行，请为该频道将 streaming.preview.toolProgress 设为 false。若要在隐藏命令/执行文本的同时保留工具进度行可见，请将 streaming.preview.commandText 设为 "status"，或将 streaming.progress.commandText 设为 "status"；默认值为 "raw"，以保留已发布行为。该策略适用于使用 OpenClaw 紧凑进度渲染器的草稿/进度频道，包括 Discord、Matrix、Microsoft Teams、Mattermost、Slack 草稿预览和 Telegram。若要完全禁用预览编辑，请将 streaming.mode 设为 off。
Telegram 选中的引用回复是个例外：当 replyToMode 不是 "off" 且存在选中的引用文本时，OpenClaw 会跳过该轮的答案预览流，因此工具进度预览行不会渲染。当前消息回复如果没有选中文本，仍会保留预览流式传输。详情见 Telegram channel docs。

保持进度行可见，但隐藏原始命令/执行文本：

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

在另一个紧凑进度频道键下使用相同结构，例如 channels.discord、channels.matrix、channels.msteams、channels.mattermost 或 Slack 草稿预览。对于进度草稿模式，请将相同策略放在 streaming.progress 下：

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

​区块流式传输（频道消息）

​使用区块流式传输的媒体投递

​分块算法（低/高边界）

​合并（合并已流式区块）

​区块之间的人类化节奏

​“流式分块还是一次全部输出”

​预览流式模式

​频道映射

​运行时行为

​工具进度预览更新

​相关内容