English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Mainstream messaging

Matrix push rules for quiet previews

When channels.matrix.streaming is "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 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 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

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

  • Get the recipient's access token

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

  • Verify pushers exist

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

    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:

    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

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

    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, DELETE the same rule URL with the recipient's token.

    Multi-bot notes

    Push rules are keyed by ruleId: re-running 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 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.

    Homeserver notes

    Synapse

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

    If you run Synapse behind a reverse proxy or workers, make sure /_matrix/client/.../pushrules/ reaches Synapse correctly. Push delivery is handled by the main process or synapse.app.pusher / configured pusher workers — ensure 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 config 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.