---
read_when:
    - Налаштування Matrix в OpenClaw
    - Налаштування наскрізного шифрування (E2EE) та перевірки в Matrix
summary: Стан підтримки Matrix, налаштування та приклади конфігурації
title: Matrix
x-i18n:
    generated_at: "2026-07-12T12:59:24Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 42f1775d1f92198d1eafdd8f3e07fcb6921bdc4a5c095ce3e793c260e037e06f
    source_path: channels/matrix.md
    workflow: 16
---

Matrix — це завантажуваний плагін каналу (`@openclaw/matrix`), створений на основі офіційного `matrix-js-sdk`. Він підтримує особисті повідомлення, кімнати, гілки, медіафайли, реакції, опитування, геопозицію та наскрізне шифрування (E2EE).

## Встановлення

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

Для специфікацій плагінів без префікса спочатку виконується пошук у ClawHub, а потім — резервний пошук у npm. Щоб примусово вибрати джерело, скористайтеся `openclaw plugins install clawhub:@openclaw/matrix` або `npm:@openclaw/matrix`. З локальної робочої копії: `openclaw plugins install ./path/to/local/matrix-plugin`.

`plugins install` реєструє та вмикає плагін; окремий крок `enable` не потрібен. Однак канал не працюватиме, доки його не буде налаштовано нижче. Загальні правила встановлення див. у розділі [Плагіни](/uk/tools/plugin).

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

1. Створіть обліковий запис Matrix на своєму домашньому сервері.
2. Налаштуйте `channels.matrix` за допомогою `homeserver` + `accessToken` або `homeserver` + `userId` + `password`.
3. Перезапустіть Gateway.
4. Почніть особисте листування з ботом або запросіть його до кімнати. Нові запрошення приймаються лише тоді, коли це дозволяє [`autoJoin`](#auto-join).

### Інтерактивне налаштування

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

Майстер запитує URL домашнього сервера, метод автентифікації (токен або пароль), ідентифікатор користувача (лише для автентифікації паролем), необов’язкову назву пристрою, чи потрібно ввімкнути E2EE, а також параметри доступу до кімнат і автоматичного приєднання. Якщо відповідні змінні середовища `MATRIX_*` уже існують, а для облікового запису немає збережених даних автентифікації, майстер пропонує скорочений шлях із використанням змінних середовища. Перед збереженням списку дозволів перетворіть назви кімнат на ідентифікатори за допомогою `openclaw channels resolve --channel matrix "Project Room"`. Увімкнення E2EE в майстрі запускає ту саму початкову конфігурацію, що й [`openclaw matrix encryption setup`](#encryption-and-verification).

### Мінімальна конфігурація

На основі токена:

```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",
    },
  },
}
```

### Автоматичне приєднання

Значенням `channels.matrix.autoJoin` за замовчуванням є `"off"`: бот не з’являтиметься в нових кімнатах або особистих чатах за новими запрошеннями, доки ви не приєднаєте його вручну. OpenClaw не може визначити в момент отримання запрошення, чи воно стосується особистого чату або групи, тому кожне запрошення спочатку обробляється через `autoJoin`; `dm.policy` застосовується лише пізніше, після приєднання бота й класифікації кімнати.

<Warning>
Установіть `autoJoin: "allowlist"` разом з `autoJoinAllowlist`, щоб обмежити прийняті запрошення, або `autoJoin: "always"`, щоб приймати всі запрошення.

`autoJoinAllowlist` приймає лише `!roomId:server`, `#alias:server` або `*`. Звичайні назви кімнат відхиляються; псевдоніми зіставляються через домашній сервер, а не зі станом, заявленим кімнатою, до якої надійшло запрошення.
</Warning>

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

### Формати цілей списків дозволів

- Особисті повідомлення (`dm.allowFrom`, `groupAllowFrom`, `groups.<room>.users`): використовуйте `@user:server`. Відображувані імена за замовчуванням ігноруються, оскільки їх можна змінювати; установлюйте `dangerouslyAllowNameMatching: true` лише для явної сумісності зі зіставленням відображуваних імен.
- Ключі списку дозволених кімнат (`groups`, застарілий псевдонім `rooms`): використовуйте `!room:server` або `#alias:server`. Звичайні назви ігноруються, якщо не встановлено `dangerouslyAllowNameMatching: true`.
- Списки дозволених запрошень (`autoJoinAllowlist`): використовуйте `!room:server`, `#alias:server` або `*`. Звичайні назви завжди відхиляються.

### Нормалізація ідентифікатора облікового запису

Майстер перетворює зручну назву на нормалізований ідентифікатор облікового запису (`Ops Bot` -> `ops-bot`). У назвах змінних середовища з областю дії розділові знаки екрануються шістнадцятковим кодом, щоб запобігти колізіям облікових записів: `-` (0x2D) перетворюється на `_X2D_`, тому `ops-prod` відповідає префіксу змінних середовища `MATRIX_OPS_X2D_PROD_`.

### Кешовані облікові дані

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

### Змінні середовища

Змінні середовища, що відповідають ключам конфігурації, використовуються, коли відповідний ключ конфігурації не задано. Для облікового запису за замовчуванням використовуються назви без префікса; для іменованих облікових записів токен облікового запису вставляється перед суфіксом (див. [нормалізацію](#account-id-normalization)).

| Обліковий запис за замовчуванням | Іменований обліковий запис (`<ID>` = токен облікового запису) |
| -------------------------------- | ------------------------------------------------------------ |
| `MATRIX_HOMESERVER`              | `MATRIX_<ID>_HOMESERVER`                                     |
| `MATRIX_ACCESS_TOKEN`            | `MATRIX_<ID>_ACCESS_TOKEN`                                   |
| `MATRIX_USER_ID`                 | `MATRIX_<ID>_USER_ID`                                        |
| `MATRIX_PASSWORD`                | `MATRIX_<ID>_PASSWORD`                                       |
| `MATRIX_DEVICE_ID`               | `MATRIX_<ID>_DEVICE_ID`                                      |
| `MATRIX_DEVICE_NAME`             | `MATRIX_<ID>_DEVICE_NAME`                                    |

Для облікового запису `ops` назви матимуть вигляд `MATRIX_OPS_HOMESERVER`, `MATRIX_OPS_ACCESS_TOKEN` тощо. `MATRIX_HOMESERVER` (і будь-який варіант `*_HOMESERVER` з областю дії) не можна задати з файлу `.env` робочого простору; див. [Файли `.env` робочого простору](/uk/gateway/security).

<Note>
Ключ відновлення не є змінною середовища, пов’язаною з конфігурацією: OpenClaw ніколи не зчитує його безпосередньо із середовища. У підказці CLI пропонується передавати його через канал із використанням змінної оболонки `MATRIX_RECOVERY_KEY` для облікового запису за замовчуванням або `MATRIX_RECOVERY_KEY_<ID>` для іменованого облікового запису (звичайний ідентифікатор облікового запису у верхньому регістрі без шістнадцяткового екранування) — див. [Підтвердження цього пристрою за допомогою ключа відновлення](#verify-this-device-with-a-recovery-key).
</Note>

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

Практична базова конфігурація зі спарюванням особистих повідомлень, списком дозволених кімнат і 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",
    },
  },
}
```

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

Потокове передавання відповідей у Matrix вмикається явно. `streaming` визначає, як OpenClaw доставляє відповідь асистента під час її формування; `blockStreaming` визначає, чи зберігатиметься кожен завершений блок як окреме повідомлення Matrix.

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

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

```json5
{
  channels: {
    matrix: {
      streaming: {
        mode: "partial",
        preview: {
          toolProgress: false,
        },
      },
    },
  },
}
```

Повна об’єктна форма приймає `{ mode, preview, progress }`:

```json5
{
  channels: {
    matrix: {
      streaming: {
        mode: "progress",
        progress: {
          label: "auto", // pick from configured or built-in labels (false to hide)
          labels: ["Thinking", "Writing", "Searching"], // candidates for label: "auto"
          maxLines: 8, // max rolling progress lines (default: 8)
          maxLineChars: 120, // max chars per line before truncation (default: 120)
          toolProgress: true, // show tool/progress activity (default: true)
        },
      },
    },
  },
}
```

- `progress.label`: власна мітка, `"auto"` або незадане значення для вибору налаштованої чи вбудованої мітки або `false`, щоб приховати її.
- `progress.labels`: варіанти, що використовуються лише тоді, коли `label` має значення `"auto"` або не задано.
- `progress.maxLines`: максимальна кількість оновлюваних рядків перебігу виконання, що зберігаються в чернетці; старіші рядки понад цей ліміт видаляються.
- `progress.maxLineChars`: максимальна кількість символів у кожному компактному рядку перебігу виконання перед обрізанням.
- `progress.toolProgress`: якщо `true` (за замовчуванням), активність інструментів і перебіг виконання в реальному часі відображаються в чернетці.

| `streaming`       | Поведінка                                                                                                                                                                                                 |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"off"` (типово)  | Очікувати на повну відповідь і надіслати її один раз. `true` <-> `"partial"`, `false` <-> `"off"`.                                                                                                         |
| `"partial"`       | Редагувати одне звичайне текстове повідомлення на місці, доки модель формує поточний блок. Стандартні клієнти можуть сповістити про перший попередній перегляд, а не про остаточне редагування.                |
| `"quiet"`         | Те саме, що й `"partial"`, але повідомлення є сповіщенням без надсилання повідомлення користувачеві. Одержувачів сповіщають один раз, коли правило push-сповіщень користувача збігається із завершеним редагуванням (див. нижче). |
| `"progress"`      | Надсилати окремі компактні рядки перебігу виконання за допомогою чернетки перебігу виконання.                                                                                                              |

`blockStreaming` (типово `false`) не залежить від `streaming`:

| `streaming`             | `blockStreaming: true`                                                            | `blockStreaming: false` (типово)                               |
| ----------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `"partial"` / `"quiet"` | Поточна чернетка для поточного блока, завершені блоки зберігаються як повідомлення | Поточна чернетка для поточного блока, завершення виконується на місці |
| `"off"`                 | Одне повідомлення Matrix зі сповіщенням на кожен завершений блок                   | Одне повідомлення Matrix зі сповіщенням для всієї відповіді    |

Примітки:

- Якщо попередній перегляд перевищує обмеження Matrix на розмір однієї події, OpenClaw припиняє його потокове передавання та переходить до надсилання лише остаточної відповіді.
- Відповіді з медіафайлами завжди надсилають вкладення звичайним способом; якщо застарілий попередній перегляд не можна безпечно використати повторно, OpenClaw приховує його перед надсиланням остаточної відповіді з медіафайлом.
- Оновлення попереднього перегляду перебігу роботи інструментів за замовчуванням увімкнено, коли активне потокове передавання попереднього перегляду. Установіть `streaming.preview.toolProgress: false`, щоб зберегти редагування попереднього перегляду тексту відповіді, але залишити перебіг роботи інструментів у звичайному шляху доставки.
- Редагування попереднього перегляду потребують додаткових викликів API Matrix. Залиште `streaming: "off"` для найбільш консервативного профілю обмеження частоти запитів.

## Голосові повідомлення

Вхідні голосові нотатки Matrix транскрибуються до перевірки згадки в кімнаті, тому голосова нотатка, у якій вимовлено ім’я бота, може активувати агента в кімнаті з `requireMention: true`, а агент отримає транскрипт замість лише заповнювача аудіовкладення.

Matrix використовує спільний постачальник обробки аудіомедіа в `tools.media.audio`, наприклад OpenAI `gpt-4o-mini-transcribe`. Налаштування постачальника й обмеження див. в [Огляді медіаінструментів](/uk/tools/media-overview).

- Події `m.audio` та події `m.file` із типом MIME `audio/*` придатні для транскрибування.
- У зашифрованих кімнатах OpenClaw розшифровує вкладення через наявний шлях обробки медіафайлів Matrix перед транскрибуванням.
- Транскрипт позначається в запиті агента як створений машиною та ненадійний.
- Вкладення позначається як уже транскрибоване, щоб подальші медіаінструменти не транскрибували його повторно.
- Установіть `tools.media.audio.enabled: false`, щоб глобально вимкнути транскрибування аудіо.

## Метадані схвалення

Вбудовані запити на схвалення Matrix є звичайними подіями `m.room.message` зі специфічним для OpenClaw вмістом у ключі `com.openclaw.approval`. Стандартні клієнти й надалі відображають текстове тіло; клієнти з підтримкою OpenClaw можуть зчитувати структуровані ідентифікатор, тип і стан схвалення, рішення, а також відомості про виконання або плагін.

Якщо запит задовгий для однієї події Matrix, OpenClaw розбиває видимий текст на частини й додає `com.openclaw.approval` лише до першої частини. Реакції дозволу або відмови прив’язуються до цієї першої події, тому довгі запити мають ту саму ціль схвалення, що й запити з однією подією.

### Правила самостійно розміщених push-сповіщень для тихих завершених попередніх переглядів

`streaming: "quiet"` сповіщає одержувачів лише після завершення блоку або ходу — правило push-сповіщень для кожного користувача має відповідати маркеру завершеного попереднього перегляду. Повну інструкцію див. у розділі [Правила push-сповіщень Matrix для тихих попередніх переглядів](/uk/channels/matrix-push-rules).

## Кімнати для взаємодії ботів

За замовчуванням повідомлення Matrix від інших налаштованих облікових записів OpenClaw Matrix ігноруються. Використовуйте `allowBots`, щоб навмисно дозволити обмін даними між агентами:

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

- `allowBots: true` приймає повідомлення від інших налаштованих облікових записів ботів Matrix у дозволених кімнатах і приватних повідомленнях.
- `allowBots: "mentions"` приймає такі повідомлення в кімнатах лише тоді, коли в них явно згадано цього бота; приватні повідомлення дозволено незалежно від цього.
- `groups.<room>.allowBots` перевизначає налаштування рівня облікового запису для однієї кімнати.
- Прийняті повідомлення налаштованих ботів використовують спільний [захист від циклів ботів](/uk/channels/bot-loop-protection). Налаштуйте `channels.defaults.botLoopProtection`, а потім перевизначте його для окремого облікового запису через `channels.matrix.botLoopProtection` або для окремої кімнати через `channels.matrix.groups.<room>.botLoopProtection`.
- OpenClaw усе одно ігнорує повідомлення від того самого ідентифікатора користувача Matrix, щоб уникнути циклів відповідей самому собі.
- Matrix не має вбудованої ознаки бота; OpenClaw вважає повідомлення «створеним ботом», якщо його «надіслав інший налаштований обліковий запис Matrix на цьому Gateway OpenClaw».

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

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

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

Усі команди `openclaw matrix` приймають `--verbose` (повна діагностика), `--json` (машиночитаний вивід) і `--account <id>` (для конфігурацій із кількома обліковими записами). За замовчуванням вивід стислий.

### Увімкнення шифрування

```bash
openclaw matrix encryption setup
```

Ініціалізує сховище секретів і перехресне підписання, за потреби створює резервну копію ключів кімнат, а потім виводить стан і подальші кроки. Корисні прапорці:

- `--recovery-key <key>` — застосувати ключ відновлення перед ініціалізацією (краще скористатися наведеною нижче формою зі стандартним вводом)
- `--force-reset-cross-signing` — відкинути поточну ідентичність перехресного підписання та створити нову (лише для навмисного використання)

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

```bash
openclaw matrix account add \
  --homeserver https://matrix.example.org \
  --access-token syt_xxx \
  --enable-e2ee
```

`--encryption` — псевдонім для `--enable-e2ee`. Еквівалент ручної конфігурації:

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

### Стан і сигнали довіри

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

`verify status` повідомляє про три незалежні сигнали довіри (`--verbose` показує їх усі):

- `Locally trusted`: довірений лише цим клієнтом
- `Cross-signing verified`: SDK повідомляє про перевірку через перехресне підписання
- `Signed by owner`: підписаний вашим власним ключем самопідписання (лише для діагностики)

`Verified by owner` має значення `yes`, лише якщо `Cross-signing verified` має значення `yes`; лише локальної довіри або підпису власника недостатньо.

`--allow-degraded-local-state` повертає діагностику за принципом максимально можливої повноти без попередньої підготовки облікового запису Matrix; це корисно для автономних або частково налаштованих перевірок.

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

Передавайте ключ відновлення через стандартний ввід, а не в командному рядку:

```bash
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
```

Команда повідомляє про три стани:

- `Recovery key accepted`: Matrix прийняв ключ для сховища секретів або довіри до пристрою.
- `Backup usable`: резервну копію ключів кімнат можна завантажити за допомогою довіреного матеріалу відновлення.
- `Device verified by owner`: цей пристрій має повну довіру ідентичності перехресного підписання Matrix.

Команда завершується з ненульовим кодом, якщо повна довіра до ідентичності не встановлена, навіть коли ключ відновлення розблокував матеріал резервної копії. У такому разі завершіть самоперевірку з іншого клієнта Matrix:

```bash
openclaw matrix verify self
```

`verify self` очікує на `Cross-signing verified: yes`, перш ніж успішно завершитися. Використовуйте `--timeout-ms <ms>`, щоб налаштувати тривалість очікування.

Форма з буквальним ключем `openclaw matrix verify device "<recovery-key>"` також працює, але ключ потрапляє в історію оболонки.

### Ініціалізація або відновлення перехресного підписання

```bash
openclaw matrix verify bootstrap
```

Команда відновлення або налаштування для зашифрованих облікових записів. Вона послідовно:

- ініціалізує сховище секретів, за можливості повторно використовуючи наявний ключ відновлення
- ініціалізує перехресне підписання та завантажує відсутні відкриті ключі
- позначає та перехресно підписує поточний пристрій
- створює серверну резервну копію ключів кімнат, якщо вона ще не існує

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

Корисні прапорці:

- `--recovery-key-stdin` (використовуйте разом із `printf '%s\n' "$MATRIX_RECOVERY_KEY" | ...`) або `--recovery-key <key>`
- `--force-reset-cross-signing` — відкинути поточну ідентичність перехресного підписання (лише навмисно; активний ключ відновлення має бути збережений або наданий через `--recovery-key-stdin`)

### Резервна копія ключів кімнат

```bash
openclaw matrix verify backup status
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
```

`backup status` показує, чи існує серверна резервна копія та чи може цей пристрій її розшифрувати. `backup restore` імпортує резервні копії ключів кімнат у локальне криптографічне сховище; не вказуйте `--recovery-key-stdin`, якщо ключ відновлення вже збережено на диску.

Щоб замінити пошкоджену резервну копію новою базовою версією (погоджуючись із втратою старої історії, яку неможливо відновити; команда також може повторно створити сховище секретів, якщо поточний секрет резервної копії неможливо завантажити):

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

Додавайте `--rotate-recovery-key` лише тоді, коли попередній ключ відновлення має навмисно припинити розблоковувати нову базову резервну копію.

### Перегляд, надсилання та обробка запитів на перевірку

```bash
openclaw matrix verify list
```

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

```bash
openclaw matrix verify request --own-user
openclaw matrix verify request --user-id @ops:example.org --device-id ABCDEF
```

Надсилає запит на перевірку з цього облікового запису. `--own-user` запитує самоперевірку (прийміть запит в іншому клієнті Matrix того самого користувача); `--user-id`/`--device-id`/`--room-id` спрямовують запит іншій особі. `--own-user` не можна поєднувати з іншими прапорцями вибору цілі.

Для низькорівневого керування життєвим циклом — зазвичай під час відстеження вхідних запитів з іншого клієнта — ці команди виконують дії з конкретним запитом `<id>` (який виводять `verify list` і `verify request`):

| Команда                                    | Призначення                                                             |
| ------------------------------------------ | ----------------------------------------------------------------------- |
| `openclaw matrix verify accept <id>`       | Прийняти вхідний запит                                                  |
| `openclaw matrix verify start <id>`        | Запустити процес SAS                                                    |
| `openclaw matrix verify sas <id>`          | Вивести емодзі або десяткові числа SAS                                  |
| `openclaw matrix verify confirm-sas <id>`  | Підтвердити, що SAS збігається з показаним в іншому клієнті             |
| `openclaw matrix verify mismatch-sas <id>` | Відхилити SAS, якщо емодзі або десяткові числа не збігаються             |
| `openclaw matrix verify cancel <id>`       | Скасувати; приймає необов’язкові `--reason <text>` і `--code <matrix-code>` |

`accept`, `start`, `sas`, `confirm-sas`, `mismatch-sas` і `cancel` також приймають `--user-id` та `--room-id` як підказки для подальшої взаємодії в приватних повідомленнях, коли перевірку прив’язано до певної кімнати прямих повідомлень.

### Примітки щодо кількох облікових записів

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

<AccordionGroup>
  <Accordion title="Поведінка під час запуску">
    За `encryption: true` значенням `startupVerification` за замовчуванням є `"if-unverified"`. Під час запуску неперевірений пристрій запитує самоперевірку в іншому клієнті Matrix, пропускаючи дублікати та застосовуючи період очікування (за замовчуванням 24 години). Налаштуйте його за допомогою `startupVerificationCooldownHours` або вимкніть через `startupVerification: "off"`.

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

    Повний процес оновлення див. у розділі [Міграція Matrix](/uk/channels/matrix-migration).

  </Accordion>

  <Accordion title="Сповіщення про перевірку">
    Matrix публікує сповіщення про життєвий цикл перевірки в суворо визначеній кімнаті приватних повідомлень для перевірки як повідомлення `m.notice`: запит, готовність (із вказівкою "Verify by emoji"), запуск/завершення та відомості SAS (емодзі/десяткові числа), якщо вони доступні.

    Вхідні запити з іншого клієнта Matrix відстежуються та приймаються автоматично. Для самоперевірки OpenClaw автоматично запускає процес SAS і підтверджує свою сторону, щойно стає доступною перевірка за допомогою емодзі — вам усе одно потрібно порівняти дані та підтвердити "They match" у своєму клієнті Matrix.

    Системні сповіщення про перевірку не передаються в конвеєр чату агента.

  </Accordion>

  <Accordion title="Видалений або недійсний пристрій Matrix">
    Якщо `verify status` повідомляє, що поточний пристрій більше не зареєстровано на домашньому сервері, створіть новий пристрій OpenClaw Matrix. Для входу за паролем:

```bash
openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --user-id '@assistant:example.org' \
  --password '<password>' \
  --device-name OpenClaw-Gateway
```

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

```bash
openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --access-token '<token>'
```

    Замініть `assistant` на ідентифікатор облікового запису з команди, що завершилася помилкою, або не вказуйте `--account` для облікового запису за замовчуванням.

  </Accordion>

  <Accordion title="Гігієна пристроїв">
    Старі пристрої, якими керує OpenClaw, можуть накопичуватися. Перегляньте список і видаліть застарілі:

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

  </Accordion>

  <Accordion title="Криптографічне сховище">
    E2EE Matrix використовує офіційний криптографічний шлях Rust у `matrix-js-sdk` із `fake-indexeddb` як адаптером IndexedDB. Криптографічний стан зберігається у `crypto-idb-snapshot.json` (з обмежувальними правами доступу до файлу).

    Зашифрований стан середовища виконання зберігається в `~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/` і містить сховище синхронізації, криптографічне сховище, ключ відновлення, знімок IDB, прив’язки гілок обговорення та стан перевірки під час запуску. Коли токен змінюється, але ідентичність облікового запису залишається тією самою, OpenClaw повторно використовує найкращий наявний кореневий каталог, щоб попередній стан залишався доступним.

    Один старіший корінь із хешем токена може бути нормальним шляхом забезпечення безперервності під час ротації токена. Якщо OpenClaw реєструє `matrix: multiple populated token-hash storage roots detected`, перевірте каталог облікового запису й архівуйте застарілі сусідні корені лише після підтвердження справності вибраного активного кореня. Замість негайного видалення застарілих коренів краще перемістити їх до каталогу `_archive/`.

  </Accordion>
</AccordionGroup>

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

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

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

## Гілки

Matrix підтримує нативні гілки як для автоматичних відповідей, так і для надсилання через інструмент повідомлень. Поведінку визначають два незалежні параметри:

### Маршрутизація сеансів (`sessionScope`)

`dm.sessionScope` визначає, як кімнати приватних повідомлень Matrix зіставляються із сеансами OpenClaw:

- `"per-user"` (типово): усі кімнати приватних повідомлень з тим самим маршрутизованим співрозмовником використовують один спільний сеанс.
- `"per-room"`: кожна кімната приватних повідомлень Matrix отримує власний ключ сеансу, навіть для того самого співрозмовника.

Явні прив’язки розмов завжди мають пріоритет над `sessionScope`; прив’язані кімнати й гілки зберігають вибраний цільовий сеанс.

### Відповіді у гілках (`threadReplies`)

`threadReplies` визначає, де бот публікує відповідь:

- `"off"`: відповіді публікуються на верхньому рівні. Вхідні повідомлення з гілок залишаються в батьківському сеансі.
- `"inbound"`: відповідати всередині гілки, лише якщо вхідне повідомлення вже було в цій гілці.
- `"always"`: відповідати всередині гілки, коренем якої є повідомлення-тригер; від першого тригера ця розмова маршрутизується через відповідний сеанс із областю дії гілки.

`dm.threadReplies` перевизначає це лише для приватних повідомлень — наприклад, дає змогу ізолювати гілки кімнат, залишаючи приватні повідомлення без гілок.

### Успадкування гілок і команди зі скісною рискою

- Вхідні повідомлення з гілок містять кореневе повідомлення гілки як додатковий контекст агента.
- Надсилання через інструмент повідомлень автоматично успадковують поточну гілку Matrix, коли цільовою є та сама кімната (або той самий користувач у приватних повідомленнях), якщо явно не вказано `threadId`.
- Повторне використання цільового користувача приватних повідомлень активується лише тоді, коли метадані поточного сеансу підтверджують того самого співрозмовника приватних повідомлень у тому самому обліковому записі Matrix; інакше OpenClaw повертається до звичайної маршрутизації з областю дії користувача.
- `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язана до гілки команда `/acp spawn` працюють у кімнатах і приватних повідомленнях Matrix.
- Команда `/focus` верхнього рівня створює нову гілку Matrix і прив’язує її до цільового сеансу, якщо ввімкнено `threadBindings.spawnSessions`.
- Виконання `/focus` або `/acp spawn --thread here` у наявній гілці Matrix прив’язує цю гілку на місці.

Коли OpenClaw виявляє конфлікт кімнати приватних повідомлень Matrix з іншою кімнатою приватних повідомлень у тому самому спільному сеансі, він одноразово публікує `m.notice` із вказівкою на обхідний шлях `/focus` і пропозицією змінити `dm.sessionScope`. Це сповіщення з’являється лише тоді, коли прив’язки гілок увімкнено.

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

Кімнати, приватні повідомлення й наявні гілки Matrix можуть стати постійними робочими просторами ACP без зміни інтерфейсу чату.

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

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

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

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

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

- `threadBindings.enabled`
- `threadBindings.idleHours`
- `threadBindings.maxAgeHours`
- `threadBindings.spawnSessions`: контролює створення гілок як для субагентів, так і для ACP.
- `threadBindings.spawnSubagentSessions` / `threadBindings.spawnAcpSessions`: вужчі перевизначення для створення лише субагентів або лише ACP.
- `threadBindings.defaultSpawnContext`

Створення прив’язаних до гілок Matrix сеансів типово ввімкнено. Установіть `threadBindings.spawnSessions: false`, щоб заборонити командам верхнього рівня `/focus` і `/acp spawn --thread auto|here` створювати або прив’язувати гілки Matrix. Установіть `threadBindings.defaultSpawnContext: "isolated"`, якщо нативне створення гілок субагентів не повинно розгалужувати батьківський журнал розмови.

## Реакції

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

Інструменти вихідних реакцій контролюються параметром `channels.matrix.actions.reactions`:

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

**Порядок визначення** (перемагає перше визначене значення):

| Параметр                | Порядок                                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| `ackReaction`           | для облікового запису -> канал -> `messages.ackReaction` -> резервний емодзі ідентичності агента |
| `ackReactionScope`      | для облікового запису -> канал -> `messages.ackReactionScope` -> типове `"group-mentions"`        |
| `reactionNotifications` | для облікового запису -> канал -> типове `"own"`                                                 |

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

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

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

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

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

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

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

## Політика приватних повідомлень і кімнат

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

Щоб повністю вимкнути приватні повідомлення, залишивши кімнати працездатними, установіть `dm.enabled: false`:

```json5
{
  channels: {
    matrix: {
      dm: { enabled: false },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
    },
  },
}
```

Опис блокування за згадкою та поведінки списків дозволених користувачів див. у розділі [Групи](/uk/channels/groups).

Приклад сполучення для приватних повідомлень Matrix:

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

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

Опис спільного процесу сполучення приватних повідомлень і структури сховища див. у розділі [Сполучення](/uk/channels/pairing).

## Відновлення кімнати приватних повідомлень

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

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

Відновіть його:

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

Обидві команди приймають `--account <id>` для конфігурацій із кількома обліковими записами. Процес відновлення:

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

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

## Схвалення виконання

Matrix може працювати як нативний клієнт схвалень. Налаштуйте це в `channels.matrix.execApprovals` (або в `channels.matrix.accounts.<account>.execApprovals` для перевизначення на рівні облікового запису):

- `enabled`: доставляє запити на схвалення через нативні запити Matrix. Якщо не встановлено або задано `"auto"`, функція автоматично вмикається, щойно вдається визначити принаймні одного уповноваженого схвалювача; установіть `false`, щоб явно вимкнути.
- `approvers`: ідентифікатори користувачів Matrix (`@owner:example.org`), яким дозволено схвалювати запити на виконання. Якщо не задано, використовується `channels.matrix.dm.allowFrom`.
- `target`: куди надсилаються запити. `"dm"` (типово) надсилає їх у приватні повідомлення схвалювачам; `"channel"` — до початкової кімнати або приватного повідомлення; `"both"` — в обидва місця.
- `agentFilter` / `sessionFilter`: необов’язкові списки дозволених агентів або сеансів, які запускають доставлення через Matrix.

Авторизація дещо відрізняється залежно від типу схвалення:

- **Схвалення виконання** використовують `execApprovals.approvers`, а якщо його не задано — `dm.allowFrom`.
- **Схвалення Plugin** авторизуються лише через `dm.allowFrom`.

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

- ✅ дозволити один раз
- ❌ відхилити
- ♾️ дозволяти завжди (коли це дозволяє чинна політика виконання)

Резервні команди зі скісною рискою: `/approve <id> allow-once`, `/approve <id> allow-always`, `/approve <id> deny`.

Схвалювати або відхиляти можуть лише визначені схвалювачі. Доставлення схвалень виконання до каналу містить текст команди — вмикайте `channel` або `both` лише в довірених кімнатах.

Пов’язаний розділ: [Схвалення виконання](/uk/tools/exec-approvals).

## Команди зі скісною рискою

Команди зі скісною рискою (`/new`, `/reset`, `/model`, `/focus`, `/unfocus`, `/agents`, `/session`, `/acp`, `/approve` тощо) працюють безпосередньо в приватних повідомленнях. У кімнатах OpenClaw також розпізнає команди з префіксом у вигляді власної згадки бота Matrix, тому `@bot:server /new` запускає шлях команди без спеціального регулярного виразу для згадок — завдяки цьому бот реагує на типові для кімнат повідомлення `@mention /command`, які Element і подібні клієнти створюють, коли користувач доповнює ім’я бота клавішею Tab перед введенням команди.

Правила авторизації залишаються чинними: відправники команд мають відповідати тим самим політикам списків дозволених користувачів або власників для приватних повідомлень чи кімнат, що й звичайні повідомлення.

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

```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` слугують типовими значеннями для іменованих облікових записів, якщо обліковий запис їх не перевизначає.
- Обмежте успадкований запис кімнати певним обліковим записом за допомогою `groups.<room>.account`. Записи без `account` є спільними для всіх облікових записів; `account: "default"` також працює, коли типовий обліковий запис налаштовано на верхньому рівні.

**Вибір типового облікового запису:**

- Установіть `defaultAccount`, щоб вибрати іменований обліковий запис, якому надаватимуть перевагу неявна маршрутизація, перевірки та команди CLI.
- Якщо у вас кілька облікових записів і один із них буквально має назву `default`, OpenClaw неявно використовує його, навіть коли `defaultAccount` не задано.
- За наявності кількох іменованих облікових записів без вибраного типового команди CLI відмовляються робити припущення — установіть `defaultAccount` або передайте `--account <id>`.
- Блок верхнього рівня `channels.matrix.*` вважається неявним обліковим записом `default`, лише якщо його автентифікаційні дані повні (`homeserver` + `accessToken` або `homeserver` + `userId` + `password`). Іменовані облікові записи залишаються доступними для виявлення за `homeserver` + `userId`, щойно кешовані облікові дані забезпечують автентифікацію.

**Перетворення:**

- Коли OpenClaw під час виправлення або налаштування перетворює конфігурацію з одним обліковим записом на конфігурацію з кількома обліковими записами, він зберігає наявний іменований обліковий запис, якщо такий існує або `defaultAccount` уже вказує на нього. До перетвореного облікового запису переміщуються лише ключі автентифікації та початкового налаштування Matrix; спільні ключі політики доставки залишаються на верхньому рівні.

Спільний шаблон для кількох облікових записів див. у [довіднику з конфігурації](/uk/gateway/config-channels#multi-account-all-channels).

## Приватні/LAN-сервери Matrix

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

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

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

Цей явний дозвіл стосується лише довірених приватних/внутрішніх цілей. Загальнодоступні сервери без шифрування, як-от `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 використовує те саме налаштування проксі для трафіку 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 чутливі до регістру. Під час налаштування явних цілей доставки, завдань cron, прив’язок або списків дозволів використовуйте точний регістр ідентифікатора кімнати з Matrix. OpenClaw зберігає внутрішні ключі сеансів у канонічній формі, тому ці ключі в нижньому регістрі не є надійним джерелом ідентифікаторів доставки Matrix.

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

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

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

Поля користувачів, що працюють як списки дозволів (`groupAllowFrom`, `dm.allowFrom`, `groups.<room>.users`), приймають повні ідентифікатори користувачів Matrix (найбезпечніший варіант). Записи, що не є ідентифікаторами, типово ігноруються. Якщо встановлено `dangerouslyAllowNameMatching: true`, точні збіги з відображуваними іменами в каталозі Matrix визначаються під час запуску й щоразу, коли список дозволів змінюється під час роботи монітора; записи, які неможливо визначити, ігноруються під час виконання.

Ключами списку дозволів кімнат (`groups`, застарілий `rooms`) мають бути ідентифікатори або псевдоніми кімнат. Ключі зі звичайними назвами кімнат типово ігноруються; `dangerouslyAllowNameMatching: true` відновлює пошук за назвами приєднаних кімнат за можливості.

### Обліковий запис і підключення

- `enabled`: увімкнути або вимкнути канал.
- `name`: необов’язкова відображувана мітка облікового запису.
- `defaultAccount`: пріоритетний ідентифікатор облікового запису, коли налаштовано кілька облікових записів Matrix.
- `accounts`: іменовані перевизначення для кожного облікового запису. Значення верхнього рівня `channels.matrix` успадковуються як типові.
- `homeserver`: URL-адреса домашнього сервера, наприклад `https://matrix.example.org`.
- `network.dangerouslyAllowPrivateNetwork`: дозволити цьому обліковому запису підключатися до `localhost`, IP-адрес LAN/Tailscale або внутрішніх імен хостів.
- `proxy`: необов’язкова URL-адреса проксі HTTP(S) для трафіку Matrix. Підтримується перевизначення для кожного облікового запису.
- `userId`: повний ідентифікатор користувача Matrix (`@bot:example.org`).
- `accessToken`: токен доступу для автентифікації на основі токена. Підтримуються значення у відкритому тексті та SecretRef від постачальників env/file/exec ([Керування секретами](/uk/gateway/secrets)).
- `password`: пароль для входу за паролем. Підтримуються значення у відкритому тексті та SecretRef.
- `deviceId`: явний ідентифікатор пристрою Matrix.
- `deviceName`: відображуване ім’я пристрою, що використовується під час входу за паролем.
- `avatarUrl`: збережена URL-адреса власного аватара для синхронізації профілю й оновлень `profile set`.
- `initialSyncLimit`: максимальна кількість подій, отриманих під час початкової синхронізації.

### Шифрування

- `encryption`: увімкнути наскрізне шифрування. Типово: `false`.
- `startupVerification`: `"if-unverified"` (типово, коли наскрізне шифрування ввімкнено) або `"off"`. Автоматично запитує самоперевірку під час запуску, якщо цей пристрій не перевірено.
- `startupVerificationCooldownHours`: період очікування до наступного автоматичного запиту під час запуску. Типово: `24`.

### Доступ і політика

- `groupPolicy`: `"open"`, `"allowlist"` або `"disabled"`. Типово: `"allowlist"`.
- `groupAllowFrom`: список дозволених ідентифікаторів користувачів для трафіку кімнат.
- `mentionPatterns`: обмежені за областю регулярні вирази для згадок у кімнатах. Об’єкт із `{ mode: "allow"|"deny", allowIn: [roomId, ...], denyIn: [roomId, ...] }`. Визначає, чи застосовуються налаштовані `agents.list[].groupChat.mentionPatterns` для кожної кімнати.
- `dm.enabled`: якщо `false`, ігнорувати всі особисті повідомлення. Типово: `true`.
- `dm.policy`: `"pairing"` (типово), `"allowlist"`, `"open"` або `"disabled"`. Застосовується після того, як бот приєднався та класифікував кімнату як особистий чат; не впливає на обробку запрошень.
- `dm.allowFrom`: список дозволених ідентифікаторів користувачів для трафіку особистих повідомлень.
- `dm.sessionScope`: `"per-user"` (типово) або `"per-room"`.
- `dm.threadReplies`: перевизначення лише для особистих повідомлень щодо відповідей у гілках (`"off"`, `"inbound"`, `"always"`).
- `allowBots`: приймати повідомлення від інших налаштованих облікових записів ботів Matrix (`true` або `"mentions"`).
- `allowlistOnly`: якщо `true`, примусово переводить усі активні політики особистих повідомлень (крім `"disabled"`) і групові політики `"open"` у `"allowlist"`. Не змінює політики `"disabled"`.
- `dangerouslyAllowNameMatching`: якщо `true`, дозволяє пошук у каталозі Matrix за відображуваним іменем для записів списку дозволів користувачів і пошук за назвою приєднаної кімнати для ключів списку дозволів кімнат. Надавайте перевагу повним ідентифікаторам `@user:server`, а також ідентифікаторам або псевдонімам кімнат.
- `autoJoin`: `"always"`, `"allowlist"` або `"off"`. Типово: `"off"`. Застосовується до кожного запрошення Matrix, зокрема до запрошень у особисті чати.
- `autoJoinAllowlist`: кімнати або псевдоніми, дозволені, коли `autoJoin` має значення `"allowlist"`. Записи псевдонімів визначаються через домашній сервер, а не через стан, заявлений запрошувальною кімнатою.
- `contextVisibility`: видимість додаткового контексту (`"all"` типово, `"allowlist"`, `"allowlist_quote"`).

### Поведінка відповідей

- `replyToMode`: `"off"` (типово), `"first"`, `"all"` або `"batched"`.
- `threadReplies`: `"off"` (типове значення верхнього рівня перетворюється на `"inbound"`, якщо його не встановлено явно), `"inbound"` або `"always"`.
- `threadBindings`: перевизначення для кожного каналу щодо маршрутизації та життєвого циклу сеансів, прив’язаних до гілок.
- `streaming`: `"off"` (типово), `"partial"`, `"quiet"`, `"progress"` або об’єктна форма `{ mode, preview: { toolProgress }, progress: { label, labels, maxLines, maxLineChars, toolProgress } }`. `true` <-> `"partial"`, `false` <-> `"off"`.
- `blockStreaming`: якщо `true`, завершені блоки асистента зберігаються як окремі повідомлення про перебіг. Типово: `false`.
- `markdown`: необов’язкова конфігурація відтворення Markdown для вихідного тексту.
- `responsePrefix`: необов’язковий рядок, що додається на початку вихідних відповідей.
- `textChunkLimit`: розмір вихідної частини в символах, коли `chunkMode: "length"`. Типово: `4000`.
- `chunkMode`: `"length"` (типово, розділяє за кількістю символів) або `"newline"` (розділяє на межах рядків).
- `historyLimit`: кількість останніх повідомлень кімнати, включених як `InboundHistory`, коли повідомлення в кімнаті запускає агента. Резервно використовує `messages.groupChat.historyLimit`; фактичне типове значення — `0` (вимкнено).
- `mediaMaxMb`: обмеження розміру медіафайлів у МБ для вихідного надсилання та обробки вхідних даних. Типово: `20`.

### Налаштування реакцій

- `ackReaction`: перевизначення реакції підтвердження для цього каналу або облікового запису.
- `ackReactionScope`: перевизначення області дії (`"group-mentions"` типово, `"group-all"`, `"direct"`, `"all"`, `"none"`, `"off"`).
- `reactionNotifications`: режим сповіщень про вхідні реакції (`"own"` типово, `"off"`).

### Інструменти та перевизначення для окремих кімнат

- `actions`: керування доступністю інструментів для кожної дії (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`).
- `groups`: карта політик для окремих кімнат. Після визначення ідентичність сеансу використовує стабільний ідентифікатор кімнати. (`rooms` — застарілий псевдонім.)
  - `groups.<room>.account`: обмежити один успадкований запис кімнати певним обліковим записом.
  - `groups.<room>.enabled`: перемикач для окремої кімнати. Якщо `false`, кімната ігнорується так, ніби її немає на карті.
  - `groups.<room>.requireMention`: перевизначення вимоги згадки на рівні каналу для окремої кімнати.
  - `groups.<room>.allowBots`: перевизначення налаштування рівня каналу для окремої кімнати (`true` або `"mentions"`).
  - `groups.<room>.botLoopProtection`: перевизначення бюджету захисту від циклів між ботами для окремої кімнати.
  - `groups.<room>.users`: список дозволених відправників для окремої кімнати.
  - `groups.<room>.tools`: перевизначення дозволу або заборони інструментів для окремої кімнати.
  - `groups.<room>.autoReply`: перевизначення обмеження за згадкою для окремої кімнати. `true` вимикає вимоги згадки для цієї кімнати; `false` примусово вмикає їх знову.
  - `groups.<room>.skills`: фільтр Skills для окремої кімнати.
  - `groups.<room>.systemPrompt`: фрагмент системної підказки для окремої кімнати.

### Налаштування схвалення виконання

- `execApprovals.enabled`: доставляти запити на схвалення виконання через вбудовані запити Matrix.
- `execApprovals.approvers`: ідентифікатори користувачів Matrix, яким дозволено схвалювати. Резервно використовує `dm.allowFrom`.
- `execApprovals.target`: `"dm"` (типово), `"channel"` або `"both"`.
- `execApprovals.agentFilter` / `execApprovals.sessionFilter`: необов’язкові списки дозволених агентів або сеансів для доставки.

## Пов’язані матеріали

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