Matrix

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

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

openclaw plugins install @openclaw/matrix

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

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

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

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

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

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

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

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

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

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

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

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

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

Примітки:

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

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

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

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

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

streaming: "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 setup

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

• --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-сервери Matrix

За замовчуванням 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 від постачальників env/file/exec (Керування секретами).
• password: пароль для входу за паролем. Підтримуються значення у відкритому тексті та SecretRef.
• deviceId: явний ідентифікатор пристрою Matrix.
• deviceName: відображуване ім’я пристрою, що використовується під час входу за паролем.
• avatarUrl: збережена URL-адреса власного аватара для синхронізації профілю й оновлень profile set.
• initialSyncLimit: максимальна кількість подій, отриманих під час початкової синхронізації.

Шифрування

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

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

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

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

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

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

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

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

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

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

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

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

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