OpenClaw Matrix Push Rules - Setting Up Quiet Preview Notifications

If you're running OpenClaw with Matrix as your messaging channel and you've tried quiet streaming mode, you've probably noticed something odd. The agent edits a message in place as it thinks, which is nice for avoiding notification spam. But then the final response doesn't notify you either. You glance at your phone twenty minutes later and realise the agent finished ages ago.

Quiet previews are a great feature in theory - they keep the channel clean while the agent is working. The problem is that Matrix's default push rules don't know how to distinguish between "agent is still editing its draft" and "agent is done, here's your answer." That's where custom push rules come in.

What Quiet Previews Actually Do

When you set channels.matrix.streaming to "quiet" in OpenClaw, the agent behaviour changes. Instead of sending multiple messages as it processes (which triggers a notification for each one), it creates a single message and edits it in place. Each edit updates the content as the agent progresses.

When the response is finalised, OpenClaw marks the final edit with a custom content flag: com.openclaw.finalized_preview = true. That flag is the hook you need. Install a push rule that matches it, and Matrix will notify you only when the agent is actually done.

The alternative is streaming: "partial", which sends partial messages and relies on standard Matrix notification behaviour. It works but it's noisy. If you get ten notifications while the agent is mid-thought, you'll switch to quiet mode pretty quickly.

Prerequisites Before You Start

A few things need to be in place before this works:

• You need a self-hosted Matrix homeserver (Synapse, Tuwunel, or similar)
• The recipient user (the person who should get notifications) needs working pushers already configured. If normal Matrix notifications aren't reaching them, fix that first - quiet preview rules won't help if the underlying push delivery is broken
• You need the recipient user's access token for the API calls
• You need the full MXID of the OpenClaw bot user (like @bot:example.org)

Don't mix up the bot and recipient accounts. The push rule goes on the recipient's account but matches against the bot's sender MXID.

Step-by-Step Setup

1. Enable Quiet Previews in OpenClaw

In your OpenClaw configuration:

{
  "channels": {
    "matrix": {
      "streaming": "quiet"
    }
  }
}

2. Get the Recipient's Access Token

Reuse an existing session token if you have one. Otherwise, mint a fresh one:

curl -sS -X POST \
  "https://matrix.example.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "m.login.password",
    "identifier": { "type": "m.id.user", "user": "@alice:example.org" },
    "password": "YOUR_PASSWORD"
  }'

3. Check That Pushers Exist

Before installing the push rule, verify the recipient has working pushers:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushers"

If this comes back empty, stop. Go fix normal Matrix push delivery for this account. There's no point adding a custom rule if the push infrastructure isn't working.

4. Install the Override Push Rule

This is the important bit. The rule matches four conditions: the event type is a message, it's an edit (replacement), it has the finalized preview flag, and it's from your specific bot:

curl -sS -X PUT \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-mybot" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "conditions": [
      { "kind": "event_match", "key": "type", "pattern": "m.room.message" },
      {
        "kind": "event_property_is",
        "key": "content.m\\.relates_to.rel_type",
        "value": "m.replace"
      },
      {
        "kind": "event_property_is",
        "key": "content.com\\.openclaw\\.finalized_preview",
        "value": true
      },
      { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" }
    ],
    "actions": [
      "notify",
      { "set_tweak": "sound", "value": "default" },
      { "set_tweak": "highlight", "value": false }
    ]
  }'

Replace the obvious placeholders: your homeserver URL, the access token, the rule ID (use a pattern like openclaw-finalized-preview-botname), and the bot's full MXID.

5. Verify the Rule

Check that the rule was installed correctly:

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-mybot"

Then test it. Send a message to the bot in quiet mode. You should see the preview updating silently, then get a single notification when the response is finalised.

Multiple Bots, Multiple Rules

Push rules are keyed by their rule ID. If you run multiple OpenClaw bots that talk to the same user, you need one rule per bot. Each rule has a different rule ID and a different sender match.

The naming convention openclaw-finalized-preview-<botname> keeps things organised. Re-running PUT against the same rule ID updates the existing rule rather than creating a duplicate.

New user-defined override rules are inserted ahead of Matrix's default suppress rules automatically, so you don't need to worry about ordering.

Homeserver-Specific Notes

Synapse

No special homeserver.yaml changes needed. If normal notifications already work for the user, the push rule is all you need. If you're running Synapse behind a reverse proxy or with worker processes, make sure the /_matrix/client/.../pushrules/ path reaches Synapse correctly. Push delivery happens through the main process or configured pusher workers - make sure those are healthy.

Tuwunel

Same flow as Synapse, no Tuwunel-specific config required. One thing to watch: if notifications disappear while the user is active on another device, check whether suppress_push_when_active is enabled. Tuwunel added this in version 1.4.2 (September 2025), and it intentionally suppresses pushes when a device is already active. That's usually what you want for human conversations, but it can cause missed notifications from bots if the user happens to have Element open on their desktop.

When to Use Quiet vs Partial Streaming

Quiet mode is best when:

• The agent takes a while to respond and you don't want notification spam
• You're using the bot in a room with other people and want to keep things tidy
• You value a clean notification that says "the agent is done" over real-time streaming

Partial mode is better when:

• You want to see the agent's thinking as it happens
• Response time is fast enough that streaming doesn't generate excessive notifications
• You're debugging and want to watch the agent's output develop

We've settled on quiet mode for most production deployments. The notification experience is cleaner, and the push rule setup is a one-time cost per user.

Removing the Rule

If you decide to switch back to partial streaming or turn off quiet mode, delete the push rule:

curl -sS -X DELETE \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-mybot"

Why This Matters for AI Agent Deployments

This might seem like a niche configuration detail, and honestly it is. But getting notification behaviour right is one of those things that determines whether people actually use an AI agent or just forget about it.

We've deployed OpenClaw for clients using various messaging channels, and the pattern is always the same: the AI capability gets people excited, but the day-to-day experience determines whether they keep using it. A bot that bombards you with notifications gets muted. A bot that never notifies you gets forgotten. Quiet previews with proper push rules hit the sweet spot.

If you're evaluating OpenClaw or other AI agent platforms for your organisation, the messaging integration details matter more than they look like on paper. We help organisations set up production AI agent deployments through our managed services, including the integration and notification plumbing that makes the difference between a demo and a tool people rely on.

For the full Matrix channel setup, check the OpenClaw Matrix documentation. And if you're exploring which messaging platform works best for your AI agent deployment, get in touch - we've tried most of them and have opinions.