Channel - Matrix 推送规则（quiet 流式预览）

当 channels.matrix.streaming 设为 "quiet" 时，OpenClaw 原地编辑单个预览事件，并在最终编辑时标记自定义内容标志。Matrix 客户端只有在每用户推送规则匹配该标志时才会通知。

如果只需要标准 Matrix 通知行为，使用 streaming: "partial" 或关闭流式即可，无需本页配置。

前提条件

接收方用户：应收到通知的人
bot 用户：发送回复的 OpenClaw Matrix 账号
以下 API 调用使用接收方用户的 access token
推送规则中的 sender 匹配 bot 用户的完整 MXID
接收方账号必须已有正常工作的 pushers

配置步骤

1. 启用 quiet 预览

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

2. 获取接收方 access 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. 验证 pushers 存在

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

4. 安装 override 推送规则

OpenClaw 用 content["com.openclaw.finalized_preview"] = true 标记最终化的文本预览编辑。

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 → 每个 bot 每个接收方唯一的规则 ID
@bot:example.org → OpenClaw bot 的 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 请求。

多 bot 说明

推送规则按 ruleId 键控，对同一 ID 重复 PUT 会更新规则。多个 OpenClaw bot 通知同一接收方时，为每个 bot 创建一条规则，使用不同的 sender 匹配。

Homeserver 注意事项

Synapse：无需特殊配置。规则使用 event_property_is 条件（MSC3758，push rule v1.10），Synapse 2023 年后版本支持。旧版 Synapse 接受 PUT 调用但不匹配条件，需升级。

Tuwunel：流程与 Synapse 相同。注意 1.4.2+ 版本的 suppress_push_when_active 选项可能在用户活跃时抑制推送。

Wiki AI

目录