Mainstream messaging
Правила надсилання Matrix для тихих попередніх переглядів
Коли channels.matrix.streaming має значення "quiet", OpenClaw редагує одну подію попереднього перегляду на місці та позначає завершене редагування спеціальним прапорцем у вмісті. Клієнти Matrix надсилають сповіщення про фінальне редагування, лише якщо правило надсилання для конкретного користувача відповідає цьому прапорцю. Ця сторінка призначена для операторів, які самостійно розміщують Matrix і хочуть встановити це правило для кожного облікового запису одержувача.
Якщо вам потрібна лише стандартна поведінка сповіщень Matrix, використовуйте streaming: "partial" або залиште потокову передачу вимкненою. Див. Налаштування каналу Matrix.
Передумови
- користувач-одержувач = людина, яка має отримувати сповіщення
- користувач бота = обліковий запис Matrix OpenClaw, який надсилає відповідь
- для наведених нижче викликів API використовуйте токен доступу користувача-одержувача
- зіставляйте
senderу правилі надсилання з повним MXID користувача бота - обліковий запис одержувача вже повинен мати налаштовані й працездатні pushers — правила тихого попереднього перегляду працюють лише тоді, коли звичайна доставка push-сповіщень Matrix справна
Кроки
Налаштуйте тихі попередні перегляди
{
channels: {
matrix: {
streaming: "quiet",
},
},
}
Отримайте токен доступу одержувача
За можливості повторно використайте токен наявної сесії клієнта. Щоб створити новий:
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"
}'
Переконайтеся, що pushers існують
curl -sS \
-H "Authorization: Bearer $USER_ACCESS_TOKEN" \
"https://matrix.example.org/_matrix/client/v3/pushers"
Якщо pushers не повертаються, спочатку виправте звичайну доставку push-сповіщень Matrix для цього облікового запису, а вже потім продовжуйте.
Встановіть override-правило надсилання
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: ідентифікатор правила, унікальний для кожного бота й одержувача (шаблон:openclaw-finalized-preview-<botname>)@bot:example.org: MXID вашого бота OpenClaw, а не одержувача
Перевірте
curl -sS \
-H "Authorization: Bearer $USER_ACCESS_TOKEN" \
"https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"
Потім протестуйте потокову відповідь. У тихому режимі кімната показує тихий чернетковий попередній перегляд і надсилає одне сповіщення, коли блок або хід завершується.
Щоб пізніше видалити правило, виконайте DELETE для того самого URL правила з токеном одержувача.
Примітки щодо кількох ботів
Правила надсилання визначаються ключем ruleId: повторний запуск PUT для того самого ідентифікатора оновлює одне правило. Якщо того самого одержувача сповіщають кілька ботів OpenClaw, створіть окреме правило для кожного бота з окремою умовою відповідності відправника.
Нові визначені користувачем override-правила вставляються перед стандартними правилами придушення, тому додатковий параметр порядку не потрібен. Правило впливає лише на текстові редагування попереднього перегляду, які можна завершити на місці; резервні варіанти для медіа та застарілих попередніх переглядів використовують звичайну доставку Matrix.
Примітки щодо homeserver
Synapse
Спеціальні зміни в homeserver.yaml не потрібні. Якщо звичайні сповіщення Matrix вже доходять до цього користувача, основним кроком налаштування є токен одержувача та виклик pushrules, наведений вище.
Якщо ви запускаєте Synapse за зворотним проксі або через workers, переконайтеся, що /_matrix/client/.../pushrules/ коректно спрямовується до Synapse. Доставка push-сповіщень обробляється основним процесом або synapse.app.pusher / налаштованими pusher workers — переконайтеся, що вони працюють справно.
Правило використовує умову правила надсилання event_property_is (MSC3758, push rule v1.10), яку було додано до Synapse у 2023 році. Старіші випуски Synapse приймають виклик PUT pushrules/..., але мовчки ніколи не зіставляють цю умову — оновіть Synapse, якщо сповіщення не надходить після завершеного редагування попереднього перегляду.
Tuwunel
Той самий процес, що й для Synapse; спеціальна конфігурація Tuwunel для маркера завершеного попереднього перегляду не потрібна.
Якщо сповіщення зникають, поки користувач активний на іншому пристрої, перевірте, чи ввімкнено suppress_push_when_active. Tuwunel додав цю опцію у версії 1.4.2 (вересень 2025 року), і вона може навмисно приглушувати push-сповіщення на інших пристроях, поки один пристрій активний.