Перейти к содержанию

Matrix

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

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

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

Как ведёт себя Hermes​

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

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

Модель сессий в Matrix​

По умолчанию: * каждая ЛС получает свою собственную сессию * каждый тред получает своё собственное пространство имён сессии * каждый пользователь в общей комнате получает свою собственную сессию внутри этой комнаты

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

[code] group_sessions_per_user: true

[/code]

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

[code] group_sessions_per_user: false

[/code]

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

Конфигурация упоминаний и тредов​

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

[code] matrix:
require_mention: true # Требовать @упоминание в комнатах (по умолчанию: true)
free_response_rooms: # Комнаты, освобождённые от требования упоминания
- "!abc123:matrix.org"
auto_thread: true # Авто-создание тредов для ответов (по умолчанию: true)
dm_mention_threads: false # Создавать тред при @упоминании в ЛС (по умолчанию: false)

[/code]

Или через переменные окружения:

[code] 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-реакции во время обработки

[/code]

Отключение реакций

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

note Если вы обновляетесь с версии, в которой не было MATRIX_REQUIRE_MENTION, бот ранее отвечал на все сообщения в комнатах. Чтобы сохранить такое поведение, установите MATRIX_REQUIRE_MENTION=false.

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

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

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

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

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

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

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

[/code]

  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:

[code] 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"
}'

[/code]

Ответ содержит поле access_token — скопируйте его.

keep-your-access-token-safe Токен доступа предоставляет полный доступ к учётной записи бота в Matrix. Никогда не публикуйте его открыто и не сохраняйте в Git. В случае компрометации отзовите его, выйдя из всех сессий этого пользователя.

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

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

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

[/code]

Шаг 3: Поиск вашего Matrix User ID​

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

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

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

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

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

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

[code] hermes gateway setup

[/code]

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

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

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

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

[code] # Обязательно
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

[/code]

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

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

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

[/code]

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

[code] group_sessions_per_user: true

[/code]

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

Запуск шлюза​

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

[code] hermes gateway

[/code]

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

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

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

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

Требования​

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

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

# Или установка с расширениями hermes  
pip install 'hermes-agent[matrix]'

[/code]

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

[code] # Debian/Ubuntu
sudo apt install libolm-dev 

# macOS  
brew install libolm

# Fedora  
sudo dnf install libolm-devel

[/code]

Включение E2EE​

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

[code] MATRIX_ENCRYPTION=true

[/code]

Когда E2EE включено, Hermes: * Хранит ключи шифрования в ~/.hermes/platforms/matrix/store/ (для старых установок: ~/.hermes/matrix/store/) * Загружает ключи устройства при первом подключении * Автоматически расшифровывает входящие сообщения и шифрует исходящие * Автоматически присоединяется к зашифрованным комнатам при приглашении

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

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

[code] MATRIX_RECOVERY_KEY=EsT... ваш ключ восстановления здесь

[/code]

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

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

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

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

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

Ручное восстановление (продвинутый — сохраняет тот же ID устройства): 1. Остановите Synapse и удалите старое устройство из его базы данных:

[code] 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

[/code]

Или через Synapse admin API (обратите внимание на URL-закодированный ID пользователя):

[code] curl -X DELETE -H "Authorization: Bearer ADMIN_TOKEN" \
'https://your-server/_synapse/admin/v2/users/%40hermes%3Ayour-server/devices/DEVICE_ID'

[/code]

Примечание: удаление устройства через admin API также может аннулировать связанный токен доступа. Возможно, потребуется сгенерировать новый токен. 2. Удалите локальное крипто-хранилище и перезапустите Hermes:

[code] rm -f ~/.hermes/platforms/matrix/store/crypto.db*
# перезапустите hermes

[/code]

Другие Matrix-клиенты (Element, matrix-commander) могут кэшировать старые ключи устройства. После восстановления введите /discardsession в Element, чтобы принудительно создать новую сессию шифрования с ботом.

info Если mautrix[encryption] не установлен или libolm отсутствует, бот автоматически переключается на обычный (незашифрованный) клиент. Вы увидите предупреждение в логах.

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

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

Использование слеш-команды​

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

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

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

[code] MATRIX_HOME_ROOM=!abc123def456:matrix.example.org

[/code]

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

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

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

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

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

«Failed to authenticate» / «whoami failed» при запуске​

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

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

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

[/code]

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

Ошибка «mautrix not installed»​

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

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

[code] pip install 'mautrix[encryption]'

[/code]

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

[code] pip install 'hermes-agent[matrix]'

[/code]

Ошибки шифрования / «could not decrypt event»​

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

Решение: 1. Убедитесь, что libolm установлен в вашей системе (см. раздел E2EE выше). 2. Убедитесь, что MATRIX_ENCRYPTION=true установлен в вашем .env. 3. В вашем Matrix-клиенте (Element) перейдите в профиль бота → Сессии → проверьте/подтвердите доверие устройству бота. 4. Если бот только что присоединился к зашифрованной комнате, он может расшифровывать только сообщения, отправленные после его входа. Старые сообщения недоступны.

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

tip Если вы также вручную удалили crypto.db, см. предупреждение «Удаление крипто-хранилища» в разделе E2EE выше — там описаны дополнительные шаги по очистке устаревших одноразовых ключей на homeserver.

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

Симптомы: Бот подключается и показывает «E2EE enabled» в логах, но все сообщения отображаются как «could not decrypt event», и бот никогда не отвечает.

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

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

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

[code] 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"
}'

[/code]

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

  1. Удалите старое крипто-состояние:

[code] rm -f ~/.hermes/platforms/matrix/store/crypto.db
rm -f ~/.hermes/platforms/matrix/store/crypto_store.*

[/code]

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

[code] MATRIX_RECOVERY_KEY=EsT... ваш ключ восстановления здесь

[/code]

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

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

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

[code] hermes gateway run

[/code]

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

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

note После миграции сообщения, отправленные до обновления, не могут быть расшифрованы — старые ключи шифрования удалены. Это влияет только на переходный период; новые сообщения работают нормально.

tip Новые установки не затронуты. Эта миграция нужна только в том случае, если у вас была работающая настройка E2EE с предыдущей версией Hermes и вы обновляетесь.

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

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

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

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

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

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

[/code]

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

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

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

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

[code] API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key-here
API_SERVER_HOST=0.0.0.0

[/code]

  • API_SERVER_HOST=0.0.0.0 привязывается ко всем интерфейсам, чтобы Docker-контейнер мог до него добраться.
  • API_SERVER_KEY требуется для привязки не к loopback. Выберите надёжную случайную строку.
  • API-сервер работает на порту 8642 по умолчанию (измените с помощью API_SERVER_PORT, если необходимо).

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

[code] hermes gateway

[/code]

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

[code] # Из Linux VM
curl http://:8642/health

[/code]

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

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

docker-compose.yml:

[code] 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

[/code]

Dockerfile:

[code] 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"]

[/code]

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

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

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

[code] hermes gateway

[/code]

  1. Запустите Docker-контейнер:

[code] docker compose up -d

[/code]

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

Справочник по конфигурации​

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

Настройка Описание
GATEWAY_PROXY_URL URL удалённого API-сервера Hermes (например, http://192.168.1.100:8642)
GATEWAY_PROXY_KEY Bearer-токен для аутентификации (должен совпадать с API_SERVER_KEY на хосте)
gateway.proxy_url То же, что и GATEWAY_PROXY_URL, но в config.yaml

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

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

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

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

tip Непрерывность сессии поддерживается через заголовок X-Hermes-Session-Id. API-сервер хоста отслеживает сессии по этому ID, так что разговоры сохраняются между сообщениями так же, как и с локальным агентом.

note Ограничения (v1): Сообщения о прогрессе инструментов от удалённого агента не ретранслируются обратно — пользователь видит только потоковый финальный ответ, а не отдельные вызовы инструментов. Запросы на подтверждение опасных команд обрабатываются на стороне хоста и не передаются пользователю Matrix. Это может быть исправлено в будущих обновлениях.

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

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

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

Бот не в сети​

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

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

«User not allowed» / Бот игнорирует вас​

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

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

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

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

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

Примечания​