OpenClaw Matrix message behaviour

A Matrix client notifies on every message, which is why a streaming bot that edits its reply in place can be either pleasant or unbearable depending on one setting. OpenClaw's Matrix streaming is off by default and offers a quiet mode built for self-hosted homeservers. Here are the streaming modes and the block switch, the caveats, voice notes, and reactions with custom emotes.

Streaming modes

• Reply streaming is opt-in: the streaming mode controls how the in-flight reply is delivered and the block switch controls whether each completed block is kept as its own Matrix message, with the docs' first example enabling partial mode and the second keeping live answer previews while hiding interim tool and progress lines through the preview tool-progress flag.
• Off, the default, waits for the full reply and sends once; partial edits one normal text message in place as the model writes the current block, where stock clients may notify on the first preview rather than the final edit; quiet is the same as partial but the message is a non-notifying notice, with recipients notified once a per-user push rule matches the finalised edit; and progress sends individual compact progress lines through a progress draft.
• The block switch is independent of the mode: with partial or quiet it keeps a live draft for the current block and, when on, keeps completed blocks as messages rather than finalising in place, and with off it sends one notifying message per finished block when on or one message for the whole reply when off.
• The progress options are a label that can be custom, automatic from configured or built-in candidates, or hidden, the candidate labels used only in automatic mode, the maximum rolling lines with older ones trimmed, the characters per compact line before truncation, and the tool-progress flag that adds live tool activity including failures to the draft, off by default so the draft keeps to its headline, commentary, plan milestones and approval requests while terminal errors still use normal delivery.

Preview edits cost extra Matrix API calls.

Caveats and voice notes

If a preview grows past Matrix's per-event size limit OpenClaw stops preview streaming and falls back to final-only delivery. Media replies always send attachments normally, and when a visible preview cannot be reused safely OpenClaw keeps it until the complete replacement is confirmed and then redacts it, leaving the preview visible if replacement delivery fails, is partial or produces no visible event. Tool-progress preview updates are on by default whenever preview streaming is active, and the preview tool-progress flag set to false keeps preview edits for answer text while tool progress takes the normal delivery path. Preview edits cost extra Matrix API calls, so the most conservative rate-limit profile is streaming off, and legacy scalar or boolean streaming values and the flat block-streaming and chunk-mode keys are rewritten to the nested shape by the doctor fix. Inbound voice notes are transcribed before the room mention gate, so a voice note saying the bot's name can trigger the agent in a mention-required room and the agent gets the transcript rather than an audio placeholder; Matrix uses the shared audio media provider, audio events and file events with an audio MIME type are eligible, encrypted rooms decrypt the attachment through the existing media path before transcription, the transcript is marked machine-generated and untrusted, the attachment is marked already transcribed so downstream tools skip it, and audio transcription can be disabled globally.

Reactions and emotes

• Outbound reaction tooling is gated by the reactions action: react adds a reaction to an event, reactions lists the current summary for an event, emoji-list discovers custom emoji from the current room's packs and your personal pack, an empty emoji removes the bot's own reactions on the event, and the remove flag removes only the specified emoji.
• Emoji-list reads the MSC2545 room emote packs from the authorised current room and the user emotes account data, returns up to a hundred sorted entries with a name, an identifier and the media URL while excluding sticker-only entries, and the identifier passed to react is the plain shortcode stored as the reaction key rather than the media URL, with the URL included separately because custom-reaction rendering depends on the client.
• Resolution order takes the first defined value: the ack reaction from the account, the channel, the global setting and then the agent identity emoji, the ack scope from the account, the channel, the global setting and then the group-mentions default, and reaction notifications from the account, the channel and then own, which forwards added reaction events targeting bot-authored messages while off disables them; reaction removals are not synthesised into events because Matrix surfaces them as redactions.

OpenClaw on Matrix is the channel post this behaviour belongs to, and OpenClaw Matrix push rules for quiet previews the homeserver-side rule that makes quiet mode notify.

Quiet by design

The quiet mode exists because Matrix cannot mark an edit as the important one on its own; the bot sends notices, and the recipient's homeserver decides which edit rings. OpenClaw Slack message behaviour shows the card-based answer to the same problem on Slack, and OpenClaw Matrix rich messages the other native Matrix surfaces.

On Diali

Matrix is on Diali’s connectable list, alongside WhatsApp, Telegram, Discord, Slack, Mattermost, SMS and voice: the homeserver account and the room allowlist are yours, the Gateway is ours. Hosted OpenClaw on Diali is the assistant and Diali security describes the boundary that applies to each connected channel.

• Streaming off by default; quiet sends notices until a push rule fires.
• Voice notes are transcribed before the mention gate.
• Custom emotes react by shortcode, not by media URL.