Платформы для обмена сообщениями

Matrix

Matrix — это открытый, децентрализованный протокол обмена сообщениями. OpenClaw подключается как пользователь Matrix к любому домашнему серверу, поэтому для бота нужна учётная запись Matrix. После входа вы можете писать боту в личные сообщения или приглашать его в комнаты (Matrix «группы»). Beeper также является допустимым вариантом клиента, но требует включения сквозного шифрования (E2EE). Статус: поддерживается через плагин (@vector-im/matrix-bot-sdk). Личные сообщения, комнаты, ветки, медиа, реакции, опросы (отправка + начало опроса как текст), геолокация и сквозное шифрование (с поддержкой криптографии).

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

Matrix поставляется в виде плагина и не входит в базовую установку. Установите через CLI (npm registry):

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. Получите токен доступа для учётной записи бота:

    • Используйте API входа Matrix с помощью 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.*
    • Если заданы оба варианта, приоритет имеет конфигурация.
    • При наличии токена доступа: идентификатор пользователя автоматически получается через /whoami.
    • При установке channels.matrix.userId должен быть полным идентификатором Matrix (пример: @bot:example.org).

  5. Перезапустите шлюз (или завершите первоначальную настройку).

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

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

{
  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)

Сквозное шифрование поддерживается через криптографический SDK на Rust. Включите его с помощью channels.matrix.encryption: true:

  • Если криптомодуль загружается, зашифрованные комнаты расшифровываются автоматически.
  • Исходящие медиафайлы шифруются при отправке в зашифрованные комнаты.
  • При первом подключении OpenClaw запрашивает подтверждение устройства в ваших других сеансах.
  • Подтвердите устройство в другом клиенте Matrix (Element и т.д.), чтобы включить обмен ключами.
  • Если криптомодуль не может быть загружен, сквозное шифрование отключается, а зашифрованные комнаты не будут расшифровываться; 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. Если токен доступа (устройство) изменяется, создаётся новое хранилище, и бот должен быть повторно подтверждён для зашифрованных комнат. Подтверждение устройства: Когда включено сквозное шифрование, бот при запуске запросит подтверждение в ваших других сеансах. Откройте Element (или другой клиент) и одобрите запрос на подтверждение, чтобы установить доверие. После подтверждения бот сможет расшифровывать сообщения в зашифрованных комнатах.

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

Поддержка нескольких аккаунтов: используйте channels.matrix.accounts с учётными данными для каждого аккаунта и необязательным параметром name. См. общий шаблон в gateway/configuration. Каждый аккаунт работает как отдельный пользователь Matrix на любом домашнем сервере. Конфигурация для каждого аккаунта наследует настройки верхнего уровня channels.matrix и может переопределять любую опцию (политика ЛС, группы, шифрование и т.д.).

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Основной ассистент",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Бот оповещений",
          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 <КОД>
  • Открытые ЛС: channels.matrix.dm.policy="open" плюс channels.matrix.dm.allowFrom=["*"].
  • channels.matrix.dm.allowFrom принимает полные идентификаторы пользователей Matrix (пример: @user:server). Мастер настройки преобразует отображаемые имена в идентификаторы пользователей, когда поиск в каталоге находит одно точное совпадение.
  • Не используйте отображаемые имена или локальные части (пример: "Alice" или "alice"). Они неоднозначны и игнорируются при сопоставлении с белым списком. Используйте полные идентификаторы @user:server.

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

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

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

Сначала выполните эту последовательность:

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: Идентификатор пользователя Matrix (необязательно при наличии токена доступа).
  • channels.matrix.accessToken: токен доступа.
  • channels.matrix.password: пароль для входа (токен сохраняется).
  • channels.matrix.deviceName: отображаемое имя устройства.
  • channels.matrix.encryption: включить сквозное шифрование (по умолчанию: 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: белый список для ЛС (полные идентификаторы пользователей Matrix). open требует "*". Мастер преобразует имена в идентификаторы, когда это возможно.
  • channels.matrix.groupPolicy: allowlist | open | disabled (по умолчанию: allowlist).
  • channels.matrix.groupAllowFrom: разрешённые отправители для групповых сообщений (полные идентификаторы пользователей Matrix).
  • 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: разрешённые идентификаторы/псевдонимы комнат для автоматического присоединения.
  • channels.matrix.accounts: конфигурация нескольких аккаунтов с ключами в виде идентификаторов аккаунтов (каждый аккаунт наследует настройки верхнего уровня).
  • channels.matrix.actions: управление инструментами для каждого действия (реакции/сообщения/закрепления/информация об участниках/информация о канале).

LINEMattermost