自托管 Matrix 的用户如果不想每次预览编辑都收到通知，可以配置 OpenClaw 的 quiet 流模式，然后为每个接收者账号安装一条自定义 push rule。这条 rule 匹配 com.openclaw.finalized_preview 标记，只在最终块或轮次完成时通知。配置依赖接收者的 access token，并且 Synapse 需支持 event_property_is 条件（2023 年后版本），Tuwunel 用户需留意 suppress_push_when_active 设置。

OpenClaw Matrix 静默推送规则：只收最终通知，不被打断

当 channels.matrix.streaming 设为 "quiet" 时，OpenClaw 会原地编辑同一条预览事件，并在最终定稿的编辑上添加自定义内容标记。Matrix 客户端只有在该标记匹配了 per-user push rule 时才会通知。本页面向自托管 Matrix 的运维人员，指导如何为每个接收者账号安装这条规则。

如果你只需要 Matrix 默认的通知行为，用 streaming: "partial" 或关闭 streaming 即可。参见 Matrix 渠道设置。

前提条件

• 接收者用户 = 应该收到通知的人
• 机器人用户 = 发送回复的 OpenClaw Matrix 账号
• 下面的 API 调用需要使用接收者用户的 access token
• push rule 中的 sender 匹配机器人用户的完整 MXID
• 接收者账号必须已有正常工作的 pusher——静默预览规则只有在正常 Matrix 推送畅通时才有效

配置步骤

1. 启用 Quiet 预览

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

2. 获取接收者的 access token

尽量复用已有的客户端会话 token。需要生成新 token 时：

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"
  }'

3. 确认 pusher 存在

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

如果没有返回 pusher，请先修复该账号的普通 Matrix 推送，再继续。

4. 安装 override push rule

OpenClaw 在定稿的纯文本预览编辑上设置 content["com.openclaw.finalized_preview"] = true。安装一条匹配该标记和机器人 MXID 的规则：

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 }
    ]
  }'

运行前替换以下内容：

• https://matrix.example.org：你的 homeserver 基础 URL
• $USER_ACCESS_TOKEN：接收者的 access token
• openclaw-finalized-preview-botname：每个机器人在每个接收者下唯一的规则 ID（建议格式 openclaw-finalized-preview-<botname>）
• @bot:example.org：你的 OpenClaw 机器人 MXID，不是接收者

5. 验证

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

然后测试一次流回复。在 quiet 模式下，房间中会显示一份安静的草稿预览，并在块或轮次完成后才触发通知。

若要删除这条规则，使用 DELETE 相同规则 URL（携带接收者 token）。

多机器人说明

Push rule 按 ruleId 键控：对同一 ID 重复 PUT 会更新规则。如果多个 OpenClaw 机器人需要通知同一个接收者，请为每个机器人创建一条独立规则，sender 匹配相应的 MXID。

新添加的用户自定义 override 规则会插入到默认的抑制规则之前，因此无需额外调整优先级。该规则只影响可以被原地定稿的纯文本预览编辑；媒体回退和过期预览回退仍然使用普通 Matrix 推送。

自制 Homeserver 注意事项

Synapse

无需修改 homeserver.yaml。只要普通 Matrix 通知能到达该用户，使用接收者 token 执行上述 pushrules 调用即可。

如果你在反向代理或 worker 后面运行 Synapse，请确保 /_matrix/client/.../pushrules/ 能正确到达 Synapse。推送由主进程或 synapse.app.pusher / 配置的 pusher worker 处理——确保它们正常工作。

该规则使用了 event_property_is push-rule 条件（MSC3758, push rule v1.10），该特性在 2023 年加入 Synapse。较老的 Synapse 版本会接收 PUT pushrules/... 调用但静默忽略条件——如果定稿编辑没有触发通知，请升级 Synapse。

Tuwunel

流程与 Synapse 相同；定稿预览标记不需要 Tuwunel 特定配置。

如果用户在其他设备上活跃时通知消失，请检查是否启用了 suppress_push_when_active。Tuwunel 在 1.4.2（2025 年 9 月）添加了该选项，它会在某个设备活跃时主动抑制其他设备的推送。

常见问题

安装规则后还是收不到最终通知怎么办？

首先确认接收者的 pusher 列表不为空（GET /pushers）。然后检查 Synapse 版本是否 ≥ 2023 年发布的版本，否则 event_property_is 条件不会生效。也可以查看机器人账号的 sender MXID 是否与规则中完全一致，注意大小写和冒号。

多个机器人通知同一个用户，规则怎么配？

为每个机器人创建一条独立的 override rule，ruleId 不同（例如 openclaw-finalized-preview-botA 和 openclaw-finalized-preview-botB），每条规则中 sender 匹配对应机器人的 MXID。

一个用户同时使用手机和电脑，为什么手机收不到通知？

检查 Tuwunel 的 suppress_push_when_active 设置，如果启用且电脑端活跃，手机端可能被抑制。另外确认两端都正常工作，且 pusher 与 device 关联正确。

---

相关文档

• Matrix 渠道设置
• 流式预览概念