Matrix (плагин)

Matrix — открытый децентрализованный протокол обмена сообщениями. OpenClaw подключается как пользователь Matrix на любом домашнем сервере, поэтому для бота нужен аккаунт Matrix. После входа можно писать боту в ЛС или приглашать его в комнаты (Matrix «группы»). Beeper тоже подходит как клиент, но требует включения E2EE.

Статус: поддерживается через плагин (@vector-im/matrix-bot-sdk). Прямые сообщения, комнаты, потоки, медиа, реакции, опросы (отправка + poll-start как текст), геолокация и E2EE (с поддержкой криптографии).

Требуется плагин

Matrix поставляется как плагин и не входит в базовую установку.

Установка через CLI (npm-реестр):

openclaw plugins install @openclaw/matrix

Из локальной копии (при работе из git-репозитория):

openclaw plugins install ./extensions/matrix

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

Подробнее: Плагины

Настройка

  1. Установите плагин Matrix:

    • Из npm: openclaw plugins install @openclaw/matrix
    • Из локальной копии: openclaw plugins install ./extensions/matrix

  2. Создайте аккаунт Matrix на домашнем сервере:

  3. Получите токен доступа для аккаунта бота:

    • Используйте Matrix login API с curl на вашем домашнем сервере:
    curl --request POST \
  --url https://matrix.example.org/_matrix/client/v3/login \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "m.login.password",
  "identifier": {
    "type": "m.id.user",
    "user": "your-user-name"
  },
  "password": "your-password"
}'
    • Замените matrix.example.org на URL вашего домашнего сервера.
    • Или задайте channels.matrix.userId + channels.matrix.password: OpenClaw вызовет тот же эндпоинт входа, сохранит токен доступа в ~/.openclaw/credentials/matrix/credentials.json и переиспользует его при следующем запуске.

  4. Настройте учётные данные:

    • Env: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (или MATRIX_USER_ID + MATRIX_PASSWORD)
    • Или конфиг: channels.matrix.*
    • При наличии обоих конфиг имеет приоритет.
    • С токеном доступа: ID пользователя получается автоматически через /whoami.
    • channels.matrix.userId должен быть полным Matrix ID (пример: @bot:example.org).

  5. Перезапустите шлюз (или завершите онбординг).

  6. Начните ЛС с ботом или пригласите его в комнату из любого Matrix-клиента (Element, Beeper и т.д.; см. https://matrix.org/ecosystem/clients/). Beeper требует E2EE, поэтому задайте channels.matrix.encryption: true и верифицируйте устройство.

Минимальная конфигурация (токен доступа, ID пользователя получается автоматически):

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

Конфигурация E2EE (сквозное шифрование включено):

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

Шифрование (E2EE)

Сквозное шифрование поддерживается через Rust crypto SDK.

Включите с помощью channels.matrix.encryption: true:

  • Если криптомодуль загружается, зашифрованные комнаты расшифровываются автоматически.
  • Исходящие медиа шифруются при отправке в зашифрованные комнаты.
  • При первом подключении OpenClaw запрашивает верификацию устройства из других сессий.
  • Верифицируйте устройство в другом Matrix-клиенте (Element и т.д.) для обмена ключами.
  • Если криптомодуль не загружается, E2EE отключается и зашифрованные комнаты не расшифровываются; OpenClaw логирует предупреждение.
  • При ошибках отсутствия криптомодуля (например, @matrix-org/matrix-sdk-crypto-nodejs-*), разрешите скрипты сборки для @matrix-org/matrix-sdk-crypto-nodejs и выполните pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs или загрузите бинарник через node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js.

Состояние криптографии хранится по аккаунту + токену доступа в ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ (база SQLite). Состояние синхронизации находится рядом в bot-storage.json. При смене токена доступа (устройства) создаётся новое хранилище, и бот должен быть заново верифицирован для зашифрованных комнат.

Верификация устройства: При включённом E2EE бот запросит верификацию из других сессий при запуске. Откройте Element (или другой клиент) и подтвердите запрос верификации для установления доверия. После верификации бот сможет расшифровывать сообщения в зашифрованных комнатах.

Мульти-аккаунт

Мульти-аккаунт: используйте channels.matrix.accounts с учётными данными для каждого аккаунта и необязательным name. Подробнее: gateway/configuration.

Каждый аккаунт работает как отдельный пользователь Matrix на любом домашнем сервере. Конфигурация аккаунта наследует настройки верхнего уровня channels.matrix и может переопределять любую опцию (политика ЛС, группы, шифрование и т.д.).

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Main assistant",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Alerts bot",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_***",
          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
        },
      },
    },
  },
}

Примечания:

  • Запуск аккаунтов сериализован для предотвращения состояний гонки при параллельном импорте модулей.
  • Переменные окружения (MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN и т.д.) применяются только к аккаунту по умолчанию.
  • Базовые настройки канала (политика ЛС, групповая политика, гейтинг по упоминанию и т.д.) применяются ко всем аккаунтам, если не переопределены для конкретного аккаунта.
  • Используйте bindings[].match.accountId для маршрутизации каждого аккаунта к разному агенту.
  • Состояние криптографии хранится по аккаунту + токену доступа (отдельные хранилища ключей для каждого аккаунта).

Модель маршрутизации

  • Ответы всегда возвращаются в Matrix.
  • ЛС используют основную сессию агента; комнаты привязаны к групповым сессиям.

Контроль доступа (ЛС)

  • По умолчанию: channels.matrix.dm.policy = "pairing". Неизвестные отправители получают код спаривания.
  • Подтверждение:
    • openclaw pairing list matrix
    • openclaw pairing approve matrix <CODE>
  • Публичные ЛС: channels.matrix.dm.policy="open" плюс channels.matrix.dm.allowFrom=["*"].
  • channels.matrix.dm.allowFrom принимает полные ID пользователей Matrix (пример: @user:server). Мастер настройки преобразует отображаемые имена в ID пользователей при единственном точном совпадении в каталоге.
  • Не используйте отображаемые имена или голые локальные части (пример: "Alice" или "alice"). Они неоднозначны и игнорируются для сопоставления списка доступа. Используйте полные ID @user:server.

Комнаты (группы)

  • По умолчанию: channels.matrix.groupPolicy = "allowlist" (с гейтингом по упоминанию). Используйте channels.defaults.groupPolicy для переопределения значения по умолчанию.
  • Примечание: если channels.matrix полностью отсутствует, runtime использует fallback к groupPolicy="allowlist" для проверок комнат (даже если задан channels.defaults.groupPolicy).
  • Список доступа комнат через channels.matrix.groups (ID комнат или алиасы; имена преобразуются в ID при единственном точном совпадении в каталоге):
{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}
  • requireMention: false включает автоответ в этой комнате.
  • groups."*" задаёт настройки по умолчанию для гейтинга по упоминанию для всех комнат.
  • groupAllowFrom ограничивает, какие отправители могут активировать бота в комнатах (полные ID пользователей Matrix).
  • Списки доступа users для конкретной комнаты могут дополнительно ограничить отправителей (используйте полные ID пользователей Matrix).
  • Мастер настройки запрашивает списки доступа комнат (ID комнат, алиасы или имена) и преобразует имена только при точном уникальном совпадении.
  • При запуске OpenClaw преобразует имена комнат/пользователей в списках доступа в ID и логирует соответствие; непреобразованные записи игнорируются для сопоставления.
  • Приглашения принимаются автоматически по умолчанию; управляйте через channels.matrix.autoJoin и channels.matrix.autoJoinAllowlist.
  • Для запрета всех комнат задайте channels.matrix.groupPolicy: "disabled" (или оставьте пустой список доступа).
  • Устаревший ключ: channels.matrix.rooms (такая же структура, как groups).

Потоки

  • Ответы в потоках поддерживаются.
  • channels.matrix.threadReplies управляет тем, остаются ли ответы в потоках:
    • off, inbound (по умолчанию), always
  • channels.matrix.replyToMode управляет метаданными reply-to при ответе вне потока:
    • off (по умолчанию), first, all

Возможности

ФункцияСтатус
Прямые сообщенияПоддерживается
КомнатыПоддерживается
ПотокиПоддерживается
МедиаПоддерживается
E2EEПоддерживается (требуется криптомодуль)
РеакцииПоддерживается (отправка/чтение через инструменты)
ОпросыОтправка поддерживается; входящие poll start преобразуются в текст (ответы/завершения игнорируются)
ГеолокацияПоддерживается (geo URI; высота игнорируется)
Нативные командыПоддерживается

Устранение неполадок

Выполните эти команды первыми:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Затем проверьте состояние спаривания ЛС при необходимости:

openclaw pairing list matrix

Частые сбои:

  • Вход выполнен, но сообщения комнат игнорируются: комната заблокирована groupPolicy или списком доступа комнат.
  • ЛС игнорируются: отправитель ожидает подтверждения при channels.matrix.dm.policy="pairing".
  • Зашифрованные комнаты не работают: несоответствие криптографической поддержки или настроек шифрования.

Процесс диагностики: /channels/troubleshooting.

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

Полная конфигурация: Конфигурация

Опции провайдера:

  • channels.matrix.enabled: включение/выключение запуска канала.
  • channels.matrix.homeserver: URL домашнего сервера.
  • channels.matrix.userId: ID пользователя Matrix (необязательно при наличии токена доступа).
  • channels.matrix.accessToken: токен доступа.
  • channels.matrix.password: пароль для входа (токен сохраняется).
  • channels.matrix.deviceName: отображаемое имя устройства.
  • channels.matrix.encryption: включение E2EE (по умолчанию: false).
  • channels.matrix.initialSyncLimit: лимит начальной синхронизации.
  • channels.matrix.threadReplies: off | inbound | always (по умолчанию: inbound).
  • channels.matrix.textChunkLimit: размер исходящего текстового чанка (символы).
  • channels.matrix.chunkMode: length (по умолчанию) или newline для разделения по пустым строкам (границам абзацев) перед разбивкой по длине.
  • channels.matrix.dm.policy: pairing | allowlist | open | disabled (по умолчанию: pairing).
  • channels.matrix.dm.allowFrom: список доступа ЛС (полные ID пользователей Matrix). Для open нужен "*". Мастер преобразует имена в ID при возможности.
  • channels.matrix.groupPolicy: allowlist | open | disabled (по умолчанию: allowlist).
  • channels.matrix.groupAllowFrom: список доступа отправителей для групповых сообщений (полные ID пользователей Matrix).
  • channels.matrix.allowlistOnly: принудительное применение правил списка доступа для ЛС + комнат.
  • channels.matrix.groups: список доступа групп + настройки по комнатам.
  • channels.matrix.rooms: устаревший список доступа/конфигурация групп.
  • channels.matrix.replyToMode: режим reply-to для потоков/тегов.
  • channels.matrix.mediaMaxMb: лимит входящих/исходящих медиа (МБ).
  • channels.matrix.autoJoin: обработка приглашений (always | allowlist | off, по умолчанию: always).
  • channels.matrix.autoJoinAllowlist: разрешённые ID/алиасы комнат для автоприсоединения.
  • channels.matrix.accounts: мульти-аккаунтная конфигурация по ID аккаунта (каждый аккаунт наследует настройки верхнего уровня).
  • channels.matrix.actions: управление действиями по инструментам (reactions/messages/pins/memberInfo/channelInfo).
arrow_back
Назад
Line
Далее
Mattermost
arrow_forward