Настройка Matrix

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

Hermes работает с любым Matrix homeserver — Synapse, Conduit, Dendrite или matrix.org.

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

Как работает Hermes

Модель сеансов в Matrix

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

• каждое ЛС получает собственный сеанс

• каждый тред получает собственное пространство имён сеанса

• каждый пользователь в общей комнате получает собственный сеанс внутри этой комнаты

Это управляется через config.yaml:

group_sessions_per_user: true

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

group_sessions_per_user: false

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

• пользователи делят рост контекста и затраты на токены

• длительная задача одного человека с интенсивным использованием инструментов может раздуть контекст для всех остальных

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

Настройка упоминаний и тредов

Вы можете настроить поведение упоминаний и авто-тредов через переменные окружения или config.yaml:

matrix:
  require_mention: true           # Требовать @упоминание в комнатах (по умолчанию: true)
  free_response_rooms:            # Комнаты, освобождённые от требования упоминания
    - "!abc123:matrix.org"
  auto_thread: true               # Автоматически создавать треды для ответов (по умолчанию: true)
  dm_mention_threads: false       # Создавать тред при @упоминании в ЛС (по умолчанию: 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          # по умолчанию: true — emoji-реакции во время обработки

Это руководство проведёт вас через полный процесс настройки — от создания учётной записи бота до отправки первого сообщения.

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

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

Вариант A: Регистрация на вашем homeserver (рекомендуется)

Если вы запускаете собственный homeserver (Synapse, Conduit, Dendrite):

1. Используйте admin API или инструмент регистрации для создания нового пользователя:

# Пример для Synapse
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008

1. Выберите имя пользователя, например hermes — полный ID пользователя будет @hermes:your-server.org.

Вариант B: Использование matrix.org или другого публичного homeserver

1. Перейдите на Element Web и создайте новую учётную запись.

2. Выберите имя пользователя для вашего бота (например, hermes-bot).

Вариант C: Использование собственной учётной записи

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

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

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

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

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

Через Element:

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 — скопируйте его.

Вариант B: Вход по паролю

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

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

Шаг 3: Найдите ваш Matrix User ID

Hermes Agent использует ваш Matrix User ID для контроля того, кто может взаимодействовать с ботом. Matrix User ID имеют формат @имя_пользователя:сервер.

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

1. Откройте Element (или ваш предпочитаемый Matrix-клиент).

2. Нажмите на ваш аватар → Настройки.

3. Ваш User ID отображается вверху профиля (например, @alice:matrix.org).

Шаг 4: Настройка Hermes Agent

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

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

hermes gateway setup

Выберите Matrix при запросе, затем укажите URL homeserver, токен доступа (или ID пользователя + пароль) и разрешённые ID пользователей.

Вариант B: Ручная настройка

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

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

# Обязательно
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=***

# Опционально: ID пользователя (автоопределяется из токена, если опущен)
# MATRIX_USER_ID=@hermes:matrix.example.org

# Безопасность: ограничьте, кто может взаимодействовать с ботом
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

# Несколько разрешённых пользователей (через запятую)
# MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org

С использованием входа по паролю:

# Обязательно
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_USER_ID=@hermes:matrix.example.org
MATRIX_PASSWORD=***

# Безопасность
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

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

group_sessions_per_user: true

• group_sessions_per_user: true изолирует контекст каждого участника внутри общих комнат

Запуск шлюза

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

hermes gateway

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

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

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

Требования

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

# Установка mautrix с поддержкой E2EE
pip install 'mautrix[encryption]'

# Или установка с расширениями hermes
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:

• Хранит ключи шифрования в ~/.hermes/platforms/matrix/store/ (для старых установок: ~/.hermes/matrix/store/)

• Загружает ключи устройства при первом подключении

• Автоматически расшифровывает входящие сообщения и шифрует исходящие

• Автоматически присоединяется к зашифрованным комнатам при приглашении

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

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

MATRIX_RECOVERY_KEY=EsT... ваш ключ восстановления

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

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

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

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

С помощью слеш-команды

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

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

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

MATRIX_HOME_ROOM=!abc123def456:matrix.example.org

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

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

Причина: Бот не присоединился к комнате, или MATRIX_ALLOWED_USERS не включает ваш User ID.

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

«Ошибка аутентификации» / «whoami не выполнена» при запуске

Причина: Неверный токен доступа или URL homeserver.

Решение: Проверьте, что MATRIX_HOMESERVER указывает на ваш homeserver (включая https://, без завершающего слеша). Убедитесь, что MATRIX_ACCESS_TOKEN действителен — проверьте с помощью curl:

curl -H "Authorization: Bearer YOUR_T... span class="w"> \\
  https://your-server/_matrix/client/v3/account/whoami

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

Ошибка «mautrix не установлен»

Причина: Пакет Python mautrix не установлен.

Решение: Установите его:

pip install 'mautrix[encryption]'

Или с расширениями Hermes:

pip install 'hermes-agent[matrix]'

Ошибки шифрования / «не удалось расшифровать событие»

Причина: Отсутствуют ключи шифрования, не установлен libolm или устройство бота не доверенное.

Решение:

1. Убедитесь, что libolm установлен в системе (см. раздел E2EE выше).

2. Проверьте, что MATRIX_ENCRYPTION=true установлен в вашем .env.

3. В вашем Matrix-клиенте (Element) перейдите в профиль бота → Сеансы → проверьте/подтвердите доверие устройству бота.

4. Если бот только что присоединился к зашифрованной комнате, он может расшифровывать только сообщения, отправленные после его присоединения. Более старые сообщения недоступны.

Обновление с предыдущей версии с E2EE

Если вы ранее использовали Hermes с MATRIX_ENCRYPTION=true и обновляетесь до версии, которая использует новое хранилище шифрования на основе SQLite, криптографическая идентичность бота изменилась. Ваш Matrix-клиент (Element) может кэшировать старые ключи устройства и отказываться делиться сеансами шифрования с ботом.

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

Что происходит: Старое состояние шифрования (от предыдущего matrix-nio или основанного на сериализации бэкенда mautrix) несовместимо с новым SQLite-хранилищем шифрования. Бот создаёт новую криптографическую идентичность, но ваш Matrix-клиент всё ещё имеет старые ключи в кэше и не поделится сеансом шифрования комнаты с устройством, чьи ключи изменились. Это функция безопасности Matrix — клиенты считают подозрительным изменение ключей идентичности для того же устройства.

Решение (однократная миграция):

1. Сгенерируйте новый токен доступа для получения нового ID устройства. Самый простой способ:

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"
}'

Скопируйте новый access_token и обновите MATRIX_ACCESS_TOKEN в ~/.hermes/.env.

1. Удалите старое состояние шифрования:

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

1. Установите ключ восстановления (если вы используете кросс-подпись — большинство пользователей Element используют её). Добавьте в ~/.hermes/.env:

bash
MATRIX_RECOVERY_KEY=EsT... ваш ключ восстановления

Это позволяет боту самостоятельно подписываться ключами кросс-подписи при запуске, поэтому Element сразу доверяет новому устройству. Без этого Element может считать новое устройство непроверенным и отказаться делиться сеансами шифрования. Найдите ключ восстановления в Element в Настройки → Безопасность и конфиденциальность → Шифрование.

1. Принудительно ротируйте сеанс шифрования в вашем Matrix-клиенте. В Element
   откройте комнату ЛС с ботом и введите /discardsession. Это заставит Element
   создать новый сеанс шифрования и поделиться им с новым устройством бота.

2. Перезапустите шлюз:

bash
hermes gateway run

Если MATRIX_RECOVERY_KEY установлен, вы должны увидеть Matrix: cross-signing verified via recovery key в логах.

1. Отправьте новое сообщение. Бот должен расшифровать его и ответить нормально.

Прокси-режим (E2EE на macOS)

Matrix E2EE требует libolm, который не компилируется на macOS ARM64 (Apple Silicon). Расширение hermes-agent[matrix] доступно только для Linux. Если вы на macOS, прокси-режим позволяет запустить E2EE в Docker-контейнере на Linux VM, в то время как сам агент работает нативно на macOS с полным доступом к локальным файлам, памяти и навыкам.

Как это работает

macOS (Хост):
  └─ hermes gateway
       ├─ api_server adapter ← слушает на 0.0.0.0:8642
       ├─ AIAgent ← единый источник истины
       ├─ Сеансы, память, навыки
       └─ Доступ к локальным файлам (Obsidian, проекты и т.д.)

Linux VM (Docker):
  └─ hermes gateway (прокси-режим)
       ├─ Matrix adapter ← расшифровка/шифрование E2EE
       └─ HTTP пересылка → macOS:8642/v1/chat/completions
           (нет ключей LLM API, нет агента, нет инференса)

Docker-контейнер обрабатывает только протокол Matrix + E2EE. Когда приходит сообщение, он расшифровывает его и пересылает текст на хост через стандартный HTTP-запрос. Хост запускает агента, вызывает инструменты, генерирует ответ и передаёт его обратно. Контейнер шифрует и отправляет ответ в Matrix. Все сеансы унифицированы — CLI, Matrix, Telegram и любая другая платформа используют одну и ту же память и историю бесед.

Шаг 1: Настройка хоста (macOS)

Включите API-сервер, чтобы хост принимал входящие запросы от Docker-контейнера.

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

API_SERVER_ENABLED=true
API_SERVER_KEY=ваш-секретный-ключ
API_SERVER_HOST=0.0.0.0

• API_SERVER_HOST=0.0.0.0 привязывается ко всем интерфейсам, чтобы Docker-контейнер мог до него добраться.

• API_SERVER_KEY обязателен для привязки не к локальному интерфейсу. Выберите надёжную случайную строку.

• API-сервер запускается на порту 8642 по умолчанию (измените с помощью API_SERVER_PORT при необходимости).

Запустите шлюз:

hermes gateway

Вы должны увидеть, как API-сервер запускается вместе с другими настроенными платформами. Проверьте его доступность из VM:

# Из Linux VM
curl http://<mac-ip>:8642/health

Шаг 2: Настройка Docker-контейнера (Linux VM)

Контейнеру нужны учётные данные Matrix и URL прокси. Ему НЕ нужны ключи LLM API.

docker-compose.yml:

services:
  hermes-matrix:
    build: .
    environment:
      # Учётные данные Matrix
      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"

      # Прокси-режим — пересылка агенту на хосте
      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"]

Это весь контейнер. Никаких ключей API для OpenRouter, Anthropic или любого провайдера инференса.

Шаг 3: Запуск обоих

1. Сначала запустите шлюз на хосте:
   bash
hermes gateway

2. Запустите Docker-контейнер:
   bash
docker compose up -d

3. Отправьте сообщение в зашифрованной Matrix-комнате. Контейнер расшифровывает его, пересылает на хост и передаёт ответ обратно.

Справочник по настройке

Прокси-режим настраивается на стороне контейнера (тонкий шлюз):

На стороне хоста нужно:

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

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

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

Причина: Длительные выполнения инструментов могут задерживать цикл синхронизации, или homeserver работает медленно.

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

Бот офлайн

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

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

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

Причина: Ваш User ID отсутствует в MATRIX_ALLOWED_USERS.

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

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

Для получения дополнительной информации о безопасности развёртывания Hermes Agent см. Руководство по безопасности.

Примечания

• Любой homeserver: Работает с Synapse, Conduit, Dendrite, matrix.org или любым совместимым со спецификацией Matrix homeserver. Не требуется какое-либо конкретное ПО для homeserver.

• Федерация: Если вы находитесь на федеративном homeserver, бот может общаться с пользователями с других серверов — просто добавьте их полные ID @user:server в MATRIX_ALLOWED_USERS.

• Авто-вступление: Бот автоматически принимает приглашения в комнаты и присоединяется. Он начинает отвечать сразу после присоединения.

• Поддержка медиа: Hermes может отправлять и получать изображения, аудио, видео и вложения файлов. Медиа загружается на ваш homeserver через Matrix content repository API.

• Нативные голосовые сообщения (MSC3245): Адаптер Matrix автоматически помечает исходящие голосовые сообщения флагом org.matrix.msc3245.voice. Это означает, что TTS-ответы и голосовое аудио отображаются как нативные голосовые пузырьки в Element и других клиентах, поддерживающих MSC3245, а не как обычные вложения аудиофайлов. Входящие голосовые сообщения с флагом MSC3245 также правильно идентифицируются и направляются на транскрипцию речи в текст. Никакой настройки не требуется — это работает автоматически.