How to Use OpenClaw Matrix Push Rules

Matrix push rules solve a specific problem: quiet streaming previews. When channels.matrix.streaming is quiet, OpenClaw edits a single preview event instead of posting every partial chunk as a new notification. That is calmer, but Matrix clients only notify on the final edit if the recipient has a push rule that matches OpenClaw's finalized-preview marker. Without that rule, users may miss the completed answer.

Start with the prerequisite

Use this guide only when you actually want quiet previews. If stock Matrix notification behavior is fine, use streaming: "partial" or leave streaming off. For quiet previews, set channels.matrix.streaming to quiet. Then identify three things: the recipient user who should receive notifications, the bot user that sends OpenClaw replies, and the recipient user's access token. The push rule is installed on the recipient account, not on the bot account.

Verify push delivery first

The docs warn that quiet preview rules only help when normal Matrix push delivery already works. Check existing pushers through the recipient account before adding a custom rule. If there are no pushers, fix the client or homeserver push setup first. A custom OpenClaw rule cannot repair a Matrix account that is not receiving normal push notifications. This small check saves a lot of false debugging later.

Install the override rule

The rule should match a finalized replacement event from the bot. OpenClaw marks finalized text-only preview edits with content["com.openclaw.finalized_preview"] = true. The docs also match m.room.message, the m.replace relationship type, and the bot's full MXID as sender. Actions notify, set the default sound, and avoid highlight. Use a unique rule id per bot per recipient, such as openclaw-finalized-preview-botname.

Keep identities exact

Replace the homeserver base URL, access token, rule id, and bot MXID before running the API call. The sender match should be the OpenClaw bot's full Matrix id, not the human recipient. The token should belong to the recipient user because that user's push rules decide what their devices notify about. If you manage multiple recipients, each recipient needs their own rule. There is no universal channel-level shortcut for every user's Matrix push account.

Operational checklist

Configure quiet streaming, verify normal pushers, install the rule, fetch it back through the Matrix API, and send a reply that streams long enough to create a preview edit. Confirm that intermediate edits stay quiet and the final edit notifies. The OpenClaw Playbook recommends storing the bot MXID, rule id pattern, and recipient rollout list. Matrix is powerful but exacting; write the exact identity and token assumptions down before calling the setup done.

Roll out per recipient

Matrix push rules are personal account settings, so treat rollout as a per-recipient operation. Keep a checklist of users who requested quiet preview notifications, the bot MXID used for each, and the rule id installed. If a user changes homeserver, client, or access token, rerun the verification rather than assuming the old rule still works. Also explain the tradeoff: quiet previews reduce notification noise during streaming, but they require this extra Matrix-side rule for final-answer alerts. Users are much more patient with the setup when they understand that it protects them from every partial edit buzzing their phone.

Final verification

Before calling How to Use OpenClaw Matrix Push Rules finished, perform one direct test, one failure test, and one rollback check. The direct test proves the happy path works. The failure test proves the documented guardrail is real, not just assumed. The rollback check tells the next operator how to undo the change without improvising. Save those notes beside the channel, node, or gateway config you changed. OpenClaw gets powerful when agents can act, but it stays trustworthy when every new surface has a small, repeatable verification habit attached to it.