> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Правила push-уведомлений Matrix для ненавязчивых предпросмотров

Когда `channels.matrix.streaming.mode` имеет значение `"quiet"`, OpenClaw передаёт ответ потоково, редактируя одно событие предварительного просмотра на месте. Предварительные версии отправляются как события `m.notice` без уведомлений, а итоговое редактирование помечается маркером `content["com.openclaw.finalized_preview"] = true`. Клиенты Matrix уведомляют только об этом итоговом редактировании и только в том случае, если пользовательское правило push-уведомлений соответствует маркеру. Эта страница предназначена для операторов, самостоятельно размещающих Matrix и желающих установить такое правило для каждой учётной записи получателя.

`streaming.mode: "progress"` завершает свои черновики тем же способом, поэтому это же правило срабатывает и для итоговых редактирований в режиме отображения прогресса.

Если вам достаточно стандартного поведения уведомлений Matrix, используйте `streaming.mode: "partial"` или отключите потоковую передачу. См. раздел [Настройка канала Matrix](https://docs2.openclaw.ai/ru/channels/matrix.md#streaming-previews).

## Предварительные требования

* пользователь-получатель = человек, который должен получить уведомление
* пользователь-бот = учётная запись OpenClaw в Matrix, отправляющая ответ
* для приведённых ниже вызовов API используйте токен доступа пользователя-получателя
* в правиле push-уведомлений сопоставляйте `sender` с полным MXID пользователя-бота
* для учётной записи получателя уже должны работать механизмы доставки push-уведомлений; правила тихого предварительного просмотра работают только при исправной обычной доставке push-уведомлений Matrix

## Шаги

**1. Настройте тихий предварительный просмотр**

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    matrix: {
      streaming: { mode: "quiet" },
    },
  },
}
```

**2. Получите токен доступа получателя**

По возможности повторно используйте токен существующего клиентского сеанса. Чтобы выпустить новый:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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. Убедитесь в наличии механизмов доставки push-уведомлений**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushers"
```

Если механизмы доставки push-уведомлений отсутствуют в ответе, прежде чем продолжить, исправьте обычную доставку push-уведомлений Matrix для этой учётной записи.

**4. Установите переопределяющее правило push-уведомлений**

Установите правило, сопоставляющее маркер завершённого предварительного просмотра и MXID бота в качестве отправителя:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`: уникальный идентификатор правила для каждой пары «бот — получатель» (шаблон: `openclaw-finalized-preview-<botname>`)
* `@bot:example.org`: MXID вашего бота OpenClaw, а не получателя

**5. Проверьте**

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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` с тем же идентификатором обновляет одно правило. Если несколько ботов OpenClaw уведомляют одного получателя, создайте отдельное правило для каждого бота с отдельным условием сопоставления отправителя.

Новые пользовательские правила `override` вставляются перед стандартными серверными правилами подавления, поэтому дополнительный параметр порядка не требуется. Правило влияет только на текстовые редактирования предварительного просмотра, которые можно завершить на месте; ответы с медиафайлами, резервные варианты для устаревших предварительных версий и итоговые тексты, которые активировали бы упоминания Matrix, вместо этого доставляются как обычные сообщения с уведомлениями.

## Примечания о домашнем сервере

> [accordion] Synapse
>
> Специально изменять `homeserver.yaml` не требуется. Если обычные уведомления Matrix уже доходят до этого пользователя, основной шаг настройки — токен получателя и приведённый выше вызов `pushrules`.
>
> Если Synapse работает за обратным прокси-сервером или с рабочими процессами, убедитесь, что `/_matrix/client/.../pushrules/` корректно достигает Synapse. Доставка push-уведомлений выполняется основным процессом либо `synapse.app.pusher` / настроенными рабочими процессами доставки push-уведомлений — убедитесь в их исправности.
>
> В правиле используется условие правила push-уведомлений `event_property_is` (MSC3758, правило push-уведомлений версии 1.10), добавленное в Synapse в 2023 году. Более старые выпуски Synapse принимают вызов `PUT pushrules/...`, но условие никогда не срабатывает без каких-либо сообщений — обновите Synapse, если уведомление не приходит при итоговом редактировании предварительного просмотра.

> [accordion] Tuwunel
>
> Используется тот же процесс, что и для Synapse; для маркера завершённого предварительного просмотра отдельная настройка Tuwunel не требуется.
>
> Если уведомления исчезают, пока пользователь активен на другом устройстве, проверьте, включён ли параметр `suppress_push_when_active`. Tuwunel добавил этот параметр в версии 1.4.2 (сентябрь 2025 года), и он может намеренно подавлять push-уведомления на других устройствах, пока одно из устройств активно.

## Связанные материалы

* [Настройка канала Matrix](https://docs2.openclaw.ai/ru/channels/matrix.md)
* [Основные понятия потоковой передачи](https://docs2.openclaw.ai/ru/concepts/streaming.md)