Matrix

Matrix — загружаемый плагин канала (@openclaw/matrix), созданный на основе официального matrix-js-sdk. Он поддерживает личные сообщения, комнаты, ветки, медиафайлы, реакции, опросы, геолокацию и сквозное шифрование.

Установка

openclaw plugins install @openclaw/matrix

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

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

Настройка

1. Создайте учётную запись Matrix на своём домашнем сервере.
2. Настройте channels.matrix с homeserver + accessToken или с homeserver + userId + password.
3. Перезапустите Gateway.
4. Начните личную переписку с ботом или пригласите его в комнату. Новые приглашения принимаются, только когда это разрешено настройкой autoJoin.

Интерактивная настройка

openclaw channels addopenclaw configure --section channels

Мастер запрашивает URL домашнего сервера, метод аутентификации (токен или пароль), идентификатор пользователя (только для аутентификации по паролю), необязательное имя устройства, необходимость включить сквозное шифрование, а также настройки доступа к комнатам и автоматического присоединения. Если соответствующие переменные среды MATRIX_* уже существуют, а для учётной записи не сохранены данные аутентификации, мастер предлагает использовать переменные среды. Перед сохранением списка разрешённых значений с openclaw channels resolve --channel matrix "Project Room" преобразуйте имена комнат в идентификаторы. Включение сквозного шифрования в мастере запускает ту же начальную настройку, что и openclaw matrix encryption setup.

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

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

{  channels: {    matrix: {      enabled: true,      homeserver: "https://matrix.example.org",      accessToken: "syt_xxx",      dm: { policy: "pairing" },    },  },}

На основе пароля (после первого входа токен кэшируется):

{  channels: {    matrix: {      enabled: true,      homeserver: "https://matrix.example.org",      userId: "@bot:example.org",      password: "replace-me", // pragma: allowlist secret      deviceName: "OpenClaw Gateway",    },  },}

Автоматическое присоединение

По умолчанию channels.matrix.autoJoin имеет значение "off": бот не появится в новых комнатах или личных переписках после новых приглашений, пока вы не присоедините его вручную. В момент приглашения OpenClaw не может определить, является ли оно приглашением в личную переписку или группу, поэтому каждое приглашение сначала обрабатывается настройкой autoJoin; dm.policy применяется только позднее, после того как бот присоединится и комната будет классифицирована.

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

Форматы целей в списках разрешённых значений

• Личные сообщения (dm.allowFrom, groupAllowFrom, groups.<room>.users): используйте @user:server. Отображаемые имена по умолчанию игнорируются, поскольку они изменяемы; задавайте dangerouslyAllowNameMatching: true только для явной совместимости с отображаемыми именами.
• Ключи списка разрешённых комнат (groups, устаревший псевдоним rooms): используйте !room:server или #alias:server. Простые имена игнорируются, если не задано dangerouslyAllowNameMatching: true.
• Списки разрешённых приглашений (autoJoinAllowlist): используйте !room:server, #alias:server или *. Простые имена всегда отклоняются.

Нормализация идентификатора учётной записи

Мастер преобразует понятное имя в нормализованный идентификатор учётной записи (Ops Bot -> ops-bot). В именах переменных среды с областью действия знаки пунктуации заменяются шестнадцатеричными кодами, чтобы избежать конфликтов между учётными записями: - (0x2D) превращается в _X2D_, поэтому ops-prod соответствует префиксу переменных среды MATRIX_OPS_X2D_PROD_.

Кэшированные учётные данные

Matrix кэширует учётные данные в ~/.openclaw/credentials/matrix/: credentials.json для учётной записи по умолчанию и credentials-<account>.json для именованных учётных записей. При наличии кэшированных учётных данных OpenClaw считает Matrix настроенным даже без accessToken в файле конфигурации — это относится к настройке, openclaw doctor и проверкам состояния канала.

Переменные среды

Переменные среды, соответствующие ключам конфигурации, используются, когда эквивалентный ключ конфигурации не задан. Для учётной записи по умолчанию используются имена без префикса; для именованных учётных записей токен учётной записи вставляется перед суффиксом (см. нормализацию).

Для учётной записи ops имена принимают вид MATRIX_OPS_HOMESERVER, MATRIX_OPS_ACCESS_TOKEN и так далее. MATRIX_HOMESERVER (а также любой вариант *_HOMESERVER с областью действия) нельзя задать из рабочего файла .env; см. раздел Файлы рабочего пространства .env.

Пример конфигурации

Практическая базовая конфигурация с сопряжением для личных сообщений, списком разрешённых комнат и сквозным шифрованием:

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

Потоковые предварительные просмотры

Потоковая передача ответов в Matrix включается явно. streaming.mode определяет, как OpenClaw доставляет формируемый ответ ассистента; streaming.block.enabled определяет, сохраняется ли каждый завершённый блок как отдельное сообщение Matrix.

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

Чтобы сохранить предварительный просмотр ответа в реальном времени, но скрыть промежуточные строки инструментов и хода выполнения:

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

Полная конфигурация принимает { mode, chunkMode, block, preview, progress }:

{  channels: {    matrix: {      streaming: {        mode: "progress",        progress: {          label: "auto", // выбрать из настроенных или встроенных меток (false — скрыть)          labels: ["Обдумывание", "Написание", "Поиск"], // варианты для label: "auto"          maxLines: 8, // максимальное число строк текущего хода выполнения (по умолчанию: 8)          maxLineChars: 120, // максимальное число символов в строке до усечения (по умолчанию: 120)          toolProgress: true, // показывать активность инструментов и ход выполнения (по умолчанию: true)        },      },    },  },}

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

streaming.block.enabled (по умолчанию false) не зависит от streaming.mode:

Примечания:

• Если предварительный просмотр превышает ограничение Matrix на размер события, OpenClaw прекращает его потоковую передачу и переходит к доставке только окончательного ответа.
• Ответы с медиафайлами всегда отправляют вложения обычным способом; если устаревший предварительный просмотр нельзя безопасно использовать повторно, OpenClaw редактирует его перед отправкой окончательного ответа с медиафайлом.
• Обновления предварительного просмотра хода работы инструментов по умолчанию включены при активной потоковой передаче предварительного просмотра. Задайте streaming.preview.toolProgress: false, чтобы сохранить редактирование предварительного просмотра текста ответа, но оставить ход работы инструментов в обычном пути доставки.
• Редактирование предварительного просмотра требует дополнительных вызовов API Matrix. Оставьте streaming.mode: "off", чтобы использовать наиболее консервативный профиль ограничения частоты запросов.
• Устаревшие скалярные или логические значения streaming, а также плоские ключи blockStreaming / chunkMode преобразуются в эту вложенную структуру с помощью openclaw doctor --fix.

Голосовые сообщения

Входящие голосовые сообщения Matrix расшифровываются до проверки упоминания в комнате, поэтому голосовое сообщение с именем бота может активировать агента в комнате requireMention: true, а агент получает расшифровку вместо одного лишь заполнителя аудиовложения.

Matrix использует общий поставщик обработки аудиоматериалов в tools.media.audio, например OpenAI gpt-4o-mini-transcribe. Настройку поставщика и ограничения см. в разделе Обзор инструментов для работы с медиафайлами.

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

Метаданные подтверждения

Нативные запросы подтверждения Matrix представляют собой обычные события m.room.message с содержимым OpenClaw в ключе com.openclaw.approval. Стандартные клиенты по-прежнему отображают текстовое содержимое; клиенты с поддержкой OpenClaw могут считывать структурированные идентификатор, тип, состояние и решения подтверждения, а также сведения о выполнении или плагине.

Если запрос слишком длинный для одного события Matrix, OpenClaw разбивает видимый текст на части и добавляет com.openclaw.approval только к первой части. Реакции разрешения или отклонения привязываются к этому первому событию, поэтому длинные запросы используют ту же цель подтверждения, что и запросы из одного события.

Правила push-уведомлений для тихих финализированных предпросмотров при самостоятельном размещении

streaming.mode: "quiet" уведомляет получателей только после финализации блока или хода — пользовательское правило push-уведомлений должно соответствовать маркеру финализированного предпросмотра. Полный рецепт приведён в разделе Правила push-уведомлений Matrix для тихих предпросмотров.

Комнаты для взаимодействия ботов

По умолчанию сообщения Matrix от других настроенных учётных записей OpenClaw Matrix игнорируются. Используйте allowBots, чтобы намеренно разрешить обмен данными между агентами:

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

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

При включении обмена данными между ботами в общих комнатах используйте строгие списки разрешённых комнат и требования к упоминаниям.

Шифрование и проверка

В зашифрованных комнатах (E2EE) исходящие события с изображениями используют thumbnail_file, поэтому предпросмотры изображений шифруются вместе с полным вложением; незашифрованные комнаты используют обычный thumbnail_url. Настройка не требуется — плагин автоматически определяет состояние E2EE.

Все команды openclaw matrix принимают --verbose (полная диагностика), --json (машиночитаемый вывод) и --account <id> (конфигурации с несколькими учётными записями). По умолчанию вывод краткий.

Включение шифрования

openclaw matrix encryption setup

Инициализирует хранилище секретов и перекрёстную подпись, при необходимости создаёт резервную копию ключей комнат, а затем выводит состояние и дальнейшие действия. Полезные флаги:

• --recovery-key <key> применяет ключ восстановления перед инициализацией (предпочтительно использовать приведённый ниже вариант со стандартным вводом)
• --force-reset-cross-signing удаляет текущую идентичность перекрёстной подписи и создаёт новую (только для намеренного использования)

Для новой учётной записи включите E2EE при её создании:

openclaw matrix account add \  --homeserver https://matrix.example.org \  --access-token syt_xxx \  --enable-e2ee

--encryption является псевдонимом для --enable-e2ee. Эквивалентная ручная конфигурация:

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

Состояние и сигналы доверия

openclaw matrix verify statusopenclaw matrix verify status --include-recovery-key --json

verify status сообщает о трёх независимых сигналах доверия (--verbose показывает их все):

• Locally trusted: доверие установлено только этим клиентом
• Cross-signing verified: SDK сообщает о проверке посредством перекрёстной подписи
• Signed by owner: подписано вашим собственным ключом самоподписи (только для диагностики)

Verified by owner имеет значение yes, только когда Cross-signing verified имеет значение yes; одного локального доверия или подписи владельца недостаточно.

--allow-degraded-local-state возвращает доступные диагностические сведения без предварительной подготовки учётной записи Matrix; это полезно для автономных проверок или проверок частично настроенных систем.

Проверка этого устройства с помощью ключа восстановления

Передавайте ключ восстановления через стандартный ввод, а не в командной строке:

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

Команда сообщает о трёх состояниях:

• Recovery key accepted: Matrix принял ключ для хранилища секретов или доверия к устройству.
• Backup usable: резервную копию ключей комнат можно загрузить с использованием доверенного материала восстановления.
• Device verified by owner: это устройство обладает полным доверием к идентичности перекрёстной подписи Matrix.

Команда завершается с ненулевым кодом, если полное доверие к идентичности не установлено, даже когда ключ восстановления разблокировал материалы резервной копии. В этом случае завершите самопроверку в другом клиенте Matrix:

openclaw matrix verify self

verify self ожидает Cross-signing verified: yes перед успешным завершением. Используйте --timeout-ms <ms>, чтобы настроить время ожидания.

Вариант с ключом в явном виде openclaw matrix verify device "<recovery-key>" также работает, но ключ сохраняется в истории командной оболочки.

Инициализация или восстановление перекрёстной подписи

openclaw matrix verify bootstrap

Команда восстановления и настройки зашифрованных учётных записей. Она по порядку:

• инициализирует хранилище секретов, по возможности повторно используя существующий ключ восстановления
• инициализирует перекрёстную подпись и отправляет отсутствующие открытые ключи
• помечает и подписывает перекрёстной подписью текущее устройство
• создаёт серверную резервную копию ключей комнат, если её ещё нет

Если домашний сервер требует UIA для отправки ключей перекрёстной подписи, OpenClaw сначала пытается выполнить операцию без аутентификации, затем с m.login.dummy, а после этого с m.login.password (требуется channels.matrix.password).

Полезные флаги:

• --recovery-key-stdin (используйте вместе с printf '%s\n' "$MATRIX_RECOVERY_KEY" | ...) или --recovery-key <key>
• --force-reset-cross-signing для удаления текущей идентичности перекрёстной подписи (только намеренно; активный ключ восстановления должен быть сохранён или передан с помощью --recovery-key-stdin)

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

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

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

Чтобы заменить повреждённую резервную копию новой базовой версией (с потерей невосстановимой старой истории; команда также может заново создать хранилище секретов, если текущий секрет резервной копии невозможно загрузить):

openclaw matrix verify backup reset --yes

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

Просмотр, запрос и обработка проверок

openclaw matrix verify list

Выводит ожидающие запросы проверки для выбранной учётной записи.

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

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

Для низкоуровневого управления жизненным циклом — обычно при отслеживании входящих запросов из другого клиента — эти команды работают с конкретным запросом <id> (выводится командами verify list и verify request):

accept, start, sas, confirm-sas, mismatch-sas и cancel принимают --user-id и --room-id в качестве подсказок для продолжения в личных сообщениях, если проверка привязана к определённой комнате личных сообщений.

Примечания о нескольких учётных записях

Без --account <id> команды 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

Управление профилем

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

Передавайте обе опции в одном вызове. Matrix напрямую принимает URL-адреса аватаров mxc://; при передаче http:///https:// файл сначала загружается, а разрешенный URL-адрес mxc:// сохраняется в channels.matrix.avatarUrl (или в переопределении для конкретной учетной записи).

Ветки

Matrix поддерживает встроенные ветки как для автоматических ответов, так и для отправки сообщений через инструмент сообщений. Поведение управляется двумя независимыми параметрами:

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

dm.sessionScope определяет, как комнаты личных сообщений Matrix сопоставляются с сеансами OpenClaw:

• "per-user" (по умолчанию): все комнаты личных сообщений с одним и тем же маршрутизируемым собеседником используют общий сеанс.
• "per-room": каждая комната личных сообщений Matrix получает собственный ключ сеанса даже для одного и того же собеседника.

Явные привязки бесед всегда имеют приоритет над sessionScope; привязанные комнаты и ветки сохраняют выбранный целевой сеанс.

Ответы в ветках (threadReplies)

threadReplies определяет, куда бот публикует ответ:

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

dm.threadReplies переопределяет это только для личных сообщений — например, позволяет изолировать ветки комнат, сохраняя личные сообщения без веток.

Наследование веток и команды с косой чертой

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

Когда OpenClaw обнаруживает конфликт комнаты личных сообщений Matrix с другой комнатой личных сообщений в том же общем сеансе, он однократно публикует m.notice, указывающий на обходной путь /focus и предлагающий изменить dm.sessionScope. Уведомление появляется только при включенных привязках веток.

Привязки бесед ACP

Комнаты, личные сообщения и существующие ветки Matrix могут стать постоянными рабочими пространствами ACP без изменения интерфейса чата.

Быстрый порядок действий для оператора:

• Выполните /acp spawn codex --bind here внутри личного сообщения, комнаты или существующей ветки Matrix, чтобы продолжить использование.
• В личном сообщении или комнате верхнего уровня текущая комната личных сообщений или обычная комната остается интерфейсом чата, а будущие сообщения маршрутизируются в созданный сеанс ACP.
• Внутри существующей ветки --bind here привязывает текущую ветку на месте.
• /new и /reset сбрасывают тот же привязанный сеанс ACP на месте.
• /acp close закрывает сеанс ACP и удаляет привязку.

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

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

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

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions: управляет созданием веток как субагентами, так и ACP.
• threadBindings.spawnSubagentSessions / threadBindings.spawnAcpSessions: более узкие переопределения для создания веток только субагентами или только ACP.
• threadBindings.defaultSpawnContext

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

Реакции

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

Инструменты исходящих реакций управляются параметром channels.matrix.actions.reactions:

• react добавляет реакцию к событию Matrix.
• reactions выводит текущую сводку реакций для события Matrix.
• emoji="" удаляет собственные реакции бота на это событие.
• remove: true удаляет у бота только указанную реакцию эмодзи.

Порядок разрешения (используется первое определенное значение):

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

Контекст истории

• channels.matrix.historyLimit определяет, сколько последних сообщений комнаты включается как InboundHistory, когда сообщение комнаты запускает агента. Используется резервное значение messages.groupChat.historyLimit; если оба параметра не заданы, эффективное значение по умолчанию — 0 (отключено).
• История комнат Matrix ограничена конкретной комнатой; личные сообщения продолжают использовать обычную историю сеанса.
• История комнаты содержит только ожидающие сообщения: OpenClaw буферизует сообщения комнаты, которые еще не вызвали ответ, а затем создает снимок этого окна при поступлении упоминания или другого триггера.
• Текущее сообщение-триггер не включается в InboundHistory; для этого хода оно остается в основном теле входящего сообщения.
• При повторной обработке того же события Matrix повторно используется исходный снимок истории, а не более новые сообщения комнаты.

Видимость контекста

Matrix поддерживает общий параметр contextVisibility для дополнительного контекста комнаты, такого как полученный текст ответа, корневые сообщения веток и ожидающая история.

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

Это влияет только на видимость дополнительного контекста, а не на возможность самого входящего сообщения вызвать ответ. Авторизация триггера по-прежнему определяется параметрами groupPolicy, groups, groupAllowFrom и настройками политики личных сообщений.

Политика личных сообщений и комнат

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

Чтобы полностью отключить личные сообщения, сохранив работу комнат, установите dm.enabled: false:

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

Поведение ограничения по упоминаниям и спискам разрешенных пользователей описано в разделе Группы.

Пример сопряжения для личных сообщений Matrix:

openclaw pairing list matrixopenclaw pairing approve matrix <CODE>

Если пользователь Matrix без подтверждения продолжает отправлять сообщения до одобрения, OpenClaw повторно использует тот же ожидающий код сопряжения и после короткого периода ожидания может отправить ответ-напоминание вместо создания нового кода.

Общий процесс сопряжения личных сообщений и структура хранения описаны в разделе Сопряжение.

Восстановление комнаты личных сообщений

Если состояние личных сообщений рассинхронизируется, в OpenClaw могут остаться устаревшие сопоставления m.direct, указывающие на старые индивидуальные комнаты вместо активной комнаты личных сообщений. Проверьте текущее сопоставление для собеседника:

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

Исправьте его:

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

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

• предпочитает строго индивидуальную комнату личных сообщений, уже сопоставленную в m.direct
• в качестве резервного варианта использует любую текущую строго индивидуальную комнату личных сообщений с этим пользователем, к которой выполнено присоединение
• создает новую комнату личных сообщений и перезаписывает m.direct, если исправной комнаты личных сообщений не существует

Старые комнаты не удаляются автоматически. Выбирается исправная комната личных сообщений, и сопоставление обновляется, чтобы будущие отправки Matrix, уведомления о проверке и другие потоки личных сообщений направлялись в правильную комнату.

Одобрения выполнения

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

• enabled: доставлять запросы на одобрение через встроенные запросы Matrix. Если параметр не задан или равен "auto", функция автоматически включается, как только удается определить хотя бы одного утверждающего; установите false, чтобы явно отключить ее.
• approvers: идентификаторы пользователей Matrix (@owner:example.org), которым разрешено одобрять запросы выполнения. Резервное значение — channels.matrix.dm.allowFrom.
• target: куда отправляются запросы. "dm" (по умолчанию) отправляет их в личные сообщения утверждающих; "channel" — в исходную комнату или личное сообщение; "both" — в оба места.
• agentFilter / sessionFilter: необязательные списки разрешенных агентов и сеансов, которые инициируют доставку через Matrix.

Авторизация немного различается в зависимости от типа одобрения:

• Одобрения выполнения используют execApprovals.approvers, а резервным значением служит dm.allowFrom.
• Одобрения плагинов авторизуются только через dm.allowFrom.

Оба типа используют общие быстрые действия с реакциями Matrix и обновления сообщений. Утверждающие видят быстрые действия с реакциями в основном сообщении с запросом на одобрение:

• ✅ разрешить один раз
• ❌ отклонить
• ♾️ разрешать всегда (если это допускает действующая политика exec)

Резервные слеш-команды: /approve <id> allow-once, /approve <id> allow-always, /approve <id> deny.

Одобрять или отклонять могут только определённые согласующие лица. Доставка запросов на одобрение exec в канал включает текст команды — включайте channel или both только в доверенных комнатах.

См. также: Одобрения exec.

Слеш-команды

Слеш-команды (/new, /reset, /model, /focus, /unfocus, /agents, /session, /acp, /approve и т. д.) работают напрямую в личных сообщениях. В комнатах OpenClaw также распознаёт команды с предшествующим упоминанием самого бота в Matrix, поэтому @bot:server /new запускает обработку команды без пользовательского регулярного выражения для упоминаний — благодаря этому бот реагирует на типичные для комнат публикации @mention /command, которые создают Element и аналогичные клиенты, когда пользователь дополняет имя бота клавишей Tab перед вводом команды.

Правила авторизации продолжают действовать: отправители команд должны соответствовать тем же политикам списка разрешённых пользователей или владельца для личных сообщений либо комнат, что и отправители обычных сообщений.

Несколько учётных записей

{  channels: {    matrix: {      enabled: true,      defaultAccount: "assistant",      dm: { policy: "pairing" },      accounts: {        assistant: {          homeserver: "https://matrix.example.org",          accessToken: "syt_assistant_xxx",          encryption: true,        },        alerts: {          homeserver: "https://matrix.example.org",          accessToken: "syt_alerts_xxx",          dm: {            policy: "allowlist",            allowFrom: ["@ops:example.org"],            threadReplies: "off",          },        },      },    },  },}

Наследование:

• Значения channels.matrix верхнего уровня служат значениями по умолчанию для именованных учётных записей, если они не переопределены в учётной записи.
• Чтобы ограничить унаследованную запись комнаты конкретной учётной записью, используйте groups.<room>.account. Записи без account совместно используются всеми учётными записями; account: "default" по-прежнему работает, когда учётная запись по умолчанию настроена на верхнем уровне.

Выбор учётной записи по умолчанию:

• Задайте defaultAccount, чтобы выбрать именованную учётную запись, которой будут отдавать предпочтение неявная маршрутизация, проверки и команды CLI.
• Если у вас несколько учётных записей и одна из них буквально называется default, OpenClaw неявно использует её, даже если defaultAccount не задан.
• При наличии нескольких именованных учётных записей и отсутствии выбранной учётной записи по умолчанию команды CLI отказываются делать предположение — задайте defaultAccount или передайте --account <id>.
• Блок channels.matrix.* верхнего уровня рассматривается как неявная учётная запись default только при полной настройке её аутентификации (homeserver + accessToken или homeserver + userId + password). Именованные учётные записи остаются доступными для обнаружения по homeserver + userId, если кэшированные учётные данные обеспечивают аутентификацию.

Перенос:

• Когда OpenClaw во время исправления или настройки преобразует конфигурацию с одной учётной записью в конфигурацию с несколькими, он сохраняет существующую именованную учётную запись, если она имеется или если defaultAccount уже указывает на неё. В перенесённую учётную запись перемещаются только ключи аутентификации и начальной настройки Matrix; общие ключи политики доставки остаются на верхнем уровне.

Общая схема работы с несколькими учётными записями описана в справочнике по конфигурации.

Частные homeserver и homeserver в локальной сети

По умолчанию для защиты от SSRF OpenClaw блокирует частные и внутренние homeserver Matrix, если вы явно не разрешили их для конкретной учётной записи.

Если ваш homeserver работает на localhost, IP-адресе локальной сети/Tailscale или внутреннем имени хоста, включите network.dangerouslyAllowPrivateNetwork для этой учётной записи:

{  channels: {    matrix: {      homeserver: "http://matrix-synapse:8008",      network: {        dangerouslyAllowPrivateNetwork: true,      },      accessToken: "syt_internal_xxx",    },  },}

Пример настройки через CLI:

openclaw matrix account add \  --account ops \  --homeserver http://matrix-synapse:8008 \  --allow-private-network \  --access-token syt_ops_xxx

Это явное разрешение распространяется только на доверенные частные и внутренние цели. Общедоступные 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

Идентификаторы комнат Matrix чувствительны к регистру. При настройке явных целей доставки, заданий Cron, привязок или списков разрешённых значений используйте точный регистр идентификатора комнаты из Matrix. OpenClaw приводит внутренние ключи сеансов к каноническому виду для хранения, поэтому эти ключи в нижнем регистре не являются надёжным источником идентификаторов доставки Matrix.

Оперативный поиск в каталоге выполняется от имени учётной записи Matrix, в которую выполнен вход:

• При поиске пользователей запрашивается каталог пользователей Matrix на соответствующем homeserver.
• При поиске комнат напрямую принимаются явные идентификаторы и псевдонимы комнат. Поиск по именам присоединённых комнат выполняется по возможности и применяется только к рабочим спискам разрешённых комнат, когда задан dangerouslyAllowNameMatching: true.
• Если имя комнаты невозможно преобразовать в идентификатор или псевдоним, оно игнорируется при формировании рабочего списка разрешённых комнат.

Справочник по конфигурации

Поля пользователей, работающие как списки разрешённых значений (groupAllowFrom, dm.allowFrom, groups.<room>.users), принимают полные идентификаторы пользователей Matrix — это наиболее безопасный вариант. По умолчанию записи, не являющиеся идентификаторами, игнорируются. Если задан dangerouslyAllowNameMatching: true, точные совпадения отображаемых имён в каталоге Matrix разрешаются при запуске и при каждом изменении списка разрешённых значений во время работы монитора; записи, которые невозможно разрешить, игнорируются во время выполнения.

Ключами списка разрешённых комнат (groups, устаревший rooms) должны быть идентификаторы или псевдонимы комнат. По умолчанию ключи с обычными именами комнат игнорируются; dangerouslyAllowNameMatching: true восстанавливает поиск по именам присоединённых комнат, выполняемый по возможности.

Учётная запись и подключение

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

Шифрование

• encryption: включает сквозное шифрование. По умолчанию: false.
• startupVerification: "if-unverified" (по умолчанию при включённом сквозном шифровании) или "off". Если это устройство не подтверждено, при запуске автоматически запрашивает самоподтверждение.
• startupVerificationCooldownHours: период ожидания перед следующим автоматическим запросом при запуске. По умолчанию: 24.

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

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

Поведение ответов

• replyToMode: "off" (по умолчанию), "first", "all" или "batched".
• threadReplies: "off" (значение по умолчанию верхнего уровня преобразуется в "inbound", если оно не задано явно), "inbound" или "always".
• threadBindings: переопределения для отдельных каналов, управляющие маршрутизацией и жизненным циклом сеансов, привязанных к веткам.
• streaming: вложенный объект { mode, chunkMode, block: { enabled, coalesce }, preview: { toolProgress }, progress: { label, labels, maxLines, maxLineChars, toolProgress } }. mode — "off" (по умолчанию), "partial", "quiet" или "progress". Устаревшие скалярные и логические варианты записи мигрируются с помощью openclaw doctor --fix.
• streaming.block.enabled: если true, завершённые блоки ассистента сохраняются как отдельные сообщения о ходе выполнения. По умолчанию: false.
• markdown: необязательная конфигурация обработки Markdown для исходящего текста.
• responsePrefix: необязательная строка, добавляемая в начало исходящих ответов.
• textChunkLimit: размер исходящего фрагмента в символах, когда streaming.chunkMode: "length". По умолчанию: 4000.
• streaming.chunkMode: "length" (по умолчанию; разделение по количеству символов) или "newline" (разделение по границам строк).
• historyLimit: количество последних сообщений комнаты, включаемых как InboundHistory, когда сообщение в комнате запускает агента. Если значение не задано, используется messages.groupChat.historyLimit; фактическое значение по умолчанию — 0 (отключено).
• mediaMaxMb: ограничение размера медиафайлов в МБ для исходящей отправки и обработки входящих данных. По умолчанию: 20.

Настройки реакций

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

Инструменты и переопределения для отдельных комнат

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

Настройки подтверждения выполнения

• execApprovals.enabled: доставляет запросы на подтверждение выполнения через встроенные запросы Matrix.
• execApprovals.approvers: идентификаторы пользователей Matrix, которым разрешено подтверждение. Если не задано, используется dm.allowFrom.
• execApprovals.target: "dm" (по умолчанию), "channel" или "both".
• execApprovals.agentFilter / execApprovals.sessionFilter: необязательные списки разрешённых агентов и сеансов для доставки.

См. также

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