用于静默预览的 Matrix 推送规则

当 channels.matrix.streaming.mode 为 "quiet" 时，OpenClaw 通过就地编辑单个预览事件来流式传输回复。预览以不通知的 m.notice 事件发送，最终确定的编辑会标记为 content["com.openclaw.finalized_preview"] = true。只有当按用户配置的推送规则匹配该标记时，Matrix 客户端才会针对该最终编辑发出通知。本页面向自托管 Matrix 并希望为每个接收者账户安装该规则的管理员。

streaming.mode: "progress" 通过相同路径确定其草稿，因此同一规则也会对 progress 模式的最终确定编辑生效。

如果你只需要 Matrix 默认通知行为，请使用 streaming.mode: "partial" 或关闭流式传输。参见 Matrix 消息行为。

先决条件¶

接收者用户 = 应接收通知的人
机器人用户 = 发送回复的 OpenClaw Matrix 账户
以下 API 调用请使用接收者用户的访问令牌
将推送规则中的 sender 与机器人用户的完整 MXID 匹配
接收者账户必须已有可用的 pushers。安静预览规则仅在正常 Matrix 推送投递处于健康状态时有效

步骤¶

1. 配置安静预览

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

2. 获取接收者的访问令牌

尽可能复用现有客户端会话令牌。若要生成一个新令牌：

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

将 `https://matrix.example.org` 替换为你的主服务器基础 URL，并将
`@alice:example.org` 替换为接收者的 MXID。将响应中的 `access_token`
导出为 `USER_ACCESS_TOKEN`；后续步骤会读取它：

export USER_ACCESS_TOKEN="<access_token from the login response>"

3. 验证 pushers 是否存在

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

如果没有返回 pushers，请先修复该账户的正常 Matrix 推送投递，再继续。

4. 安装覆盖推送规则

安装一条规则，匹配最终确定预览标记，并将机器人 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`：你的主服务器基础 URL
- `$USER_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"

然后测试一条流式回复。在安静模式下，房间会显示安静的草稿预览，并在块或回合结束时通知一次。

之后若要删除该规则，请使用接收者的令牌对同一规则 URL 执行 DELETE。

多机器人说明¶

推送规则以 ruleId 为键：对同一 ID 重新执行 PUT 只会更新一条规则。对于多个 OpenClaw 机器人通知同一接收者，请为每个机器人创建一条规则，并使用不同的发送者匹配。

新的用户定义 override 规则会插入到服务器默认抑制规则之前，因此无需额外的排序参数。该规则仅影响可以就地最终确定的纯文本预览编辑。媒体回复、过期预览回退以及会激活 Matrix 提及的最终文本，将作为正常通知消息投递。

主服务器说明¶

Synapse

无需对 homeserver.yaml 进行特殊更改。如果正常 Matrix 通知已经能到达该用户，则上述接收者令牌 + pushrules 调用是主要配置步骤。

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

该规则使用 event_property_is 推送规则条件（MSC3758，推送规则 v1.10），该条件于 2023 年添加到 Synapse。旧版 Synapse 会接受 PUT pushrules/... 调用，但会静默地从不匹配该条件——如果最终确定预览编辑没有收到通知，请升级 Synapse。

Tuwunel

流程与 Synapse 相同。最终确定预览标记无需 Tuwunel 特定配置。

如果用户在另一台设备上处于活跃状态时通知消失，请检查是否启用了 suppress_push_when_active。Tuwunel 在 1.4.2（2025 年 9 月）中添加了此选项，它可以在一台设备活跃时有意抑制对其他设备的推送。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw

用于静默预览的 Matrix 推送规则

先决条件¶

步骤¶

多机器人说明¶

主服务器说明¶

相关¶