Матрица - OpenClaw

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

Установка

Установите Matrix из ClawHub перед настройкой канала:

openclaw plugins install @openclaw/matrix

Простые спецификации Plugin сначала пробуют ClawHub, затем используют резервный вариант npm. Чтобы принудительно выбрать источник реестра, используйте openclaw plugins install clawhub:@openclaw/matrix или openclaw plugins install npm:@openclaw/matrix. Из локальной рабочей копии:

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

plugins install регистрирует и включает Plugin, поэтому отдельный шаг openclaw plugins enable matrix не нужен. Plugin по-прежнему ничего не делает, пока вы не настроите канал ниже. Общие сведения о поведении Plugin и правилах установки см. в Plugins.

Настройка

Создайте учетную запись Matrix на своем homeserver.
Настройте channels.matrix с homeserver + accessToken либо с homeserver + userId + password.
Перезапустите gateway.
Начните личное сообщение с ботом или пригласите его в комнату (см. автоприсоединение — новые приглашения срабатывают только когда autoJoin их разрешает).

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

openclaw channels add
openclaw configure --section channels

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

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

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

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

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

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

Автоприсоединение

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

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

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

Чтобы принимать каждое приглашение, используйте autoJoin: "always".

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

Списки разрешений для личных сообщений и комнат лучше заполнять стабильными ID:

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

Нормализация ID учетной записи

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

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

Matrix хранит кэшированные учетные данные в ~/.openclaw/credentials/matrix/:

учетная запись по умолчанию: credentials.json
именованные учетные записи: credentials-<account>.json

Когда там есть кэшированные учетные данные, OpenClaw считает Matrix настроенным, даже если токена доступа нет в файле конфигурации — это покрывает настройку, openclaw doctor и проверки статуса канала.

Переменные окружения

Используются, когда эквивалентный ключ конфигурации не задан. Учетная запись по умолчанию использует имена без префикса; именованные учетные записи используют ID учетной записи, вставленный перед суффиксом.

Учетная запись по умолчанию	Именованная учетная запись (`<ID>` — нормализованный ID учетной записи)
`MATRIX_HOMESERVER`	`MATRIX_<ID>_HOMESERVER`
`MATRIX_ACCESS_TOKEN`	`MATRIX_<ID>_ACCESS_TOKEN`
`MATRIX_USER_ID`	`MATRIX_<ID>_USER_ID`
`MATRIX_PASSWORD`	`MATRIX_<ID>_PASSWORD`
`MATRIX_DEVICE_ID`	`MATRIX_<ID>_DEVICE_ID`
`MATRIX_DEVICE_NAME`	`MATRIX_<ID>_DEVICE_NAME`
`MATRIX_RECOVERY_KEY`	`MATRIX_<ID>_RECOVERY_KEY`

Для учетной записи ops имена становятся MATRIX_OPS_HOMESERVER, MATRIX_OPS_ACCESS_TOKEN и так далее. Переменные окружения ключа восстановления читаются CLI-потоками с поддержкой восстановления (verify backup restore, verify device, verify bootstrap), когда вы передаете ключ через --recovery-key-stdin. MATRIX_HOMESERVER нельзя задать из рабочего .env; см. файлы .env рабочей области.

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

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

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

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

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

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

Потоковые предпросмотры

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

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

Чтобы сохранить live-предпросмотры ответов, но скрыть промежуточные строки инструментов/прогресса, используйте объектную форму:

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

`streaming`	Поведение
`"off"` (по умолчанию)	Ждет полного ответа, отправляет один раз. `true` ↔ `"partial"`, `false` ↔ `"off"`.
`"partial"`	Редактирует одно обычное текстовое сообщение на месте, пока модель пишет текущий блок. Стандартные клиенты Matrix могут уведомить о первом предпросмотре, а не о финальном редактировании.
`"quiet"`	То же, что `"partial"`, но сообщение является уведомлением без оповещения. Получатели получают уведомление только после того, как пользовательское push-правило сопоставится с финализированным редактированием (см. ниже).

blockStreaming не зависит от streaming:

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

Примечания:

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

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

Входящие голосовые заметки 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. Matrix разрешает пользовательские ключи содержимого события, поэтому стандартные клиенты по-прежнему отображают текстовое тело, а клиенты с поддержкой OpenClaw могут читать структурированный ID подтверждения, тип, состояние, доступные решения и сведения об exec/Plugin. Когда запрос подтверждения слишком длинный для одного события Matrix, OpenClaw разбивает видимый текст на части и прикрепляет com.openclaw.approval только к первой части. Реакции для решений разрешить/запретить привязаны к этому первому событию, поэтому длинные запросы сохраняют ту же цель подтверждения, что и запросы из одного события.

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

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

Комнаты бот-бот

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

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

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

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

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

В зашифрованных комнатах (E2EE) исходящие события изображений используют thumbnail_file, чтобы превью изображений шифровались вместе с полным вложением. Незашифрованные комнаты по-прежнему используют обычный thumbnail_url. Настройка не требуется: Plugin автоматически определяет состояние E2EE. Все команды openclaw matrix принимают --verbose (полная диагностика), --json (машиночитаемый вывод) и --account <id> (настройки с несколькими аккаунтами). По умолчанию вывод краткий, с тихим внутренним логированием SDK. Примеры ниже показывают каноническую форму; добавляйте флаги по мере необходимости.

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

openclaw matrix encryption setup

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

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

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

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

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

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

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

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

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

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

Verified by owner становится yes только когда Cross-signing verified равно yes. Одного локального доверия или подписи владельца недостаточно. --allow-degraded-local-state возвращает диагностические данные best-effort без предварительной подготовки аккаунта Matrix; полезно для офлайн-проверок или частично настроенных проверок.

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

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

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

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

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

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

openclaw matrix verify self

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

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

openclaw matrix verify bootstrap

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

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

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

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

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

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

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

openclaw matrix verify backup reset --yes

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

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

openclaw matrix verify list

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

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

Отправляет запрос проверки из этого аккаунта OpenClaw. --own-user запрашивает самопроверку (вы принимаете приглашение в другом клиенте Matrix того же пользователя); --user-id/--device-id/--room-id нацелены на другого пользователя. --own-user нельзя сочетать с другими флагами выбора цели. Для более низкоуровневой обработки жизненного цикла — обычно при сопровождении входящих запросов из другого клиента — эти команды действуют на конкретный запрос <id> (выводится verify list и verify request):

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

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

Заметки о нескольких аккаунтах

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

Startup behavior

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

Verification notices

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

Deleted or invalid Matrix device

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

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

Для аутентификации по токену создайте свежий access token в вашем клиенте Matrix или admin UI, затем обновите OpenClaw:

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

Замените assistant на ID аккаунта из завершившейся с ошибкой команды или опустите --account для аккаунта по умолчанию.

Device hygiene

Старые устройства, управляемые OpenClaw, могут накапливаться. Выведите список и очистите устаревшие:

openclaw matrix devices list
openclaw matrix devices prune-stale

Crypto store

Matrix E2EE использует официальный криптографический путь Rust из matrix-js-sdk с fake-indexeddb как прослойкой IndexedDB. Криптосостояние сохраняется в crypto-idb-snapshot.json (строгие права доступа к файлу).Зашифрованное состояние runtime хранится в ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/ и включает sync store, crypto store, ключ восстановления, снимок IDB, привязки потоков и состояние проверки при запуске. Когда токен меняется, но идентичность аккаунта остается прежней, OpenClaw повторно использует лучший существующий корень, чтобы предыдущее состояние оставалось видимым.Один более старый корень token-hash может быть нормальным путем непрерывности при ротации токена. Если OpenClaw пишет в лог matrix: multiple populated token-hash storage roots detected, проверьте каталог аккаунта и архивируйте устаревшие соседние корни только после подтверждения, что выбранный активный корень исправен. Предпочитайте перемещать устаревшие корни в каталог _archive/, а не удалять их сразу.

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

Обновите собственный профиль Matrix для выбранного аккаунта:

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

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

Треды

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

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

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

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

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

Треды ответов (`threadReplies`)

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

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

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

Наследование тредов и slash-команды

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

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

Привязки разговоров ACP

Комнаты Matrix, DM и существующие треды Matrix можно превратить в долговечные рабочие области ACP без изменения поверхности чата. Быстрый операторский сценарий:

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

Примечания:

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

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

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

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

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

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

Реакции

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. Группы для поведения шлюза по упоминаниям и allowlist. Пример сопряжения для DM Matrix:

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

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

Ремонт прямых комнат

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

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

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

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

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

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

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

Утверждения exec

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

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

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

Утверждения exec используют execApprovals.approvers, с откатом к dm.allowFrom.
Утверждения Plugin авторизуются только через dm.allowFrom.

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

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

Резервные slash-команды: /approve <id> allow-once, /approve <id> allow-always, /approve <id> deny. Только разрешенные утверждающие могут утверждать или отклонять. Доставка в канал для утверждений exec включает текст команды - включайте channel или both только в доверенных комнатах. Связано: Утверждения exec.

Slash-команды

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

Несколько аккаунтов

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

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

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

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

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

Повышение:

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

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

Приватные/LAN homeserver

По умолчанию OpenClaw блокирует приватные/внутренние Matrix homeserver для защиты от SSRF, если вы явно не включите их для каждой учетной записи. Если ваш homeserver работает на localhost, LAN/Tailscale IP или внутреннем имени хоста, включите network.dangerouslyAllowPrivateNetwork для этой учетной записи Matrix:

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

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

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

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

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

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

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

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

Разрешение целей

Matrix принимает эти формы целей везде, где OpenClaw запрашивает цель комнаты или пользователя:

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

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

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

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

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

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

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

Шифрование

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

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

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

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

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

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

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

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

actions: ограничение инструментов для отдельных действий (messages, reactions, pins, profile, memberInfo, channelInfo, verification).
groups: карта политик для отдельных комнат. Идентичность сеанса использует стабильный ID комнаты после разрешения. (rooms — устаревший псевдоним.)
- groups.<room>.account: ограничить одну унаследованную запись комнаты конкретной учетной записью.
- groups.<room>.allowBots: переопределение настройки уровня канала для отдельной комнаты (true или "mentions").
- groups.<room>.users: список разрешенных отправителей для отдельной комнаты.
- groups.<room>.tools: переопределения разрешения/запрета инструментов для отдельной комнаты.
- groups.<room>.autoReply: переопределение требования упоминания для отдельной комнаты. true отключает требования упоминания для этой комнаты; false принудительно включает их обратно.
- groups.<room>.skills: фильтр Skills для отдельной комнаты.
- groups.<room>.systemPrompt: фрагмент системного промпта для отдельной комнаты.

Настройки одобрения exec

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

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

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

Переход с BlueBubbles Миграция Matrix

⌘I

​Установка

​Настройка

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

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

​Автоприсоединение

​Форматы целей списка разрешений

​Нормализация ID учетной записи

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

​Переменные окружения

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

​Потоковые предпросмотры

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

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

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

​Комнаты бот-бот

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

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

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

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

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

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

​Просмотр, запрос и ответы на проверки

​Заметки о нескольких аккаунтах

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

​Треды

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

​Треды ответов (threadReplies)

​Наследование тредов и slash-команды

​Привязки разговоров ACP

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

​Реакции

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

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

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

​Ремонт прямых комнат

​Утверждения exec

​Slash-команды

​Несколько аккаунтов

​Приватные/LAN homeserver

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

​Разрешение целей

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

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

​Шифрование

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

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

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

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

​Настройки одобрения exec

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