|
| 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) |
0 commit comments