---
read_when:
    - Налаштування Matrix в OpenClaw
    - Налаштування E2EE та верифікації Matrix
summary: Статус підтримки Matrix, налаштування та приклади конфігурації
title: Matrix
x-i18n:
    generated_at: "2026-04-20T12:12:13Z"
    model: gpt-5.4
    provider: openai
    source_hash: 00fa6201d2ee4ac4ae5be3eb18ff687c5c2c9ef70cff12af1413b4c311484b24
    source_path: channels/matrix.md
    workflow: 15
---

# Matrix

Matrix — це вбудований channel Plugin для OpenClaw.
Він використовує офіційний `matrix-js-sdk` і підтримує DM, кімнати, треди, медіа, реакції, опитування, локацію та E2EE.

## Вбудований Plugin

Matrix постачається як вбудований Plugin у поточних релізах OpenClaw, тому звичайним
пакетним збіркам не потрібне окреме встановлення.

Якщо ви використовуєте старішу збірку або власне встановлення без Matrix, встановіть
його вручну:

Встановити з npm:

```bash
openclaw plugins install @openclaw/matrix
```

Встановити з локального checkout:

```bash
openclaw plugins install ./path/to/local/matrix-plugin
```

Див. [Plugins](/uk/tools/plugin) щодо поведінки Plugin і правил встановлення.

## Налаштування

1. Переконайтеся, що Plugin Matrix доступний.
   - У поточних пакетних релізах OpenClaw він уже вбудований.
   - У старіших/власних встановленнях його можна додати вручну за допомогою наведених вище команд.
2. Створіть обліковий запис Matrix на своєму homeserver.
3. Налаштуйте `channels.matrix` одним із варіантів:
   - `homeserver` + `accessToken`, або
   - `homeserver` + `userId` + `password`.
4. Перезапустіть Gateway.
5. Почніть DM із ботом або запросіть його до кімнати.
   - Нові запрошення Matrix працюють лише тоді, коли `channels.matrix.autoJoin` це дозволяє.

Інтерактивні шляхи налаштування:

```bash
openclaw channels add
openclaw configure --section channels
```

Майстер Matrix запитує:

- URL homeserver
- метод автентифікації: токен доступу або пароль
- ID користувача (лише для автентифікації за паролем)
- необов’язкову назву пристрою
- чи вмикати E2EE
- чи налаштовувати доступ до кімнат і автоматичне приєднання за запрошенням

Ключові особливості майстра:

- Якщо змінні середовища автентифікації Matrix уже існують і для цього облікового запису ще не збережено автентифікацію в конфігурації, майстер запропонує скористатися env, щоб зберегти автентифікацію в змінних середовища.
- Назви облікових записів нормалізуються до ID облікового запису. Наприклад, `Ops Bot` стає `ops-bot`.
- Записи allowlist для DM приймають `@user:server` напряму; відображувані імена працюють лише тоді, коли пошук у живому каталозі знаходить один точний збіг.
- Записи allowlist для кімнат приймають ID кімнат і псевдоніми напряму. Віддавайте перевагу `!room:server` або `#alias:server`; нерозв’язані імена ігноруються під час виконання резолюцією allowlist.
- У режимі allowlist для автоматичного приєднання за запрошенням використовуйте лише стабільні цілі запрошення: `!roomId:server`, `#alias:server` або `*`. Звичайні назви кімнат відхиляються.
- Щоб розв’язати назви кімнат перед збереженням, використовуйте `openclaw channels resolve --channel matrix "Project Room"`.

<Warning>
`channels.matrix.autoJoin` за замовчуванням має значення `off`.

Якщо залишити його без значення, бот не приєднуватиметься до запрошених кімнат або нових запрошень у стилі DM, тому не з’являтиметься в нових групах або запрошених DM, якщо ви спочатку не приєднаєте його вручну.

Установіть `autoJoin: "allowlist"` разом із `autoJoinAllowlist`, щоб обмежити, які запрошення він прийматиме, або встановіть `autoJoin: "always"`, якщо хочете, щоб він приєднувався до кожного запрошення.

У режимі `allowlist` `autoJoinAllowlist` приймає лише `!roomId:server`, `#alias:server` або `*`.
</Warning>

Приклад allowlist:

```json5
{
  channels: {
    matrix: {
      autoJoin: "allowlist",
      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
      groups: {
        "!ops:example.org": {
          requireMention: true,
        },
      },
    },
  },
}
```

Приєднуватися до кожного запрошення:

```json5
{
  channels: {
    matrix: {
      autoJoin: "always",
    },
  },
}
```

Мінімальне налаштування на основі токена:

```json5
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      dm: { policy: "pairing" },
    },
  },
}
```

Налаштування на основі пароля (токен кешується після входу):

```json5
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me", // pragma: allowlist secret
      deviceName: "OpenClaw Gateway",
    },
  },
}
```

Matrix зберігає кешовані облікові дані в `~/.openclaw/credentials/matrix/`.
Для облікового запису за замовчуванням використовується `credentials.json`; для іменованих облікових записів — `credentials-<account>.json`.
Якщо там існують кешовані облікові дані, OpenClaw вважає Matrix налаштованим для setup, doctor і виявлення статусу channel, навіть якщо поточна автентифікація не задана безпосередньо в конфігурації.

Відповідники змінних середовища (використовуються, коли ключ конфігурації не встановлено):

- `MATRIX_HOMESERVER`
- `MATRIX_ACCESS_TOKEN`
- `MATRIX_USER_ID`
- `MATRIX_PASSWORD`
- `MATRIX_DEVICE_ID`
- `MATRIX_DEVICE_NAME`

Для облікових записів не за замовчуванням використовуйте змінні середовища з областю облікового запису:

- `MATRIX_<ACCOUNT_ID>_HOMESERVER`
- `MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN`
- `MATRIX_<ACCOUNT_ID>_USER_ID`
- `MATRIX_<ACCOUNT_ID>_PASSWORD`
- `MATRIX_<ACCOUNT_ID>_DEVICE_ID`
- `MATRIX_<ACCOUNT_ID>_DEVICE_NAME`

Приклад для облікового запису `ops`:

- `MATRIX_OPS_HOMESERVER`
- `MATRIX_OPS_ACCESS_TOKEN`

Для нормалізованого ID облікового запису `ops-bot` використовуйте:

- `MATRIX_OPS_X2D_BOT_HOMESERVER`
- `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN`

Matrix екранує розділові знаки в ID облікових записів, щоб уникнути колізій у змінних середовища з областю.
Наприклад, `-` стає `_X2D_`, тому `ops-prod` перетворюється на `MATRIX_OPS_X2D_PROD_*`.

Інтерактивний майстер пропонує скористатися ярликом env vars, лише якщо ці змінні середовища автентифікації вже присутні і для вибраного облікового запису ще не збережено автентифікацію Matrix у конфігурації.

## Приклад конфігурації

Це практична базова конфігурація з pairing для DM, allowlist для кімнат і увімкненим E2EE:

```json5
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
        sessionScope: "per-room",
        threadReplies: "off",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
      streaming: "partial",
    },
  },
}
```

`autoJoin` застосовується до всіх запрошень Matrix, включно із запрошеннями у стилі DM. OpenClaw не може надійно
визначити, чи є запрошена кімната DM чи групою на момент запрошення, тому всі запрошення спочатку проходять через `autoJoin`.
`dm.policy` застосовується після того, як бот уже приєднався і кімнату класифіковано як DM.

## Попередній перегляд потокових відповідей

Потокова передача відповідей Matrix вмикається лише за бажанням.

Установіть `channels.matrix.streaming` у `"partial"`, якщо хочете, щоб OpenClaw надсилав одну живу
попередню відповідь, редагував цей попередній перегляд на місці, поки модель генерує текст, а потім завершував її, коли
відповідь буде готова:

```json5
{
  channels: {
    matrix: {
      streaming: "partial",
    },
  },
}
```

- `streaming: "off"` — значення за замовчуванням. OpenClaw чекає на остаточну відповідь і надсилає її один раз.
- `streaming: "partial"` створює одне редаговане повідомлення попереднього перегляду для поточного блоку відповіді помічника, використовуючи звичайні текстові повідомлення Matrix. Це зберігає застарілу поведінку Matrix із сповіщенням спочатку про попередній перегляд, тому стандартні клієнти можуть сповіщати про перший текст потокового попереднього перегляду, а не про завершений блок.
- `streaming: "quiet"` створює одне редаговане тихе повідомлення-попередній перегляд для поточного блоку відповіді помічника. Використовуйте це лише тоді, коли ви також налаштовуєте правила push для одержувачів для завершених редагувань попереднього перегляду.
- `blockStreaming: true` вмикає окремі повідомлення прогресу Matrix. Якщо попередній перегляд потокової передачі ввімкнено, Matrix зберігає живу чернетку для поточного блоку та залишає завершені блоки як окремі повідомлення.
- Коли потоковий попередній перегляд увімкнено, а `blockStreaming` вимкнено, Matrix редагує живу чернетку на місці та завершує ту саму подію, коли блок або хід завершується.
- Якщо попередній перегляд більше не вміщується в одну подію Matrix, OpenClaw зупиняє потоковий попередній перегляд і повертається до звичайної фінальної доставки.
- Відповіді з медіа, як і раніше, надсилають вкладення у звичайному режимі. Якщо застарілий попередній перегляд більше не можна безпечно використати повторно, OpenClaw редагує його перед надсиланням фінальної відповіді з медіа.
- Редагування попереднього перегляду потребують додаткових викликів Matrix API. Залиште потокову передачу вимкненою, якщо хочете максимально консервативну поведінку щодо обмежень частоти.

`blockStreaming` сам по собі не вмикає чернетки попереднього перегляду.
Використовуйте `streaming: "partial"` або `streaming: "quiet"` для редагувань попереднього перегляду; потім додавайте `blockStreaming: true` лише якщо також хочете, щоб завершені блоки відповіді помічника залишалися видимими як окремі повідомлення прогресу.

Якщо вам потрібні стандартні сповіщення Matrix без власних правил push, використовуйте `streaming: "partial"` для поведінки з попереднім переглядом спочатку або залиште `streaming` вимкненим для доставки лише фінальної відповіді. Із `streaming: "off"`:

- `blockStreaming: true` надсилає кожен завершений блок як звичайне повідомлення Matrix зі сповіщенням.
- `blockStreaming: false` надсилає лише фінальну завершену відповідь як звичайне повідомлення Matrix зі сповіщенням.

### Власні правила push для тихих завершених попередніх переглядів

Якщо ви використовуєте власну інфраструктуру Matrix і хочете, щоб тихі попередні перегляди надсилали сповіщення лише тоді, коли блок або
фінальна відповідь завершені, установіть `streaming: "quiet"` і додайте правило push для кожного користувача для завершених редагувань попереднього перегляду.

Зазвичай це налаштування для користувача-одержувача, а не глобальна зміна конфігурації homeserver:

Коротке зіставлення перед початком:

- recipient user = особа, яка має отримувати сповіщення
- bot user = обліковий запис Matrix OpenClaw, який надсилає відповідь
- для наведених нижче викликів API використовуйте токен доступу користувача-одержувача
- у правилі push значення `sender` має відповідати повному MXID користувача-бота

1. Налаштуйте OpenClaw на використання тихих попередніх переглядів:

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

2. Переконайтеся, що обліковий запис одержувача вже отримує звичайні push-сповіщення Matrix. Правила тихого попереднього перегляду
   працюють лише тоді, коли в цього користувача вже є налаштовані pusher-и/пристрої.

3. Отримайте токен доступу користувача-одержувача.
   - Використовуйте токен користувача, який отримує повідомлення, а не токен бота.
   - Зазвичай найпростіше повторно використати токен наявної сесії клієнта.
   - Якщо вам потрібно випустити новий токен, можна увійти через стандартний Matrix Client-Server API:

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

4. Переконайтеся, що обліковий запис одержувача вже має pusher-и:

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

Якщо це не повертає активних pusher-ів/пристроїв, спочатку виправте звичайні сповіщення Matrix, перш ніж додавати
наведене нижче правило OpenClaw.

OpenClaw позначає завершені текстові редагування попереднього перегляду так:

```json
{
  "com.openclaw.finalized_preview": true
}
```

5. Створіть override-правило push для кожного облікового запису одержувача, який має отримувати ці сповіщення:

```bash
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 правила, унікальний для цього бота для цього користувача-одержувача
- `@bot:example.org`: MXID вашого Matrix-бота OpenClaw, а не MXID користувача-одержувача

Важливо для конфігурацій із кількома ботами:

- Правила push визначаються за `ruleId`. Повторний виклик `PUT` для того самого ID правила оновлює саме це правило.
- Якщо один користувач-одержувач має отримувати сповіщення від кількох облікових записів Matrix бота OpenClaw, створіть окреме правило для кожного бота з унікальним ID правила для кожного збігу `sender`.
- Простий шаблон — `openclaw-finalized-preview-<botname>`, наприклад `openclaw-finalized-preview-ops` або `openclaw-finalized-preview-support`.

Правило оцінюється щодо відправника події:

- автентифікуйтеся токеном користувача-одержувача
- зіставляйте `sender` з MXID бота OpenClaw

6. Переконайтеся, що правило існує:

```bash
curl -sS \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"
```

7. Протестуйте потокову відповідь. У тихому режимі в кімнаті має відображатися тиха чернетка попереднього перегляду, а фінальне
   редагування на місці має надіслати сповіщення, щойно блок або хід завершиться.

Якщо пізніше вам потрібно видалити правило, видаліть той самий ID правила токеном користувача-одержувача:

```bash
curl -sS -X DELETE \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"
```

Примітки:

- Створюйте правило з токеном доступу користувача-одержувача, а не токеном бота.
- Нові визначені користувачем правила `override` вставляються перед типовими правилами придушення, тому додатковий параметр порядку не потрібен.
- Це впливає лише на текстові редагування попереднього перегляду, які OpenClaw може безпечно завершити на місці. Відкати для медіа та застарілих попередніх переглядів, як і раніше, використовують звичайну доставку Matrix.
- Якщо `GET /_matrix/client/v3/pushers` не показує жодних pusher-ів, користувач іще не має робочої доставки push-сповіщень Matrix для цього облікового запису/пристрою.

#### Synapse

Для Synapse наведеного вище налаштування зазвичай достатньо:

- Жодних спеціальних змін у `homeserver.yaml` для сповіщень про завершені попередні перегляди OpenClaw не потрібно.
- Якщо ваше розгортання Synapse уже надсилає звичайні push-сповіщення Matrix, основним кроком налаштування є токен користувача + виклик `pushrules`, наведений вище.
- Якщо ви запускаєте Synapse за reverse proxy або через workers, переконайтеся, що `/_matrix/client/.../pushrules/` коректно доходить до Synapse.
- Якщо ви використовуєте workers у Synapse, переконайтеся, що pusher-и справні. Доставка push виконується основним процесом або `synapse.app.pusher` / налаштованими pusher workers.

#### Tuwunel

Для Tuwunel використовуйте той самий процес налаштування та виклик API `pushrules`, наведені вище:

- Жодна специфічна для Tuwunel конфігурація для самого маркера завершеного попереднього перегляду не потрібна.
- Якщо для цього користувача вже працюють звичайні сповіщення Matrix, основним кроком налаштування є токен користувача + виклик `pushrules`, наведений вище.
- Якщо здається, що сповіщення зникають, поки користувач активний на іншому пристрої, перевірте, чи ввімкнено `suppress_push_when_active`. Tuwunel додав цей параметр у Tuwunel 1.4.2 12 вересня 2025 року, і він може навмисно придушувати push на інші пристрої, поки один пристрій активний.

## Кімнати бот-до-бота

За замовчуванням повідомлення Matrix від інших налаштованих облікових записів Matrix OpenClaw ігноруються.

Використовуйте `allowBots`, якщо ви навмисно хочете дозволити міжагентний трафік Matrix:

```json5
{
  channels: {
    matrix: {
      allowBots: "mentions", // true | "mentions"
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}
```

- `allowBots: true` приймає повідомлення від інших налаштованих облікових записів Matrix ботів у дозволених кімнатах і DM.
- `allowBots: "mentions"` приймає ці повідомлення лише тоді, коли вони явно згадують цього бота в кімнатах. DM, як і раніше, дозволені.
- `groups.<room>.allowBots` перевизначає налаштування рівня облікового запису для однієї кімнати.
- OpenClaw, як і раніше, ігнорує повідомлення від того самого ID користувача Matrix, щоб уникнути циклів самовідповіді.
- Matrix не надає тут нативного прапорця бота; OpenClaw трактує «створене ботом» як «надіслане іншим налаштованим обліковим записом Matrix на цьому Gateway OpenClaw».

Використовуйте суворі allowlist кімнат і вимоги до згадки, коли вмикаєте трафік бот-до-бота в спільних кімнатах.

## Шифрування та верифікація

У зашифрованих кімнатах (E2EE) вихідні події зображень використовують `thumbnail_file`, тому попередні перегляди зображень шифруються разом із повним вкладенням. Незашифровані кімнати, як і раніше, використовують звичайний `thumbnail_url`. Жодної конфігурації не потрібно — Plugin автоматично визначає стан E2EE.

Увімкнути шифрування:

```json5
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}
```

Перевірити статус верифікації:

```bash
openclaw matrix verify status
```

Докладний статус (повна діагностика):

```bash
openclaw matrix verify status --verbose
```

Включити збережений ключ відновлення у машиночитаний вивід:

```bash
openclaw matrix verify status --include-recovery-key --json
```

Ініціалізувати cross-signing і стан верифікації:

```bash
openclaw matrix verify bootstrap
```

Докладна діагностика bootstrap:

```bash
openclaw matrix verify bootstrap --verbose
```

Примусово скинути поточну identity cross-signing перед bootstrap:

```bash
openclaw matrix verify bootstrap --force-reset-cross-signing
```

Верифікувати цей пристрій за допомогою ключа відновлення:

```bash
openclaw matrix verify device "<your-recovery-key>"
```

Докладні відомості про верифікацію пристрою:

```bash
openclaw matrix verify device "<your-recovery-key>" --verbose
```

Перевірити стан резервного копіювання ключів кімнати:

```bash
openclaw matrix verify backup status
```

Докладна діагностика стану резервного копіювання:

```bash
openclaw matrix verify backup status --verbose
```

Відновити ключі кімнат із резервної копії на сервері:

```bash
openclaw matrix verify backup restore
```

Докладна діагностика відновлення:

```bash
openclaw matrix verify backup restore --verbose
```

Видалити поточну резервну копію на сервері та створити нову базову резервну копію. Якщо збережений
ключ резервного копіювання не вдається коректно завантажити, це скидання також може відтворити secret storage, щоб
у майбутніх cold start можна було завантажити новий ключ резервного копіювання:

```bash
openclaw matrix verify backup reset --yes
```

Усі команди `verify` за замовчуванням лаконічні (включно з тихим внутрішнім логуванням SDK) і показують детальну діагностику лише з `--verbose`.
Для повного машиночитаного виводу у скриптах використовуйте `--json`.

У конфігураціях із кількома обліковими записами команди Matrix CLI використовують неявний обліковий запис Matrix за замовчуванням, якщо ви не передасте `--account <id>`.
Якщо ви налаштували кілька іменованих облікових записів, спочатку встановіть `channels.matrix.defaultAccount`, інакше такі неявні операції CLI зупиняться й попросять вас явно вибрати обліковий запис.
Використовуйте `--account`, коли хочете явно націлити верифікацію або операції з пристроєм на іменований обліковий запис:

```bash
openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant
```

Коли шифрування вимкнене або недоступне для іменованого облікового запису, попередження Matrix і помилки верифікації вказують на ключ конфігурації цього облікового запису, наприклад `channels.matrix.accounts.assistant.encryption`.

### Що означає «верифіковано»

OpenClaw вважає цей пристрій Matrix верифікованим лише тоді, коли його верифіковано вашою власною identity cross-signing.
На практиці `openclaw matrix verify status --verbose` показує три сигнали довіри:

- `Locally trusted`: цьому пристрою довіряє лише поточний клієнт
- `Cross-signing verified`: SDK повідомляє, що пристрій верифікований через cross-signing
- `Signed by owner`: пристрій підписаний вашим власним ключем self-signing

`Verified by owner` стає `yes` лише тоді, коли присутня верифікація cross-signing або підпис власника.
Самої лише локальної довіри недостатньо, щоб OpenClaw вважав пристрій повністю верифікованим.

### Що робить bootstrap

`openclaw matrix verify bootstrap` — це команда відновлення та налаштування для зашифрованих облікових записів Matrix.
Вона по черзі виконує все наведене нижче:

- ініціалізує secret storage, за можливості повторно використовуючи наявний ключ відновлення
- ініціалізує cross-signing і завантажує відсутні відкриті ключі cross-signing
- намагається позначити й підписати поточний пристрій через cross-signing
- створює нову серверну резервну копію ключів кімнат, якщо її ще не існує

Якщо homeserver вимагає інтерактивної автентифікації для завантаження ключів cross-signing, OpenClaw спочатку намагається виконати завантаження без автентифікації, потім із `m.login.dummy`, а далі з `m.login.password`, якщо налаштовано `channels.matrix.password`.

Використовуйте `--force-reset-cross-signing` лише тоді, коли ви навмисно хочете відкинути поточну identity cross-signing і створити нову.

Якщо ви навмисно хочете відкинути поточну резервну копію ключів кімнат і почати нову
базову резервну копію для майбутніх повідомлень, використовуйте `openclaw matrix verify backup reset --yes`.
Робіть це лише тоді, коли ви погоджуєтеся, що невідновлювана стара зашифрована історія залишиться
недоступною і що OpenClaw може відтворити secret storage, якщо поточний секрет резервної копії неможливо безпечно завантажити.

### Нова базова резервна копія

Якщо ви хочете зберегти роботу майбутніх зашифрованих повідомлень і погоджуєтеся втратити невідновлювану стару історію, виконайте ці команди по черзі:

```bash
openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status
```

Додавайте `--account <id>` до кожної команди, якщо хочете явно націлити їх на іменований обліковий запис Matrix.

### Поведінка під час запуску

Коли `encryption: true`, для Matrix значення `startupVerification` за замовчуванням — `"if-unverified"`.
Під час запуску, якщо цей пристрій іще не верифіковано, Matrix надішле запит на самоверифікацію в іншому клієнті Matrix,
пропустить дублікати запитів, якщо один уже очікує, і застосує локальну затримку перед повторною спробою після перезапусків.
За замовчуванням після невдалих спроб запиту повторні спроби виконуються раніше, ніж після успішного створення запиту.
Установіть `startupVerification: "off"`, щоб вимкнути автоматичні запити під час запуску, або налаштуйте `startupVerificationCooldownHours`,
якщо хочете коротше або довше вікно повторних спроб.

Під час запуску також автоматично виконується консервативний прохід bootstrap криптографії.
Цей прохід спочатку намагається повторно використати поточні secret storage та identity cross-signing і уникає скидання cross-signing, якщо ви не запускаєте явний процес відновлення bootstrap.

Якщо під час запуску все ще виявляється зламаний стан bootstrap, OpenClaw може спробувати захищений шлях відновлення навіть тоді, коли `channels.matrix.password` не налаштовано.
Якщо homeserver вимагає UIA на основі пароля для такого відновлення, OpenClaw записує попередження в лог і залишає запуск нефатальним замість переривання роботи бота.
Якщо поточний пристрій уже підписаний власником, OpenClaw зберігає цю identity замість автоматичного скидання.

Див. [Міграція Matrix](/uk/install/migrating-matrix) для повного процесу оновлення, обмежень, команд відновлення та поширених повідомлень міграції.

### Повідомлення про верифікацію

Matrix публікує повідомлення життєвого циклу верифікації безпосередньо в сувору DM-кімнату верифікації як повідомлення `m.notice`.
До них належать:

- повідомлення про запит на верифікацію
- повідомлення про готовність до верифікації (з явною вказівкою «Verify by emoji»)
- повідомлення про початок і завершення верифікації
- деталі SAS (emoji та десяткові значення), коли вони доступні

Вхідні запити на верифікацію з іншого клієнта Matrix відстежуються й автоматично приймаються OpenClaw.
Для потоків самоверифікації OpenClaw також автоматично запускає потік SAS, коли стає доступною верифікація за emoji, і підтверджує свій бік.
Для запитів на верифікацію від іншого користувача/пристрою Matrix OpenClaw автоматично приймає запит, а потім чекає, доки потік SAS продовжиться у звичайному режимі.
Щоб завершити верифікацію, вам усе одно потрібно порівняти emoji або десятковий SAS у вашому клієнті Matrix і там підтвердити «They match».

OpenClaw не приймає автоматично власноруч ініційовані дубльовані потоки беззастережно. Під час запуску створення нового запиту пропускається, якщо запит на самоверифікацію вже очікує.

Системні/протокольні повідомлення про верифікацію не пересилаються в pipeline чату агента, тому вони не спричиняють `NO_REPLY`.

### Гігієна пристроїв

Старі пристрої Matrix під керуванням OpenClaw можуть накопичуватися в обліковому записі й ускладнювати розуміння довіри в зашифрованих кімнатах.
Переглянути їх можна так:

```bash
openclaw matrix devices list
```

Видалити застарілі пристрої Matrix під керуванням OpenClaw можна так:

```bash
openclaw matrix devices prune-stale
```

### Crypto store

Matrix E2EE використовує офіційний шлях Rust crypto з `matrix-js-sdk` у Node, із `fake-indexeddb` як shim для IndexedDB. Стан crypto зберігається у файл snapshot (`crypto-idb-snapshot.json`) і відновлюється під час запуску. Файл snapshot містить чутливий стан runtime і зберігається з обмежувальними правами доступу до файлу.

Зашифрований стан runtime розміщується в коренях для кожного облікового запису, користувача та хешу токена в
`~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/`.
Цей каталог містить sync store (`bot-storage.json`), crypto store (`crypto/`),
файл ключа відновлення (`recovery-key.json`), snapshot IndexedDB (`crypto-idb-snapshot.json`),
прив’язки тредів (`thread-bindings.json`) і стан верифікації під час запуску (`startup-verification.json`).
Коли токен змінюється, але identity облікового запису залишається тією самою, OpenClaw повторно використовує найкращий наявний
root для цього кортежу account/homeserver/user, щоб попередній стан sync, стан crypto, прив’язки тредів
і стан верифікації під час запуску залишалися доступними.

## Керування профілем

Оновіть власний профіль Matrix для вибраного облікового запису за допомогою:

```bash
openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png
```

Додайте `--account <id>`, якщо хочете явно націлити команду на іменований обліковий запис Matrix.

Matrix безпосередньо приймає URL аватара `mxc://`. Якщо ви передаєте URL аватара `http://` або `https://`, OpenClaw спочатку завантажує його в Matrix, а потім зберігає отриманий URL `mxc://` назад у `channels.matrix.avatarUrl` (або в перевизначення вибраного облікового запису).

## Треди

Matrix підтримує нативні треди Matrix як для автоматичних відповідей, так і для надсилання через message-tool.

- `dm.sessionScope: "per-user"` (за замовчуванням) зберігає маршрутизацію Matrix DM на рівні відправника, тому кілька кімнат DM можуть використовувати одну сесію, якщо вони відповідають одному й тому самому співрозмовнику.
- `dm.sessionScope: "per-room"` ізолює кожну кімнату Matrix DM у власний ключ сесії, водночас зберігаючи звичайну автентифікацію DM і перевірки allowlist.
- Явні прив’язки conversation у Matrix все одно мають пріоритет над `dm.sessionScope`, тому прив’язані кімнати й треди зберігають вибрану цільову сесію.
- `threadReplies: "off"` зберігає відповіді на верхньому рівні та залишає вхідні повідомлення в тредах на батьківській сесії.
- `threadReplies: "inbound"` відповідає всередині треду лише тоді, коли вхідне повідомлення вже було в цьому треді.
- `threadReplies: "always"` зберігає відповіді в кімнаті в треді, коренем якого є повідомлення-тригер, і маршрутизує цю conversation через відповідну session з областю треду від першого повідомлення-тригера.
- `dm.threadReplies` перевизначає глобальне налаштування лише для DM. Наприклад, ви можете ізолювати треди в кімнатах, залишивши DM пласкими.
- Вхідні повідомлення в тредах включають кореневе повідомлення треду як додатковий контекст агента.
- Надсилання через message-tool автоматично успадковує поточний тред Matrix, якщо ціль — та сама кімната або та сама DM-ціль користувача, якщо явно не вказано `threadId`.
- Повторне використання DM user-target для тієї самої session спрацьовує лише тоді, коли метадані поточної session підтверджують того самого співрозмовника DM в тому самому обліковому записі Matrix; інакше OpenClaw повертається до звичайної маршрутизації на рівні користувача.
- Коли OpenClaw бачить, що кімната Matrix DM конфліктує з іншою кімнатою DM у тій самій спільній session Matrix DM, він публікує одноразове `m.notice` у цій кімнаті з escape hatch `/focus`, якщо прив’язки тредів увімкнені, і з підказкою `dm.sessionScope`.
- Runtime-прив’язки тредів підтримуються для Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і `/acp spawn`, прив’язаний до треду, працюють у кімнатах і DM Matrix.
- `/focus` на верхньому рівні кімнати/DM Matrix створює новий тред Matrix і прив’язує його до цільової session, коли `threadBindings.spawnSubagentSessions=true`.
- Виконання `/focus` або `/acp spawn --thread here` всередині наявного треду Matrix натомість прив’язує цей поточний тред.

## Прив’язки conversation ACP

Кімнати, DM і наявні треди Matrix можна перетворити на довговічні ACP workspace без зміни поверхні чату.

Швидкий операторський процес:

- Виконайте `/acp spawn codex --bind here` всередині Matrix DM, кімнати або наявного треду, яким хочете надалі користуватися.
- На верхньому рівні Matrix DM або кімнати поточний DM/кімната залишається поверхнею чату, а майбутні повідомлення маршрутизуються до створеної ACP session.
- Усередині наявного треду Matrix `--bind here` прив’язує цей поточний тред на місці.
- `/new` і `/reset` скидають ту саму прив’язану ACP session на місці.
- `/acp close` закриває ACP session і видаляє прив’язку.

Примітки:

- `--bind here` не створює дочірній тред Matrix.
- `threadBindings.spawnAcpSessions` потрібен лише для `/acp spawn --thread auto|here`, коли OpenClaw має створити або прив’язати дочірній тред Matrix.

### Конфігурація прив’язки тредів

Matrix успадковує глобальні значення за замовчуванням із `session.threadBindings`, а також підтримує перевизначення для конкретного channel:

- `threadBindings.enabled`
- `threadBindings.idleHours`
- `threadBindings.maxAgeHours`
- `threadBindings.spawnSubagentSessions`
- `threadBindings.spawnAcpSessions`

Прапорці створення прив’язаних до тредів session у Matrix вмикаються лише за бажанням:

- Установіть `threadBindings.spawnSubagentSessions: true`, щоб дозволити `/focus` на верхньому рівні створювати й прив’язувати нові треди Matrix.
- Установіть `threadBindings.spawnAcpSessions: true`, щоб дозволити `/acp spawn --thread auto|here` прив’язувати ACP session до тредів Matrix.

## Реакції

Matrix підтримує вихідні дії реакцій, вхідні сповіщення про реакції та вхідні реакції-підтвердження.

- Інструментарій вихідних реакцій контролюється `channels["matrix"].actions.reactions`.
- `react` додає реакцію до конкретної події Matrix.
- `reactions` показує поточне зведення реакцій для конкретної події Matrix.
- `emoji=""` видаляє власні реакції облікового запису бота на цю подію.
- `remove: true` видаляє лише вказану emoji-реакцію з облікового запису бота.

Область реакцій-підтверджень визначається стандартним порядком резолюції OpenClaw:

- `channels["matrix"].accounts.<accountId>.ackReaction`
- `channels["matrix"].ackReaction`
- `messages.ackReaction`
- запасний emoji з identity агента

Область дії реакції-підтвердження визначається в такому порядку:

- `channels["matrix"].accounts.<accountId>.ackReactionScope`
- `channels["matrix"].ackReactionScope`
- `messages.ackReactionScope`

Режим сповіщень про реакції визначається в такому порядку:

- `channels["matrix"].accounts.<accountId>.reactionNotifications`
- `channels["matrix"].reactionNotifications`
- за замовчуванням: `own`

Поведінка:

- `reactionNotifications: "own"` пересилає додані події `m.reaction`, коли вони націлені на створені ботом повідомлення Matrix.
- `reactionNotifications: "off"` вимикає системні події реакцій.
- Видалення реакцій не синтезуються в системні події, оскільки Matrix подає їх як redaction, а не як окремі видалення `m.reaction`.

## Контекст історії

- `channels.matrix.historyLimit` керує тим, скільки недавніх повідомлень кімнати включаються як `InboundHistory`, коли повідомлення кімнати Matrix запускає агента. Якщо не задано, використовується `messages.groupChat.historyLimit`; якщо обидва параметри не задані, ефективне значення за замовчуванням — `0`. Установіть `0`, щоб вимкнути.
- Історія кімнати Matrix обмежена лише кімнатою. DM і надалі використовують звичайну історію session.
- Історія кімнати Matrix стосується лише очікуваних повідомлень: OpenClaw буферизує повідомлення кімнати, які ще не викликали відповіді, а потім знімає snapshot цього вікна, коли надходить згадка або інший тригер.
- Поточне повідомлення-тригер не включається в `InboundHistory`; воно залишається в основному вхідному body для цього ходу.
- Повторні спроби для тієї самої події Matrix повторно використовують початковий snapshot історії, а не зміщуються вперед до новіших повідомлень кімнати.

## Видимість контексту

Matrix підтримує спільний елемент керування `contextVisibility` для додаткового контексту кімнати, такого як отриманий текст відповіді, корені тредів і очікувана історія.

- `contextVisibility: "all"` — значення за замовчуванням. Додатковий контекст зберігається як отримано.
- `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками allowlist кімнати/користувача.
- `contextVisibility: "allowlist_quote"` поводиться як `allowlist`, але все одно зберігає одну явну цитовану відповідь.

Це налаштування впливає на видимість додаткового контексту, а не на те, чи може саме вхідне повідомлення запустити відповідь.
Авторизація тригера, як і раніше, визначається `groupPolicy`, `groups`, `groupAllowFrom` і налаштуваннями політики DM.

## Політика DM і кімнат

```json5
{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
        threadReplies: "off",
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}
```

Див. [Groups](/uk/channels/groups) щодо поведінки gating за згадкою та allowlist.

Приклад pairing для Matrix DM:

```bash
openclaw pairing list matrix
openclaw pairing approve matrix <CODE>
```

Якщо непідтверджений користувач Matrix продовжує писати вам до схвалення, OpenClaw повторно використовує той самий очікуваний код pairing і може знову надіслати відповідь-нагадування після короткої паузи замість створення нового коду.

Див. [Pairing](/uk/channels/pairing) щодо спільного процесу pairing для DM і структури зберігання.

## Відновлення direct room

Якщо стан direct message виходить із синхронізації, OpenClaw може отримати застарілі зіставлення `m.direct`, які вказують на старі solo room замість активного DM. Перегляньте поточне зіставлення для співрозмовника за допомогою:

```bash
openclaw matrix direct inspect --user-id @alice:example.org
```

Виправте його за допомогою:

```bash
openclaw matrix direct repair --user-id @alice:example.org
```

Процес відновлення:

- надає перевагу суворому DM 1:1, який уже зіставлено в `m.direct`
- у разі потреби використовує будь-який наразі приєднаний суворий DM 1:1 із цим користувачем
- створює нову direct room і переписує `m.direct`, якщо справного DM не існує

Процес відновлення не видаляє старі кімнати автоматично. Він лише вибирає справний DM і оновлює зіставлення, щоб нові надсилання Matrix, повідомлення про верифікацію та інші direct-message потоки знову націлювалися на правильну кімнату.

## Підтвердження exec

Matrix може виступати нативним клієнтом підтвердження для облікового запису Matrix. Нативні
параметри маршрутизації DM/channel, як і раніше, розміщені в конфігурації підтверджень exec:

- `channels.matrix.execApprovals.enabled`
- `channels.matrix.execApprovals.approvers` (необов’язково; якщо не задано, використовується `channels.matrix.dm.allowFrom`)
- `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, за замовчуванням: `dm`)
- `channels.matrix.execApprovals.agentFilter`
- `channels.matrix.execApprovals.sessionFilter`

Особи, що підтверджують, мають бути ID користувачів Matrix, наприклад `@owner:example.org`. Matrix автоматично вмикає нативні підтвердження, коли `enabled` не задано або має значення `"auto"` і принаймні одного approver можна визначити. Підтвердження exec спочатку використовують `execApprovals.approvers`, а в разі потреби можуть використовувати `channels.matrix.dm.allowFrom`. Підтвердження Plugin авторизуються через `channels.matrix.dm.allowFrom`. Установіть `enabled: false`, щоб явно вимкнути Matrix як нативний клієнт підтвердження. Інакше запити на підтвердження повертаються до інших налаштованих маршрутів підтвердження або до запасної політики підтвердження.

Нативна маршрутизація Matrix підтримує обидва типи підтверджень:

- `channels.matrix.execApprovals.*` керує нативним режимом fanout DM/channel для запитів на підтвердження Matrix.
- Підтвердження exec використовують набір осіб, що підтверджують exec, із `execApprovals.approvers` або `channels.matrix.dm.allowFrom`.
- Підтвердження Plugin використовують allowlist Matrix DM із `channels.matrix.dm.allowFrom`.
- Скорочення реакціями Matrix і оновлення повідомлень застосовуються як до підтверджень exec, так і до підтверджень Plugin.

Правила доставки:

- `target: "dm"` надсилає запити на підтвердження в DM осіб, що підтверджують
- `target: "channel"` надсилає запит назад у вихідну кімнату або DM Matrix
- `target: "both"` надсилає в DM осіб, що підтверджують, і у вихідну кімнату або DM Matrix

Запити на підтвердження Matrix додають скорочення реакціями до основного повідомлення підтвердження:

- `✅` = дозволити один раз
- `❌` = відхилити
- `♾️` = дозволити завжди, якщо таке рішення дозволене ефективною політикою exec

Особи, що підтверджують, можуть реагувати на це повідомлення або використовувати запасні slash commands: `/approve <id> allow-once`, `/approve <id> allow-always` або `/approve <id> deny`.

Лише визначені approver-и можуть дозволяти або відхиляти. Для підтверджень exec доставка через channel включає текст команди, тому вмикайте `channel` або `both` лише в довірених кімнатах.

Перевизначення для окремого облікового запису:

- `channels.matrix.accounts.<account>.execApprovals`

Пов’язана документація: [Exec approvals](/uk/tools/exec-approvals)

## Кілька облікових записів

```json5
{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
          dm: {
            policy: "allowlist",
            allowFrom: ["@ops:example.org"],
            threadReplies: "off",
          },
        },
      },
    },
  },
}
```

Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для іменованих облікових записів, якщо обліковий запис не має власного перевизначення.
Ви можете обмежити успадковані записи кімнат одним обліковим записом Matrix через `groups.<room>.account`.
Записи без `account` залишаються спільними для всіх облікових записів Matrix, а записи з `account: "default"` і далі працюють, коли обліковий запис за замовчуванням налаштований безпосередньо на верхньому рівні `channels.matrix.*`.
Часткові спільні значення автентифікації за замовчуванням самі по собі не створюють окремий неявний обліковий запис за замовчуванням. OpenClaw синтезує обліковий запис верхнього рівня `default` лише тоді, коли цей обліковий запис за замовчуванням має актуальну автентифікацію (`homeserver` плюс `accessToken`, або `homeserver` плюс `userId` і `password`); іменовані облікові записи все одно можуть залишатися доступними для виявлення через `homeserver` плюс `userId`, якщо кешовані облікові дані пізніше задовольнять вимоги автентифікації.
Якщо в Matrix уже є рівно один іменований обліковий запис або `defaultAccount` вказує на наявний ключ іменованого облікового запису, під час підвищення від режиму одного облікового запису до кількох облікових записів для відновлення/налаштування цей обліковий запис зберігається замість створення нового запису `accounts.default`. У цей підвищений обліковий запис переміщуються лише ключі автентифікації/bootstrap Matrix; спільні ключі політики доставки залишаються на верхньому рівні.
Установіть `defaultAccount`, якщо хочете, щоб OpenClaw віддавав перевагу одному іменованому обліковому запису Matrix для неявної маршрутизації, probe і операцій CLI.
Якщо налаштовано кілька облікових записів Matrix і один ID облікового запису має значення `default`, OpenClaw неявно використовує цей обліковий запис навіть тоді, коли `defaultAccount` не задано.
Якщо ви налаштували кілька іменованих облікових записів, установіть `defaultAccount` або передавайте `--account <id>` для команд CLI, які покладаються на неявний вибір облікового запису.
Передавайте `--account <id>` до `openclaw matrix verify ...` і `openclaw matrix devices ...`, якщо хочете перевизначити цей неявний вибір для однієї команди.

Див. [Configuration reference](/uk/gateway/configuration-reference#multi-account-all-channels) щодо спільного шаблону для кількох облікових записів.

## Приватні/LAN homeserver

За замовчуванням OpenClaw блокує приватні/внутрішні homeserver Matrix для захисту від SSRF, якщо ви
явно не дозволите це для кожного облікового запису окремо.

Якщо ваш homeserver працює на localhost, LAN/Tailscale IP або внутрішньому імені хоста, увімкніть
`network.dangerouslyAllowPrivateNetwork` для цього облікового запису Matrix:

```json5
{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      network: {
        dangerouslyAllowPrivateNetwork: true,
      },
      accessToken: "syt_internal_xxx",
    },
  },
}
```

Приклад налаштування через CLI:

```bash
openclaw matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx
```

Ця опція дозволяє лише довірені приватні/внутрішні цілі. Публічні homeserver без шифрування, такі як
`http://matrix.example.org:8008`, як і раніше, блокуються. За можливості віддавайте перевагу `https://`.

## Проксіювання трафіку Matrix

Якщо вашому розгортанню Matrix потрібен явний вихідний HTTP(S)-проксі, установіть `channels.matrix.proxy`:

```json5
{
  channels: {
    matrix: {
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
    },
  },
}
```

Іменовані облікові записи можуть перевизначити значення верхнього рівня через `channels.matrix.accounts.<id>.proxy`.
OpenClaw використовує те саме налаштування проксі для runtime-трафіку Matrix і probe перевірки статусу облікового запису.

## Розв’язання цілей

Matrix приймає такі форми цілей скрізь, де OpenClaw просить вас указати кімнату або ціль користувача:

- Користувачі: `@user:server`, `user:@user:server` або `matrix:user:@user:server`
- Кімнати: `!room:server`, `room:!room:server` або `matrix:room:!room:server`
- Псевдоніми: `#alias:server`, `channel:#alias:server` або `matrix:channel:#alias:server`

Пошук у живому каталозі використовує обліковий запис Matrix, під яким виконано вхід:

- Пошук користувачів звертається до каталогу користувачів Matrix на цьому homeserver.
- Пошук кімнат напряму приймає явні ID кімнат і псевдоніми, а потім у разі потреби шукає назви приєднаних кімнат для цього облікового запису.
- Пошук за назвами приєднаних кімнат є best-effort. Якщо назву кімнати не вдається розв’язати до ID або псевдоніма, її ігнорують під час runtime-розв’язання allowlist.

## Довідник конфігурації

- `enabled`: увімкнути або вимкнути channel.
- `name`: необов’язкова мітка для облікового запису.
- `defaultAccount`: бажаний ID облікового запису, коли налаштовано кілька облікових записів Matrix.
- `homeserver`: URL homeserver, наприклад `https://matrix.example.org`.
- `network.dangerouslyAllowPrivateNetwork`: дозволити цьому обліковому запису Matrix підключатися до приватних/внутрішніх homeserver. Увімкніть це, коли homeserver резолвиться в `localhost`, LAN/Tailscale IP або внутрішній хост, наприклад `matrix-synapse`.
- `proxy`: необов’язковий URL HTTP(S)-проксі для трафіку Matrix. Іменовані облікові записи можуть перевизначати значення верхнього рівня власним `proxy`.
- `userId`: повний ID користувача Matrix, наприклад `@bot:example.org`.
- `accessToken`: токен доступу для автентифікації на основі токена. Для `channels.matrix.accessToken` і `channels.matrix.accounts.<id>.accessToken` підтримуються як значення у відкритому тексті, так і значення SecretRef через провайдери env/file/exec. Див. [Secrets Management](/uk/gateway/secrets).
- `password`: пароль для входу на основі пароля. Підтримуються значення у відкритому тексті та значення SecretRef.
- `deviceId`: явний ID пристрою Matrix.
- `deviceName`: відображувана назва пристрою для входу за паролем.
- `avatarUrl`: збережений URL власного аватара для синхронізації профілю та оновлень `profile set`.
- `initialSyncLimit`: максимальна кількість подій, що завантажуються під час startup sync.
- `encryption`: увімкнути E2EE.
- `allowlistOnly`: коли має значення `true`, підвищує політику кімнат `open` до `allowlist` і примусово змінює всі активні політики DM, крім `disabled` (включно з `pairing` і `open`), на `allowlist`. Не впливає на політики `disabled`.
- `allowBots`: дозволяти повідомлення від інших налаштованих облікових записів Matrix OpenClaw (`true` або `"mentions"`).
- `groupPolicy`: `open`, `allowlist` або `disabled`.
- `contextVisibility`: режим видимості додаткового контексту кімнати (`all`, `allowlist`, `allowlist_quote`).
- `groupAllowFrom`: allowlist ID користувачів для трафіку кімнат. Повні ID користувачів Matrix — найбезпечніший варіант; точні збіги в каталозі резолвляться під час запуску та коли allowlist змінюється, поки monitor працює. Нерозв’язані імена ігноруються.
- `historyLimit`: максимальна кількість повідомлень кімнати, що включаються як контекст історії групи. Якщо не задано, використовується `messages.groupChat.historyLimit`; якщо обидва параметри не задані, ефективне значення за замовчуванням — `0`. Установіть `0`, щоб вимкнути.
- `replyToMode`: `off`, `first`, `all` або `batched`.
- `markdown`: необов’язкова конфігурація рендерингу Markdown для вихідного тексту Matrix.
- `streaming`: `off` (за замовчуванням), `"partial"`, `"quiet"`, `true` або `false`. `"partial"` і `true` вмикають оновлення чернетки з попереднім переглядом спочатку, використовуючи звичайні текстові повідомлення Matrix. `"quiet"` використовує попередні тихі повідомлення для власних конфігурацій push-rule. `false` еквівалентне `"off"`.
- `blockStreaming`: `true` вмикає окремі повідомлення прогресу для завершених блоків відповіді помічника, поки активна потокова передача чернетки попереднього перегляду.
- `threadReplies`: `off`, `inbound` або `always`.
- `threadBindings`: перевизначення для конкретного channel для маршрутизації session, прив’язаних до тредів, та їх життєвого циклу.
- `startupVerification`: режим автоматичного запиту на самоверифікацію під час запуску (`if-unverified`, `off`).
- `startupVerificationCooldownHours`: затримка перед повторною спробою автоматичних запитів на верифікацію під час запуску.
- `textChunkLimit`: розмір фрагмента вихідного повідомлення в символах (застосовується, коли `chunkMode` має значення `length`).
- `chunkMode`: `length` ділить повідомлення за кількістю символів; `newline` ділить на межах рядків.
- `responsePrefix`: необов’язковий рядок, що додається на початку всіх вихідних відповідей для цього channel.
- `ackReaction`: необов’язкове перевизначення реакції-підтвердження для цього channel/облікового запису.
- `ackReactionScope`: необов’язкове перевизначення області реакції-підтвердження (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`).
- `reactionNotifications`: режим вхідних сповіщень про реакції (`own`, `off`).
- `mediaMaxMb`: ліміт розміру медіа в МБ для вихідного надсилання та обробки вхідних медіа.
- `autoJoin`: політика автоматичного приєднання за запрошенням (`always`, `allowlist`, `off`). За замовчуванням: `off`. Застосовується до всіх запрошень Matrix, включно із запрошеннями у стилі DM.
- `autoJoinAllowlist`: кімнати/псевдоніми, дозволені, коли `autoJoin` має значення `allowlist`. Записи псевдонімів резолвляться до ID кімнат під час обробки запрошень; OpenClaw не довіряє стану псевдоніма, заявленому запрошеною кімнатою.
- `dm`: блок політики DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`).
- `dm.policy`: керує доступом до DM після того, як OpenClaw приєднався до кімнати та класифікував її як DM. Це не змінює те, чи буде запрошення автоматично прийняте.
- `dm.allowFrom`: allowlist ID користувачів для трафіку DM. Повні ID користувачів Matrix — найбезпечніший варіант; точні збіги в каталозі резолвляться під час запуску та коли allowlist змінюється, поки monitor працює. Нерозв’язані імена ігноруються.
- `dm.sessionScope`: `per-user` (за замовчуванням) або `per-room`. Використовуйте `per-room`, якщо хочете, щоб кожна кімната Matrix DM зберігала окремий контекст, навіть якщо співрозмовник той самий.
- `dm.threadReplies`: перевизначення політики тредів лише для DM (`off`, `inbound`, `always`). Воно перевизначає налаштування верхнього рівня `threadReplies` як для розміщення відповідей, так і для ізоляції сесій у DM.
- `execApprovals`: нативна доставка підтверджень exec для Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`).
- `execApprovals.approvers`: ID користувачів Matrix, яким дозволено підтверджувати запити exec. Необов’язково, якщо `dm.allowFrom` уже визначає approver-ів.
- `execApprovals.target`: `dm | channel | both` (за замовчуванням: `dm`).
- `accounts`: іменовані перевизначення для окремих облікових записів. Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для цих записів.
- `groups`: карта політик для кожної кімнати. Віддавайте перевагу ID кімнат або псевдонімам; нерозв’язані назви кімнат ігноруються під час runtime. Ідентичність session/group після резолюції використовує стабільний ID кімнати.
- `groups.<room>.account`: обмежити один успадкований запис кімнати конкретним обліковим записом Matrix у конфігураціях із кількома обліковими записами.
- `groups.<room>.allowBots`: перевизначення на рівні кімнати для відправників із налаштованих ботів (`true` або `"mentions"`).
- `groups.<room>.users`: allowlist відправників для конкретної кімнати.
- `groups.<room>.tools`: перевизначення allow/deny інструментів для конкретної кімнати.
- `groups.<room>.autoReply`: перевизначення gating за згадкою на рівні кімнати. `true` вимикає вимогу згадки для цієї кімнати; `false` примусово знову вмикає її.
- `groups.<room>.skills`: необов’язковий фільтр Skills на рівні кімнати.
- `groups.<room>.systemPrompt`: необов’язковий фрагмент system prompt на рівні кімнати.
- `rooms`: застарілий псевдонім для `groups`.
- `actions`: керування інструментами для окремих дій (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`).

## Пов’язане

- [Channels Overview](/uk/channels) — усі підтримувані channels
- [Pairing](/uk/channels/pairing) — автентифікація DM і процес pairing
- [Groups](/uk/channels/groups) — поведінка групового чату та gating за згадкою
- [Channel Routing](/uk/channels/channel-routing) — маршрутизація session для повідомлень
- [Security](/uk/gateway/security) — модель доступу та посилення безпеки
