@@ -0,0 +1,284 @@
1+---
2+summary: "Progress drafts: one visible work-in-progress message that updates while an agent runs"
3+read_when:
4+ - Configuring visible progress updates for long-running chat turns
5+ - Choosing between partial, block, and progress streaming modes
6+ - Explaining how OpenClaw updates one channel message while work is in progress
7+ - Troubleshooting progress drafts, standalone progress messages, or finalization fallback
8+title: "Progress drafts"
9+---
10+11+Progress drafts make long-running agent turns feel alive in chat without turning
12+the conversation into a stack of temporary status replies.
13+14+When progress drafts are enabled, OpenClaw creates one visible work-in-progress
15+message, updates it while the agent reads, plans, calls tools, or waits for
16+approval, and then turns that draft into the final answer when the channel can
17+do that safely.
18+19+```text
20+Shelling
21+- reading recent channel context
22+- checking matching issues
23+- preparing reply
24+```
25+26+Use progress drafts when you want one tidy status message during tool-heavy work
27+and the final answer when the turn is done.
28+29+## Quick Start
30+31+Enable progress drafts per channel with `streaming.mode: "progress"`:
32+33+```json5
34+{
35+ channels: {
36+ discord: {
37+ streaming: {
38+ mode: "progress",
39+ },
40+ },
41+ },
42+}
43+```
44+45+That is usually enough. OpenClaw will pick an automatic one-word label, add
46+compact progress lines while useful work happens, and suppress duplicate
47+standalone progress chatter for that turn.
48+49+## What Users See
50+51+A progress draft has two parts:
52+53+| Part | Purpose |
54+| -------------- | ----------------------------------------------------------------- |
55+| Label | A short title such as `Thinking` or `Shelling`. |
56+| Progress lines | Compact run updates such as tool calls, task steps, or approvals. |
57+58+The label appears immediately when the agent starts replying. Progress lines are
59+added only when the agent emits useful work updates. The final answer replaces
60+the draft when possible; otherwise OpenClaw sends the final answer normally and
61+cleans up or stops updating the draft according to the channel's transport.
62+63+## Choose A Mode
64+65+`channels.<channel>.streaming.mode` controls the visible in-progress behavior:
66+67+| Mode | Best for | What appears in chat |
68+| ---------- | -------------------------------- | ------------------------------------------------- |
69+| `off` | Quiet channels | Only the final answer. |
70+| `partial` | Watching answer text appear | One draft edited with the latest answer text. |
71+| `block` | Larger answer-preview chunks | One preview updated or appended in bigger chunks. |
72+| `progress` | Tool-heavy or long-running turns | One status draft, then the final answer. |
73+74+Choose `progress` when users care more about "what is happening" than watching
75+the answer text stream token by token.
76+77+Choose `partial` when the answer itself is the progress signal.
78+79+Choose `block` when you want draft preview updates in larger text chunks. On
80+Discord and Telegram, `streaming.mode: "block"` is still preview streaming, not
81+normal block delivery. Use `streaming.block.enabled` or legacy
82+`blockStreaming` when you want normal block replies.
83+84+## Configure Labels
85+86+Progress labels live under `channels.<channel>.streaming.progress`.
87+88+The default label is `auto`, which chooses from OpenClaw's built-in single-word
89+label pool:
90+91+```text
92+Thinking
93+Shelling
94+Scuttling
95+Clawing
96+Pinching
97+Molting
98+Bubbling
99+Tiding
100+Reefing
101+Cracking
102+Sifting
103+Brining
104+Nautiling
105+Krilling
106+Barnacling
107+Lobstering
108+Tidepooling
109+Pearling
110+Snapping
111+Surfacing
112+```
113+114+Use a fixed label:
115+116+```json5
117+{
118+ channels: {
119+ discord: {
120+ streaming: {
121+ mode: "progress",
122+ progress: {
123+ label: "Investigating",
124+ },
125+ },
126+ },
127+ },
128+}
129+```
130+131+Use your own automatic label pool:
132+133+```json5
134+{
135+ channels: {
136+ discord: {
137+ streaming: {
138+ mode: "progress",
139+ progress: {
140+ label: "auto",
141+ labels: ["Checking", "Reading", "Testing", "Finishing"],
142+ },
143+ },
144+ },
145+ },
146+}
147+```
148+149+Hide the label and show only progress lines:
150+151+```json5
152+{
153+ channels: {
154+ discord: {
155+ streaming: {
156+ mode: "progress",
157+ progress: {
158+ label: false,
159+ },
160+ },
161+ },
162+ },
163+}
164+```
165+166+## Control Progress Lines
167+168+Progress lines are enabled by default in progress mode. They come from real run
169+events: tool starts, item updates, task plans, approvals, command output, patch
170+summaries, and similar agent activity.
171+172+Limit how many lines stay visible:
173+174+```json5
175+{
176+ channels: {
177+ discord: {
178+ streaming: {
179+ mode: "progress",
180+ progress: {
181+ maxLines: 4,
182+ },
183+ },
184+ },
185+ },
186+}
187+```
188+189+Keep the single progress draft but hide tool and task lines:
190+191+```json5
192+{
193+ channels: {
194+ discord: {
195+ streaming: {
196+ mode: "progress",
197+ progress: {
198+ toolProgress: false,
199+ },
200+ },
201+ },
202+ },
203+}
204+```
205+206+With `toolProgress: false`, OpenClaw still suppresses the older standalone
207+tool-progress messages for that turn. The channel stays visually quiet until the
208+final answer, except for the label if one is configured.
209+210+## Channel Behavior
211+212+Each channel uses the cleanest transport it supports:
213+214+| Channel | Progress transport | Notes |
215+| --------------- | -------------------------------------- | --------------------------------------------------------------------- |
216+| Discord | Send one message, then edit it. | Final text edits in place when it fits one safe preview message. |
217+| Matrix | Send one event, then edit it. | Account-level streaming config controls account-level drafts. |
218+| Microsoft Teams | Native Teams stream in personal chats. | `streaming.mode: "block"` maps to Teams block delivery. |
219+| Slack | Native stream or editable draft post. | Thread availability affects whether native streaming can be used. |
220+| Telegram | Send one message, then edit it. | Older visible drafts may be replaced so final timestamps stay useful. |
221+| Mattermost | Editable draft post. | Tool activity is folded into the same draft-style post. |
222+223+Channels without safe edit support usually fall back to typing indicators or
224+final-only delivery.
225+226+## Finalization
227+228+When the final answer is ready, OpenClaw tries to keep the chat clean:
229+230+- If the draft can safely become the final answer, OpenClaw edits it in place.
231+- If the channel uses native progress streaming, OpenClaw finalizes that stream
232+ when the native transport accepts the final text.
233+- If the final answer has media, an approval prompt, an explicit reply target,
234+ too many chunks, or a failed edit/send, OpenClaw sends the final answer through
235+ the normal channel delivery path.
236+237+The fallback path is intentional. It is better to send a fresh final answer than
238+to lose text, mis-thread a reply, or overwrite a draft with a payload the channel
239+cannot represent safely.
240+241+## Troubleshooting
242+243+**I only see the final answer.**
244+245+Check that `channels.<channel>.streaming.mode` is set to `progress` for the
246+account or channel that handled the message. Some group or quote-reply paths may
247+disable draft previews for a turn when the channel cannot safely edit the right
248+message.
249+250+**I see the label but no tool lines.**
251+252+Check `streaming.progress.toolProgress`. If it is `false`, OpenClaw keeps the
253+single draft behavior but hides tool and task progress lines.
254+255+**I see a fresh final message instead of an edited draft.**
256+257+That is a safety fallback. It can happen for media replies, long answers,
258+explicit reply targets, old Telegram drafts, missing Slack thread targets,
259+deleted preview messages, or failed native stream finalization.
260+261+**I still see standalone progress messages.**
262+263+Progress mode suppresses default standalone tool-progress messages when a draft
264+is active. If standalone messages still appear, verify that the turn is actually
265+using progress mode and not `streaming.mode: "off"` or a channel path that
266+cannot create a draft for that message.
267+268+**Teams behaves differently from Discord or Telegram.**
269+270+Microsoft Teams uses a native stream in personal chats instead of the generic
271+send-and-edit preview transport. Teams also treats `streaming.mode: "block"` as
272+Teams block delivery because it does not have the same draft-preview block mode
273+used by Discord and Telegram.
274+275+## Related
276+277+- [Streaming and chunking](/concepts/streaming)
278+- [Messages](/concepts/messages)
279+- [Channel configuration](/gateway/config-channels)
280+- [Discord](/channels/discord)
281+- [Matrix](/channels/matrix)
282+- [Microsoft Teams](/channels/msteams)
283+- [Slack](/channels/slack)
284+- [Telegram](/channels/telegram)
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。