跳转至

进度草稿

Progress drafts 将一条频道消息变成实时状态行,在代理工作时持续更新,而不是一堆临时“仍在处理”回复。设置 channels.<channel>.streaming.mode: "progress" 后,OpenClaw 会在实际工作开始时创建消息,并在代理读取、规划、调用工具或等待批准时编辑该消息,最后交付最终答案。

Checking the streaming behavior and running the focused tests.
✅ Read the channel docs
▸ Run the focused tests
▢ Summarize the result

默认草稿会显示状态标题、已编写的计划步骤和批准请求。在 Discord 和 Telegram 上,它还会保持当前操作和委派任务状态可见,而不显示详细的工具日志或实用模型。中间工具失败和非零命令退出码不会出现在草稿中。设置 streaming.progress.toolProgress: true 可添加滚动工具日志,包括工具失败,例如 Bash: run tests 这样的行。Discord 和 Telegram 会为每个工具行添加对应工具的文字字形前缀,例如 📖 Read: from docs/index.md;其他频道保持纯文本行。频道插件通过 createChannelProgressDraftCompositor 的 toolIcons 选项选择加入。

Note

Discord 和 Telegram 默认使用 progress,无需额外配置。在任一频道上设置 mode: "partial" 可改为流式传输答案文本,或设置 mode: "off" 以禁用预览。已有的显式模式会被保留。完整逐频道默认表见 流式传输与分块。

快速开始

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

从此处开始默认:1.5 秒的启动延迟,在有实际工作时保持安静的状态草稿,并抑制该轮次中旧的独立进度消息。原始工具行草稿使用自动的单词标签;状态标题会省略该冗余标题,除非你显式配置一个。

本页介绍进度草稿体验及其配置项。完整的流式模式矩阵、逐频道运行时说明和旧键迁移,见 流式传输与分块。

用户看到的内容

部分 用途
状态标题 在 Discord 和 Telegram 上,是模型前言;Discord 会添加实用填充内容。
标签 可选的起始/状态行,例如 Working。
进度行 计划里程碑、已启用的评论/推理以及批准请求。
工具日志 可选工具行,使用与 /verbose 相同的详细格式器。

状态标题位于进度行上方。当 progress.toolProgress: true 时,工具行仍显示在其下方。

对于原始工具进度,标签会在代理开始有意义的工作并持续忙碌初始延迟期间出现。 它位于滚动进度行列表的顶部,因此当出现足够多的具体工作行后就会滚动消失。当存在状态标题时,隐式标签会被隐藏,除非你显式配置一个。纯文本回复永远不会显示进度草稿;只有实际工作更新才会出现行,例如 Bash: run tests、Web Search: for "discord edit message" 或 Write: to /tmp/file。

最终交付取决于频道和传输方式。OpenClaw 要么定稿草稿,要么发送单独答案并清理或停止更新草稿(见 定稿)。

选择模式

channels.<channel>.streaming.mode 控制可见的处理中行为:

模式 最适合 聊天中显示的内容
off 安静频道 仅最终答案。
partial 观察答案文本出现 一个草稿,用最新答案文本编辑。
block 更大的答案预览块 一个预览,以更大的块更新或追加。
progress 工具密集或长时间运行的轮次 一个状态草稿,然后是最终答案。

当用户更关心“正在发生什么”,而不是逐 token 观察答案文本流式传输时,选择 progress;当答案文本本身就是进度信号时,选择 partial;需要更大的预览块时选择 block。在 Discord 和 Telegram 上,streaming.mode: "block" 仍然是预览流式传输,而不是正常的块回复交付——请使用 streaming.block.enabled 来实现该功能。

配置标签

进度标签位于 channels.<channel>.streaming.progress 下。默认原始工具行标签是 "auto",它使用内置的纯文本 Working 标签。状态标题会隐藏该隐式标签;如果你也想在其上方显示标签,请显式设置 label: "auto":

Working

使用固定标签:

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          label: "Investigating",
        },
      },
    },
  },
}

使用你自己的标签池(当 label: "auto" 时仍会随机/按种子选择):

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          label: "auto",
          labels: ["Checking", "Reading", "Testing", "Finishing"],
        },
      },
    },
  },
}

隐藏标签,仅显示进度行:

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          label: false,
        },
      },
    },
  },
}

控制进度行

进度行来自实际运行事件:工具启动、项目更新、任务计划、批准、命令输出、补丁摘要以及类似的代理活动。progress.toolProgress 决定普通工具调用是否变成状态标题下方的滚动行。它在所有频道上默认为 false,以保持草稿安静:标题、已启用的评论和推理、计划里程碑以及批准请求仍会显示。中间工具失败和非零命令退出码会与其他工具行一起隐藏;阻止轮次完成的失败仍会通过正常错误交付显示。将其设置为 true 以启用滚动工具日志。成功的后台进程轮询和内部等待不会添加例行行。失败的调用仍遵循所选的工具进度策略;/verbose 会保留其诊断摘要。

在 Discord 和 Telegram 上,静默草稿保留一行当前操作状态和有限数量的委派任务状态行。这些行使用公开的操作名称和任务标签,绝不使用命令文本、参数、子级文本或结果。较旧操作的迟到完成不能替换当前显示的操作。其他进度频道保留其现有展示方式。启用工具日志后,生命周期更新会为每个 worker 复用一行。发送给 worker 的消息会获得独立条目,因为发送消息并不能证明某个 worker 已开始运行。委派提示不会包含在这些进度行中。

工具也可以在单个调用仍在运行时发出类型化进度。这就是缓慢的获取或搜索在工具返回最终结果之前更新可见草稿的方式。进度更新是一个部分工具结果,具有空的模型内容和明确的公开频道元数据:

{
  "content": [],
  "progress": {
    "text": "Fetching page content...",
    "visibility": "channel",
    "privacy": "public",
    "id": "web_fetch:fetching"
  }
}

OpenClaw 仅在频道进度 UI 中渲染 progress.text。常规工具结果仍会稍后以 content/details 形式到达,并且是唯一返回给模型的部分。

为工具添加进度时,应发出简短、通用的消息,并延迟该消息,直到操作已挂起足够长时间而变得有用。web_fetch 正是这样做的,使用 5 秒延迟:

const clearProgressTimer = scheduleToolProgress(
  onUpdate,
  { text: "Fetching page content...", id: "web_fetch:fetching" },
  5_000,
  { signal },
);

try {
  return await runToolWork();
} finally {
  clearProgressTimer();
}

快速调用不显示进度行;长时间调用在仍挂起时显示一行;已取消的调用会在过期进度出现之前清除计时器。进度文本是公开的 UI 侧通道,因此绝不能包含机密、原始参数、获取的内容、命令输出或页面文本。

详情模式

OpenClaw 对进度草稿和 /verbose 使用相同的格式化器:

{
  agents: {
    defaults: {
      toolProgressDetail: "explain", // explain | raw
    },
  },
}

"explain" 是默认值,并使用简洁标签保持草稿稳定。 "raw" 在可用时附加底层工具详情。命令文本还需要下面显式的 streaming.progress.commandText: "raw" 选择加入。 启用该选择加入后,node --check /tmp/app.js 调用会按模式呈现不同结果:

模式 进度行
explain check js syntax for /tmp/app.js
raw check js syntax for /tmp/app.js · node --check /tmp/app.js

命令/执行文本

streaming.progress.commandText(默认 "status")控制 exec/bash 进度行旁边显示多少命令详情,独立于上面的详情模式。将其设置为 "raw" 以选择加入命令文本;保留 "status" 以仅显示工具进度状态:

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          toolProgress: true,
          commandText: "raw",
        },
      },
    },
  },
}

评论通道

streaming.progress.commentary(默认 false)将模型的工具前评论/前言旁白(💬,例如 "我会检查……然后……")与草稿中的工具行交错显示。有关跨频道共享的配置形状,请参阅 流式传输与分块。

启用评论通道后,前言仅渲染为那些交错的 💬 行;下方的状态标题保持不显眼,以便该通道保持其文档中描述的形状。

状态标题

在 Discord 和 Telegram 的进度模式下,只要模型键入的工具前前言可用,它就会成为草稿的状态标题。其他进度模式频道保留其现有状态行为。标题默认开启,并且不会绕过短回合的正常活动门控;启用 streaming.progress.commentary 会将前言交给交错的评论通道处理。

在 Telegram 上,/verbose on 和 /verbose full 会保留此临时前言标题,同时单独发送工具诊断信息。前言不会被复制到最终答案中。

在 Discord 上,当为代理解析出 utility 模型时——显式的 utilityModel,或主要提供商声明的小模型默认值(OpenAI → gpt-5.6-luna, Anthropic → claude-haiku-4-5)——当模型未发出前言或已安静约 20 秒时,它会提供一段简短的通俗语言填充文本 (目前 Telegram 的标题仅基于前言):

Updating the default model in your config, then restarting the gateway to pick
it up. One agent listing call failed and is being retried.

Utility 旁白默认开启(streaming.progress.narration,默认 true),并且从不回退到主模型:它仅在存在显式 utilityModel 或代理主要提供商所声明的默认值时运行。设置 utilityModel: "" 可完全禁用 utility 路由。当 progress.toolProgress 启用时,工具行会继续在下方累积。草稿 编辑仍会等待正常活动门控和实际 文本变化,这可以避免快速回合中的闪烁,并减少繁忙频道中的编辑抖动。设置 narration: false 可仅禁用 utility 模型填充文本;模型 前言标题仍保持启用:

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          narration: false,
        },
      },
    },
  },
}

旁白输入是有界且经过脱敏的:utility 模型会收到入站请求文本,以及草稿本应渲染的相同紧凑、脱敏的工具摘要——绝不包含原始命令输出或工具结果。当 commandText: "status" 时,旁白输入也会省略 exec/bash 命令文本, 与草稿显示的内容保持一致。

旁白属于当前回合。结束或替换该回合会取消其待处理的 utility-model 请求,并防止迟到的结果更新草稿。 在旁白请求期间累积的工具活动会在该请求完成时重新考虑,因此符合条件的状态更新无需额外事件。

行数限制

限制保持可见的行数(默认 8):

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          maxLines: 4,
        },
      },
    },
  },
}

当 toolProgress: true 时,来自任意命名工具的命令退出行和失败项行使用普通工具日志容量。这包括内置、插件和自定义工具,无需维护名称列表。一个滚动活动槽位会与计划一起保持可见,因此失败行会在发生时出现,然后随着较新的活动到达而滚动消失。 审批请求、阻止/错误状态和未命名失败仍然优先。当工具日志隐藏时,工具失败和非零退出也会被隐藏;审批请求仍保持可见。

进度行会自动压缩,以减少草稿编辑期间聊天气泡的重排,并且 OpenClaw 会截断长行,使重复的草稿编辑不会在每次更新时以不同方式换行。默认每行预算为 120 个字符;文本在单词边界处截断,而路径或原始命令等长细节会用中间省略号缩短,以便后缀保持可见。 相同预算也适用于准备好的工具标题,包括嵌入在 Read 标题中的路径,而不仅适用于单独的工具细节。 在 Telegram 上,预算包括工具图标、标签和状态,以及命令或细节文本。

调整每行预算:

{
  channels: {
    discord: {
      streaming: {
        mode: "progress",
        progress: {
          maxLineChars: 160,
        },
      },
    },
  },
}

显示工具日志

将滚动工具日志添加到单个进度草稿中:

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

在默认 toolProgress: false 下,OpenClaw 仍会抑制该回合中较旧的独立工具进度消息;草稿会显示标题、撰写文本、计划里程碑和审批请求。Discord 和 Telegram 还会显示安全的当前操作和委派任务状态。工具诊断信息仍可在会话记录中查看。

渠道行为

渠道 进度传输 备注
Discord 发送一条消息,然后编辑它。 progress 是默认值;最终答案落地后,状态草稿会被删除。
Matrix 发送一个事件,然后编辑它。 账户级流式配置控制账户级草稿。
Microsoft Teams 个人聊天中的原生 Teams 流。 streaming.mode: "block" 会映射为 Teams 块传输。
Slack 原生流或可编辑草稿帖子。 卡片样式是默认值;progress.style: "compact" 使用临时文本草稿,在最终答案交付后删除。
Telegram 发送一条消息,然后编辑它。 如果一条消息落在进度草稿和答案之间,草稿会在其下方重新发布(先发布新消息再删除旧消息),而不是让客户端滚动跳转。
Mattermost 可编辑草稿帖子。 block 模式在已完成文本和工具活动帖子之间轮换;其他模式将工具活动折叠到同一草稿样式帖子中。

不支持安全编辑的渠道会回退到输入指示器或仅最终交付。有关每个渠道的完整运行时行为分解,请参阅流式传输和分块。

定稿

当最终答案准备好时,OpenClaw 会尝试保持聊天整洁:

  • 一个 Telegram 或 Discord 进度草稿如果移交给已接受的公告子代理,则在父代理让出后仍保持可见,并继续显示子状态和准备好的操作名称;最终答案单独发送。请参阅 子代理让出移交。

  • 否则,在 Discord 的 progress 模式下,最终答案会作为新消息发送,并且一旦该答案交付,状态草稿就会被删除。繁忙渠道不会在回复上方保留孤立的工具日志;错误最终结果会保留草稿,作为失败回合的可见记录。

  • 如果草稿可以安全地成为最终答案(partial/block 模式),OpenClaw 会就地编辑它。
  • Slack 的紧凑进度样式会将最终答案作为新消息发布,并在确认交付后删除其临时草稿。交付失败会保留草稿可见。
  • 如果渠道使用原生进度流式传输,OpenClaw 会在原生传输接受最终文本时定稿该流。
  • 否则(媒体、审批提示、显式回复目标、过多分块,或编辑/发送失败),OpenClaw 会通过正常渠道交付路径发送最终答案,而不是覆盖草稿。

回退是有意为之:发送新的最终答案优于丢失文本、错误线程化回复,或用渠道无法安全表示的负载覆盖草稿。

故障排查

我只看到最终答案。

检查处理该消息的账户或频道的 channels.<channel>.streaming.mode 是否为 progress。某些群组或引用回复路径会在频道无法安全编辑正确消息时,禁用该回合的草稿预览。

我看到标签但没有工具行。

检查 streaming.progress.toolProgress。它默认为 false,这会保留单个草稿但隐藏滚动的工具行;将其设置为 true 以显示完整工具日志。

我看到一条新的最终消息,而不是编辑后的草稿。

这是 最终化 中描述的安全回退机制。它可能发生在媒体回复、长答案、显式回复目标、旧版 Telegram 草稿、缺失的 Slack 线程目标、已删除的预览消息或原生流最终化失败时。

我仍然看到独立的进度消息。

进度模式会在草稿处于活动状态时抑制默认的独立工具进度消息。如果仍然出现独立消息,请确认该回合确实正在使用 progress 模式,而不是 streaming.mode: "off" 或无法为该消息创建草稿的频道路径。

Teams 的行为与 Discord 或 Telegram 不同。

Microsoft Teams 在个人聊天中使用原生流,而不是通用的发送并编辑预览传输方式,并将 streaming.mode: "block" 映射到 Teams 块传输,因为它没有像 Discord 和 Telegram 那样的草稿预览块模式。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw