流式传输和分块
OpenClaw 有两个独立的流式传输层,并且没有真正的 token-delta 流式传输用于频道消息:
- 块流式传输(频道): 在助手写入时发出已完成的块。这些是普通频道消息,而不是 token 增量。
- 预览流式传输(Telegram/Discord/Slack/Matrix/Mattermost/MS Teams): 在生成期间更新一条临时预览消息(发送 + 编辑/追加)。
控制界面启动状态¶
在 chat.send 确认一个活动运行后,Gateway 可以在助手文本或工具活动可见之前发送一个类型化、粗粒度的启动状态。控制界面会在工作指示器旁边显示此状态,并包含工作区准备、环境配置、上下文准备和模型启动等阶段。
第一个助手增量或工具开始会永久替换该运行的启动状态。当工具正在等待操作员操作时,审批状态优先。Worktree 创建和初始云分发发生在聊天运行存在之前,因此它们的运行前 RPC 进度不会作为运行启动状态呈现;只有当活动运行重新配置一个已回收的 worker 时,环境配置才会在此处出现。
块流式传输(频道消息)¶
块流式传输会在助手输出可用时以粗粒度块发送。
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" |
blockStreamingBreak |
"text_end" / "message_end" |
- |
blockStreamingChunk |
{ minChars, maxChars, breakPreference? } |
- |
blockStreamingCoalesce |
{ minChars?, maxChars?, idleMs? }(在发送前合并流式块) |
- |
*.streaming.block.enabled(频道覆盖) |
true / false,按频道(以及按账户)强制启用块流式传输 |
- |
*.textChunkLimit(例如 channels.whatsapp.textChunkLimit) |
数字,硬性上限 | 4000 |
*.streaming.chunkMode |
"length" / "newline" |
"length" |
channels.discord.maxLinesPerMessage |
数字,软性行数上限,用于拆分较长的回复以避免 UI 裁剪 | 17 |
streaming.chunkMode: "newline" 按空行(段落边界)拆分,而不是按每个换行符拆分;当文本超过限制后,再回退到按长度分块。
内置频道将这些覆盖项拼写为 channels.<id>.streaming.{chunkMode,block.enabled,block.coalesce}。扁平的 *.chunkMode / *.blockStreaming / *.blockStreamingCoalesce 拼写会被校验拒绝。在启动 Gateway 之前,运行 openclaw doctor --fix 将旧配置迁移到嵌套结构。参见 Doctor 迁移指南。
边界语义(针对 blockStreamingBreak):
text_end:分块器一旦发出块,就立即流式发送;在每个text_end时刷新。message_end:等待助手消息完成,然后刷新已缓冲的输出。如果缓冲文本超过maxChars,仍会使用分块器,因此它可以在末尾发出多个块。
待定文本阶段¶
在工具边界解析旁白的传输层会暂缓持久块回复,直到阶段已知。Chat Completions 和原生 Ollama(api: "ollama"、/api/chat)会等待助手消息完成,即使使用 blockStreamingBreak: "text_end" 也是如此:较早的文本仍可能成为工具旁白。因此,一个较长的无工具回答在生成期间不会产生任何持久块。
普通最终回答和受长度限制的局部回答仍然可投递。当启用且频道支持时,独立的实时助手/预览流仍可在生成期间更新。
块流式传输中的媒体投递¶
当插件使用 before_agent_finalize 验证内置运行时的回答时,助手回复会保持延迟,直到该决定完成。后续回答会取代较早工具轮次中延迟的文本,即使最终回答是 NO_REPLY 也是如此。这同时适用于回复块和预览更新;它不会撤回已经发送的回复。旁白保持实时,媒体、推理以及对较早用户输入的已完成回答会被保留。每个被引导的用户输入都会获得自己的已投递回答,即使其待定工具被跳过。被取代回答中的媒体会在没有旧说明的情况下投递。
在块流式传输关闭时,包含媒体的助手消息仍可在消息边界处发送,并附带其说明。预览更新不计为单独投递的说明。
流式媒体必须使用结构化负载字段,例如 mediaUrl 或 mediaUrls;流式文本不会被解析为附件命令。当块流式传输提前发送媒体时,OpenClaw 会记住该轮次的投递。如果最终助手负载重复了相同的媒体 URL,最终投递会去除重复媒体,而不是再次发送附件。
完全重复的最终载荷会被抑制。如果最终载荷在已流式传输的媒体周围添加了不同的文本,OpenClaw 仍会发送新文本,同时保持媒体单次投递。这可防止在 Telegram 等频道上出现重复的语音消息或文件。
分块算法(低/高边界)¶
块分块由 EmbeddedBlockChunker 实现:
- 低边界: 在缓冲区 >=
minChars之前不输出(除非强制)。 - 高边界: 优先在
maxChars之前拆分;如果强制,则在maxChars处拆分。 - 换行偏好链:
paragraph->newline->sentence-> 空白 -> 强制换行。 - 代码围栏: 绝不在围栏内拆分;当在
maxChars处强制拆分时,关闭并重新打开围栏,以保持 Markdown 有效。 - 表格: 能容纳在
maxChars内的 Markdown 表格会保留在一个块中,即使这意味着在低于minChars时在其之前拆分,以便渲染表格的频道能够同时看到表头和行。更大的表格会在行边界处拆分。
maxChars 会被限制在频道的 textChunkLimit 内,因此你无法超过每个频道的上限。
合并(合并流式块)¶
当启用块流式传输时,OpenClaw 可以在发送前合并连续的块分块,减少单行刷屏,同时仍提供渐进式输出。
- 合并会等待空闲间隔(
idleMs)后再刷新。 - 缓冲区受
maxChars限制,如果超过则刷新。 minChars可防止微小片段在积累足够文本之前发送(最终刷新始终发送剩余文本)。- 连接符由
blockStreamingChunk.breakPreference派生:paragraph->\n\n,newline->\n,sentence-> 空格。 - 可通过
*.streaming.block.coalesce提供频道覆盖(包括按账号配置)。 - Discord、Signal 和 Slack 默认合并为
{ minChars: 1500, idleMs: 1000 },除非被覆盖。
块之间拟人化节奏¶
当启用块流式传输时,在第一个块之后的块回复之间添加随机暂停,使多气泡响应感觉更自然。
agents.defaults.humanDelay.mode |
行为 |
|---|---|
off(默认) |
无暂停 |
natural |
800-2500ms 随机暂停 |
custom |
minMs/maxMs |
通过 agents.entries.*.humanDelay 按代理覆盖。仅适用于块回复,不适用于最终回复或工具摘要。
“流式分块或全部内容”¶
- 流式分块:
blockStreamingDefault: "on"+blockStreamingBreak: "text_end"(边生成边发送)。非 Telegram 频道还需要*.streaming.block.enabled: true。 - 在末尾流式传输全部内容:
blockStreamingBreak: "message_end"(刷新 一次,如果非常长则可能分为多个块)。 - 无块流式传输:
blockStreamingDefault: "off"(最终文本回复; 携带媒体的消息仍可在消息边界处发送)。
块流式传输遵循 agents.defaults.blockStreamingDefault,除非频道或账号显式设置 *.streaming.block.enabled。QQ Bot 没有 streaming.block 键,并且会流式传输块回复,除非 channels.qqbot.streaming.mode 为 "off"。频道可以在没有块回复的情况下流式传输实时预览(channels.<channel>.streaming.mode)。blockStreaming* 默认值位于 agents.defaults 下,而不是配置根。
对于 Discord 和 Telegram,显式配置的非 off 预览模式优先于继承的 agents.defaults.blockStreamingDefault: "on"。当块回复应覆盖其预览时,设置该频道的 streaming.block.enabled: true。对于普通单代理轮次,如果修改回复的钩子阻止了 Telegram 预览,则已完成的块使用正常的钩子投递,除非块流式传输在全局或针对 Telegram 被显式禁用。配置的多代理群线程轮次不使用此强制回退;与其他没有预览的轮次一样,它们保留已配置的块投递策略。
预览流式传输模式¶
规范键:channels.<channel>.streaming(嵌套 { mode, ... };旧版顶层布尔/字符串拼写由 openclaw doctor --fix 重写)。
| 模式 | 行为 |
|---|---|
off |
禁用预览流式传输 |
partial |
单个预览被最新文本替换 |
block |
预览以分块/追加步骤更新 |
progress |
生成期间显示进度/状态预览,完成时显示最终答案 |
streaming.mode: "block" 是 Discord 和 Telegram 等支持编辑的频道的预览流式传输模式;它本身不会在那里启用频道块投递。对于普通块回复,请使用 streaming.block.enabled。Microsoft Teams 是例外:它没有草稿预览块传输,因此 streaming.mode: "block" 会完全禁用原生流式传输,回复将以常规块投递方式到达,而不是原生 partial/progress 流式传输。Mattermost 也不同:在 block 模式下,它会在已完成文本和工具活动块之间轮换预览,因此较早的块会作为单独的帖子保持可见,而不是在一个可编辑草稿中被覆盖。
频道映射¶
当 streaming 未设置时,Discord、Telegram 和 Slack 默认为 progress。Mattermost 和 MS Teams 默认为 partial。显式配置的模式保持不变;off 禁用预览。
| 频道 | off |
partial |
block |
progress |
|---|---|---|---|---|
| Telegram | 是 | 是 | 是 | 可编辑进度草稿(默认) |
| Discord | 是 | 是 | 是 | 可编辑进度草稿(默认) |
| 渠道 | off |
partial |
block |
progress |
|---|---|---|---|---|
| Slack | 是 | 是 | 是 | 线程内使用原生卡片;线程外保持安静 |
| Mattermost | 是 | 是 | 是 | 是 |
| MS Teams | 是 | 是 | 是 | 原生进度流 |
预览分块配置(streaming.preview.chunk.*,例如位于
channels.discord.streaming 或 channels.telegram.streaming 下)默认值为
minChars: 200、maxChars: 800(会被限制在渠道的 textChunkLimit 范围内),以及
breakPreference: "paragraph"。
仅限 Slack:
channels.slack.streaming.nativeTransport在channels.slack.streaming.mode="partial"时切换 Slack 原生流式 API 调用(chat.startStream/chat.appendStream/chat.stopStream) (nativeTransport默认为true)。- Slack 原生流式和 Slack 助手线程状态需要一个回复线程目标。顶层私信不会显示该线程式预览,但仍可 使用 Slack 草稿预览帖子和编辑。
旧版键迁移¶
| 渠道 | 旧版键 | 状态 |
|---|---|---|
| Telegram | streamMode、标量/布尔 streaming |
由 openclaw doctor --fix 重写为 streaming.mode;运行时不会读取 |
| Discord | streamMode、布尔 streaming |
由 openclaw doctor --fix 重写为 streaming.mode;运行时不会读取 |
| Slack | streamMode;布尔 streaming;旧版 nativeStreaming |
由 openclaw doctor --fix 重写为 streaming.mode(布尔/旧版形式还会重写为 streaming.nativeTransport);运行时不会读取 |
| Matrix | 标量/布尔 streaming |
由 openclaw doctor --fix 重写为 streaming.mode(包括 Matrix 的 "quiet" 模式);运行时不会读取 |
| Feishu | 布尔 streaming |
由 openclaw doctor --fix 重写为 streaming.mode;运行时不会读取 |
| QQ Bot | 布尔 streaming;streaming.c2cStreamApi |
由 openclaw doctor --fix 重写为 streaming.mode(布尔/c2cStreamApi 形式还会重写为 streaming.nativeTransport);运行时不会读取 |
运行时行为¶
Telegram¶
- 在私信和群组/主题中使用
sendMessage+editMessageText进行预览更新;最终文本会就地编辑当前预览。Telegram 临时 30 秒“正在输入”草稿(sendMessageDraft)不用于答案流式传输。 - 较短的初始预览仍会进行防抖以优化推送通知体验,但会在有限延迟后显示,以避免活动运行在视觉上保持静默。
- 较长的最终回复会复用预览消息作为第一个分块,并仅发送剩余分块。
block模式会在达到streaming.preview.chunk.maxChars(默认 800,上限为 Telegram 的 4096 编辑限制)时,将预览轮换为一条新消息;其他模式会将单个预览扩展到最多 4096 个字符。progress模式会在可编辑的状态草稿中保留工具进度;当答案流式传输已激活但尚无可用工具行时,会显示状态标签;完成时清除草稿,并通过正常投递发送最终答案。当父级让渡给已接受的子代理时,同一草稿会持续更新,直到它们稳定;参见 子代理让渡交接。- 当
channels.telegram.richMessages为true时,计划预览使用原生复选框;否则使用可读的 HTML 清单。已完成步骤会被勾选,当前活动步骤会标记为“进行中”。 - 如果在确认完成文本之前最终编辑失败,OpenClaw 会使用正常最终投递并清理过期的预览。
- 当明确启用 Telegram 块流式传输时,会跳过预览流式传输,以避免重复流式传输。
/reasoning stream可以将推理写入临时预览,该预览会在最终投递后删除。- Telegram 选中引用回复是一个例外:当
replyToMode不为"off"且存在选中的引用文本时,OpenClaw 会跳过该轮的答案预览流(最终答案必须通过原生引用回复路径),因此工具进度预览行无法渲染。没有选中引用文本的当前消息回复仍会保留预览流式传输。详见 Telegram 渠道文档。
Discord¶
- 使用发送 + 编辑预览消息。
block模式会在分块边界处更新预览,同时在编辑后的消息中保留答案的段落分隔符和代码围栏。- 当明确启用 Discord 块流式传输时,会跳过预览流式传输。
progress默认保持安静:仅显示标题、作者撰写的评论和推理、计划里程碑、审批请求,以及安全的当前操作和委派任务状态。状态不需要实用模型或模型撰写的开场白。中间工具失败和非零命令退出会被隐藏。streaming.progress.toolProgress: true会添加带图标的滚动工具日志。Telegram 共享安全的工作状态展示;其他渠道保留其现有进度布局。progress模式会在最终答案投递后删除状态草稿,因此繁忙渠道不会在回复上方留下孤立的工具日志。错误最终回复会保留草稿,作为失败轮次的记录。- 最终媒体、错误和显式回复负载会取消待处理的预览,而不会刷新新草稿,然后使用正常投递。
Slack¶
- 使用
streaming.progress.toolProgress: false的紧凑进度会保留最新的模型前言。当commentary: true、label: false且maxLines: 1时,它是一条斜体临时消息,不包含推理、工具图标、命令失败、计划或文件编辑计数器。第一条帖子会等待完整的前言,以便其 Slack 通知可读;后续前言会编辑该消息。可操作的审批请求保持可见。最终回答是一条新回复,并且只有在 Slack 确认送达后,预览才会被删除。成功的静默轮次也会移除其预览;显式消息工具发布的帖子会持久保留。 partial在可用时可以使用 Slack 原生流式(chat.startStream/append/stop)。block使用追加式草稿预览。- 在回复线程中,
progress默认流式传输 Slack 的原生代理卡片:一条消息承载旁白、实时计划卡片(已创建里程碑,或一行工作摘要,直到streaming.progress.toolProgress: true为每个工具调用提供一行)以及最终回答。常规进度更新按一秒间隔合并;需要关注的更新和完成会立即刷新。卡片仅出现在执行实际工作的轮次中,因此普通问题会在没有卡片的情况下得到回答。streaming.progress.nativeTaskCards: false会回退到 Block Kit 会话卡片。默认情况下,它显示评论和文本,包括斜体旁白和推理、可操作的审批请求,以及仅在显式配置时显示的纯标题。完成的卡片在可用时保留 在 OpenClaw 中打开 或 打开工作会话 链接。streaming.progress.toolProgress: true在工作时添加工具活动、计划检查清单、中间错误和恢复行,以及工具/文件/时间总计;完成的详细卡片仅保留文件差异总计。两种模式都不会添加表情符号、粗体文本或状态标题,除非轮次失败时显示一行纯 Failed。只有当卡片有内容可显示时才会发布,因此默认轮次如果只有工具活动则不显示卡片;一个正在工作或成功的卡片,如果其最后一个可见行消失(例如已解决的审批),则会被删除。助手的最终文本和错误回复使用正常投递;失败的轮次即使没有回复也会保留其标记为 Failed 的卡片。 - 仅当会话确实可打开时,卡片才包含 在 OpenClaw 中打开:
gateway.publicOrigin已设置,且gateway.controlUi.enabled不为false。 - 在没有回复线程的情况下,默认
progress轮次只保留最终回答,并在工作期间使用临时的hourglass_flowing_sand正在输入反应。已配置的typingReaction优先;""禁用它。任何显式的streaming.progress设置都会让顶层轮次加入预览,包括commentary: true或自定义label。唯一例外是nativeTaskCards: true,它只影响线程。空的进度设置保持静默。该规则使用合并后的根设置和账户设置。这包括普通的顶层 DM;Agent View 和 Assistant View 保持其线程行为。显式的off、partial和block模式保持不变。 - 原生和草稿预览流式传输会抑制该轮次的块回复,因此 Slack 回复只通过一条投递路径流式传输。
- 即使成功的轮次没有可见回复,也会删除其草稿卡片。失败的无回复轮次会保留其进度卡片并标记为 Failed,或者如果工作时没有出现卡片,则发布一个纯 Failed 卡片。
Mattermost¶
- 在
partial模式下,将思考和部分回复文本流式传输到单个草稿预览帖子中,当最终回答可以安全发送时,该帖子会就地定稿。 - 在
progress模式下,将思考和工具活动流式传输到单个状态预览中,当最终回答可以安全发送时,该预览会就地定稿。 - 在
block模式下,在已完成文本和工具活动帖子之间轮换;并行和连续的工具更新共享当前工具活动帖子。 - 如果预览帖子在定稿时已被删除或以其他方式不可用,则回退为发送一条新的最终帖子。
- 最终媒体/错误负载会在正常投递前取消待处理的预览更新,而不是刷新一个临时预览帖子。
Matrix¶
- 当最终文本可以复用预览事件时,草稿预览会就地定稿。
- 仅媒体、错误以及回复目标不匹配的最终结果会在正常投递前取消待处理的预览更新;已经可见的过期预览会被撤回。
工具进度预览更新¶
预览流式传输还可以包含 工具进度 更新:短状态行,例如“搜索网络”、“读取文件”或“调用工具”,在工具运行期间出现在同一条预览消息中,先于最终回复。在 Codex app-server 模式下,Codex 前言/评论消息使用相同的预览路径,因此简短的“我正在检查……”进度备注可以流式传输到可编辑草稿中,而不会成为最终回答的一部分。这使得多步工具轮次在首次思考预览和最终回答之间保持视觉上的活跃,而不是静默。
响应评论在工具交接过程中保持每个消息项的身份。后续工具更新不会将较早的评论作为额外的合并前言重放。
长时间运行的工具可能在返回前发出类型化进度。例如,web_fetch 在启动时设置一个五秒计时器:如果获取仍在等待中,预览会显示 Fetching page content...;如果获取在此之前完成或被取消,则不会发出进度行。稍后的最终工具结果仍会正常投递给模型。
支持的平台:
- Discord、Slack、Telegram 和 Matrix 在预览流式传输激活时,默认将工具进度和 Codex 前言更新流式传输到实时预览编辑中。Microsoft Teams 在个人聊天中使用其原生进度流。
- Telegram 自
v2026.4.22起已默认启用工具进度预览更新;保持启用可保留该已发布行为。 - Mattermost 在
partial和progress模式下将工具活动合并到一个预览帖子中,或在block模式下在文本块之间使用一个工具活动帖子(见上文)。 - 工具进度编辑遵循当前激活的预览流式传输模式;当预览流式传输为
off或块流式传输已接管消息时,它们会被跳过。在 Telegram 上,streaming.mode: "off"表示仅最终结果:通用进度信息也会被抑制,而不是作为独立状态消息投递,而审批提示、媒体负载和错误仍会正常路由。 streaming.preview.toolProgress(默认true)控制partial和block预览中的工具进度行;streaming.progress.toolProgress(默认false)让progress草稿加入滚动工具日志。要在隐藏命令/执行文本的同时保持工具进度行可见,请将streaming.preview.commandText或streaming.progress.commandText设置为"status"(默认值)。将任一选项设置为"raw"可启用命令文本。此策略由使用 OpenClaw 紧凑进度渲染器的草稿/进度通道共享,包括 Discord、Matrix、Microsoft Teams、Mattermost、Slack 会话卡片和 Telegram。要完全禁用预览编辑,请将streaming.mode设置为off。
进度草稿渲染¶
进度卡片 在启用计划更新时,会替换 partial、block 和 progress 预览中的完整计划状态。
可见步骤遵循通道的行数限制。清除卡片会移除其清单和状态,同时保留其他活动;如果草稿没有其他内容,则在通道支持删除时删除该草稿。Microsoft Teams 会用其进度标签替换已清除的
临时预览。当 streaming.progress.label: false 时,
Teams 会保留临时预览,直到下一次更新或最终回复。失败或被阻止的写入会保留之前的计划。活动预览会保留一条安全的
失败通知。
进度模式草稿(streaming.progress.*)具有以下按通道设置的配置:
| 键 | 默认值 | 行为 |
|---|---|---|
streaming.progress.maxLines |
8 |
草稿标签下方保留的最大紧凑进度行数 |
streaming.progress.maxLineChars |
120 |
截断前每条紧凑行的最大字符数(按词感知) |
streaming.progress.label |
"auto" |
草稿标题;自定义字符串,或 false 以隐藏它 |
streaming.progress.labels |
内置池 | 当 label: "auto" 时使用的候选标签 |
Slack 始终将进度模式渲染为其固定的会话卡片布局;这些 限制仍然约束该卡片内的活动行和计划文本。
评论进度通道¶
除工具进度外,紧凑进度渲染器还可以在草稿中显示另一个进度通道:
streaming.progress.commentary- 在进度草稿中,将模型在工具调用前的 评论(一段简短的“我将检查……然后……”叙述)与工具行交错渲染。在 Discord 和 Telegram 的进度模式下, 即使此可选通道关闭,同一前言也会提供状态标题;其他通道保持现有进度行为。参见 进度草稿。
当详细日志负责独立评论时,每个前言只发送一次。 缓冲的评论和工具摘要会在答案预览之前完成; 在最终投递开始后到达的纯文本进度会被抑制。
{
"channels": {
"discord": {
"streaming": { "mode": "progress", "progress": { "commentary": true } }
}
}
}
保持进度行可见,但隐藏原始命令/执行文本:
{
"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"
}
}
}
}
}
相关¶
- Agent loop - 发出这些流事件的回合生命周期
- Channel outbound API - 共享预览、持久发送和最终化 API
- Progress drafts - 在长回合期间更新的可见进行中消息
- Messages - 消息生命周期和投递
- Retry - 投递失败时的重试行为
- Typing indicators - 回合进行中显示的输入状态
- Channels - 按通道的流式支持
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw