Use this file to discover all available pages before exploring further.

Matrix push rules for quiet previews

When

text

channels.matrix.streaming

text

"quiet"

, OpenClaw edits a single preview event in place and marks the finalized edit with a custom content flag. Matrix clients notify on the final edit only if a per-user push rule matches that flag. This page is for operators who self-host Matrix and want to install that rule for each recipient account.

If you only want stock Matrix notification behavior, use

text

streaming: "partial"

or leave streaming off. See Matrix channel setup.

Prerequisites

recipient user = the person who should receive the notification
bot user = the OpenClaw Matrix account that sends the reply
use the recipient user's access token for the API calls below
match
text
sender
in the push rule against the bot user's full MXID
the recipient account must already have working pushers — quiet preview rules only work when normal Matrix push delivery is healthy

Steps

Configure quiet previews

```json5} { channels: { matrix: { streaming: "quiet", }, }, } ```

Get the recipient's access token

Reuse an existing client session token where possible. To mint a fresh one:


text
```bash}
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

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


text
If no pushers come back, fix normal Matrix push delivery for this account before continuing.

Install the override push rule

OpenClaw marks finalized text-only preview edits with `content["com.openclaw.finalized_preview"] = true`. Install a rule that matches that marker plus the bot MXID as sender:


text
```bash}
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 before running:

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

Verify

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


text
Then test a streamed reply. In quiet mode the room shows a quiet draft preview and notifies once the block or turn finishes.

To remove the rule later,

text

DELETE

the same rule URL with the recipient's token.

Multi-bot notes

Push rules are keyed by

text

ruleId

: re-running

text

PUT

against 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

text

override

rules are inserted ahead of 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 fallbacks and stale-preview fallbacks use normal Matrix delivery.

OpenClaw Docs

Matrix push rules for quiet previews

Prerequisites

Steps

Configure quiet previews

Get the recipient's access token

Verify pushers exist

Install the override push rule

Verify

Multi-bot notes

Homeserver notes

Related