Matrix

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

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

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

openclaw plugins install @openclaw/matrix

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

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

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

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

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

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

openclaw channels add
openclaw configure --section channels

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

Якщо відповідні env vars MATRIX_* уже існують, а вибраний обліковий запис не має збереженої автентифікації, майстер пропонує скорочення через 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. Із типовим значенням бот не з’являтиметься в нових кімнатах або особистих повідомленнях із нових запрошень, доки ви не приєднаєтеся вручну.

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

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

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

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

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

• Особисті повідомлення (dm.allowFrom, groupAllowFrom, groups.<room>.users): використовуйте @user:server. Відображувані імена розпізнаються лише тоді, коли каталог homeserver повертає рівно один збіг.
• Кімнати (groups, autoJoinAllowlist): використовуйте !room:server або #alias:server. Назви розпізнаються best-effort серед кімнат, до яких уже приєднанося; нерозпізнані записи ігноруються під час виконання.

# Нормалізація 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 налаштованим, навіть якщо токена доступу немає у файлі конфігурації - це охоплює налаштування, openclaw doctor і перевірки статусу каналу.

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

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

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

MATRIX_HOMESERVER не можна задати з workspace .env; див. файли workspace .env.

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

Практична базова конфігурація з pairing для особистих повідомлень, 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 увімкнені лише за явним вибором. streaming керує тим, як OpenClaw доставляє поточну відповідь асистента; blockStreaming керує тим, чи кожен завершений блок зберігається як окреме повідомлення Matrix.

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

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

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

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

Примітки:

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

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

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

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

# Самостійно розміщені push rules для тихих фіналізованих попередніх переглядів

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

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

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

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

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

• allowBots: true приймає повідомлення від інших налаштованих облікових записів ботів Matrix у дозволених кімнатах і особистих повідомленнях.
• allowBots: "mentions" приймає такі повідомлення лише тоді, коли вони помітно згадують цього бота в кімнатах. Особисті повідомлення все ще дозволені.
• groups.<room>.allowBots перевизначає налаштування рівня облікового запису для однієї кімнати.
• OpenClaw усе ще ігнорує повідомлення від того самого ID користувача Matrix, щоб уникнути циклів самовідповідей.
• Matrix не надає тут нативного прапорця бота; OpenClaw трактує "bot-authored" як "надіслано іншим налаштованим обліковим записом Matrix на цьому OpenClaw gateway".

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

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

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

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

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

openclaw matrix encryption setup

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

• --recovery-key <key> застосувати ключ відновлення перед завантаженням (надавайте перевагу формі через stdin, описаній нижче)
• --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 status
openclaw 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; корисно для офлайн-перевірок або частково налаштованих перевірок.

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

Ключ відновлення є чутливим - передавайте його через 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.

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

openclaw matrix verify self

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

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

# Завантаження або відновлення перехресного підписування

openclaw matrix verify bootstrap

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

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

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

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

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

openclaw matrix verify backup reset --yes

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

# Перелік, запит і відповідь на перевірки

openclaw matrix verify list

Показує очікувані запити на перевірку для вибраного облікового запису.

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

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

Для нижчорівневої обробки життєвого циклу - зазвичай під час відстеження вхідних запитів з іншого клієнта - ці команди діють на конкретний запит <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 list
openclaw matrix devices prune-stale

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

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

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 як для автоматичних відповідей, так і для надсилань через message-tool. Дві незалежні ручки керують поведінкою:

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

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

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

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

# Потокові відповіді (threadReplies)

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

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

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

# Наслідування потоків і slash commands

• Вхідні повідомлення в тредах містять кореневе повідомлення треду як додатковий контекст агента.
• Надсилання через інструмент повідомлень автоматично успадковують поточний тред 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 виявляє, що кімната DM Matrix конфліктує з іншою кімнатою 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 видаляє лише вказану реакцію емодзі від бота.

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

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" фільтрує додатковий контекст до відправників, дозволених активними перевірками списку дозволених кімнати/користувача.
• 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"],
    },
  },
}

Див. Групи щодо поведінки шлюзу згадок і списку дозволених.

Приклад сполучення для Matrix DM:

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

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

Див. Сполучення щодо спільного потоку сполучення DM і структури зберігання.

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

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

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

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

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

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

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

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

# Схвалення exec

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

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

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

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

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

• ✅ дозволити один раз
• ❌ відхилити
• ♾️ завжди дозволяти (коли ефективна політика 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 запускає шлях команди без користувацького регулярного виразу для згадок. Це зберігає чутливість бота до кімнатного стилю дописів @mention /command, які Element і подібні клієнти надсилають, коли користувач завершує ім’я бота клавішею Tab перед введенням команди.

Правила авторизації й далі застосовуються: відправники команд мають відповідати тим самим політикам списку дозволених/власника для 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 блокує приватні/внутрішні homeserver-и Matrix для захисту від 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

Це явне ввімкнення дозволяє лише довірені приватні/внутрішні цілі. Публічні незашифровані домашні сервери, такі як 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 чутливі до регістру. Використовуйте точний регістр ідентифікатора кімнати з Matrix під час налаштування явних цілей доставки, завдань cron, прив’язок або списків дозволених. OpenClaw зберігає внутрішні ключі сеансів у канонічному вигляді для сховища, тому ці ключі в нижньому регістрі не є надійним джерелом для ідентифікаторів доставки Matrix.

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

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

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

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

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

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

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

• groupPolicy: "open", "allowlist" або "disabled". Типово: "allowlist".
• groupAllowFrom: список дозволених ідентифікаторів користувачів для трафіку кімнат.
• dm.enabled: коли false, ігнорувати всі DM. Типово: true.
• dm.policy: "pairing" (типово), "allowlist", "open" або "disabled". Застосовується після того, як бот приєднався та класифікував кімнату як DM; не впливає на обробку запрошень.
• dm.allowFrom: список дозволених ідентифікаторів користувачів для трафіку DM.
• dm.sessionScope: "per-user" (типово) або "per-room".
• dm.threadReplies: перевизначення лише для DM для відповідей у гілках ("off", "inbound", "always").
• allowBots: приймати повідомлення від інших налаштованих облікових записів ботів Matrix (true або "mentions").
• allowlistOnly: коли true, примусово переводить усі активні політики DM (крім "disabled") і політики груп "open" у "allowlist". Не змінює політики "disabled".
• autoJoin: "always", "allowlist" або "off". Типово: "off". Застосовується до кожного запрошення Matrix, включно із запрошеннями у стилі DM.
• autoJoinAllowlist: кімнати/псевдоніми, дозволені, коли autoJoin дорівнює "allowlist". Записи псевдонімів визначаються відносно домашнього сервера, а не відносно стану, заявленого запрошеною кімнатою.
• contextVisibility: додаткова видимість контексту (типово "all", "allowlist", "allowlist_quote").

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

• replyToMode: "off", "first", "all" або "batched".
• threadReplies: "off", "inbound" або "always".
• threadBindings: перевизначення для окремих каналів для маршрутизації сеансів, прив’язаних до гілок, і життєвого циклу.
• streaming: "off" (типово), "partial", "quiet" або форма об’єкта { mode, preview: { 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: перевизначення реакції підтвердження для цього каналу/облікового запису.
• 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>.allowBots: перевизначення для окремої кімнати параметра рівня каналу (true або "mentions").
  • 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: ідентифікатори користувачів Matrix, яким дозволено схвалювати. Повертається до dm.allowFrom.
• execApprovals.target: "dm" (типово), "channel" або "both".
• execApprovals.agentFilter / execApprovals.sessionFilter: необов’язкові списки дозволених агентів/сеансів для доставки.

# Пов’язане

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