Matrix

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

Установлення

openclaw plugins install @openclaw/matrix

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

plugins install реєструє та вмикає Plugin; окремий крок enable не потрібен. Канал усе одно не працюватиме, доки його не буде налаштовано нижче. Загальні правила встановлення див. у розділі Plugins.

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

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

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

openclaw channels addopenclaw configure --section channels

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Змінні середовища, пов’язані з ключами конфігурації, використовуються, якщо відповідний ключ конфігурації не задано. Обліковий запис за замовчуванням використовує назви без префікса; для іменованих облікових записів токен облікового запису вставляється перед суфіксом (див. нормалізацію).

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

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

Практична базова конфігурація зі спарюванням для особистих повідомлень, списком дозволених кімнат і E2EE:

{  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: { mode: "partial" },    },  },}

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

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

{  channels: {    matrix: {      streaming: { mode: "partial" },    },  },}

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

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

Повна конфігурація приймає { mode, chunkMode, block, preview, progress }:

{  channels: {    matrix: {      streaming: {        mode: "progress",        progress: {          label: "auto", // вибрати з налаштованих або вбудованих міток (false — приховати)          labels: ["Thinking", "Writing", "Searching"], // кандидати для label: "auto"          maxLines: 8, // максимальна кількість рухомих рядків перебігу виконання (за замовчуванням: 8)          maxLineChars: 120, // максимальна кількість символів у рядку до скорочення (за замовчуванням: 120)          toolProgress: true, // показувати активність інструментів/перебігу виконання (за замовчуванням: true)        },      },    },  },}

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

streaming.block.enabled (за замовчуванням false) не залежить від streaming.mode:

Примітки:

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

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

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

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

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

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

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

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

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

streaming.mode: "quiet" сповіщає одержувачів лише після завершення блока або ходу — правило push-сповіщень для кожного користувача має відповідати маркеру завершеного попереднього перегляду. Повну інструкцію див. у розділі Правила push-сповіщень Matrix для тихих попередніх переглядів.

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

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

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

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

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

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

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

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

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

openclaw matrix encryption setupprintf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix encryption setup --recovery-key-stdin

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

• --recovery-key-stdin зчитує ключ відновлення зі стандартного вводу, не розкриваючи його в аргументах процесу; --recovery-key <key> залишається доступним для сумісності
• --force-reset-cross-signing відкидає поточну ідентичність перехресного підписування та створює нову (лише для свідомого використання)

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

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

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

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

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

openclaw matrix verify statusopenclaw matrix verify status --include-recovery-key --json

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

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

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

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

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

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

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

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

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

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

openclaw matrix verify self

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

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

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

openclaw matrix verify bootstrap

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

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

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

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

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

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

openclaw matrix verify backup statusprintf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin

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

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

openclaw matrix verify backup reset --yes

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

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

openclaw matrix verify list

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

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

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

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

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

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

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

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

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

openclaw matrix devices listopenclaw matrix devices prune-stale

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

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

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

Гілки

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Швидкий порядок дій для оператора:

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

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

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

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

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

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

Реакції

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

openclaw pairing list matrixopenclaw pairing approve matrix <CODE>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Схвалення виконання використовують execApprovals.approvers, а резервним є dm.allowFrom.
• Схвалення Plugin авторизуються лише через dm.allowFrom.

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

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

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

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

Пов’язаний матеріал: Схвалення виконання.

Слеш-команди

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

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

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

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

Успадкування:

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

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

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

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

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

Спільний шаблон для кількох облікових записів див. у довіднику з конфігурації.

Приватні/LAN домашні сервери

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Шифрування

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

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

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

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

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

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

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

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

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

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

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

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

• Огляд каналів — усі підтримувані канали
• Сполучення — автентифікація в особистих повідомленнях і процес сполучення
• Групи — поведінка групових чатів і перевірка згадувань
• Маршрутизація каналів — маршрутизація сеансів для повідомлень
• Безпека — модель доступу та посилення захисту