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: ["Thinking", "Writing", "Searching"], // варианты для 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 setupprintf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix encryption setup --recovery-key-stdin

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

openclaw matrix verify self

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

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

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

openclaw matrix verify bootstrap

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

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

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

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

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

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

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

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

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

openclaw matrix verify backup reset --yes

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

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

openclaw matrix verify list

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

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

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

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

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

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

Без --account <id> команды CLI Matrix используют неявную учётную запись по умолчанию. Если настроено несколько именованных учётных записей и параметр channels.matrix.defaultAccount не указан, команды не пытаются угадать выбор и предлагают выбрать учётную запись. Если E2EE отключено или недоступно для именованной учётной записи, ошибка указывает на ключ конфигурации этой учётной записи, например channels.matrix.accounts.assistant.encryption.

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

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

openclaw matrix devices listopenclaw matrix devices prune-stale

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

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

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

Ветки

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Быстрый процесс для оператора:

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

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

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

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

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

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

Реакции

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

openclaw pairing list matrixopenclaw pairing approve matrix <CODE>

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

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

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

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

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

Восстановите его:

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также: Утверждения выполнения.

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

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

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

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

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

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

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

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

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

Преобразование:

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

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

Частные и локальные домашние серверы

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

Если домашний сервер работает на 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

Это явное разрешение допускает только доверенные частные и внутренние адресаты. Общедоступные домашние серверы с незашифрованным подключением, такие как http://matrix.example.org:8008, по-прежнему блокируются. По возможности используйте https://.

Проксирование трафика Matrix

Если развёртыванию Matrix требуется явный исходящий прокси-сервер HTTP(S), задайте channels.matrix.proxy:

{  channels: {    matrix: {      homeserver: "https://matrix.example.org",      accessToken: "syt_bot_xxx",      proxy: "http://127.0.0.1:7890",    },  },}

Именованные учётные записи могут переопределять значение верхнего уровня с помощью channels.matrix.accounts.<id>.proxy. OpenClaw использует одну и ту же настройку прокси-сервера для рабочего трафика Matrix и проверок состояния учётной записи.

Разрешение адресатов

Matrix принимает следующие формы адресатов везде, где OpenClaw запрашивает комнату или пользователя:

• Пользователи: @user:server, user:@user:server или matrix:user:@user:server
• Комнаты: !room:server, room:!room:server или matrix:room:!room:server
• Псевдонимы: #alias:server, channel:#alias:server или matrix:channel:#alias:server

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

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

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

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

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

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

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

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

Шифрование

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

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

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

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

• replyToMode: "off" (по умолчанию), "first", "all" или "batched".
• threadReplies: "off" (значение по умолчанию верхнего уровня разрешается в "inbound", если не задано явно), "inbound" или "always".
• threadBindings: переопределения для отдельных каналов, управляющие маршрутизацией и жизненным циклом сеансов, привязанных к веткам.
• streaming: вложенный объект { 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: необязательные списки разрешённых агентов или сеансов для доставки.

Связанные материалы

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