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

# Matrix

Matrix — це вбудований 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 і виявлення статусу каналу, навіть якщо поточна автентифікація не задана безпосередньо в конфігурації.

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

- `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_*`.

Інтерактивний майстер пропонує ярлик змінних середовища лише тоді, коли ці змінні середовища автентифікації вже наявні, а для вибраного облікового запису автентифікацію 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.

## Попередній перегляд streaming

Потокове надсилання відповідей 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 редагує його перед надсиланням фінальної відповіді з медіа.
- Редагування попереднього перегляду потребують додаткових викликів API Matrix. Залишайте streaming вимкненим, якщо хочете максимально консервативну поведінку щодо rate limit.

`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:

Швидка схема перед початком:

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

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

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

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

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

```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. Переконайтеся, що обліковий запис одержувача вже має pushers:

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

Якщо у відповіді немає активних pushers/пристроїв, спочатку виправте звичайні сповіщення 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 вашого бота OpenClaw Matrix, а не MXID користувача-одержувача

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

- Правила push прив’язані до `ruleId`. Повторний запуск `PUT` для того самого ID правила оновлює саме це правило.
- Якщо один користувач-одержувач має отримувати сповіщення від кількох облікових записів ботів OpenClaw Matrix, створіть по одному правилу для кожного бота з унікальним 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` не показує жодних pushers, користувач ще не має налаштованої робочої доставки push у Matrix для цього облікового запису/пристрою.

#### Synapse

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

- Жодна спеціальна зміна `homeserver.yaml` для сповіщень про фіналізований попередній перегляд OpenClaw не потрібна.
- Якщо ваше розгортання Synapse вже надсилає звичайні push-сповіщення Matrix, токен користувача + виклик `pushrules` вище є основним кроком налаштування.
- Якщо ви запускаєте Synapse за reverse proxy або workers, переконайтеся, що `/_matrix/client/.../pushrules/` коректно доходить до Synapse.
- Якщо ви використовуєте workers Synapse, переконайтеся, що pushers працездатні. Доставку 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 від інших налаштованих облікових записів OpenClaw Matrix ігноруються.

Використовуйте `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 трактує “bot-authored” як “надіслане іншим налаштованим обліковим записом 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
```

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

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

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

```bash
openclaw matrix verify bootstrap
```

Розширена діагностика bootstrap:

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

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

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

Верифікувати цей пристрій за допомогою recovery key:

```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`.

### Що означає “verified”

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

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

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

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

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

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

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

Використовуйте `--force-reset-cross-signing` лише тоді, коли ви свідомо хочете відкинути поточну ідентичність 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`, значенням за замовчуванням для `startupVerification` є `"if-unverified"`.
Під час запуску, якщо цей пристрій усе ще не верифіковано, Matrix запитає самоверифікацію в іншому клієнті Matrix,
пропустить дубльовані запити, якщо один уже очікує на виконання, і застосує локальну затримку перед повторною спробою після перезапусків.
За замовчуванням невдалі спроби запиту повторюються раніше, ніж успішне створення запиту.
Установіть `startupVerification: "off"`, щоб вимкнути автоматичні запити під час запуску, або налаштуйте `startupVerificationCooldownHours`,
якщо хочете коротше або довше вікно повторної спроби.

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

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

Див. [міграцію 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 не приймає автоматично беззастережно дубльовані самостійно ініційовані потоки. Під час запуску створення нового запиту пропускається, якщо запит на самоверифікацію вже очікує на виконання.

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

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

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

```bash
openclaw matrix devices list
```

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

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

### Crypto store

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

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

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

Оновіть власний профіль 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 у власний ключ сеансу, при цьому все одно використовуються звичайні перевірки автентифікації та allowlist для DM.
- Явні прив’язки розмов Matrix, як і раніше, мають пріоритет над `dm.sessionScope`, тому прив’язані кімнати й треди зберігають вибраний цільовий сеанс.
- `threadReplies: "off"` зберігає відповіді на верхньому рівні й утримує вхідні повідомлення з тредів у батьківському сеансі.
- `threadReplies: "inbound"` відповідає всередині треду лише тоді, коли вхідне повідомлення вже було в цьому треді.
- `threadReplies: "always"` зберігає відповіді в кімнаті в треді, коренем якого є повідомлення-тригер, і маршрутизує цю розмову через відповідний сеанс у межах треду від першого повідомлення-тригера.
- `dm.threadReplies` перевизначає налаштування верхнього рівня лише для DM. Наприклад, ви можете ізолювати треди кімнат, водночас залишаючи DM пласкими.
- Вхідні повідомлення з тредів включають кореневе повідомлення треду як додатковий контекст агента.
- Надсилання через message-tool автоматично успадковують поточний тред Matrix, коли ціллю є та сама кімната або той самий цільовий користувач DM, якщо явно не задано `threadId`.
- Повторне використання DM user-target у тому самому сеансі спрацьовує лише тоді, коли метадані поточного сеансу підтверджують того самого співрозмовника DM у тому самому обліковому записі Matrix; інакше OpenClaw повертається до звичайної маршрутизації в межах користувача.
- Коли OpenClaw бачить, що кімната Matrix DM конфліктує з іншою кімнатою DM у тому самому спільному сеансі 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 і прив’язує його до цільового сеансу, коли `threadBindings.spawnSubagentSessions=true`.
- Запуск `/focus` або `/acp spawn --thread here` всередині наявного треду Matrix натомість прив’язує цей поточний тред.

## Прив’язки розмов ACP

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

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

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

Примітки:

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

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

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

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

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

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

## Реакції

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

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

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

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

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

- `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 подає їх як редагування, а не як окремі видалення `m.reaction`.

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

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

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

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

- `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 повторно використовує той самий pending код pairing і може знову надіслати відповідь-нагадування після короткої затримки, замість створення нового коду.

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

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

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

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

Відновити її можна так:

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

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

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

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

## Exec approvals

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

- `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 автоматично вмикає native approvals, коли `enabled` не задано або дорівнює `"auto"` і принаймні одного схвалювача вдається розв’язати. Exec approvals спочатку використовують `execApprovals.approvers`, а якщо потрібно, можуть повернутися до `channels.matrix.dm.allowFrom`. Plugin approvals авторизуються через `channels.matrix.dm.allowFrom`. Установіть `enabled: false`, щоб явно вимкнути Matrix як нативний клієнт схвалення. Інакше запити на схвалення повертаються до інших налаштованих маршрутів схвалення або до резервної політики схвалення.

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

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

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

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

Запити на схвалення Matrix ініціалізують скорочення реакцій у первинному повідомленні схвалення:

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

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

Лише розв’язані схвалювачі можуть схвалювати або відхиляти. Для exec approvals доставка в канал включає текст команди, тому вмикайте `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 для неявної маршрутизації, перевірок і операцій CLI.
Якщо налаштовано кілька облікових записів Matrix і один із ID облікових записів — `default`, OpenClaw неявно використовує цей обліковий запис, навіть якщо `defaultAccount` не задано.
Якщо ви налаштували кілька іменованих облікових записів, задайте `defaultAccount` або передавайте `--account <id>` для команд CLI, які покладаються на неявний вибір облікового запису.
Передавайте `--account <id>` до `openclaw matrix verify ...` і `openclaw matrix devices ...`, якщо хочете перевизначити цей неявний вибір для однієї команди.

Див. [Довідник із конфігурації](/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
```

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

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

Якщо вашому розгортанню Matrix потрібен явний вихідний HTTP(S) proxy, задайте `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 використовує те саме налаштування proxy і для runtime-трафіку Matrix, і для перевірок статусу облікового запису.

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

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`: увімкнути або вимкнути канал.
- `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) proxy для трафіку Matrix. Іменовані облікові записи можуть перевизначати значення верхнього рівня власним `proxy`.
- `userId`: повний ID користувача Matrix, наприклад `@bot:example.org`.
- `accessToken`: токен доступу для автентифікації на основі токена. Підтримуються звичайні текстові значення і значення SecretRef для `channels.matrix.accessToken` і `channels.matrix.accounts.<id>.accessToken` у провайдерах env/file/exec. Див. [Керування секретами](/uk/gateway/secrets).
- `password`: пароль для входу на основі пароля. Підтримуються звичайні текстові значення і значення SecretRef.
- `deviceId`: явний ID пристрою Matrix.
- `deviceName`: відображувана назва пристрою для входу за паролем.
- `avatarUrl`: збережений URL власного аватара для синхронізації профілю та оновлень `profile set`.
- `initialSyncLimit`: максимальна кількість подій, отриманих під час стартової синхронізації.
- `encryption`: увімкнути E2EE.
- `allowlistOnly`: коли `true`, підвищує політику кімнат `open` до `allowlist` і примусово переводить усі активні політики DM, окрім `disabled` (включно з `pairing` і `open`), у `allowlist`. Не впливає на політики `disabled`.
- `allowBots`: дозволити повідомлення від інших налаштованих облікових записів OpenClaw Matrix (`true` або `"mentions"`).
- `groupPolicy`: `open`, `allowlist` або `disabled`.
- `contextVisibility`: режим видимості додаткового контексту кімнати (`all`, `allowlist`, `allowlist_quote`).
- `groupAllowFrom`: allowlist ID користувачів для трафіку кімнат. Записи мають бути повними ID користувачів Matrix; нерозв’язані імена ігноруються під час виконання.
- `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. `false` еквівалентно `"off"`.
- `blockStreaming`: `true` вмикає окремі повідомлення про прогрес для завершених блоків асистента, поки активне потокове надсилання з чернеткою попереднього перегляду.
- `threadReplies`: `off`, `inbound` або `always`.
- `threadBindings`: перевизначення для окремого каналу для маршрутизації та життєвого циклу сеансів, прив’язаних до тредів.
- `startupVerification`: режим автоматичного запиту самоверифікації під час запуску (`if-unverified`, `off`).
- `startupVerificationCooldownHours`: затримка перед повторною спробою автоматичних запитів на верифікацію під час запуску.
- `textChunkLimit`: розмір фрагмента вихідного повідомлення в символах (застосовується, коли `chunkMode` має значення `length`).
- `chunkMode`: `length` розбиває повідомлення за кількістю символів; `newline` розбиває за межами рядків.
- `responsePrefix`: необов’язковий рядок, який додається на початок усіх вихідних відповідей для цього каналу.
- `ackReaction`: необов’язкове перевизначення ack-реакції для цього каналу/облікового запису.
- `ackReactionScope`: необов’язкове перевизначення області ack-реакції (`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`: записи мають бути повними ID користувачів Matrix, якщо тільки ви вже не розв’язали їх через пошук у живому каталозі.
- `dm.sessionScope`: `per-user` (за замовчуванням) або `per-room`. Використовуйте `per-room`, якщо хочете, щоб кожна кімната Matrix DM зберігала окремий контекст, навіть якщо співрозмовник той самий.
- `dm.threadReplies`: перевизначення політики тредів лише для DM (`off`, `inbound`, `always`). Воно перевизначає верхньорівневе налаштування `threadReplies` як для розміщення відповідей, так і для ізоляції сеансів у DM.
- `execApprovals`: нативна доставка exec approval у Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`).
- `execApprovals.approvers`: ID користувачів Matrix, яким дозволено схвалювати запити exec. Необов’язково, якщо `dm.allowFrom` уже визначає схвалювачів.
- `execApprovals.target`: `dm | channel | both` (за замовчуванням: `dm`).
- `accounts`: іменовані перевизначення для окремих облікових записів. Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для цих записів.
- `groups`: карта політик для окремих кімнат. Надавайте перевагу ID кімнат або псевдонімам; нерозв’язані назви кімнат ігноруються під час виконання. Ідентичність сеансу/групи використовує стабільний ID кімнати після розв’язання.
- `groups.<room>.account`: обмежити один успадкований запис кімнати конкретним обліковим записом Matrix у конфігураціях із кількома обліковими записами.
- `groups.<room>.allowBots`: перевизначення рівня кімнати для відправників-ботів із конфігурації (`true` або `"mentions"`).
- `groups.<room>.users`: allowlist відправників для окремої кімнати.
- `groups.<room>.tools`: перевизначення дозволу/заборони tools для окремої кімнати.
- `groups.<room>.autoReply`: перевизначення рівня кімнати для gating згадок. `true` вимикає вимоги до згадок для цієї кімнати; `false` примусово знову вмикає їх.
- `groups.<room>.skills`: необов’язковий фільтр Skills для окремої кімнати.
- `groups.<room>.systemPrompt`: необов’язковий фрагмент системного prompt для окремої кімнати.
- `rooms`: застарілий псевдонім для `groups`.
- `actions`: контроль доступу до tools для окремих дій (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`).

## Пов’язане

- [Огляд каналів](/uk/channels) — усі підтримувані канали
- [Pairing](/uk/channels/pairing) — автентифікація DM і процес pairing
- [Groups](/uk/channels/groups) — поведінка групового чату і gating згадок
- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сеансів для повідомлень
- [Безпека](/uk/gateway/security) — модель доступу та захист
