---
read_when:
- Налаштування Matrix в OpenClaw
- Налаштування E2EE та верифікації Matrix
summary: Стан підтримки Matrix, налаштування та приклади конфігурації
title: Матриця
x-i18n:
generated_at: "2026-07-01T13:20:30Z"
model: gpt-5.5
postprocess_version: locale-links-v1
provider: openai
source_hash: 2aa86a477c4f15e792ba01c45bb06f37a55fee26ee2c895bfa308ff57ef6d819
source_path: channels/matrix.md
workflow: 16
---
Matrix — це завантажуваний канальний плагін для OpenClaw.
Він використовує офіційний `matrix-js-sdk` і підтримує DM, кімнати, потоки, медіа, реакції, опитування, геолокацію та E2EE.
## Встановлення
Встановіть Matrix із ClawHub перед налаштуванням каналу:
```bash
openclaw plugins install @openclaw/matrix
```
Голі специфікації плагінів спершу пробують ClawHub, а потім fallback до npm. Щоб примусово вибрати джерело реєстру, використайте `openclaw plugins install clawhub:@openclaw/matrix` або `openclaw plugins install npm:@openclaw/matrix`.
З локального checkout:
```bash
openclaw plugins install ./path/to/local/matrix-plugin
```
`plugins install` реєструє й вмикає плагін, тому окремий крок `openclaw plugins enable matrix` не потрібен. Плагін усе одно нічого не робитиме, доки ви не налаштуєте канал нижче. Загальну поведінку плагінів і правила встановлення дивіться в [Плагіни](/uk/tools/plugin).
## Налаштування
1. Створіть обліковий запис Matrix на своєму homeserver.
2. Налаштуйте `channels.matrix` з `homeserver` + `accessToken` або з `homeserver` + `userId` + `password`.
3. Перезапустіть Gateway.
4. Почніть DM з ботом або запросіть його до кімнати (див. [автоприєднання](#auto-join) - нові запрошення спрацьовують лише тоді, коли їх дозволяє `autoJoin`).
### Інтерактивне налаштування
```bash
openclaw channels add
openclaw configure --section channels
```
Майстер запитує: URL homeserver, метод автентифікації (токен доступу або пароль), ID користувача (лише для автентифікації паролем), необов’язкову назву пристрою, чи вмикати E2EE, а також чи налаштовувати доступ до кімнат і автоприєднання.
Якщо відповідні env-змінні `MATRIX_*` уже існують, а вибраний обліковий запис не має збереженої автентифікації, майстер пропонує shortcut через env-var. Щоб розв’язати назви кімнат перед збереженням allowlist, запустіть `openclaw channels resolve --channel matrix "Project Room"`. Коли E2EE увімкнено, майстер записує конфігурацію та запускає той самий bootstrap, що й [`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`. Із типовим значенням бот не з’являтиметься в нових кімнатах або DM із нових запрошень, доки ви не приєднаєте його вручну.
OpenClaw не може визначити під час запрошення, чи запрошена кімната є DM або групою, тому всі запрошення - включно із запрошеннями в стилі DM - спершу проходять через `autoJoin`. `dm.policy` застосовується лише пізніше, після того як бот приєднався і кімнату класифіковано.
Задайте `autoJoin: "allowlist"` разом із `autoJoinAllowlist`, щоб обмежити, які запрошення приймає бот, або `autoJoin: "always"`, щоб приймати кожне запрошення.
`autoJoinAllowlist` приймає лише стабільні цілі: `!roomId:server`, `#alias:server` або `*`. Звичайні назви кімнат відхиляються; записи alias розв’язуються відносно homeserver, а не відносно стану, заявленого запрошеною кімнатою.
```json5
{
channels: {
matrix: {
autoJoin: "allowlist",
autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
groups: {
"!ops:example.org": { requireMention: true },
},
},
},
}
```
Щоб приймати кожне запрошення, використовуйте `autoJoin: "always"`.
### Формати цілей allowlist
Allowlist для DM і кімнат найкраще заповнювати стабільними ID:
- DM (`dm.allowFrom`, `groupAllowFrom`, `groups..users`): використовуйте `@user:server`. Відображувані імена за замовчуванням ігноруються, бо вони змінні; задавайте `dangerouslyAllowNameMatching: true` лише тоді, коли вам явно потрібна сумісність із записами відображуваних імен.
- Ключі allowlist кімнат (`groups`, legacy `rooms`): використовуйте `!room:server` або `#alias:server`. Звичайні назви кімнат за замовчуванням ігноруються; задавайте `dangerouslyAllowNameMatching: true` лише тоді, коли вам явно потрібна сумісність із пошуком за назвою приєднаної кімнати.
- Allowlist запрошень (`autoJoinAllowlist`): використовуйте `!room:server`, `#alias:server` або `*`. Звичайні назви кімнат відхиляються.
### Нормалізація ID облікового запису
Майстер перетворює дружню назву на нормалізований ID облікового запису. Наприклад, `Ops Bot` стає `ops-bot`. Розділові знаки екрануються в scoped env-var names, щоб два облікові записи не могли зіткнутися: `-` → `_X2D_`, тому `ops-prod` відображається на `MATRIX_OPS_X2D_PROD_*`.
### Кешовані облікові дані
Matrix зберігає кешовані облікові дані в `~/.openclaw/credentials/matrix/`:
- типовий обліковий запис: `credentials.json`
- іменовані облікові записи: `credentials-.json`
Коли кешовані облікові дані там існують, OpenClaw вважає Matrix налаштованим, навіть якщо токена доступу немає у файлі конфігурації - це охоплює setup, `openclaw doctor` і зонди стану каналу.
### Змінні середовища
Використовуються, коли еквівалентний ключ конфігурації не задано. Типовий обліковий запис використовує назви без префікса; іменовані облікові записи використовують ID облікового запису, вставлений перед суфіксом.
| Типовий обліковий запис | Іменований обліковий запис (`` — нормалізований ID облікового запису) |
| ----------------------- | ------------------------------------------------------------------------- |
| `MATRIX_HOMESERVER` | `MATRIX__HOMESERVER` |
| `MATRIX_ACCESS_TOKEN` | `MATRIX__ACCESS_TOKEN` |
| `MATRIX_USER_ID` | `MATRIX__USER_ID` |
| `MATRIX_PASSWORD` | `MATRIX__PASSWORD` |
| `MATRIX_DEVICE_ID` | `MATRIX__DEVICE_ID` |
| `MATRIX_DEVICE_NAME` | `MATRIX__DEVICE_NAME` |
| `MATRIX_RECOVERY_KEY` | `MATRIX__RECOVERY_KEY` |
Для облікового запису `ops` назви стають `MATRIX_OPS_HOMESERVER`, `MATRIX_OPS_ACCESS_TOKEN` тощо. Env-vars ключа відновлення читаються CLI-потоками, що підтримують відновлення (`verify backup restore`, `verify device`, `verify bootstrap`), коли ви передаєте ключ через `--recovery-key-stdin`.
`MATRIX_HOMESERVER` не можна задати з workspace `.env`; дивіться [Workspace `.env` files](/uk/gateway/security).
## Приклад конфігурації
Практична базова конфігурація з паруванням DM, allowlist кімнат і E2EE:
```json5
{
channels: {
matrix: {
enabled: true,
homeserver: "https://matrix.example.org",
accessToken: "syt_xxx",
encryption: true,
dm: {
policy: "pairing",
sessionScope: "per-room",
threadReplies: "off",
},
groupPolicy: "allowlist",
groupAllowFrom: ["@admin:example.org"],
groups: {
"!roomid:example.org": { requireMention: true },
},
autoJoin: "allowlist",
autoJoinAllowlist: ["!roomid:example.org"],
threadReplies: "inbound",
replyToMode: "off",
streaming: "partial",
},
},
}
```
## Попередні перегляди streaming
Streaming відповідей Matrix вмикається явно. `streaming` керує тим, як OpenClaw доставляє відповідь асистента в процесі створення; `blockStreaming` керує тим, чи кожен завершений блок зберігається як окреме повідомлення Matrix.
```json5
{
channels: {
matrix: {
streaming: "partial",
},
},
}
```
Щоб зберегти live-попередні перегляди відповідей, але приховати проміжні рядки інструментів/прогресу, використовуйте об’єктну
форму:
```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`: максимальна кількість rolling progress lines, що зберігаються в чернетці. Після цього ліміту старіші рядки обрізаються.
- `progress.maxLineChars`: максимальна кількість символів у компактному рядку прогресу перед усіченням.
- `progress.toolProgress`: коли `true` (за замовчуванням), live-активність інструментів/прогресу з’являється в чернетці.
| `streaming` | Поведінка |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"off"` (за замовчуванням) | Чекає на повну відповідь, надсилає один раз. `true` ↔ `"partial"`, `false` ↔ `"off"`. |
| `"partial"` | Редагує одне звичайне текстове повідомлення на місці, поки модель пише поточний блок. Стандартні клієнти Matrix можуть сповістити про перший preview, а не про фінальне редагування. |
| `"quiet"` | Те саме, що `"partial"`, але повідомлення є notice без сповіщення. Одержувачі отримують сповіщення лише тоді, коли per-user push rule збігається з фіналізованим редагуванням (див. нижче). |
| `"progress"` | Надсилає окремі компактні рядки прогресу за допомогою чернетки прогресу. |
`blockStreaming` не залежить від `streaming`:
| `streaming` | `blockStreaming: true` | `blockStreaming: false` (за замовчуванням) |
| ----------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------- |
| `"partial"` / `"quiet"` | Live-чернетка для поточного блока, завершені блоки збережені як повідомлення | Live-чернетка для поточного блока, фіналізована на місці |
| `"off"` | Одне повідомлення Matrix зі сповіщенням на кожен завершений блок | Одне повідомлення Matrix зі сповіщенням для повної відповіді |
Примітки:
- Якщо preview перевищує per-event size limit Matrix, OpenClaw зупиняє preview streaming і повертається до доставки лише фінального повідомлення.
- Медіавідповіді завжди надсилають вкладення звичайним способом. Якщо застарілий preview більше не можна безпечно використати повторно, OpenClaw редагує його перед надсиланням фінальної медіавідповіді.
- Оновлення preview прогресу інструментів увімкнені за замовчуванням, коли активний Matrix preview streaming. Задайте `streaming.preview.toolProgress: false`, щоб залишити preview edits для тексту відповіді, але перенести прогрес інструментів на звичайний шлях доставки.
- Preview edits коштують додаткових викликів Matrix API. Залиште `streaming: "off"`, якщо хочете найконсервативніший профіль rate-limit.
## Голосові повідомлення
Вхідні голосові нотатки Matrix транскрибуються перед gate згадки кімнати. Це дозволяє голосовій нотатці, яка вимовляє ім’я бота, запустити агента в кімнаті з `requireMention: true`, і дає агенту транскрипт замість лише placeholder аудіовкладення.
Matrix використовує спільний audio media provider, налаштований у `tools.media.audio`, наприклад OpenAI `gpt-4o-mini-transcribe`. Дивіться [Огляд медіаінструментів](/uk/tools/media-overview), щоб налаштувати provider і переглянути ліміти.
Деталі поведінки:
- Події `m.audio` та події `m.file` з MIME-типом `audio/*` підлягають обробці.
- У зашифрованих кімнатах OpenClaw розшифровує вкладення через наявний шлях медіа Matrix перед транскрибуванням.
- Транскрипт позначається в промпті агента як машинно згенерований і ненадійний.
- Вкладення позначається як уже транскрибоване, щоб нижчі за потоком медіаінструменти не транскрибували ту саму голосову нотатку повторно.
- Установіть `tools.media.audio.enabled: false`, щоб вимкнути аудіотранскрибування глобально.
## Метадані схвалення
Нативні запити схвалення Matrix є звичайними подіями `m.room.message` зі специфічним для OpenClaw власним вмістом події в `com.openclaw.approval`. Matrix дозволяє власні ключі вмісту подій, тому стандартні клієнти все одно відображають текстове тіло, а клієнти, що підтримують OpenClaw, можуть читати структурований ідентифікатор схвалення, тип, стан, доступні рішення та деталі exec/plugin.
Коли запит схвалення надто довгий для однієї події Matrix, OpenClaw розбиває видимий текст на фрагменти й додає `com.openclaw.approval` лише до першого фрагмента. Реакції для рішень дозволити/відхилити прив’язуються до цієї першої події, тому довгі запити зберігають ту саму ціль схвалення, що й запити з однією подією.
### Self-hosted push-правила для тихих фіналізованих прев’ю
`streaming: "quiet"` сповіщає одержувачів лише після фіналізації блока або ходу - push-правило для кожного користувача має збігатися з маркером фіналізованого прев’ю. Повний рецепт дивіться в [push-правилах Matrix для тихих прев’ю](/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 у дозволених кімнатах і DM.
- `allowBots: "mentions"` приймає такі повідомлення лише тоді, коли вони видимо згадують цього бота в кімнатах. DM усе ще дозволені.
- `groups..allowBots` перевизначає налаштування рівня облікового запису для однієї кімнати.
- Прийняті повідомлення від налаштованих ботів використовують спільний [захист від циклів ботів](/uk/channels/bot-loop-protection). Налаштуйте `channels.defaults.botLoopProtection`, а потім перевизначте через `channels.matrix.botLoopProtection` або `channels.matrix.groups..botLoopProtection`, коли одній кімнаті потрібен інший бюджет.
- OpenClaw усе ще ігнорує повідомлення від того самого ID користувача Matrix, щоб уникнути циклів самовідповідей.
- Matrix тут не надає нативного прапорця бота; OpenClaw трактує «створено ботом» як «надіслано іншим налаштованим обліковим записом Matrix на цьому OpenClaw gateway».
Використовуйте суворі списки дозволених кімнат і вимоги згадування, коли вмикаєте трафік бот-до-бота в спільних кімнатах.
## Шифрування й верифікація
У зашифрованих (E2EE) кімнатах вихідні події зображень використовують `thumbnail_file`, щоб прев’ю зображень шифрувалися разом із повним вкладенням. Незашифровані кімнати все ще використовують звичайний `thumbnail_url`. Налаштування не потрібне - Plugin автоматично визначає стан E2EE.
Усі команди `openclaw matrix` приймають `--verbose` (повна діагностика), `--json` (машинозчитуваний вивід) і `--account ` (налаштування з кількома обліковими записами). За замовчуванням вивід стислий із тихим внутрішнім логуванням SDK. Наведені нижче приклади показують канонічну форму; додавайте прапорці за потреби.
### Увімкнення шифрування
```bash
openclaw matrix encryption setup
```
Ініціалізує секретне сховище та cross-signing, за потреби створює резервну копію ключів кімнат, а потім виводить стан і наступні кроки. Корисні прапорці:
- `--recovery-key ` застосувати ключ відновлення перед ініціалізацією (надавайте перевагу формі через stdin, задокументованій нижче)
- `--force-reset-cross-signing` відкинути поточну ідентичність 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 повідомляє про верифікацію через cross-signing
- `Signed by owner`: підписано вашим власним ключем самопідписування (лише діагностика)
`Verified by owner` стає `yes` лише тоді, коли `Cross-signing verified` має значення `yes`. Локальної довіри або самого лише підпису власника недостатньо.
`--allow-degraded-local-state` повертає best-effort діагностику без попередньої підготовки облікового запису Matrix; корисно для офлайн- або частково налаштованих перевірок.
### Верифікація цього пристрою ключем відновлення
Ключ відновлення чутливий - передавайте його через stdin замість передавання в командному рядку. Установіть `MATRIX_RECOVERY_KEY` (або `MATRIX__RECOVERY_KEY` для іменованого облікового запису):
```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 cross-signing.
Вона завершується з ненульовим кодом, коли повна довіра ідентичності неповна, навіть якщо ключ відновлення розблокував матеріал резервної копії. У такому разі завершіть самоверифікацію з іншого клієнта Matrix:
```bash
openclaw matrix verify self
```
`verify self` чекає на `Cross-signing verified: yes`, перш ніж успішно завершитися. Використовуйте `--timeout-ms `, щоб налаштувати очікування.
Форма з буквальним ключем `openclaw matrix verify device ""` також приймається, але ключ потрапляє в історію вашої оболонки.
### Ініціалізація або відновлення cross-signing
```bash
openclaw matrix verify bootstrap
```
`verify bootstrap` — це команда відновлення й налаштування для зашифрованих облікових записів. По черзі вона:
- ініціалізує секретне сховище, повторно використовуючи наявний ключ відновлення, коли це можливо
- ініціалізує cross-signing і завантажує відсутні публічні ключі
- позначає та підписує поточний пристрій через cross-signing
- створює серверну резервну копію ключів кімнат, якщо її ще не існує
Якщо homeserver вимагає UIA для завантаження ключів cross-signing, OpenClaw спочатку пробує без автентифікації, потім `m.login.dummy`, потім `m.login.password` (потребує `channels.matrix.password`).
Корисні прапорці:
- `--recovery-key-stdin` (поєднуйте з `printf '%s\n' "$MATRIX_RECOVERY_KEY" | …`) або `--recovery-key `
- `--force-reset-cross-signing`, щоб відкинути поточну ідентичність 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
```
Надсилає запит верифікації з цього облікового запису OpenClaw. `--own-user` запитує самоверифікацію (ви приймаєте запит в іншому клієнті Matrix того самого користувача); `--user-id`/`--device-id`/`--room-id` спрямовують запит на когось іншого. `--own-user` не можна поєднувати з іншими прапорцями націлювання.
Для нижчорівневої обробки життєвого циклу - зазвичай під час супроводу вхідних запитів з іншого клієнта - ці команди діють на конкретний запит `` (виводиться `verify list` і `verify request`):
| Команда | Призначення |
| ------------------------------------------ | ------------------------------------------------------------------ |
| `openclaw matrix verify accept ` | Прийняти вхідний запит |
| `openclaw matrix verify start ` | Запустити SAS-потік |
| `openclaw matrix verify sas ` | Вивести SAS emoji або десяткові числа |
| `openclaw matrix verify confirm-sas ` | Підтвердити, що SAS збігається з тим, що показує інший клієнт |
| `openclaw matrix verify mismatch-sas ` | Відхилити SAS, коли emoji або десяткові числа не збігаються |
| `openclaw matrix verify cancel ` | Скасувати; приймає необов’язкові `--reason ` і `--code ` |
`accept`, `start`, `sas`, `confirm-sas`, `mismatch-sas` і `cancel` усі приймають `--user-id` і `--room-id` як підказки подальшого DM, коли верифікація прив’язана до конкретної кімнати прямих повідомлень.
### Примітки щодо кількох облікових записів
Без `--account ` команди Matrix CLI використовують неявний типовий обліковий запис. Якщо у вас кілька іменованих облікових записів і ви не встановили `channels.matrix.defaultAccount`, вони відмовляться вгадувати й попросять вас вибрати. Коли E2EE вимкнено або недоступне для іменованого облікового запису, помилки вказують на ключ конфігурації цього облікового запису, наприклад `channels.matrix.accounts.assistant.encryption`.
З `encryption: true` значення `startupVerification` за замовчуванням дорівнює `"if-unverified"`. Під час запуску неверифікований пристрій запитує самоверифікацію в іншому клієнті Matrix, пропускаючи дублікати й застосовуючи cooldown (24 години за замовчуванням). Налаштуйте через `startupVerificationCooldownHours` або вимкніть через `startupVerification: "off"`.
Під час запуску також виконується консервативний прохід ініціалізації криптографії, який повторно використовує поточне секретне сховище й ідентичність cross-signing. Якщо стан ініціалізації пошкоджений, OpenClaw намагається виконати захищене відновлення навіть без `channels.matrix.password`; якщо homeserver вимагає пароль UIA, запуск записує попередження в журнал і не завершується аварійно. Пристрої, уже підписані власником, зберігаються.
Дивіться повний потік оновлення в [міграції Matrix](/uk/channels/matrix-migration).
Matrix публікує сповіщення життєвого циклу верифікації в сувору DM-кімнату верифікації як повідомлення `m.notice`: запит, готовність (із підказкою "Verify by emoji"), запуск/завершення та деталі SAS (emoji/десяткові), коли доступні.
Вхідні запити з іншого клієнта Matrix відстежуються й автоматично приймаються. Для самоверифікації OpenClaw автоматично запускає SAS-потік і підтверджує свій бік, щойно верифікація emoji стане доступною - вам усе одно потрібно порівняти й підтвердити "They match" у вашому клієнті Matrix.
Системні сповіщення верифікації не пересилаються в конвеєр чату агента.
Якщо `verify status` повідомляє, що поточного пристрою більше немає в списку на homeserver, створіть новий пристрій OpenClaw Matrix. Для входу з паролем:
```bash
openclaw matrix account add \
--account assistant \
--homeserver https://matrix.example.org \
--user-id '@assistant:example.org' \
--password '' \
--device-name OpenClaw-Gateway
```
Для автентифікації токеном створіть свіжий токен доступу у вашому Matrix-клієнті або інтерфейсі адміністратора, а потім оновіть OpenClaw:
```bash
openclaw matrix account add \
--account assistant \
--homeserver https://matrix.example.org \
--access-token ''
```
Замініть `assistant` на ID облікового запису з команди, що завершилася помилкою, або пропустіть `--account` для типового облікового запису.
Старі пристрої, керовані OpenClaw, можуть накопичуватися. Перегляньте список і очистьте зайві:
```bash
openclaw matrix devices list
openclaw matrix devices prune-stale
```
Matrix E2EE використовує офіційний шлях Rust-криптографії `matrix-js-sdk` з `fake-indexeddb` як shim для IndexedDB. Криптографічний стан зберігається в `crypto-idb-snapshot.json` (обмежувальні дозволи файлу).
Зашифрований runtime-стан розташований у `~/.openclaw/matrix/accounts//__//` і включає сховище синхронізації, криптосховище, ключ відновлення, знімок IDB, прив’язки потоків і стан перевірки запуску. Коли токен змінюється, але ідентичність облікового запису лишається тією самою, OpenClaw повторно використовує найкращий наявний корінь, щоб попередній стан лишався видимим.
Один старіший корінь token-hash може бути нормальною траєкторією безперервності ротації токена. Якщо OpenClaw журналює `matrix: multiple populated token-hash storage roots detected`, перевірте каталог облікового запису й архівуйте застарілі сусідні корені лише після підтвердження, що вибраний активний корінь справний. Надавайте перевагу переміщенню застарілих коренів у каталог `_archive/`, а не негайному видаленню.
## Керування профілем
Оновіть Matrix self-profile для вибраного облікового запису:
```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://`, OpenClaw спершу завантажує файл і зберігає вирішений URL `mxc://` у `channels.matrix.avatarUrl` (або в перевизначення для окремого облікового запису).
## Потоки
Matrix підтримує нативні потоки Matrix як для автоматичних відповідей, так і для надсилань через інструмент повідомлень. Дві незалежні ручки керують поведінкою:
### Маршрутизація сесій (`sessionScope`)
`dm.sessionScope` визначає, як Matrix DM-кімнати зіставляються із сесіями OpenClaw:
- `"per-user"` (типово): усі DM-кімнати з тим самим маршрутизованим співрозмовником спільно використовують одну сесію.
- `"per-room"`: кожна Matrix DM-кімната отримує власний ключ сесії, навіть коли співрозмовник той самий.
Явні прив’язки розмов завжди мають перевагу над `sessionScope`, тому прив’язані кімнати й потоки зберігають вибрану цільову сесію.
### Відповіді в потоках (`threadReplies`)
`threadReplies` визначає, де бот публікує свою відповідь:
- `"off"`: відповіді є верхньорівневими. Вхідні повідомлення в потоках лишаються в батьківській сесії.
- `"inbound"`: відповідати всередині потоку лише тоді, коли вхідне повідомлення вже було в цьому потоці.
- `"always"`: відповідати всередині потоку, коренем якого є повідомлення-тригер; ця розмова маршрутизується через відповідну сесію з областю дії потоку, починаючи з першого тригера.
`dm.threadReplies` перевизначає це лише для DM - наприклад, щоб ізолювати потоки кімнат, але лишити DM пласкими.
### Успадкування потоків і slash-команди
- Вхідні повідомлення в потоках включають кореневе повідомлення потоку як додатковий контекст агента.
- Надсилання через інструмент повідомлень автоматично успадковують поточний Matrix-потік, коли цільова кімната та сама (або та сама ціль користувача DM), якщо не надано явний `threadId`.
- Повторне використання цілі DM-користувача спрацьовує лише тоді, коли метадані поточної сесії доводять того самого DM-співрозмовника в тому самому Matrix-обліковому записі; інакше OpenClaw повертається до звичайної маршрутизації з областю дії користувача.
- `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язаний до потоку `/acp spawn` працюють у Matrix-кімнатах і DM.
- Верхньорівневий `/focus` створює новий Matrix-потік і прив’язує його до цільової сесії, коли `threadBindings.spawnSessions` увімкнено.
- Запуск `/focus` або `/acp spawn --thread here` всередині наявного Matrix-потоку прив’язує цей потік на місці.
Коли OpenClaw виявляє, що Matrix DM-кімната конфліктує з іншою DM-кімнатою в тій самій спільній сесії, він публікує одноразове `m.notice` у цій кімнаті з посиланням на запасний вихід `/focus` і пропозицією змінити `dm.sessionScope`. Сповіщення з’являється лише тоді, коли прив’язки потоків увімкнені.
## Прив’язки розмов ACP
Matrix-кімнати, DM і наявні Matrix-потоки можна перетворити на довговічні ACP-робочі простори без зміни поверхні чату.
Швидкий операторський потік:
- Запустіть `/acp spawn codex --bind here` всередині Matrix DM, кімнати або наявного потоку, яким хочете й надалі користуватися.
- У верхньорівневому Matrix DM або кімнаті поточний DM/кімната лишається поверхнею чату, а майбутні повідомлення маршрутизуються до створеної ACP-сесії.
- Усередині наявного Matrix-потоку `--bind here` прив’язує цей поточний потік на місці.
- `/new` і `/reset` скидають ту саму прив’язану ACP-сесію на місці.
- `/acp close` закриває ACP-сесію та видаляє прив’язку.
Примітки:
- `--bind here` не створює дочірній Matrix-потік.
- `threadBindings.spawnSessions` контролює `/acp spawn --thread auto|here`, де OpenClaw потрібно створити або прив’язати дочірній Matrix-потік.
### Конфігурація прив’язки потоків
Matrix успадковує глобальні типові значення з `session.threadBindings`, а також підтримує перевизначення для окремих каналів:
- `threadBindings.enabled`
- `threadBindings.idleHours`
- `threadBindings.maxAgeHours`
- `threadBindings.spawnSessions`
- `threadBindings.defaultSpawnContext`
Створення Matrix-сесій, прив’язаних до потоків, типово увімкнене:
- Установіть `threadBindings.spawnSessions: false`, щоб заблокувати створення/прив’язування Matrix-потоків верхньорівневим `/focus` і `/acp spawn --thread auto|here`.
- Установіть `threadBindings.defaultSpawnContext: "isolated"`, коли нативні створення потоків субагентів не мають відгалужувати батьківську стенограму.
## Реакції
Matrix підтримує вихідні реакції, вхідні сповіщення про реакції та реакції-підтвердження.
Інструменти вихідних реакцій контролюються `channels.matrix.actions.reactions`:
- `react` додає реакцію до Matrix-події.
- `reactions` перелічує поточний підсумок реакцій для Matrix-події.
- `emoji=""` видаляє власні реакції бота на цій події.
- `remove: true` видаляє лише вказану emoji-реакцію від бота.
**Порядок вирішення** (перемагає перше визначене значення):
| Налаштування | Порядок |
| ---------------------- | -------------------------------------------------------------------------------- |
| `ackReaction` | для облікового запису → канал → `messages.ackReaction` → запасний emoji ідентичності агента |
| `ackReactionScope` | для облікового запису → канал → `messages.ackReactionScope` → типово `"group-mentions"` |
| `reactionNotifications` | для облікового запису → канал → типово `"own"` |
`reactionNotifications: "own"` пересилає додані події `m.reaction`, коли вони спрямовані на Matrix-повідомлення, написані ботом; `"off"` вимикає системні події реакцій. Видалення реакцій не синтезуються в системні події, тому що Matrix представляє їх як редагування-вилучення, а не як окремі видалення `m.reaction`.
## Контекст історії
- `channels.matrix.historyLimit` керує тим, скільки останніх повідомлень кімнати включається як `InboundHistory`, коли повідомлення Matrix-кімнати запускає агента. Повертається до `messages.groupChat.historyLimit`; якщо обидва не задані, ефективне типове значення дорівнює `0`. Установіть `0`, щоб вимкнути.
- Історія Matrix-кімнати стосується лише кімнати. DM продовжують використовувати звичайну історію сесії.
- Історія Matrix-кімнати є лише очікуваною: OpenClaw буферизує повідомлення кімнати, які ще не спричинили відповідь, а потім робить знімок цього вікна, коли надходить згадка або інший тригер.
- Поточне повідомлення-тригер не включається в `InboundHistory`; воно лишається в основному вхідному тілі для цього ходу.
- Повторні спроби тієї самої Matrix-події повторно використовують початковий знімок історії, а не зсуваються вперед до новіших повідомлень кімнати.
## Видимість контексту
Matrix підтримує спільний елемент керування `contextVisibility` для додаткового контексту кімнати, такого як отриманий текст відповіді, корені потоків і очікувана історія.
- `contextVisibility: "all"` є типовим. Додатковий контекст зберігається таким, як отриманий.
- `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками allowlist кімнати/користувача.
- `contextVisibility: "allowlist_quote"` поводиться як `allowlist`, але все одно зберігає одну явну цитовану відповідь.
Це налаштування впливає на видимість додаткового контексту, а не на те, чи саме вхідне повідомлення може спричинити відповідь.
Авторизація тригера й надалі походить із `groupPolicy`, `groups`, `groupAllowFrom` і налаштувань політики DM.
## Політика DM і кімнат
```json5
{
channels: {
matrix: {
dm: {
policy: "allowlist",
allowFrom: ["@admin:example.org"],
threadReplies: "off",
},
groupPolicy: "allowlist",
groupAllowFrom: ["@admin:example.org"],
groups: {
"!roomid:example.org": { requireMention: true },
},
},
},
}
```
Щоб повністю заглушити DM, зберігши роботу кімнат, установіть `dm.enabled: false`:
```json5
{
channels: {
matrix: {
dm: { enabled: false },
groupPolicy: "allowlist",
groupAllowFrom: ["@admin:example.org"],
},
},
}
```
Див. [Групи](/uk/channels/groups) щодо поведінки mention-gating і allowlist.
Приклад спарювання для Matrix DM:
```bash
openclaw pairing list matrix
openclaw pairing approve matrix
```
Якщо незатверджений користувач Matrix продовжує писати вам до схвалення, OpenClaw повторно використовує той самий очікуваний код спарювання й може надіслати відповідь-нагадування після короткого cooldown замість створення нового коду.
Див. [Спарювання](/uk/channels/pairing) щодо спільного потоку спарювання DM і структури сховища.
## Відновлення прямих кімнат
Якщо стан direct-message розсинхронізується, OpenClaw може опинитися із застарілими зіставленнями `m.direct`, які вказують на старі solo-кімнати замість активного DM. Перевірте поточне зіставлення для співрозмовника:
```bash
openclaw matrix direct inspect --user-id @alice:example.org
```
Відновіть його:
```bash
openclaw matrix direct repair --user-id @alice:example.org
```
Обидві команди приймають `--account ` для конфігурацій із кількома обліковими записами. Потік відновлення:
- надає перевагу строгому 1:1 DM, який уже зіставлений у `m.direct`
- повертається до будь-якого наразі приєднаного строгого 1:1 DM з цим користувачем
- створює свіжу пряму кімнату й переписує `m.direct`, якщо справного DM не існує
Він не видаляє старі кімнати автоматично. Він вибирає справний DM і оновлює зіставлення, щоб майбутні Matrix-надсилання, сповіщення перевірки та інші потоки direct-message були спрямовані в правильну кімнату.
## Схвалення exec
Matrix може діяти як нативний клієнт схвалень. Налаштуйте в `channels.matrix.execApprovals` (або `channels.matrix.accounts..execApprovals` для перевизначення окремого облікового запису):
- `enabled`: доставляти схвалення через нативні підказки Matrix. Коли не задано або встановлено `"auto"`, Matrix автоматично вмикається після того, як можна визначити принаймні одного approver. Установіть `false`, щоб явно вимкнути.
- `approvers`: ID користувачів Matrix (`@owner:example.org`), яким дозволено схвалювати exec-запити. Необов’язково - повертається до `channels.matrix.dm.allowFrom`.
- `target`: куди надходять підказки. `"dm"` (типово) надсилає в DM approver; `"channel"` надсилає до початкової Matrix-кімнати або DM; `"both"` надсилає в обидва місця.
- `agentFilter` / `sessionFilter`: необов’язкові allowlist для того, які агенти/сесії запускають доставку Matrix.
Авторизація трохи відрізняється між типами схвалень:
- **Схвалення exec** використовують `execApprovals.approvers`, повертаючись до `dm.allowFrom`.
- **Схвалення Plugin** авторизуються лише через `dm.allowFrom`.
Обидва типи спільно використовують Matrix-скорочення реакцій і оновлення повідомлень. Approver бачать скорочення реакцій на основному повідомленні схвалення:
- `✅` дозволити один раз
- `❌` відхилити
- `♾️` дозволяти завжди (коли ефективна політика exec це дозволяє)
Резервні slash-команди: `/approve allow-once`, `/approve allow-always`, `/approve deny`.
Лише визначені затверджувачі можуть схвалювати або відхиляти. Доставка каналом для exec-схвалень містить текст команди - вмикайте `channel` або `both` лише в довірених кімнатах.
Пов’язано: [Exec-схвалення](/uk/tools/exec-approvals).
## Slash-команди
Slash-команди (`/new`, `/reset`, `/model`, `/focus`, `/unfocus`, `/agents`, `/session`, `/acp`, `/approve` тощо) працюють безпосередньо в DM. У кімнатах OpenClaw також розпізнає команди з префіксом власної Matrix-згадки бота, тож `@bot:server /new` запускає шлях команди без власного regex для згадок. Це зберігає чутливість бота до дописів у стилі кімнат `@mention /command`, які Element і подібні клієнти надсилають, коли користувач завершує ім’я бота клавішею Tab перед введенням команди.
Правила авторизації й далі застосовуються: відправники команд мають відповідати тим самим політикам allowlist/власника для DM або кімнат, що й звичайні повідомлення.
## Кілька облікових записів
```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..account`. Записи без `account` спільні для всіх облікових записів; `account: "default"` і далі працює, коли типовий обліковий запис налаштовано на верхньому рівні.
**Вибір типового облікового запису:**
- Задайте `defaultAccount`, щоб вибрати іменований обліковий запис, якому надають перевагу неявна маршрутизація, зондування та CLI-команди.
- Якщо у вас кілька облікових записів і один буквально названий `default`, OpenClaw використовує його неявно, навіть коли `defaultAccount` не задано.
- Якщо у вас кілька іменованих облікових записів і типовий не вибрано, CLI-команди відмовляються вгадувати - задайте `defaultAccount` або передайте `--account `.
- Блок верхнього рівня `channels.matrix.*` розглядається як неявний обліковий запис `default` лише коли його автентифікація повна (`homeserver` + `accessToken` або `homeserver` + `userId` + `password`). Іменовані облікові записи залишаються доступними для виявлення за `homeserver` + `userId`, щойно кешовані облікові дані покривають автентифікацію.
**Підвищення:**
- Коли OpenClaw під час виправлення або налаштування підвищує конфігурацію з одним обліковим записом до конфігурації з кількома обліковими записами, він зберігає наявний іменований обліковий запис, якщо такий існує або `defaultAccount` уже вказує на нього. До підвищеного облікового запису переміщуються лише ключі автентифікації/початкового завантаження Matrix; спільні ключі політики доставки залишаються на верхньому рівні.
Спільний шаблон для кількох облікових записів див. у [довіднику з конфігурації](/uk/gateway/config-channels#multi-account-all-channels).
## Приватні/LAN homeserver-и
Типово OpenClaw блокує приватні/внутрішні Matrix homeserver-и для захисту від SSRF, якщо ви
явно не ввімкнете це для кожного облікового запису.
Якщо ваш homeserver працює на localhost, IP у LAN/Tailscale або внутрішньому імені хоста, увімкніть
`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..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`
ID кімнат Matrix чутливі до регістру. Використовуйте точний регістр ID кімнати з Matrix
під час налаштування явних цілей доставки, cron-завдань, прив’язок або allowlist-ів.
OpenClaw зберігає внутрішні ключі сесій у канонічному вигляді для сховища, тому ці ключі в нижньому регістрі
не є надійним джерелом для ID доставки Matrix.
Живий пошук у каталозі використовує обліковий запис Matrix, під яким виконано вхід:
- Пошуки користувачів запитують каталог користувачів Matrix на цьому homeserver-і.
- Пошуки кімнат безпосередньо приймають явні ID кімнат і псевдоніми. Пошук за назвою приєднаної кімнати виконується за принципом best-effort і застосовується лише до allowlist-ів кімнат під час виконання, коли задано `dangerouslyAllowNameMatching: true`.
- Якщо назву кімнати не можна визначити як ID або псевдонім, вона ігнорується під час визначення allowlist-а під час виконання.
## Довідник з конфігурації
Поля користувачів у стилі allowlist (`groupAllowFrom`, `dm.allowFrom`, `groups..users`) приймають повні ID користувачів Matrix (найбезпечніше). Записи користувачів, які не є ID, типово ігноруються. Якщо ви задаєте `dangerouslyAllowNameMatching: true`, точні збіги відображуваних імен у каталозі Matrix визначаються під час запуску і щоразу, коли allowlist змінюється під час роботи монітора; записи, які неможливо визначити, ігноруються під час виконання.
Ключі allowlist-а кімнат (`groups`, застаріле `rooms`) мають бути ID кімнат або псевдонімами. Звичайні ключі-назви кімнат типово ігноруються; `dangerouslyAllowNameMatching: true` відновлює best-effort пошук за назвами приєднаних кімнат.
### Обліковий запис і підключення
- `enabled`: увімкнути або вимкнути канал.
- `name`: необов’язкова відображувана мітка для облікового запису.
- `defaultAccount`: бажаний ID облікового запису, коли налаштовано кілька облікових записів Matrix.
- `accounts`: іменовані перевизначення для окремих облікових записів. Значення верхнього рівня `channels.matrix` успадковуються як типові.
- `homeserver`: URL homeserver-а, наприклад `https://matrix.example.org`.
- `network.dangerouslyAllowPrivateNetwork`: дозволити цьому обліковому запису підключатися до `localhost`, IP у LAN/Tailscale або внутрішніх імен хостів.
- `proxy`: необов’язковий URL HTTP(S)-проксі для Matrix-трафіку. Підтримується перевизначення для окремого облікового запису.
- `userId`: повний ID користувача Matrix (`@bot:example.org`).
- `accessToken`: токен доступу для автентифікації на основі токена. Підтримуються відкритий текст і значення SecretRef у провайдерах env/file/exec ([Керування секретами](/uk/gateway/secrets)).
- `password`: пароль для входу на основі пароля. Підтримуються відкритий текст і значення SecretRef.
- `deviceId`: явний ID пристрою Matrix.
- `deviceName`: відображуване ім’я пристрою, що використовується під час входу з паролем.
- `avatarUrl`: збережений URL власного аватара для синхронізації профілю та оновлень `profile set`.
- `initialSyncLimit`: максимальна кількість подій, отриманих під час синхронізації запуску.
### Шифрування
- `encryption`: увімкнути E2EE. Типово: `false`.
- `startupVerification`: `"if-unverified"` (типово, коли E2EE увімкнено) або `"off"`. Автоматично запитує самоперевірку під час запуску, коли цей пристрій неперевірений.
- `startupVerificationCooldownHours`: період очікування перед наступним автоматичним запитом під час запуску. Типово: `24`.
### Доступ і політика
- `groupPolicy`: `"open"`, `"allowlist"` або `"disabled"`. Типово: `"allowlist"`.
- `groupAllowFrom`: allowlist ID користувачів для трафіку кімнат.
- `mentionPatterns`: scoped regex-шаблони для згадок у кімнатах. Об’єкт із `{ mode: "allow"|"deny", allowIn: [roomId, ...], denyIn: [roomId, ...] }`. Керує тим, чи налаштовані `agents.list[].groupChat.mentionPatterns` застосовуються для кожної кімнати.
- `dm.enabled`: коли `false`, ігнорувати всі DM. Типово: `true`.
- `dm.policy`: `"pairing"` (типово), `"allowlist"`, `"open"` або `"disabled"`. Застосовується після того, як бот приєднався й класифікував кімнату як DM; не впливає на обробку запрошень.
- `dm.allowFrom`: allowlist ID користувачів для DM-трафіку.
- `dm.sessionScope`: `"per-user"` (типово) або `"per-room"`.
- `dm.threadReplies`: перевизначення лише для DM для потокових відповідей (`"off"`, `"inbound"`, `"always"`).
- `allowBots`: приймати повідомлення від інших налаштованих облікових записів ботів Matrix (`true` або `"mentions"`).
- `allowlistOnly`: коли `true`, примусово переводить усі активні політики DM (крім `"disabled"`) і групові політики `"open"` у `"allowlist"`. Не змінює політики `"disabled"`.
- `dangerouslyAllowNameMatching`: коли `true`, дозволяє пошук за відображуваними іменами в каталозі Matrix для записів allowlist-а користувачів і пошук за назвами приєднаних кімнат для ключів allowlist-а кімнат. Надавайте перевагу повним ID `@user:server` та ID кімнат або псевдонімам.
- `autoJoin`: `"always"`, `"allowlist"` або `"off"`. Типово: `"off"`. Застосовується до кожного запрошення Matrix, включно із запрошеннями у стилі DM.
- `autoJoinAllowlist`: кімнати/псевдоніми, дозволені, коли `autoJoin` має значення `"allowlist"`. Записи псевдонімів визначаються відносно homeserver-а, а не відносно стану, заявленого запрошеною кімнатою.
- `contextVisibility`: додаткова видимість контексту (`"all"` типово, `"allowlist"`, `"allowlist_quote"`).
### Поведінка відповідей
- `replyToMode`: `"off"`, `"first"`, `"all"` або `"batched"`.
- `threadReplies`: `"off"`, `"inbound"` або `"always"`.
- `threadBindings`: перевизначення для кожного каналу для маршрутизації та життєвого циклу сесій, прив’язаних до тредів.
- `streaming`: `"off"` (типово), `"partial"`, `"quiet"`, `"progress"` або об’єктна форма `{ mode, preview: { toolProgress }, progress: { label, labels, maxLines, maxLineChars, toolProgress } }`. `true` ↔ `"partial"`, `false` ↔ `"off"`.
- `blockStreaming`: коли `true`, завершені блоки асистента зберігаються як окремі повідомлення перебігу.
- `markdown`: необов’язкова конфігурація рендерингу Markdown для вихідного тексту.
- `responsePrefix`: необов’язковий рядок, що додається на початок вихідних відповідей.
- `textChunkLimit`: розмір вихідного фрагмента в символах, коли `chunkMode: "length"`. Типово: `4000`.
- `chunkMode`: `"length"` (типово, розбиває за кількістю символів) або `"newline"` (розбиває на межах рядків).
- `historyLimit`: кількість нещодавніх повідомлень кімнати, включених як `InboundHistory`, коли повідомлення кімнати запускає агента. Повертається до `messages.groupChat.historyLimit`; ефективне типове значення `0` (вимкнено).
- `mediaMaxMb`: обмеження розміру медіа в МБ для вихідних надсилань і вхідної обробки.
### Налаштування реакцій
- `ackReaction`: перевизначення ack-реакції для цього каналу/облікового запису.
- `ackReactionScope`: перевизначення області (`"group-mentions"` типово, `"group-all"`, `"direct"`, `"all"`, `"none"`, `"off"`).
- `reactionNotifications`: режим сповіщень про вхідні реакції (`"own"` типово, `"off"`).
### Інструменти та перевизначення для окремих кімнат
- `actions`: обмеження інструментів для кожної дії (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`).
- `groups`: мапа політик для кожної кімнати. Ідентичність сесії використовує стабільний ID кімнати після розв’язання. (`rooms` — застарілий псевдонім.)
- `groups..account`: обмежує один успадкований запис кімнати конкретним обліковим записом.
- `groups..enabled`: перемикач для кожної кімнати. Коли `false`, кімната ігнорується так, ніби її немає в мапі.
- `groups..requireMention`: перевизначення вимоги згадки рівня каналу для окремої кімнати.
- `groups..allowBots`: перевизначення налаштування рівня каналу для окремої кімнати (`true` або `"mentions"`).
- `groups..botLoopProtection`: перевизначення бюджету захисту від циклів бот-до-бота для окремої кімнати.
- `groups..users`: список дозволених відправників для окремої кімнати.
- `groups..tools`: перевизначення дозволів/заборон інструментів для окремої кімнати.
- `groups..autoReply`: перевизначення керування згадками для окремої кімнати. `true` вимикає вимоги згадок для цієї кімнати; `false` примусово вмикає їх знову.
- `groups..skills`: фільтр Skills для окремої кімнати.
- `groups..systemPrompt`: фрагмент системного промпта для окремої кімнати.
### Налаштування схвалення exec
- `execApprovals.enabled`: доставляти схвалення exec через нативні для Matrix запити.
- `execApprovals.approvers`: ID користувачів Matrix, яким дозволено схвалювати. Повертається до `dm.allowFrom`.
- `execApprovals.target`: `"dm"` (типово), `"channel"` або `"both"`.
- `execApprovals.agentFilter` / `execApprovals.sessionFilter`: необов’язкові списки дозволених агентів/сесій для доставки.
## Пов’язане
- [Огляд каналів](/uk/channels) - усі підтримувані канали
- [Пов’язування](/uk/channels/pairing) - автентифікація DM і потік пов’язування
- [Групи](/uk/channels/groups) - поведінка групового чату та керування згадками
- [Маршрутизація каналів](/uk/channels/channel-routing) - маршрутизація сесій для повідомлень
- [Безпека](/uk/gateway/security) - модель доступу та посилення захисту