Перейти до основного вмісту

​
Правила push-сповіщень Matrix для тихих попередніх переглядів

Коли channels.matrix.streaming має значення "quiet", OpenClaw редагує одну подію попереднього перегляду на місці й позначає фіналізоване редагування спеціальним прапорцем у вмісті. Клієнти Matrix надсилають сповіщення лише про фінальне редагування, якщо правило push для конкретного користувача відповідає цьому прапорцю. Ця сторінка призначена для операторів, які самостійно хостять Matrix і хочуть встановити це правило для кожного облікового запису одержувача. Якщо вам потрібна лише стандартна поведінка сповіщень Matrix, використовуйте streaming: "partial" або залиште потокову передачу вимкненою. Див. Налаштування каналу Matrix.

​
Передумови

  • користувач-одержувач = людина, яка має отримувати сповіщення
  • бот-користувач = обліковий запис OpenClaw Matrix, який надсилає відповідь
  • для наведених нижче викликів API використовуйте токен доступу користувача-одержувача
  • у правилі push значення sender має збігатися з повним MXID бот-користувача
  • обліковий запис одержувача вже повинен мати справні pushers — правила тихого попереднього перегляду працюють лише тоді, коли звичайна доставка push у Matrix працює коректно

​
Кроки

1

Налаштуйте тихі попередні перегляди

{
  channels: {
    matrix: {
      streaming: "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"
  }'
3

Переконайтеся, що pushers існують

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushers"
Якщо pushers не повертаються, спочатку виправте звичайну доставку push у Matrix для цього облікового запису.
4

Встановіть override-правило push

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: базовий URL вашого homeserver
  • $USER_ACCESS_TOKEN: токен доступу користувача-одержувача
  • openclaw-finalized-preview-botname: ID правила, унікальний для кожного бота й одержувача (шаблон: openclaw-finalized-preview-<botname>)
  • @bot:example.org: MXID вашого бота OpenClaw, а не одержувача
5

Перевірте

curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"
Потім протестуйте потокову відповідь. У тихому режимі в кімнаті показується чернетка тихого попереднього перегляду, а сповіщення надходить один раз, коли блок або хід завершується.
Щоб пізніше видалити правило, виконайте DELETE для того самого URL правила з токеном одержувача.

​
Примітки щодо кількох ботів

Ключем push-правил є ruleId: повторний запуск PUT для того самого ID оновлює одне правило. Якщо кілька ботів OpenClaw надсилають сповіщення одному одержувачу, створіть окреме правило для кожного бота з різним збігом sender. Нові користувацькі правила override вставляються перед стандартними правилами приглушення, тому жоден додатковий параметр упорядкування не потрібен. Правило впливає лише на редагування текстового попереднього перегляду, які можна фіналізувати на місці; резервні варіанти для медіа та застарілого попереднього перегляду використовують звичайну доставку Matrix.

​
Примітки щодо homeserver

Спеціальні зміни в homeserver.yaml не потрібні. Якщо звичайні сповіщення Matrix уже доходять до цього користувача, головний крок налаштування — це токен одержувача та виклик pushrules, наведений вище.Якщо ви запускаєте Synapse за reverse proxy або workers, переконайтеся, що /_matrix/client/.../pushrules/ коректно доходить до Synapse. Доставка push обробляється основним процесом або synapse.app.pusher / налаштованими pusher workers — переконайтеся, що вони працюють справно.
Такий самий процес, як і для Synapse; жодна специфічна для Tuwunel конфігурація для маркера фіналізованого попереднього перегляду не потрібна.Якщо сповіщення зникають, поки користувач активний на іншому пристрої, перевірте, чи ввімкнено suppress_push_when_active. Tuwunel додав цю опцію у версії 1.4.2 (вересень 2025 року), і вона може навмисно приглушувати push на інших пристроях, поки один пристрій активний.

​
Пов’язане