Перейти до основного вмісту

​
Matrix

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

​
Вбудований плагін

Matrix постачається як вбудований плагін у поточних релізах OpenClaw, тому звичайним зібраним пакетам не потрібне окреме встановлення. Якщо ви використовуєте старішу збірку або власне встановлення без Matrix, установіть його вручну: Установлення з npm: 
openclaw plugins install @openclaw/matrix
Установлення з локального checkout: 
openclaw plugins install ./path/to/local/matrix-plugin
Див. Plugins щодо поведінки плагінів і правил встановлення.

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

  1. Переконайтеся, що плагін Matrix доступний.
    • У поточних пакетних релізах OpenClaw він уже вбудований.
    • У старіших/кастомних встановленнях його можна додати вручну наведеними вище командами.
  2. Створіть обліковий запис Matrix на своєму homeserver.
  3. Налаштуйте channels.matrix, використовуючи один із варіантів:
    • homeserver + accessToken, або
    • homeserver + userId + password.
  4. Перезапустіть gateway.
  5. Почніть DM із ботом або запросіть його до кімнати.
Шляхи інтерактивного налаштування: 
openclaw channels add
openclaw configure --section channels
Що саме запитує майстер Matrix:
  • URL homeserver
  • метод автентифікації: токен доступу або пароль
  • user ID лише якщо ви вибрали автентифікацію паролем
  • необов’язкова назва пристрою
  • чи вмикати E2EE
  • чи налаштувати доступ до кімнат Matrix зараз
Важлива поведінка майстра:
  • Якщо для вибраного облікового запису вже існують змінні середовища автентифікації Matrix, і цей обліковий запис ще не має збереженої автентифікації в конфігурації, майстер запропонує скорочений варіант через env і запише для цього облікового запису лише enabled: true.
  • Коли ви інтерактивно додаєте ще один обліковий запис Matrix, введена назва облікового запису нормалізується до ID облікового запису, що використовується в конфігурації та env vars. Наприклад, Ops Bot стає ops-bot.
  • Підказки allowlist для DM одразу приймають повні значення @user:server. Відображувані імена працюють лише тоді, коли живий пошук у директорії знаходить один точний збіг; інакше майстер попросить повторити спробу з повним Matrix ID.
  • Підказки allowlist для кімнат напряму приймають ID кімнат і аліаси. Вони також можуть у реальному часі розпізнавати назви приєднаних кімнат, але нерозпізнані назви під час налаштування зберігаються лише як введені та пізніше ігноруються під час виконання allowlist. Надавайте перевагу !room:server або #alias:server.
  • Ідентичність кімнати/сесії під час виконання використовує стабільний Matrix room ID. Аліаси, оголошені кімнатою, використовуються лише як вхідні дані для пошуку, а не як довгостроковий ключ сесії чи стабільна ідентичність групи.
  • Щоб розпізнати назви кімнат перед збереженням, використовуйте openclaw channels resolve --channel matrix "Project Room".
Мінімальне налаштування на основі токена: 
{
  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",
    },
  },
}
Matrix зберігає кешовані облікові дані в ~/.openclaw/credentials/matrix/. Обліковий запис за замовчуванням використовує credentials.json; іменовані облікові записи використовують credentials-<account>.json. Еквіваленти змінних середовища (використовуються, коли ключ конфігурації не задано):
  • MATRIX_HOMESERVER
  • MATRIX_ACCESS_TOKEN
  • MATRIX_USER_ID
  • MATRIX_PASSWORD
  • MATRIX_DEVICE_ID
  • MATRIX_DEVICE_NAME
Для облікових записів не за замовчуванням використовуйте змінні середовища з областю облікового запису:
  • MATRIX_<ACCOUNT_ID>_HOMESERVER
  • MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN
  • MATRIX_<ACCOUNT_ID>_USER_ID
  • MATRIX_<ACCOUNT_ID>_PASSWORD
  • MATRIX_<ACCOUNT_ID>_DEVICE_ID
  • MATRIX_<ACCOUNT_ID>_DEVICE_NAME
Приклад для облікового запису ops:
  • MATRIX_OPS_HOMESERVER
  • MATRIX_OPS_ACCESS_TOKEN
Для нормалізованого ID облікового запису ops-bot використовуйте:
  • MATRIX_OPS_X2D_BOT_HOMESERVER
  • MATRIX_OPS_X2D_BOT_ACCESS_TOKEN
Matrix екранує розділові знаки в ID облікових записів, щоб уникнути колізій у змінних середовища з областю видимості. Наприклад, - стає _X2D_, тому ops-prod перетворюється на MATRIX_OPS_X2D_PROD_*. Інтерактивний майстер пропонує скорочений варіант через env vars лише тоді, коли ці змінні середовища автентифікації вже присутні, а для вибраного облікового запису ще не збережено автентифікацію Matrix у конфігурації.

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

Це практична базова конфігурація з pairing для DM, allowlist кімнат і ввімкненим 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: "partial",
    },
  },
}

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

Потокові відповіді Matrix вмикаються за бажанням. Установіть channels.matrix.streaming у "partial", якщо хочете, щоб OpenClaw надсилав одну чернетку відповіді, редагував цю чернетку на місці під час генерування тексту моделлю, а потім завершував її, коли відповідь буде готова: 
{
  channels: {
    matrix: {
      streaming: "partial",
    },
  },
}
  • streaming: "off" — це значення за замовчуванням. OpenClaw чекає на фінальну відповідь і надсилає її один раз.
  • streaming: "partial" створює одне редаговане повідомлення попереднього перегляду для поточного блоку відповіді помічника замість надсилання кількох часткових повідомлень.
  • blockStreaming: true вмикає окремі повідомлення прогресу Matrix. Якщо streaming: "partial", Matrix зберігає живу чернетку для поточного блоку та залишає завершені блоки окремими повідомленнями.
  • Коли streaming: "partial" і blockStreaming вимкнено, Matrix лише редагує живу чернетку й надсилає завершену відповідь, коли цей блок або хід завершується.
  • Якщо попередній перегляд більше не вміщується в одну подію Matrix, OpenClaw припиняє потоковий попередній перегляд і повертається до звичайного фінального доставлення.
  • Відповіді з медіа, як і раніше, надсилають вкладення звичайним способом. Якщо застарілий попередній перегляд більше не можна безпечно використати повторно, OpenClaw виконує його redaction перед надсиланням фінальної медіавідповіді.
  • Редагування попереднього перегляду створює додаткові виклики Matrix API. Залишайте streaming вимкненим, якщо хочете найобережнішу поведінку щодо обмежень частоти.
blockStreaming сам по собі не вмикає чернетки попереднього перегляду. Використовуйте streaming: "partial" для редагування попереднього перегляду; потім додайте blockStreaming: true, лише якщо також хочете, щоб завершені блоки помічника залишалися видимими як окремі повідомлення прогресу.

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

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

​
Кімнати bot-to-bot

За замовчуванням повідомлення Matrix від інших налаштованих облікових записів Matrix OpenClaw ігноруються. Використовуйте allowBots, якщо ви навмисно хочете дозволити міжагентний трафік Matrix: 
{
  channels: {
    matrix: {
      allowBots: "mentions", // true | "mentions"
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}
  • allowBots: true приймає повідомлення від інших налаштованих облікових записів ботів Matrix у дозволених кімнатах і DM.
  • allowBots: "mentions" приймає ці повідомлення лише тоді, коли вони явно згадують цього бота в кімнатах. DM усе одно дозволені.
  • groups.<room>.allowBots перевизначає налаштування рівня облікового запису для однієї кімнати.
  • OpenClaw все одно ігнорує повідомлення від того самого Matrix user ID, щоб уникнути циклів самовідповіді.
  • Matrix тут не надає нативного прапорця бота; OpenClaw трактує “bot-authored” як “надіслане іншим налаштованим обліковим записом Matrix на цьому gateway OpenClaw”.
Використовуйте суворі allowlist кімнат і вимоги щодо згадок, коли вмикаєте трафік bot-to-bot у спільних кімнатах. Увімкнення шифрування: 
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}
Перевірка стану верифікації: 
openclaw matrix verify status
Докладний стан (повна діагностика): 
openclaw matrix verify status --verbose
Включити збережений recovery key у машиночитний вивід: 
openclaw matrix verify status --include-recovery-key --json
Ініціалізувати cross-signing і стан верифікації: 
openclaw matrix verify bootstrap
Підтримка кількох облікових записів: використовуйте channels.matrix.accounts з обліковими даними для кожного облікового запису та необов’язковим name. Див. Configuration reference щодо спільного шаблону. Докладна діагностика bootstrap: 
openclaw matrix verify bootstrap --verbose
Примусово скинути ідентичність cross-signing перед bootstrap: 
openclaw matrix verify bootstrap --force-reset-cross-signing
Верифікувати цей пристрій за допомогою recovery key: 
openclaw matrix verify device "<your-recovery-key>"
Докладні відомості про верифікацію пристрою: 
openclaw matrix verify device "<your-recovery-key>" --verbose
Перевірка стану резервного копіювання ключів кімнат: 
openclaw matrix verify backup status
Докладна діагностика стану резервного копіювання: 
openclaw matrix verify backup status --verbose
Відновлення ключів кімнат із резервної копії на сервері: 
openclaw matrix verify backup restore
Докладна діагностика відновлення: 
openclaw matrix verify backup restore --verbose
Видалити поточну резервну копію на сервері та створити нову базову резервну копію. Якщо збережений ключ резервної копії не вдається коректно завантажити, це скидання також може відтворити secret storage, щоб майбутні холодні запуски могли завантажувати новий ключ резервної копії: 
openclaw matrix verify backup reset --yes
Усі команди verify за замовчуванням є лаконічними (включно з тихим внутрішнім логуванням SDK) і показують детальну діагностику лише з --verbose. Для повного машиночитного виводу в сценаріях використовуйте --json. У конфігураціях із кількома обліковими записами команди Matrix CLI використовують неявний обліковий запис Matrix за замовчуванням, якщо ви не передасте --account <id>. Якщо ви налаштували кілька іменованих облікових записів, спочатку встановіть channels.matrix.defaultAccount, інакше такі неявні операції CLI зупиняться й попросять вас явно вибрати обліковий запис. Використовуйте --account, коли хочете, щоб операції верифікації або роботи з пристроями явно націлювалися на іменований обліковий запис: 
openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant
Коли шифрування вимкнено або недоступне для іменованого облікового запису, попередження Matrix і помилки верифікації вказують на ключ конфігурації цього облікового запису, наприклад channels.matrix.accounts.assistant.encryption.

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

OpenClaw вважає цей пристрій Matrix верифікованим лише тоді, коли його верифікує ваша власна ідентичність cross-signing. На практиці openclaw matrix verify status --verbose показує три сигнали довіри:
  • Locally trusted: цьому пристрою довіряє лише поточний клієнт
  • Cross-signing verified: SDK повідомляє, що пристрій верифіковано через cross-signing
  • Signed by owner: пристрій підписано вашим власним self-signing key
Verified by owner стає yes лише тоді, коли є верифікація cross-signing або підпис власника. Самої локальної довіри недостатньо, щоб OpenClaw вважав пристрій повністю верифікованим.

​
Що робить bootstrap

openclaw matrix verify bootstrap — це команда відновлення та налаштування для зашифрованих облікових записів Matrix. Вона послідовно виконує все наведене нижче:
  • ініціалізує secret storage, повторно використовуючи наявний recovery key, коли це можливо
  • ініціалізує cross-signing і завантажує відсутні публічні ключі cross-signing
  • намагається позначити й підписати поточний пристрій через cross-signing
  • створює нову серверну резервну копію ключів кімнат, якщо її ще не існує
Якщо homeserver вимагає інтерактивної автентифікації для завантаження ключів cross-signing, OpenClaw спочатку пробує завантаження без автентифікації, потім із m.login.dummy, а потім із m.login.password, якщо налаштовано channels.matrix.password. Використовуйте --force-reset-cross-signing лише тоді, коли навмисно хочете відкинути поточну ідентичність cross-signing і створити нову. Якщо ви навмисно хочете відкинути поточну резервну копію ключів кімнат і почати нову базову лінію резервного копіювання для майбутніх повідомлень, використовуйте openclaw matrix verify backup reset --yes. Робіть це лише тоді, коли погоджуєтеся, що невідновлювана стара зашифрована історія залишиться недоступною і що OpenClaw може відтворити secret storage, якщо поточний секрет резервної копії не вдається безпечно завантажити.

​
Нова базова резервна копія

Якщо ви хочете зберегти працездатність майбутніх зашифрованих повідомлень і погоджуєтеся на втрату невідновлюваної старої історії, виконайте ці команди в такому порядку: 
openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status
Додайте --account <id> до кожної команди, якщо хочете явно націлитися на іменований обліковий запис Matrix.

​
Поведінка під час запуску

Коли encryption: true, Matrix за замовчуванням встановлює startupVerification у "if-unverified". Під час запуску, якщо цей пристрій усе ще не верифікований, Matrix запитує self-verification в іншому клієнті Matrix, пропускає дубльовані запити, якщо один уже очікує, і застосовує локальний cooldown перед повторною спробою після перезапусків. За замовчуванням після невдалих спроб запиту повтор виконується швидше, ніж після успішного створення запиту. Установіть startupVerification: "off", щоб вимкнути автоматичні запити під час запуску, або налаштуйте startupVerificationCooldownHours, якщо вам потрібне коротше або довше вікно повторних спроб. Під час запуску також автоматично виконується консервативний прохід bootstrap для crypto. Цей прохід спочатку намагається повторно використати поточні secret storage та ідентичність cross-signing і уникає скидання cross-signing, якщо ви не запускаєте явний сценарій відновлення bootstrap. Якщо під час запуску виявлено зламаний стан bootstrap і налаштовано channels.matrix.password, OpenClaw може спробувати суворіший шлях відновлення. Якщо поточний пристрій уже підписаний власником, OpenClaw зберігає цю ідентичність замість автоматичного скидання. Оновлення з попереднього публічного плагіна Matrix:
  • OpenClaw автоматично повторно використовує той самий обліковий запис Matrix, токен доступу та ідентичність пристрою, коли це можливо.
  • Перш ніж виконуються будь-які дієві зміни міграції Matrix, OpenClaw створює або повторно використовує recovery snapshot у ~/Backups/openclaw-migrations/.
  • Якщо ви використовуєте кілька облікових записів Matrix, установіть channels.matrix.defaultAccount перед оновленням зі старого плоского сховища, щоб OpenClaw знав, який обліковий запис має отримати цей спільний застарілий стан.
  • Якщо попередній плагін зберігав локально ключ розшифрування резервної копії ключів кімнат Matrix, запуск або openclaw doctor --fix автоматично імпортує його в новий потік recovery key.
  • Якщо токен доступу Matrix змінився після підготовки міграції, під час запуску тепер виконується сканування сусідніх коренів сховища хеша токена на наявність очікуваного стану відновлення старих даних, перш ніж автоматичне відновлення резервної копії буде припинено.
  • Якщо токен доступу зміниться пізніше для того самого облікового запису, homeserver і користувача, OpenClaw тепер надає перевагу повторному використанню найповнішого наявного кореня сховища хеша токена, замість початку з порожнього каталогу стану Matrix.
  • Під час наступного запуску gateway резервні ключі кімнат автоматично відновлюються в нове crypto store.
  • Якщо старий плагін мав лише локальні ключі кімнат, які ніколи не резервувалися, OpenClaw чітко попередить про це. Ці ключі не можна автоматично експортувати з попереднього rust crypto store, тому частина старої зашифрованої історії може залишатися недоступною, доки її не буде відновлено вручну.
  • Повний процес оновлення, обмеження, команди відновлення та типові повідомлення міграції див. у Matrix migration.
Стан зашифрованого runtime організовано в коренях на основі хеша токена для кожного облікового запису та користувача в ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/. Цей каталог містить sync store (bot-storage.json), crypto store (crypto/), файл recovery key (recovery-key.json), snapshot IndexedDB (crypto-idb-snapshot.json), прив’язки тредів (thread-bindings.json) і стан верифікації під час запуску (startup-verification.json), коли ці можливості використовуються. Коли токен змінюється, але ідентичність облікового запису залишається тією самою, OpenClaw повторно використовує найкращий наявний корінь для цього кортежу обліковий запис/homeserver/користувач, щоб попередній sync state, crypto state, прив’язки тредів і стан верифікації під час запуску залишалися видимими.

​
Модель Node crypto store

Matrix E2EE у цьому плагіні використовує офіційний шлях Rust crypto з matrix-js-sdk у Node. Цей шлях очікує persistence на основі IndexedDB, якщо ви хочете, щоб crypto state зберігався після перезапусків. Наразі OpenClaw забезпечує це в Node так:
  • використовуючи fake-indexeddb як API shim IndexedDB, який очікує SDK
  • відновлюючи вміст Rust crypto IndexedDB з crypto-idb-snapshot.json перед initRustCrypto
  • зберігаючи оновлений вміст IndexedDB назад у crypto-idb-snapshot.json після ініціалізації та під час runtime
  • серіалізуючи відновлення та збереження snapshot відносно crypto-idb-snapshot.json за допомогою advisory file lock, щоб persistence під час виконання gateway і обслуговування CLI не змагалися за той самий файл snapshot
Це plumbing сумісності/сховища, а не власна криптографічна реалізація. Файл snapshot є чутливим runtime state і зберігається з обмежувальними правами доступу до файлу. У межах моделі безпеки OpenClaw хост gateway і локальний каталог стану OpenClaw уже перебувають усередині довіреної межі оператора, тому це насамперед питання експлуатаційної надійності, а не окрема межа віддаленої довіри. Заплановане покращення:
  • додати підтримку SecretRef для постійного матеріалу ключів Matrix, щоб recovery keys і пов’язані секрети шифрування сховища можна було брати з постачальників секретів OpenClaw, а не лише з локальних файлів

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

Оновіть self-profile Matrix для вибраного облікового запису за допомогою: 
openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png
Додайте --account <id>, якщо хочете явно націлитися на іменований обліковий запис Matrix. Matrix напряму приймає URL аватара mxc://. Якщо ви передаєте URL аватара http:// або https://, OpenClaw спочатку завантажує його в Matrix, а потім зберігає розпізнаний URL mxc:// назад у channels.matrix.avatarUrl (або в перевизначення вибраного облікового запису).

​
Автоматичні сповіщення про верифікацію

Тепер Matrix публікує сповіщення про життєвий цикл верифікації безпосередньо в суворій DM-кімнаті верифікації як повідомлення m.notice. Це включає:
  • сповіщення про запит верифікації
  • сповіщення про готовність до верифікації (з явною підказкою “Verify by emoji”)
  • сповіщення про початок і завершення верифікації
  • дані SAS (emoji і десяткові значення), коли вони доступні
Вхідні запити на верифікацію від іншого клієнта Matrix відстежуються й автоматично приймаються OpenClaw. Для потоків self-verification OpenClaw також автоматично запускає SAS-процес, коли стає доступною верифікація за emoji, і підтверджує свій бік. Для запитів на верифікацію від іншого користувача/пристрою Matrix OpenClaw автоматично приймає запит, а потім чекає, поки SAS-процес продовжиться звичайним способом. Вам усе одно потрібно порівняти emoji або десятковий SAS у своєму клієнті Matrix і підтвердити “They match” там, щоб завершити верифікацію. OpenClaw не приймає наосліп дубльовані self-initiated потоки автоматично. Під час запуску пропускається створення нового запиту, якщо запит self-verification уже очікує. Повідомлення системи/протоколу верифікації не пересилаються в конвеєр чату агента, тому вони не створюють NO_REPLY.

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

Старі пристрої Matrix, якими керував OpenClaw, можуть накопичуватися в обліковому записі й ускладнювати розуміння довіри в зашифрованих кімнатах. Переглянути їх можна так: 
openclaw matrix devices list
Видалити застарілі пристрої Matrix, якими керував OpenClaw: 
openclaw matrix devices prune-stale

​
Відновлення Direct Room

Якщо стан direct-message виходить із синхронізації, OpenClaw може отримати застарілі зіставлення m.direct, які вказують на старі окремі кімнати замість активного DM. Перегляньте поточне зіставлення для співрозмовника за допомогою: 
openclaw matrix direct inspect --user-id @alice:example.org
Відновіть його так: 
openclaw matrix direct repair --user-id @alice:example.org
Відновлення зберігає логіку, специфічну для Matrix, усередині плагіна:
  • воно надає перевагу суворому 1:1 DM, який уже відображено в m.direct
  • інакше воно переходить до будь-якого поточного приєднаного суворого 1:1 DM із цим користувачем
  • якщо здорового DM не існує, воно створює нову direct room і переписує m.direct, щоб вона вказувала на неї
Потік відновлення не видаляє старі кімнати автоматично. Він лише вибирає здоровий DM і оновлює зіставлення, щоб нові надсилання Matrix, сповіщення верифікації та інші потоки direct-message знову націлювалися на правильну кімнату.

​
Треди

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

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

Кімнати Matrix, DM та наявні треди Matrix можна перетворювати на довговічні робочі простори ACP без зміни поверхні чату. Швидкий робочий потік оператора:
  • Виконайте /acp spawn codex --bind here у DM Matrix, кімнаті або наявному треді, який ви хочете й надалі використовувати.
  • У верхньорівневому DM Matrix або кімнаті поточний DM/кімната залишається поверхнею чату, а майбутні повідомлення маршрутизуються до створеної ACP-сесії.
  • Усередині наявного треду Matrix --bind here прив’язує цей поточний тред на місці.
  • /new і /reset скидають ту саму прив’язану ACP-сесію на місці.
  • /acp close закриває ACP-сесію та видаляє прив’язку.
Примітки:
  • --bind here не створює дочірній тред Matrix.
  • threadBindings.spawnAcpSessions потрібен лише для /acp spawn --thread auto|here, коли OpenClaw має створити або прив’язати дочірній тред Matrix.

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

Matrix успадковує глобальні значення за замовчуванням із session.threadBindings, а також підтримує перевизначення для конкретного каналу:
  • threadBindings.enabled
  • threadBindings.idleHours
  • threadBindings.maxAgeHours
  • threadBindings.spawnSubagentSessions
  • threadBindings.spawnAcpSessions
Прапорці створення з прив’язкою до треду для Matrix вмикаються за бажанням:
  • Установіть threadBindings.spawnSubagentSessions: true, щоб дозволити верхньорівневому /focus створювати й прив’язувати нові треди Matrix.
  • Установіть threadBindings.spawnAcpSessions: true, щоб дозволити /acp spawn --thread auto|here прив’язувати ACP-сесії до тредів Matrix.

​
Реакції

Matrix підтримує вихідні дії реакцій, вхідні сповіщення про реакції та вхідні реакції-підтвердження.
  • Інструменти вихідних реакцій контролюються через channels["matrix"].actions.reactions.
  • react додає реакцію до конкретної події Matrix.
  • reactions показує поточне зведення реакцій для конкретної події Matrix.
  • emoji="" видаляє власні реакції облікового запису бота на цій події.
  • remove: true видаляє лише вказану реакцію emoji з облікового запису бота.
Область реакцій-підтверджень визначається у стандартному порядку OpenClaw:
  • channels["matrix"].accounts.<accountId>.ackReaction
  • channels["matrix"].ackReaction
  • messages.ackReaction
  • резервне emoji ідентичності агента
Область дії реакції-підтвердження визначається в такому порядку:
  • channels["matrix"].accounts.<accountId>.ackReactionScope
  • channels["matrix"].ackReactionScope
  • messages.ackReactionScope
Режим сповіщень про реакції визначається в такому порядку:
  • channels["matrix"].accounts.<accountId>.reactionNotifications
  • channels["matrix"].reactionNotifications
  • значення за замовчуванням: own
Поточна поведінка:
  • reactionNotifications: "own" пересилає додані події m.reaction, коли вони націлені на повідомлення Matrix, створені ботом.
  • reactionNotifications: "off" вимикає системні події реакцій.
  • Видалення реакцій усе ще не синтезуються в системні події, тому що Matrix показує їх як redaction, а не як окремі видалення m.reaction.

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

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

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

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

​
Приклад політики для DM і кімнат

{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
        threadReplies: "off",
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}
Див. Groups щодо поведінки згадок і allowlist. Приклад pairing для Matrix DM: 
openclaw pairing list matrix
openclaw pairing approve matrix <CODE>
Якщо непідтверджений користувач Matrix продовжує писати вам до схвалення, OpenClaw повторно використовує той самий очікуваний код pairing і може знову надіслати відповідь-нагадування після короткого cooldown замість створення нового коду. Див. Pairing щодо спільного потоку pairing для DM і структури сховища.

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

Matrix може виступати клієнтом підтвердження exec для облікового запису Matrix.
  • channels.matrix.execApprovals.enabled
  • channels.matrix.execApprovals.approvers (необов’язково; використовується fallback на channels.matrix.dm.allowFrom)
  • channels.matrix.execApprovals.target (dm | channel | both, за замовчуванням: dm)
  • channels.matrix.execApprovals.agentFilter
  • channels.matrix.execApprovals.sessionFilter
Особи, що підтверджують, мають бути Matrix user ID, наприклад @owner:example.org. Matrix автоматично вмикає нативні підтвердження exec, коли enabled не задано або дорівнює "auto", і принаймні одного approver можна визначити або з execApprovals.approvers, або з channels.matrix.dm.allowFrom. Установіть enabled: false, щоб явно вимкнути Matrix як нативний клієнт підтвердження. Інакше запити на підтвердження використовують fallback на інші налаштовані маршрути підтвердження або політику fallback для підтверджень exec. Нативна маршрутизація Matrix наразі стосується лише exec:
  • channels.matrix.execApprovals.* керує нативною маршрутизацією DM/каналу лише для підтверджень exec.
  • Підтвердження плагінів і далі використовують спільний /approve у тому самому чаті плюс будь-яке налаштоване пересилання approvals.plugin.
  • Matrix усе ще може повторно використовувати channels.matrix.dm.allowFrom для авторизації підтвердження плагінів, коли може безпечно визначити approvers, але не надає окремий нативний шлях fanout DM/каналу для підтверджень плагінів.
Правила доставлення:
  • target: "dm" надсилає запити на підтвердження в DM approver’ів
  • target: "channel" надсилає запит назад у вихідну кімнату або DM Matrix
  • target: "both" надсилає в DM approver’ів і у вихідну кімнату або DM Matrix
Підказки підтвердження Matrix ініціалізують ярлики реакцій у первинному повідомленні підтвердження:
  • ✅ = дозволити один раз
  • ❌ = відхилити
  • ♾️ = дозволити завжди, коли таке рішення дозволено ефективною політикою exec
Approver’и можуть реагувати на це повідомлення або використовувати резервні slash-команди: /approve <id> allow-once, /approve <id> allow-always або /approve <id> deny. Лише визначені approver’и можуть підтверджувати або відхиляти. Доставлення в канал включає текст команди, тому вмикайте channel або both лише в довірених кімнатах. Підказки підтвердження Matrix повторно використовують спільний core approval planner. Нативна поверхня, специфічна для Matrix, є лише транспортом для підтверджень exec: маршрутизація кімната/DM і поведінка надсилання/оновлення/видалення повідомлень. Перевизначення для облікового запису:
  • channels.matrix.accounts.<account>.execApprovals
Пов’язана документація: Exec approvals

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

{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
          dm: {
            policy: "allowlist",
            allowFrom: ["@ops:example.org"],
            threadReplies: "off",
          },
        },
      },
    },
  },
}
Значення верхнього рівня channels.matrix діють як значення за замовчуванням для іменованих облікових записів, якщо обліковий запис не перевизначає їх. Ви можете обмежити успадкований запис кімнати одним обліковим записом Matrix за допомогою groups.<room>.account (або застарілого rooms.<room>.account). Записи без account залишаються спільними для всіх облікових записів Matrix, а записи з account: "default" усе ще працюють, коли обліковий запис за замовчуванням налаштовано безпосередньо на верхньому рівні channels.matrix.*. Часткові спільні значення автентифікації за замовчуванням самі по собі не створюють окремий неявний обліковий запис за замовчуванням. OpenClaw синтезує верхньорівневий обліковий запис default лише тоді, коли цей обліковий запис за замовчуванням має актуальну автентифікацію (homeserver плюс accessToken або homeserver плюс userId і password); іменовані облікові записи все ще можуть залишатися виявлюваними через homeserver плюс userId, якщо кешовані облікові дані пізніше задовольнять автентифікацію. Якщо в Matrix уже є рівно один іменований обліковий запис або defaultAccount вказує на наявний ключ іменованого облікового запису, відновлення/налаштування з переходом від одного облікового запису до кількох зберігає цей обліковий запис замість створення нового запису accounts.default. Лише ключі автентифікації/bootstrap Matrix переносяться до цього підвищеного облікового запису; спільні ключі політики доставлення залишаються на верхньому рівні. Установіть defaultAccount, якщо хочете, щоб OpenClaw надавав перевагу одному іменованому обліковому запису Matrix для неявної маршрутизації, probe і операцій CLI. Якщо ви налаштували кілька іменованих облікових записів, установіть defaultAccount або передавайте --account <id> для команд CLI, які покладаються на неявний вибір облікового запису. Передавайте --account <id> до openclaw matrix verify ... і openclaw matrix devices ..., якщо хочете перевизначити цей неявний вибір для однієї команди.

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

За замовчуванням OpenClaw блокує приватні/внутрішні homeserver Matrix для захисту від SSRF, якщо ви явно не дозволите це для кожного облікового запису. Якщо ваш homeserver працює на localhost, LAN/Tailscale IP або внутрішньому hostname, увімкніть allowPrivateNetwork для цього облікового запису Matrix: 
{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      allowPrivateNetwork: 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
Це явне ввімкнення дозволяє лише довірені приватні/внутрішні цілі. Публічні незашифровані homeserver, наприклад http://matrix.example.org:8008, і далі блокуються. За можливості надавайте перевагу https://.

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

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

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

Matrix приймає такі форми цілей усюди, де OpenClaw просить вас вказати ціль кімнати або користувача:
  • Користувачі: @user:server, user:@user:server або matrix:user:@user:server
  • Кімнати: !room:server, room:!room:server або matrix:room:!room:server
  • Аліаси: #alias:server, channel:#alias:server або matrix:channel:#alias:server
Живий пошук у директорії використовує обліковий запис Matrix, під яким виконано вхід:
  • Пошук користувачів звертається до директорії користувачів Matrix на цьому homeserver.
  • Пошук кімнат напряму приймає явні ID кімнат і аліаси, а потім використовує fallback до пошуку назв приєднаних кімнат для цього облікового запису.
  • Пошук за назвою приєднаної кімнати виконується за принципом best-effort. Якщо назву кімнати не вдається зіставити з ID або аліасом, під час виконання її буде проігноровано в allowlist.

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

  • enabled: увімкнути або вимкнути канал.
  • name: необов’язкова мітка для облікового запису.
  • defaultAccount: бажаний ID облікового запису, коли налаштовано кілька облікових записів Matrix.
  • homeserver: URL homeserver, наприклад https://matrix.example.org.
  • allowPrivateNetwork: дозволити цьому обліковому запису Matrix підключатися до приватних/внутрішніх homeserver. Увімкніть це, якщо homeserver визначається як localhost, LAN/Tailscale IP або внутрішній хост, наприклад matrix-synapse.
  • proxy: необов’язковий URL HTTP(S) proxy для трафіку Matrix. Іменовані облікові записи можуть перевизначити значення верхнього рівня за замовчуванням власним proxy.
  • userId: повний Matrix user ID, наприклад @bot:example.org.
  • accessToken: токен доступу для автентифікації на основі токена. Для channels.matrix.accessToken і channels.matrix.accounts.<id>.accessToken підтримуються як відкриті значення, так і значення SecretRef у постачальниках env/file/exec. Див. Secrets Management.
  • password: пароль для входу на основі пароля. Підтримуються відкриті значення та значення SecretRef.
  • deviceId: явний Matrix device ID.
  • deviceName: відображувана назва пристрою для входу за паролем.
  • avatarUrl: збережений self-avatar URL для синхронізації профілю та оновлень set-profile.
  • initialSyncLimit: ліміт подій синхронізації під час запуску.
  • encryption: увімкнути E2EE.
  • allowlistOnly: примусово використовувати лише поведінку allowlist для DM і кімнат.
  • allowBots: дозволити повідомлення від інших налаштованих облікових записів Matrix OpenClaw (true або "mentions").
  • groupPolicy: open, allowlist або disabled.
  • contextVisibility: режим видимості додаткового контексту кімнати (all, allowlist, allowlist_quote).
  • groupAllowFrom: allowlist user ID для трафіку кімнат.
  • Записи groupAllowFrom мають бути повними Matrix user ID. Нерозпізнані імена ігноруються під час виконання.
  • historyLimit: максимальна кількість повідомлень кімнати, що включаються як контекст історії групи. Використовує fallback на messages.groupChat.historyLimit. Установіть 0, щоб вимкнути.
  • replyToMode: off, first або all.
  • markdown: необов’язкова конфігурація рендерингу Markdown для вихідного тексту Matrix.
  • streaming: off (за замовчуванням), partial, true або false. partial і true вмикають попередній перегляд чернетки одним повідомленням з оновленнями редагування на місці.
  • blockStreaming: true вмикає окремі повідомлення прогресу для завершених блоків помічника, поки активне потокове передавання чернетки попереднього перегляду.
  • threadReplies: off, inbound або always.
  • threadBindings: перевизначення для конкретного каналу для маршрутизації та життєвого циклу сесій, прив’язаних до тредів.
  • startupVerification: режим автоматичного запиту self-verification під час запуску (if-unverified, off).
  • startupVerificationCooldownHours: cooldown перед повторними спробами автоматичних запитів верифікації під час запуску.
  • textChunkLimit: розмір фрагмента вихідного повідомлення.
  • chunkMode: length або newline.
  • responsePrefix: необов’язковий префікс повідомлення для вихідних відповідей.
  • ackReaction: необов’язкове перевизначення реакції-підтвердження для цього каналу/облікового запису.
  • ackReactionScope: необов’язкове перевизначення області реакції-підтвердження (group-mentions, group-all, direct, all, none, off).
  • reactionNotifications: режим вхідних сповіщень про реакції (own, off).
  • mediaMaxMb: обмеження розміру медіа в MB для обробки медіа Matrix. Застосовується до вихідного надсилання та обробки вхідних медіа.
  • autoJoin: політика автоматичного приєднання за запрошенням (always, allowlist, off). За замовчуванням: off.
  • autoJoinAllowlist: кімнати/аліаси, дозволені, коли autoJoin має значення allowlist. Записи аліасів під час обробки запрошення перетворюються на ID кімнат; OpenClaw не довіряє стану аліаса, заявленому запрошеною кімнатою.
  • dm: блок політики DM (enabled, policy, allowFrom, sessionScope, threadReplies).
  • Записи dm.allowFrom мають бути повними Matrix user ID, якщо тільки ви вже не розпізнали їх через живий пошук у директорії.
  • dm.sessionScope: per-user (за замовчуванням) або per-room. Використовуйте per-room, якщо хочете, щоб кожна Matrix DM-кімната зберігала окремий контекст, навіть якщо співрозмовник той самий.
  • dm.threadReplies: перевизначення політики тредів лише для DM (off, inbound, always). Воно перевизначає параметр верхнього рівня threadReplies як для розміщення відповіді, так і для ізоляції сесії в DM.
  • execApprovals: нативне доставлення підтверджень exec для Matrix (enabled, approvers, target, agentFilter, sessionFilter).
  • execApprovals.approvers: Matrix user ID, яким дозволено підтверджувати exec-запити. Необов’язково, якщо approver’ів уже визначає dm.allowFrom.
  • execApprovals.target: dm | channel | both (за замовчуванням: dm).
  • accounts: іменовані перевизначення для кожного облікового запису. Значення верхнього рівня channels.matrix діють як значення за замовчуванням для цих записів.
  • groups: карта політик для кожної кімнати. Надавайте перевагу ID кімнат або аліасам; нерозпізнані назви кімнат під час виконання ігноруються. Ідентичність сесії/групи після розпізнавання використовує стабільний ID кімнати, тоді як людиночитані мітки й надалі походять із назв кімнат.
  • groups.<room>.account: обмежити один успадкований запис кімнати конкретним обліковим записом Matrix у конфігураціях із кількома обліковими записами.
  • groups.<room>.allowBots: перевизначення на рівні кімнати для відправників із налаштованих ботів (true або "mentions").
  • groups.<room>.users: allowlist відправників для конкретної кімнати.
  • groups.<room>.tools: перевизначення allow/deny інструментів для конкретної кімнати.
  • groups.<room>.autoReply: перевизначення вимоги згадки на рівні кімнати. true вимикає вимоги щодо згадки для цієї кімнати; false знову примусово вмикає їх.
  • groups.<room>.skills: необов’язковий фільтр Skills на рівні кімнати.
  • groups.<room>.systemPrompt: необов’язковий фрагмент system prompt на рівні кімнати.
  • rooms: застарілий аліас для groups.
  • actions: керування інструментами для конкретних дій (messages, reactions, pins, profile, memberInfo, channelInfo, verification).

​
Пов’язане

  • Channels Overview — усі підтримувані канали
  • Pairing — автентифікація DM і потік pairing
  • Groups — поведінка групового чату та керування згадками
  • Channel Routing — маршрутизація сесій для повідомлень
  • Security — модель доступу та посилення безпеки