🏠 Главная › User Guide › matrix

sidebar_position: 9 title: "Matrix" description: "Set up Hermes Agent as a Matrix bot" lang: ru

Настройка матрицы

Hermes Agent интегрируется с Matrix, открытым федеративным протоколом обмена сообщениями. Matrix позволяет вам запустить собственный домашний сервер или использовать общедоступный, такой как Matrix.org — в любом случае вы сохраняете контроль над своими коммуникациями. Бот подключается через mautrix Python SDK, обрабатывает сообщения через конвейер агента Hermes (включая использование инструментов, память и рассуждения) и отвечает в режиме реального времени. Он поддерживает текст, вложения файлов, изображения, аудио, видео и дополнительное сквозное шифрование (E2EE).

Hermes работает с любым домашним сервером Matrix — Synapse, Conduit, Dendrite или Matrix.org.

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

Как ведет себя Гермес

Контекст Поведение
DM Гермес отвечает на каждое сообщение. @mention не требуется. У каждого DM есть своя сессия. Установите MATRIX_DM_MENTION_THREADS=true, чтобы запускать тред, когда бот @mentioned находится в личном сообщении.
Номера По умолчанию для ответа Hermes требуется @mention. Установите MATRIX_REQUIRE_MENTION=false или добавьте идентификаторы комнат к MATRIX_FREE_RESPONSE_ROOMS для комнат с бесплатным ответом. Приглашения в комнаты принимаются автоматически.
Темы Hermes поддерживает потоки Matrix (MSC3440). Если вы отвечаете в теме, Hermes сохраняет контекст темы изолированным от основной временной шкалы комнаты. Темы, в которых уже участвовал бот, упоминания не требуют.
Автоматическая обработка По умолчанию Hermes автоматически создает цепочку сообщений для каждого сообщения, на которое отвечает в комнате. Это делает разговоры изолированными. Установите MATRIX_AUTO_THREAD=false для отключения.
Общие комнаты с несколькими пользователями По умолчанию Hermes изолирует историю сеансов каждого пользователя внутри комнаты. Два человека, разговаривающие в одной комнате, не будут использовать одну стенограмму, если вы явно не отключите ее.

:::совет Бот автоматически присоединяется к комнатам по приглашению. Просто пригласите пользователя Matrix бота в любую комнату, и он присоединится и начнет отвечать.

Модель сеанса в матрице

По умолчанию:

Это контролируется config.yaml:

group_sessions_per_user: true

Установите значение false только в том случае, если вы явно хотите, чтобы один общий разговор был доступен для всей комнаты:

group_sessions_per_user: false

Общие сеансы могут быть полезны для совместной комнаты, но они также означают:

Упоминание и конфигурация потоков

Вы можете настроить упоминание и поведение автоматической многопоточности с помощью переменных среды или config.yaml:

matrix:
  require_mention: true           # Require @mention in rooms (default: true)
  free_response_rooms:            # Rooms exempt from mention requirement
    - "!abc123:matrix.org"
  auto_thread: true               # Auto-create threads for responses (default: true)
  dm_mention_threads: false       # Create thread when @mentioned in DM (default: false)

Или через переменные среды:

MATRIX_REQUIRE_MENTION=true
MATRIX_FREE_RESPONSE_ROOMS=!abc123:matrix.org,!def456:matrix.org
MATRIX_AUTO_THREAD=true
MATRIX_DM_MENTION_THREADS=false
MATRIX_REACTIONS=true          # default: true — emoji reactions during processing

💡 Tip

Отключение реакций `MATRIX_REACTIONS=false` отключает эмодзи-реакции жизненного цикла обработки (👀/ ✅/❌), которые бот публикует на входящие сообщения. Полезно для комнат, где события реакции шумные или не поддерживаются всеми участвующими клиентами.

:::примечание Если вы обновляетесь с версии, в которой не было MATRIX_REQUIRE_MENTION, бот ранее отвечал на все сообщения в комнатах. Чтобы сохранить это поведение, установите MATRIX_REQUIRE_MENTION=false. Это руководство проведет вас через весь процесс настройки — от создания учетной записи бота до отправки первого сообщения.

Шаг 1: Создайте учетную запись бота

Для работы бота вам понадобится учетная запись пользователя Matrix. Есть несколько способов сделать это:

Вариант А: зарегистрируйтесь на своем домашнем сервере (рекомендуется)

Если вы используете собственный домашний сервер (Synapse, Conduit, Dendrite):

  1. Используйте API администратора или инструмент регистрации, чтобы создать нового пользователя:
# Synapse example
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008
  1. Выберите имя пользователя, например hermes — полный идентификатор пользователя будет @hermes:your-server.org.

Вариант Б: используйте Matrix.org или другой публичный домашний сервер

  1. Перейдите в Element Web и создайте новую учетную запись.
  2. Выберите имя пользователя для своего бота (например, hermes-bot).

Вариант C: использовать свою учетную запись

Вы также можете запустить Hermes как свой собственный пользователь. Это означает, что бот публикует сообщения от вашего имени — полезно для личных помощников.

Шаг 2. Получите токен доступа

Гермесу нужен токен доступа для аутентификации на домашнем сервере. У вас есть два варианта:

Вариант A: токен доступа (рекомендуется)

Самый надежный способ получить токен:

Через элемент: 1. Войдите в Element под учетной записью бота. 2. Откройте Настройки → Справка и информация. 3. Прокрутите вниз и разверните Дополнительно — там отображается токен доступа. 4. Скопируйте немедленно.

Через API:

curl -X POST https://your-server/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "@hermes:your-server.org",
    "password": "your-password"
  }'

В ответе есть поле access_token — скопируйте его.

:::предупреждение[Храните свой токен доступа в безопасности] Токен доступа дает полный доступ к учетной записи бота Matrix. Никогда не делитесь им публично и не передавайте его в Git. В случае взлома отмените его, выполнив выход из всех сеансов этого пользователя.

Вариант Б: Вход с паролем

Вместо предоставления токена доступа вы можете предоставить Hermes идентификатор пользователя и пароль бота. Гермес автоматически войдет в систему при запуске. Это проще, но означает, что пароль хранится в вашем файле .env.

MATRIX_USER_ID=@hermes:your-server.org
MATRIX_PASSWORD=your-password

Шаг 3. Найдите свой идентификатор пользователя Matrix

Агент Hermes использует ваш идентификатор пользователя Matrix, чтобы контролировать, кто может взаимодействовать с ботом. Идентификаторы пользователей матрицы имеют формат @username:server.

Чтобы найти свой:

  1. Откройте Element (или предпочитаемый вами клиент Matrix).
  2. Нажмите на свой аватар → Настройки.
  3. Ваш идентификатор пользователя отображается в верхней части профиля (например, @alice:matrix.org).

:::совет Идентификаторы пользователей Matrix всегда начинаются с @ и содержат :, за которым следует имя сервера. Например: @alice:matrix.org, @bob:your-server.com.

Шаг 4. Настройка агента Hermes

Вариант A: Интерактивная настройка (рекомендуется)

Запустите команду управляемой настройки:

hermes gateway setup

При появлении запроса выберите Матрица, а затем укажите URL-адрес домашнего сервера, токен доступа (или идентификатор пользователя + пароль) и разрешенные идентификаторы пользователей, когда его спросят.

Вариант Б: настройка вручную

Добавьте следующее в свой файл ~/.hermes/.env:

Использование токена доступа:

# Required
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=***

# Optional: user ID (auto-detected from token if omitted)
# MATRIX_USER_ID=@hermes:matrix.example.org

# Security: restrict who can interact with the bot
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

# Multiple allowed users (comma-separated)
# MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org

Использование пароля для входа:

# Required
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_USER_ID=@hermes:matrix.example.org
MATRIX_PASSWORD=***

# Security
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

Дополнительные настройки поведения в ~/.hermes/config.yaml:

group_sessions_per_user: true

Запуск шлюза

После настройки запустите шлюз Matrix:

hermes gateway

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

:::совет Вы можете запустить hermes gateway в фоновом режиме или в качестве службы systemd для постоянной работы. Подробности см. в документации по развертыванию.

Сквозное шифрование (E2EE)

Hermes поддерживает сквозное шифрование Matrix, поэтому вы можете общаться со своим ботом в зашифрованных комнатах.

Требования

Для E2EE требуется библиотека mautrix с дополнительными функциями шифрования и библиотека libolm C:

# Install mautrix with E2EE support
pip install 'mautrix[encryption]'

# Or install with hermes extras
pip install 'hermes-agent[matrix]'

Вам также необходимо установить libolm в вашей системе:

# Debian/Ubuntu
sudo apt install libolm-dev

# macOS
brew install libolm

# Fedora
sudo dnf install libolm-devel

Включить E2EE

Добавьте в свой ~/.hermes/.env:

MATRIX_ENCRYPTION=true

Когда E2EE включен, Hermes:

Проверка перекрестной подписи (рекомендуется)

Если в вашей учетной записи Matrix включена перекрестная подпись (по умолчанию в Element), установите ключ восстановления, чтобы бот мог самостоятельно подписывать свое устройство при запуске. Без этого другие клиенты Matrix могут отказаться делиться сеансами шифрования с ботом после смены ключа устройства.

MATRIX_RECOVERY_KEY=EsT... your recovery key here

Где его найти: В Element выберите Настройки → Безопасность и конфиденциальность → Шифрование → ваш ключ восстановления (также называемый «Ключ безопасности»). Это ключ, который вас попросили сохранить при первой настройке перекрестной подписи.

Если при каждом запуске установлен MATRIX_RECOVERY_KEY, Hermes импортирует ключи перекрестной подписи из безопасного секретного хранилища домашнего сервера и подписывает текущее устройство. Это идемпотентно, и его можно безопасно оставить включенным навсегда.

:::предупреждение[Удаление криптохранилища] Если вы удалите ~/.hermes/platforms/matrix/store/crypto.db, бот потеряет свою шифровальную идентификацию. Простой перезапуск с тем же идентификатором устройства не полностью восстановится — домашний сервер по-прежнему хранит одноразовые ключи, подписанные старым ключом идентификации, а одноранговые узлы не могут устанавливать новые сеансы Olm.

Hermes обнаруживает это состояние при запуске и отказывается включать E2EE, записывая в журнал: device XXXX has stale one-time keys on the server signed with a previous identity key.

Самое простое восстановление: создайте новый токен доступа (который получает новый идентификатор устройства без устаревшей истории ключей). См. раздел «Обновление предыдущей версии с помощью E2EE» ниже. Это наиболее надежный путь, позволяющий избежать вмешательства в базу данных домашнего сервера.

Восстановление вручную (расширенное — сохраняет тот же идентификатор устройства):

  1. Остановите Synapse и удалите старое устройство из его базы данных: bash sudo systemctl stop matrix-synapse sudo sqlite3 /var/lib/matrix-synapse/homeserver.db " DELETE FROM e2e_device_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server'; DELETE FROM e2e_one_time_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server'; DELETE FROM e2e_fallback_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server'; DELETE FROM devices WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server'; " sudo systemctl start matrix-synapse Или через API администратора Synapse (обратите внимание на идентификатор пользователя в URL-адресе): bash curl -X DELETE -H "Authorization: Bearer ADMIN_TOKEN" \ 'https://your-server/_synapse/admin/v2/users/%40hermes%3Ayour-server/devices/DEVICE_ID' Примечание. Удаление устройства через API администратора также может привести к аннулированию связанного токена доступа. Возможно, после этого вам придется сгенерировать новый токен.

  2. Удалите локальный криптомагазин и перезапустите Hermes: bash rm -f ~/.hermes/platforms/matrix/store/crypto.db* # restart hermes

Другие клиенты Matrix (Element, Matrix-Commander) могут кэшировать старые ключи устройства. После восстановления введите /discardsession в Element, чтобы принудительно провести новый сеанс шифрования с ботом. :::информация Если mautrix[encryption] не установлен или libolm отсутствует, бот автоматически переключается на простой (незашифрованный) клиент. Вы увидите предупреждение в журналах.

Домашняя комната

Вы можете назначить «домашнюю комнату», куда бот будет отправлять упреждающие сообщения (например, выходные данные заданий cron, напоминания и уведомления). Есть два способа установить его:

Использование команды косой черты

Введите /sethome в любой комнате Матрицы, где присутствует бот. Эта комната становится домашней комнатой.

Ручная настройка

Добавьте это в свой ~/.hermes/.env:

MATRIX_HOME_ROOM=!abc123def456:matrix.example.org

:::совет Чтобы найти идентификатор комнаты: в Element перейдите в комнату → Настройки → Дополнительно → там отображается Внутренний идентификатор комнаты (начинается с !).

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

Бот не отвечает на сообщения

Причина: Бот не присоединился к комнате или MATRIX_ALLOWED_USERS не содержит ваш идентификатор пользователя.

Исправление: пригласите бота в комнату — он автоматически присоединяется по приглашению. Убедитесь, что ваш идентификатор пользователя имеет формат MATRIX_ALLOWED_USERS (используйте полный формат @user:server). Перезапустите шлюз.

«Не удалось выполнить аутентификацию» / «Ошибка Whoami» при запуске

Причина: токен доступа или URL-адрес домашнего сервера неверен.

Исправление. Убедитесь, что MATRIX_HOMESERVER указывает на ваш домашний сервер (включая https://, no trailing slash). Check that MATRIX_ACCESS_TOKEN is valid — try it with curl:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/_matrix/client/v3/account/whoami

If this returns your user info, the token is valid. If it returns an error, generate a new token.

"mautrix not installed" error

Cause: The mautrix Python package is not installed.

Fix: Install it:

pip install 'mautrix[encryption]'

Or with Hermes extras:

pip install 'hermes-agent[matrix]'

Encryption errors / "could not decrypt event"

Cause: Missing encryption keys, libolm not installed, or the bot's device isn't trusted.

Fix: 1. Verify libolm is installed on your system (see the E2EE section above). 2. Make sure MATRIX_ ENCRYPTION=true is set in your .env. 3. In your Matrix client (Element), go to the bot's profile -> Sessions -> verify/trust the bot's device. 4. If the bot just joined an encrypted room, it can only decrypt messages sent after it joined. Older messages are inaccessible.

Upgrading from a previous version with E2EE

💡 Tip

If you also manually deleted `crypto.db`, see the "Deleting the crypto store" warning in the E2EE section above — there are additional steps to clear stale one-time keys from the homeserver.

If you previously used Hermes with MATRIX_ENCRYPTION=true and are upgrading to a version that uses the new SQLite-based crypto store, the bot's encryption identity has changed. Your Matrix client (Element) may cache the old device keys and refuse to share encryption sessions with the bot.

Symptoms: The bot connects and shows "E2EE enabled" in the logs, but all messages show "could not decrypt event" and the bot never responds.

What's happening: The old encryption state (from the previous matrix -nio or serialization-based mautrix backend) is incompatible with the new SQLite crypto store. The bot creates a fresh encryption identity, but your Matrix client still has the old keys cached and won't share the room's encryption session with a device whose keys changed. This is a Matrix security feature -- clients treat changed identity keys for the same device as suspicious.

Fix (one-time migration):

  1. Generate a new access token to get a fresh device ID. The simplest way:

bash curl -X POST https://your-server/_matrix/client/v3/login \ -H "Content-Type: application/json" \ -d '{ "type": "m.login.password", "identifier": {"type": "m.id.user", "user": "@hermes:your-server.org"}, "password": "***", "initial_device_display_name": "Hermes Agent" }'

Copy the new access_token and update MATRIX_ACCESS_TOKEN in ~/.hermes/.en v.

  1. Delete old encryption state:

bash rm -f ~/.hermes/platforms/matrix/store/crypto.db rm -f ~/.hermes/platforms/matrix/store/crypto_store.*

  1. Set your recovery key (if you use cross-signing — most Element users do). Add to ~/.hermes/.env:

bash MATRIX_RECOVERY_KEY=EsT... your recovery key here

This lets the bot self-sign with cross-signing keys on startup, so Element trusts the new device immediately. Without this, Element may see the new device as unverified and refuse to share encryption sessions. Find your recovery key in Element under Settings → Security & Privacy → Encryption.

  1. Force your Matrix client to rotate the encryption session. In Element, open the DM room with the bot and type /discardsession. This forces Element to create a new encryption session and share it with the bot's new device.

  2. Restart the gateway:

bash hermes gateway run

If MATRIX_RECOVERY_KEY is set, you should see Matrix: перекрестная подпись проверена через восстановление key in the logs.

  1. Send a new message. The bot should decrypt and respond normally.

📝 Note

After migration, messages sent *before* the upgrade cannot be decrypted -- the old encryption keys are gone. This only affects the transition; new messages work normally.

💡 Tip

**New installations are not affected.** This migration is only needed if you had a working E2EE setup with a previous version of Hermes and are upgrading. **Why a new access token?** Each Matrix access token is bound to a specific device ID. Reusing the same device ID with new encryption keys causes other Matrix clients to distrust the device (they see changed identity keys as a potential security breach). A new access token gets a new device ID with no stale key history, so other clients trust it immediately.

Proxy Mode (E2EE on macOS)

Matrix E2EE requires libolm, which doesn't compile on macOS ARM64 (Apple Silicon). The hermes-agent[matrix] extra is gated to Linux only. If you're on macOS, proxy mode lets you run E2EE in a Docker container on a Linux VM while the actual agent runs natively on macOS with full access to your local files, memory, and skills.

How It Works

macOS (Host):
  └─ hermes gateway
       ├─ api_server adapter ← listens on 0.0.0.0:8642
       ├─ AIAgent ← single source of truth
       ├─ Sessions, memory, skills
       └─ Local file access (Obsidian, projects, etc.)

Linux VM (Docker):
  └─ hermes gateway (proxy mode)
       ├─ Matrix adapter ← E2EE decryption/encryption
       └─ HTTP forward → macOS:8642/v1/chat/completions
           (no LLM API keys, no agent, no inference)

The Docker container only handles Matrix protocol + E2EE. When a message arrives, it decrypts it and forwards the text to the host via a standard HTTP request. The host runs the agent, calls tools, generates a response, and streams it back. The container encrypts and sends the response to Matrix. All sessions are unified — CLI, Matrix, Telegram, and any other platform share the same memory and conversation history.

Step 1: Configure the Host (macOS)

Enable the API server so the host accepts incoming requests from the Docker container.

Add to ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key-here
API_SERVER_HOST=0.0.0.0

Start the gateway:

hermes gateway

You should see the API server start alongside any other platforms you have configured. Verify it's reachable from the VM:

# From the Linux VM
curl http://<mac-ip>:8642/health

Step 2: Configure the Docker Container (Linux VM)

The container needs Matrix credentials and the proxy URL. It does NOT need LLM API keys.

docker-compose.yml:

services:
  hermes-matrix:
    build: .
    environment:
      # Matrix credentials
      MATRIX_HOMESERVER: "https://matrix.example.org"
      MATRIX_ACCESS_TOKEN: "syt_..."
      MATRIX_ALLOWED_USERS: "@you:matrix.example.org"
      MATRIX_ENCRYPTION: "true"
      MATRIX_DEVICE_ID: "HERMES_BOT"

      # Proxy mode — forward to host agent
      GATEWAY_PROXY_URL: "http://192.168.1.100:8642"
      GATEWAY_PROXY_KEY: "your-secret-key-here"
    volumes:
      - ./matrix-store:/root/.hermes/platforms/matrix/store

Dockerfile:

FROM python:3.11-slim

RUN apt-get update && apt-get install -y libolm-dev && rm -rf /var/lib/apt/lists/*
RUN pip install 'hermes-agent[matrix]'

CMD ["hermes", "gateway"]

That's the entire container. No API keys for OpenRouter, Anthropic, or any inference provider.

Step 3: Start Both

  1. Start the host gateway first: bash hermes gateway

  2. Start the Docker container: bash docker compose up -d

  3. Send a message in an encrypted Matrix room. The container decrypts it, forwards it to the host, and streams the response back.

Configuration Reference

Proxy mode is configured on the container side (the thin gateway):

Setting Description
GATEWAY_PROXY_URL URL of the remote Hermes API server (e.g., http://192.168.1.100:8642)
GATEWAY_PROXY_KEY Токен носителя для аутентификации (должен соответствовать API_SERVER_KEY на хосте)
gateway.proxy_url То же, что GATEWAY_PROXY_URL, но в config.yaml

Принимающей стороне необходимо:

Настройка Описание
API_SERVER_ENABLED Установите true
API_SERVER_KEY Токен на предъявителя (совместно с контейнером)
API_SERVER_HOST Установите 0.0.0.0 для доступа к сети
API_SERVER_PORT Номер порта (по умолчанию: 8642)

Работает для любой платформы

Режим прокси не ограничивается Matrix. Его может использовать любой адаптер платформы — установите GATEWAY_PROXY_URL на любом экземпляре шлюза, и он будет пересылать данные удаленному агенту, а не запускать его локально. Это полезно для любого развертывания, когда адаптер платформы должен работать в среде, отличной от среды агента (сетевая изоляция, требования E2EE, ограничения ресурсов).

:::совет Непрерывность сеанса поддерживается с помощью заголовка X-Hermes-Session-Id. Сервер API хоста отслеживает сеансы по этому идентификатору, поэтому диалоги сохраняются между сообщениями так же, как и с локальным агентом. :::примечание Ограничения (версия 1): Сообщения о ходе работы инструмента от удаленного агента не передаются обратно — пользователь видит только потоковый окончательный ответ, а не отдельные вызовы инструмента. Запросы на одобрение опасных команд обрабатываются на стороне хоста, а не передаются пользователю Matrix. Эти проблемы могут быть устранены в будущих обновлениях.

Проблемы с синхронизацией / бот отстает

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

Исправление: В случае ошибки цикл синхронизации автоматически повторяется каждые 5 секунд. Проверьте журналы Hermes на наличие предупреждений, связанных с синхронизацией. Если бот постоянно отстает, убедитесь, что на вашем домашнем сервере достаточно ресурсов.

Бот не в сети

Причина: шлюз Hermes не работает или не удалось подключиться.

Исправление: убедитесь, что hermes gateway работает. Посмотрите на вывод терминала сообщения об ошибках. Распространенные проблемы: неправильный URL-адрес домашнего сервера, срок действия токена доступа истек, домашний сервер недоступен.

«Пользователь не разрешен» / Бот вас игнорирует

Причина: вашего идентификатора пользователя нет в MATRIX_ALLOWED_USERS.

Исправление: добавьте свой идентификатор пользователя в MATRIX_ALLOWED_USERS в ~/.hermes/.env и перезапустите шлюз. Используйте полный формат @user:server.

Безопасность

:::предупреждение Всегда устанавливайте MATRIX_ALLOWED_USERS, чтобы ограничить круг лиц, которые могут взаимодействовать с ботом. Без него шлюз по умолчанию запрещает доступ всем пользователям в качестве меры безопасности. Добавляйте идентификаторы пользователей только тех людей, которым вы доверяете — авторизованные пользователи имеют полный доступ к возможностям агента, включая использование инструментов и доступ к системе. Дополнительную информацию о защите вашего агента Hermes см. в Руководстве по безопасности.

Примечания