Matrix - OpenClaw

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

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

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

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

openclaw channels add
openclaw configure --section channels

Майстер запитує: URL homeserver, метод автентифікації (access token або password), ID користувача (лише для автентифікації паролем), необовʼязкову назву пристрою, чи ввімкнути E2EE, а також чи налаштувати доступ до кімнат і автоприєднання. Якщо відповідні env vars MATRIX_* уже існують, а вибраний обліковий запис не має збереженої автентифікації, майстер запропонує shortcut через env-var. Щоб розвʼязати назви кімнат перед збереженням allowlist, запустіть openclaw channels resolve --channel matrix "Project Room". Коли E2EE увімкнено, майстер записує config і запускає той самий 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 застосовується лише пізніше, після того як бот приєднався, а кімнату класифіковано.

Установіть autoJoin: "allowlist" плюс autoJoinAllowlist, щоб обмежити, які запрошення бот приймає, або autoJoin: "always", щоб приймати кожне запрошення.autoJoinAllowlist приймає лише стабільні цілі: !roomId:server, #alias:server або *. Звичайні назви кімнат відхиляються; записи alias розвʼязуються відносно homeserver, а не відносно стану, заявленого запрошеною кімнатою.

{
  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, застарілий rooms): використовуйте !room:server або #alias:server. Звичайні назви кімнат за замовчуванням ігноруються; установлюйте dangerouslyAllowNameMatching: true лише тоді, коли вам явно потрібна сумісність із пошуком назв приєднаних кімнат.
Allowlist запрошень (autoJoinAllowlist): використовуйте !room:server, #alias:server або *. Звичайні назви кімнат відхиляються.

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

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

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

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

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

Коли кешовані облікові дані там існують, OpenClaw вважає Matrix налаштованим, навіть якщо access token не в config-файлі - це покриває налаштування, openclaw doctor і channel-status probes.

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

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

Типовий обліковий запис	Іменований обліковий запис (`<ID>` є нормалізованим ID облікового запису)
`MATRIX_HOMESERVER`	`MATRIX_<ID>_HOMESERVER`
`MATRIX_ACCESS_TOKEN`	`MATRIX_<ID>_ACCESS_TOKEN`
`MATRIX_USER_ID`	`MATRIX_<ID>_USER_ID`
`MATRIX_PASSWORD`	`MATRIX_<ID>_PASSWORD`
`MATRIX_DEVICE_ID`	`MATRIX_<ID>_DEVICE_ID`
`MATRIX_DEVICE_NAME`	`MATRIX_<ID>_DEVICE_NAME`
`MATRIX_RECOVERY_KEY`	`MATRIX_<ID>_RECOVERY_KEY`

Для облікового запису ops імена стають MATRIX_OPS_HOMESERVER, MATRIX_OPS_ACCESS_TOKEN тощо. Recovery-key env vars читаються recovery-aware CLI flows (verify backup restore, verify device, verify bootstrap), коли ви передаєте ключ через pipe за допомогою --recovery-key-stdin. MATRIX_HOMESERVER не можна встановити з workspace .env; див. Workspace .env файли.

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

Практична базова конфігурація з pairing для DM, allowlist кімнат і E2EE:

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

      dm: {
        policy: "pairing",
        sessionScope: "per-room",
        threadReplies: "off",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": { requireMention: true },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
      streaming: "partial",
    },
  },
}

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

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

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

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

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

`streaming`	Поведінка
`"off"` (за замовчуванням)	Чекати повної відповіді, надіслати один раз. `true` ↔ `"partial"`, `false` ↔ `"off"`.
`"partial"`	Редагувати одне звичайне текстове повідомлення на місці, поки модель пише поточний блок. Стандартні клієнти Matrix можуть сповістити про перший preview, а не про фінальне редагування.
`"quiet"`	Те саме, що `"partial"`, але повідомлення є notice без сповіщення. Одержувачі отримують сповіщення лише тоді, коли push rule для кожного користувача збігається з фіналізованим редагуванням (див. нижче).

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

`streaming`	`blockStreaming: true`	`blockStreaming: false` (за замовчуванням)
`"partial"` / `"quiet"`	Live draft для поточного блоку, завершені блоки збережено як повідомлення	Live draft для поточного блоку, фіналізовано на місці
`"off"`	Одне повідомлення Matrix зі сповіщенням на кожен завершений блок	Одне повідомлення Matrix зі сповіщенням для повної відповіді

Примітки:

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

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

Нативні prompts схвалення Matrix є звичайними подіями m.room.message з custom event content, специфічним для OpenClaw, під com.openclaw.approval. Matrix дозволяє custom event-content keys, тому стандартні клієнти все одно відображають текстове тіло, а клієнти, обізнані з OpenClaw, можуть читати структурований approval id, kind, state, available decisions і деталі exec/plugin. Коли prompt схвалення занадто довгий для однієї події Matrix, OpenClaw ділить видимий текст на chunks і додає com.openclaw.approval лише до першого chunk. Reactions для рішень allow/deny привʼязані до цієї першої події, тому довгі prompts зберігають ту саму ціль схвалення, що й prompts з однією подією.

Self-hosted push rules для тихих фіналізованих previews

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

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

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

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

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

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

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

У зашифрованих кімнатах (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 - це команда відновлення й налаштування для зашифрованих акаунтів. Послідовно вона:

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

Якщо homeserver вимагає 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):

Команда	Призначення
`openclaw matrix verify accept <id>`	Прийняти вхідний запит
`openclaw matrix verify start <id>`	Запустити потік SAS
`openclaw matrix verify sas <id>`	Вивести emoji або десяткові числа SAS
`openclaw matrix verify confirm-sas <id>`	Підтвердити, що SAS збігається з тим, що показує інший клієнт
`openclaw matrix verify mismatch-sas <id>`	Відхилити SAS, коли emoji або десяткові числа не збігаються
`openclaw matrix verify cancel <id>`	Скасувати; приймає необов’язкові `--reason <text>` і `--code <matrix-code>`

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.

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

З encryption: true для startupVerification типовим є "if-unverified". Під час запуску неперевірений пристрій запитує самоперевірку в іншому клієнті Matrix, пропускаючи дублікати й застосовуючи період очікування (типово 24 години). Налаштовуйте через startupVerificationCooldownHours або вимикайте через startupVerification: "off".Під час запуску також виконується консервативний прохід криптоініціалізації, який повторно використовує поточне сховище секретів і ідентичність перехресного підписування. Якщо стан ініціалізації пошкоджений, OpenClaw пробує контрольоване відновлення навіть без channels.matrix.password; якщо homeserver вимагає UIA з паролем, запуск записує попередження в журнал і не завершується аварійно. Пристрої, уже підписані власником, зберігаються.Див. міграцію Matrix для повного процесу оновлення.

Сповіщення про перевірку

Matrix публікує сповіщення життєвого циклу перевірки в сувору DM-кімнату перевірки як повідомлення m.notice: запит, готовність (із вказівками “Перевірити за emoji”), початок/завершення та деталі SAS (emoji/десяткові числа), коли вони доступні.Вхідні запити від іншого клієнта Matrix відстежуються й автоматично приймаються. Для самоперевірки OpenClaw автоматично запускає потік SAS і підтверджує свою сторону, щойно перевірка за emoji стає доступною - вам усе одно потрібно порівняти й підтвердити “Вони збігаються” у вашому клієнті Matrix.Системні сповіщення про перевірку не передаються в конвеєр чату агента.

Видалений або недійсний пристрій Matrix

Якщо verify status каже, що поточного пристрою більше немає в списку на homeserver, створіть новий пристрій OpenClaw Matrix. Для входу з паролем:

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

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

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

Замініть assistant на ID акаунта з невдалої команди або опустіть --account для типового акаунта.

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

Старі пристрої, керовані OpenClaw, можуть накопичуватися. Перегляньте й очистьте:

openclaw matrix devices list
openclaw matrix devices prune-stale

Криптосховище

Matrix E2EE використовує офіційний Rust-криптошлях matrix-js-sdk із fake-indexeddb як shim для IndexedDB. Криптостан зберігається в crypto-idb-snapshot.json (обмежувальні права доступу до файла).Зашифрований стан виконання розміщується в ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/ і містить сховище синхронізації, криптосховище, ключ відновлення, знімок IDB, прив’язки потоків і стан перевірки під час запуску. Коли токен змінюється, але ідентичність акаунта лишається тією самою, OpenClaw повторно використовує найкращий наявний корінь, щоб попередній стан залишався видимим.

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

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

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

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

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

Явні прив’язки розмов завжди мають пріоритет над 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 видаляє лише вказану реакцію емодзі від бота.

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

Налаштування	Порядок
`ackReaction`	для облікового запису → канал → `messages.ackReaction` → резервний емодзі ідентичності агента
`ackReactionScope`	для облікового запису → канал → `messages.ackReactionScope` → типове `"group-mentions"`
`reactionNotifications`	для облікового запису → канал → типове `"own"`

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 запускає шлях команди без користувацького regex згадки. Це підтримує чутливість бота до кімнатного стилю дописів @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

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

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

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

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

Обліковий запис і з’єднання

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: список дозволених ID користувачів для трафіку кімнат.
dm.enabled: коли false, ігнорувати всі приватні повідомлення. За замовчуванням: true.
dm.policy: "pairing" (за замовчуванням), "allowlist", "open" або "disabled". Застосовується після того, як бот приєднався та класифікував кімнату як приватну; не впливає на обробку запрошень.
dm.allowFrom: список дозволених ID користувачів для трафіку приватних повідомлень.
dm.sessionScope: "per-user" (за замовчуванням) або "per-room".
dm.threadReplies: перевизначення лише для приватних повідомлень для потоків відповідей ("off", "inbound", "always").
allowBots: приймати повідомлення від інших налаштованих облікових записів ботів Matrix (true або "mentions").
allowlistOnly: коли true, примусово переводить усі активні політики приватних повідомлень (крім "disabled") і групові політики "open" у "allowlist". Не змінює політики "disabled".
dangerouslyAllowNameMatching: коли true, дозволяє пошук відображуваних імен Matrix у каталозі для записів списку дозволених користувачів і пошук назв приєднаних кімнат для ключів списку дозволених кімнат. Надавайте перевагу повним ID @user:server та ID кімнат або псевдонімам.
autoJoin: "always", "allowlist" або "off". За замовчуванням: "off". Застосовується до кожного запрошення Matrix, включно із запрошеннями в стилі приватних повідомлень.
autoJoinAllowlist: кімнати/псевдоніми, дозволені, коли autoJoin має значення "allowlist". Записи псевдонімів визначаються відносно homeserver, а не відносно стану, заявленого запрошеною кімнатою.
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: мапа політик для окремих кімнат. Ідентичність сеансу використовує стабільний ID кімнати після визначення. (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: ID користувачів Matrix, яким дозволено схвалювати. Відступає до dm.allowFrom.
execApprovals.target: "dm" (за замовчуванням), "channel" або "both".
execApprovals.agentFilter / execApprovals.sessionFilter: необов’язкові списки дозволених агентів/сеансів для доставки.

Пов’язане

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

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

Documentation Index

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

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

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

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

​Автоприєднання

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

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

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

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

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

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

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

​Self-hosted push rules для тихих фіналізованих previews

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

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

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

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

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

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

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

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

​Примітки щодо кількох акаунтів

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

​Потоки

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

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

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

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

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

​Реакції

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

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

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

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

​Схвалення exec

​Slash-команди

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

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

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

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

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

​Обліковий запис і з’єднання

​Шифрування

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

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

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

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

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

​Пов’язане