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

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

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

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

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

Установлення з npm:

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

Установлення з локального checkout:

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

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

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

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

Шляхи інтерактивного налаштування:

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

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

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

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

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

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

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

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

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

Приклад списку дозволу:

```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 налаштованим для налаштування, 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_*`.

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

`MATRIX_HOMESERVER` не можна встановити з `.env` робочого простору; див. [Файли `.env` робочого простору](/uk/gateway/security).

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

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

## Попередній перегляд потокової передачі

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

У зашифрованих кімнатах (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" },
    },
  },
}
```

Команди верифікації (усі приймають `--verbose` для діагностики та `--json` для машиночитного виводу):

| Команда                                                        | Призначення                                                                         |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `openclaw matrix verify status`                                | Перевірити стан cross-signing і верифікації пристрою                                |
| `openclaw matrix verify status --include-recovery-key --json`  | Включити збережений recovery key                                                    |
| `openclaw matrix verify bootstrap`                             | Ініціалізувати cross-signing і верифікацію (див. нижче)                             |
| `openclaw matrix verify bootstrap --force-reset-cross-signing` | Відкинути поточну identity cross-signing і створити нову                            |
| `openclaw matrix verify device "<recovery-key>"`               | Верифікувати цей пристрій за допомогою recovery key                                 |
| `openclaw matrix verify backup status`                         | Перевірити стан резервного копіювання ключів кімнат                                 |
| `openclaw matrix verify backup restore`                        | Відновити ключі кімнат із резервної копії на сервері                                |
| `openclaw matrix verify backup reset --yes`                    | Видалити поточну резервну копію і створити нову базову точку (може повторно створити сховище секретів) |

У конфігураціях із кількома обліковими записами команди 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`.

<AccordionGroup>
  <Accordion title="Що означає verified">
    OpenClaw вважає пристрій verified лише тоді, коли його підписує ваша власна identity cross-signing. `verify status --verbose` показує три сигнали довіри:

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

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

  </Accordion>

  <Accordion title="Що робить bootstrap">
    `verify bootstrap` — це команда відновлення та налаштування для зашифрованих облікових записів. Послідовно вона:

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

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

  </Accordion>

  <Accordion title="Нова базова точка резервної копії">
    Якщо ви хочете зберегти роботу майбутніх зашифрованих повідомлень і погоджуєтеся втратити невідновлювану стару історію:

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

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

  </Accordion>

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

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

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

  </Accordion>

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

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

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

  </Accordion>

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

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

  </Accordion>

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

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

  </Accordion>
</AccordionGroup>

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

Оновіть власний профіль 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 як для автоматичних відповідей, так і для надсилань через інструмент повідомлень.

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

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

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

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

- Виконайте `/acp spawn codex --bind here` у особистому повідомленні Matrix, кімнаті або наявному потоці, які ви хочете й надалі використовувати.
- У особистому повідомленні або кімнаті Matrix верхнього рівня поточне особисте повідомлення/кімната залишається поверхнею чату, а майбутні повідомлення маршрутизуються до створеної сесії 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 підтримує вихідні дії реакцій, вхідні сповіщення про реакції та вхідні реакції-підтвердження.

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

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

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

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

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

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

- `channels["matrix"].accounts.<accountId>.reactionNotifications`
- `channels["matrix"].reactionNotifications`
- типово: `own`

Поведінка:

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

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

- `channels.matrix.historyLimit` визначає, скільки останніх повідомлень кімнати включається як `InboundHistory`, коли повідомлення кімнати Matrix активує агента. Використовується запасний варіант `messages.groupChat.historyLimit`; якщо обидва параметри не встановлено, фактичне значення за замовчуванням — `0`. Установіть `0`, щоб вимкнути.
- Історія кімнат Matrix обмежується лише кімнатою. Особисті повідомлення й далі використовують звичайну історію сесії.
- Історія кімнат 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,
        },
      },
    },
  },
}
```

Поведінку згадок і списку дозволу див. у [Groups](/uk/channels/groups).

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

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

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

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

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

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

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

Відновіть його за допомогою:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Slash-команди

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

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

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

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

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

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

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

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

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

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

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

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

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

## Визначення цілі

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

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

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

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

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

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

## Пов’язане

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