Матриця

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

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

Встановіть Matrix із ClawHub перед налаштуванням каналу:

openclaw plugins install @openclaw/matrix

Голі специфікації плагінів спершу пробують ClawHub, а потім fallback до npm. Щоб примусово вибрати джерело реєстру, використайте openclaw plugins install clawhub:@openclaw/matrix або openclaw plugins install npm:@openclaw/matrix.

З локального checkout:

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

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

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

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

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

openclaw channels addopenclaw configure --section channels

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

Якщо відповідні env-змінні MATRIX_* уже існують, а вибраний обліковий запис не має збереженої автентифікації, майстер пропонує shortcut через env-var. Щоб розв’язати назви кімнат перед збереженням allowlist, запустіть openclaw channels resolve --channel matrix "Project Room". Коли E2EE увімкнено, майстер записує конфігурацію та запускає той самий bootstrap, що й openclaw matrix encryption setup.

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

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

{  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. Із типовим значенням бот не з’являтиметься в нових кімнатах або DM із нових запрошень, доки ви не приєднаєте його вручну.

OpenClaw не може визначити під час запрошення, чи запрошена кімната є DM або групою, тому всі запрошення - включно із запрошеннями в стилі DM - спершу проходять через autoJoin. dm.policy застосовується лише пізніше, після того як бот приєднався і кімнату класифіковано.

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

Щоб приймати кожне запрошення, використовуйте autoJoin: "always".

Формати цілей allowlist

Allowlist для DM і кімнат найкраще заповнювати стабільними ID:

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

Нормалізація ID облікового запису

Майстер перетворює дружню назву на нормалізований ID облікового запису. Наприклад, Ops Bot стає ops-bot. Розділові знаки екрануються в scoped env-var names, щоб два облікові записи не могли зіткнутися: - → _X2D_, тому ops-prod відображається на MATRIX_OPS_X2D_PROD_*.

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

Matrix зберігає кешовані облікові дані в ~/.openclaw/credentials/matrix/:

• типовий обліковий запис: credentials.json
• іменовані облікові записи: credentials-<account>.json

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

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

Використовуються, коли еквівалентний ключ конфігурації не задано. Типовий обліковий запис використовує назви без префікса; іменовані облікові записи використовують ID облікового запису, вставлений перед суфіксом.

Для облікового запису ops назви стають MATRIX_OPS_HOMESERVER, MATRIX_OPS_ACCESS_TOKEN тощо. Env-vars ключа відновлення читаються CLI-потоками, що підтримують відновлення (verify backup restore, verify device, verify bootstrap), коли ви передаєте ключ через --recovery-key-stdin.

MATRIX_HOMESERVER не можна задати з workspace .env; дивіться Workspace .env files.

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

Практична базова конфігурація з паруванням 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",    },  },}

Попередні перегляди streaming

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

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

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

{  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: максимальна кількість rolling progress lines, що зберігаються в чернетці. Після цього ліміту старіші рядки обрізаються.
• progress.maxLineChars: максимальна кількість символів у компактному рядку прогресу перед усіченням.
• progress.toolProgress: коли true (за замовчуванням), live-активність інструментів/прогресу з’являється в чернетці.

blockStreaming не залежить від streaming:

Примітки:

• Якщо preview перевищує per-event size limit Matrix, OpenClaw зупиняє preview streaming і повертається до доставки лише фінального повідомлення.
• Медіавідповіді завжди надсилають вкладення звичайним способом. Якщо застарілий preview більше не можна безпечно використати повторно, OpenClaw редагує його перед надсиланням фінальної медіавідповіді.
• Оновлення preview прогресу інструментів увімкнені за замовчуванням, коли активний Matrix preview streaming. Задайте streaming.preview.toolProgress: false, щоб залишити preview edits для тексту відповіді, але перенести прогрес інструментів на звичайний шлях доставки.
• Preview edits коштують додаткових викликів Matrix API. Залиште streaming: "off", якщо хочете найконсервативніший профіль rate-limit.

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

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

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

Деталі поведінки:

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

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

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

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

Self-hosted push-правила для тихих фіналізованих прев’ю

streaming: "quiet" сповіщає одержувачів лише після фіналізації блока або ходу - push-правило для кожного користувача має збігатися з маркером фіналізованого прев’ю. Повний рецепт дивіться в push-правилах Matrix для тихих прев’ю (токен одержувача, перевірка pusher, установлення правила, примітки для кожного homeserver).

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

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

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

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

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

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

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

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

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

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

openclaw matrix encryption setup

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

• --recovery-key <key> застосувати ключ відновлення перед ініціалізацією (надавайте перевагу формі через stdin, задокументованій нижче)
• --force-reset-cross-signing відкинути поточну ідентичність 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 повідомляє про верифікацію через cross-signing
• Signed by owner: підписано вашим власним ключем самопідписування (лише діагностика)

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

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

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

Ключ відновлення чутливий - передавайте його через stdin замість передавання в командному рядку. Установіть MATRIX_RECOVERY_KEY (або MATRIX_<ID>_RECOVERY_KEY для іменованого облікового запису):

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

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

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

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

openclaw matrix verify self

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

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

Ініціалізація або відновлення cross-signing

openclaw matrix verify bootstrap

verify bootstrap — це команда відновлення й налаштування для зашифрованих облікових записів. По черзі вона:

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

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

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

• --recovery-key-stdin (поєднуйте з printf '%s\n' "$MATRIX_RECOVERY_KEY" | …) або --recovery-key <key>
• --force-reset-cross-signing, щоб відкинути поточну ідентичність 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

Надсилає запит верифікації з цього облікового запису OpenClaw. --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 як підказки подальшого DM, коли верифікація прив’язана до конкретної кімнати прямих повідомлень.

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

Без --account <id> команди Matrix CLI використовують неявний типовий обліковий запис. Якщо у вас кілька іменованих облікових записів і ви не встановили 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

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

Оновіть Matrix self-profile для вибраного облікового запису:

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

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

Потоки

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

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

dm.sessionScope визначає, як Matrix DM-кімнати зіставляються із сесіями OpenClaw:

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

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

Відповіді в потоках (threadReplies)

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

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

dm.threadReplies перевизначає це лише для DM - наприклад, щоб ізолювати потоки кімнат, але лишити DM пласкими.

Успадкування потоків і slash-команди

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

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

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

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

Швидкий операторський потік:

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

Примітки:

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

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

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

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions
• threadBindings.defaultSpawnContext

Створення Matrix-сесій, прив’язаних до потоків, типово увімкнене:

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

Реакції

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

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

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

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

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

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

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

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

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

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

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

Політика DM і кімнат

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

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

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

Див. Групи щодо поведінки mention-gating і allowlist.

Приклад спарювання для Matrix DM:

openclaw pairing list matrixopenclaw pairing approve matrix <CODE>

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

Див. Спарювання щодо спільного потоку спарювання DM і структури сховища.

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

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

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

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

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

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

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

Він не видаляє старі кімнати автоматично. Він вибирає справний DM і оновлює зіставлення, щоб майбутні Matrix-надсилання, сповіщення перевірки та інші потоки direct-message були спрямовані в правильну кімнату.

Схвалення exec

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

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

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

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

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

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

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

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

Пов’язано: Exec-схвалення.

Slash-команди

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

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

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

{  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 homeserver-и

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

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

{  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

Це явне ввімкнення дозволяє лише довірені приватні/внутрішні цілі. Публічні homeserver-и без шифрування, як-от 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

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

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

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

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

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

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

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

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

Шифрування

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

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

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

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

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

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

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

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

• actions: обмеження інструментів для кожної дії (messages, reactions, pins, profile, memberInfo, channelInfo, verification).
• groups: мапа політик для кожної кімнати. Ідентичність сесії використовує стабільний ID кімнати після розв’язання. (rooms — застарілий псевдонім.)
  • groups.<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: фрагмент системного промпта для окремої кімнати.

Налаштування схвалення exec

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

Пов’язане

• Огляд каналів - усі підтримувані канали
• Пов’язування - автентифікація DM і потік пов’язування
• Групи - поведінка групового чату та керування згадками
• Маршрутизація каналів - маршрутизація сесій для повідомлень
• Безпека - модель доступу та посилення захисту