Matrix (плагин)

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

Статус: поддерживается через плагин (@vector-im/matrix-bot-sdk). Личные сообщения, комнаты, треды, медиа, реакции, опросы (отправка + начало опроса как текст), местоположение и 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. Настройте учетные данные:

    • Окружение: 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 (или другой клиент) и одобрите запрос проверки для установления доверия. После проверки бот может расшифровывать сообщения в зашифрованных комнатах.

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

  • Ответы всегда возвращаются в 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 пользователей или отображаемые имена. Мастер разрешает отображаемые имена в ID пользователей, когда доступен поиск в каталоге.

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

  • По умолчанию: channels.matrix.groupPolicy = "allowlist" (с упоминанием). Используйте channels.defaults.groupPolicy для переопределения значения по умолчанию, если не установлено.
  • Список разрешенных комнат с channels.matrix.groups (ID комнат, псевдонимы или имена):
{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true }
      },
      groupAllowFrom: ["@owner:example.org"]
    }
  }
}
  • requireMention: false включает авто-ответ в этой комнате.
  • groups."*" может устанавливать значения по умолчанию для упоминаний в комнатах.
  • groupAllowFrom ограничивает отправителей, которые могут активировать бота в комнатах (необязательно).
  • Списки разрешений users для каждой комнаты могут дополнительно ограничить отправителей внутри конкретной комнаты.
  • Мастер настройки запрашивает списки разрешенных комнат (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 контролирует метаданные ответа, когда не отвечает в треде:
    • off (по умолчанию), first, all

Возможности

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

Справочник по конфигурации (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 пользователей или отображаемые имена). open требует "*". Мастер разрешает имена в ID, когда это возможно.
  • channels.matrix.groupPolicy: allowlist | open | disabled (по умолчанию: allowlist).
  • channels.matrix.groupAllowFrom: список разрешенных отправителей для групповых сообщений.
  • channels.matrix.allowlistOnly: принудительное применение правил списка разрешений для личных сообщений + комнат.
  • channels.matrix.groups: карта списка разрешенных групп + настроек для каждой комнаты.
  • channels.matrix.rooms: устаревший список разрешенных групп/конфигурация.
  • channels.matrix.replyToMode: режим ответа для тредов/тегов.
  • channels.matrix.mediaMaxMb: лимит входящих/исходящих медиа (МБ).
  • channels.matrix.autoJoin: обработка приглашений (always | allowlist | off, по умолчанию: always).
  • channels.matrix.autoJoinAllowlist: разрешенные ID/псевдонимы комнат для автоприсоединения.
  • channels.matrix.actions: ограничение инструментов для каждого действия (реакции/сообщения/закрепления/memberInfo/channelInfo).
← Назад к документации