Matrix Push Rules for Quiet Previews

When channels.matrix.streaming.mode is set to "quiet", OpenClaw sends the reply by updating a single preview event in place. These previews are dispatched as non-notifying m.notice events, and the final edit carries the content["com.openclaw.finalized_preview"] = true marker. Matrix clients only generate a notification for that final edit when a per-user push rule matches the marker. This documentation targets operators who self-host Matrix and need to configure that rule for each recipient account.

Drafts are finalized via the same path when streaming.mode: "progress" is active, so the same rule also triggers for progress-mode finalized edits.

If you prefer standard Matrix notification behavior, use streaming.mode: "partial" or disable streaming. Refer to Matrix channel setup.

Prerequisites

The recipient user is the person who should receive the notification.
The bot user is the OpenClaw Matrix account delivering the reply.
Use the recipient user's access token for all API calls listed below.
Match sender in the push rule against the bot user's full MXID.
The recipient account must have working pushers already; quiet preview rules depend on normal Matrix push delivery being functional.

Steps

Configure quiet previews

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

Get the recipient's access token

Reuse an existing client session token when possible. To generate a new 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": "REDACTED"
  }'

Verify pushers exist

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

If no pushers are returned, resolve normal Matrix push delivery for this account before proceeding.

Install the override push rule

Create a rule that matches the finalized-preview marker and the bot MXID as the sender:

curl -sS -X PUT \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" \
  -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 these values before execution:

https://matrix.example.org: your homeserver base URL
$USER_ACCESS_TOKEN: the recipient user's access token
openclaw-finalized-preview-botname: a rule ID that is unique per bot per recipient (format: openclaw-finalized-preview-<botname>)
@bot:example.org: your OpenClaw bot MXID, not the recipient's

Verify

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

Next, test a streamed reply. In quiet mode, the room displays a quiet draft preview and notifies once the block or turn finishes.

To remove the rule later, DELETE the same rule URL using the recipient's token.

Multi-bot notes

Push rules are identified by ruleId: running PUT again with the same ID updates a single rule. For multiple OpenClaw bots notifying the same recipient, create one rule per bot with a distinct sender match.

New user-defined override rules are placed ahead of server-default suppress rules, so no extra ordering parameter is needed. The rule only affects text-only preview edits that can be finalized in place; media replies, stale-preview fallbacks, and final texts that would trigger Matrix mentions are delivered as normal notifying messages instead.

Homeserver notes

Synapse

No special homeserver.yaml change is required. If normal Matrix notifications already reach this user, the recipient token and pushrules call above are the main setup steps.

If you run Synapse behind a reverse proxy or workers, ensure /_matrix/client/.../pushrules/ reaches Synapse correctly. Push delivery is handled by the main process or synapse.app.pusher / configured pusher workers, confirm those are healthy.

The rule uses the event_property_is push-rule condition (MSC3758, push rule v1.10), which was added to Synapse in 2023. Older Synapse releases accept the PUT pushrules/... call but silently never match the condition, upgrade Synapse if no notification arrives on a finalized preview edit.

Tuwunel

Same flow as Synapse; no Tuwunel-specific configuration is needed for the finalized preview marker.

If notifications disappear while the user is active on another device, check whether suppress_push_when_active is enabled. Tuwunel added this option in 1.4.2 (September 2025) and it can intentionally suppress pushes to other devices while one device is active.