Интеграция платформенных сообщений Hermes Agent
Шлюз обмена сообщениями позволяетодному и тому же агенту— с одними и теми же воспоминаниями, навыками и инструментами — беспрепятственно работать на более чем 20 платформах.
В этой главе будут представлены настройка и развёртывание шлюза, жизненный цикл сеансов, политики изоляции нескольких пользователей, контроль доступа и безопасность.
Обзор шлюза обмена сообщениями
Шлюз обмена сообщениями — это постоянно работающий фоновый процесс, который централизованно управляет подключениями, сеансами, запланированными задачами и доставкой медиа для всех платформ обмена сообщениями.
Всё, чему вы учите агента в CLI — память, навыки, предпочтения — полностью согласовано на всех платформах.
Поддерживаемые платформы
Hermes поддерживает 20+ платформ обмена сообщениями: CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost, Email, SMS, DingTalk, Feishu/Lark, WeChat Work, micro信, QQ, 元宝, BlueBubbles (iMessage), Home Assistant, Microsoft Teams, Google Chat и т. д.
Сравнение возможностей платформ
| Платформа | Речь | Образы | Файл | строка сообщения | Эмодзи-реакция | Индикатор набора текста | Потоковый вывод |
|---|---|---|---|---|---|---|---|
| Telegram | Поддерживается | Поддерживается | Поддерживается | Поддерживается | — | Поддерживается | Поддерживается |
| Discord | Поддерживается | Поддерживается | Поддерживается | Поддерживается | Поддерживается | Поддерживается | Поддерживается |
| Slack | Поддерживается | Поддерживается | Поддерживается | Поддерживается | Поддерживается | Поддерживается | Поддерживается |
| — | Поддерживается | Поддерживается | — | — | Поддерживается | Поддерживается | |
| Signal | — | Поддерживается | Поддерживается | — | — | Поддерживается | Поддерживается |
| Feishu/Lark | Поддерживается | Поддерживается | Поддерживается | Поддерживается | Поддерживается | Поддерживается | Поддерживается |
| WeChat Work | Поддерживается | Поддерживается | Поддерживается | — | — | — | — |
| DingTalk | — | Поддерживается | Поддерживается | — | Поддерживается | — | Поддерживается |
| Microsoft Teams | — | Поддерживается | — | Поддерживается | — | Поддерживается | — |
| Электронная почта | — | Поддерживается | Поддерживается | Поддерживается | — | — | — |
| SMS | — | — | — | — | — | — | — |
| Matrix | Поддерживается | Поддерживается | Поддерживается | Поддерживается | Поддерживается | Поддерживается | Поддерживается |
Кроссплатформенная непрерывность сессии: один и тот же Агент может сохранять контекст на разных платформах. Например, если вы в середине разговора с Агентом в Telegram и переключитесь на Discord, Агент всё ещё помнит предыдущий разговор.
Запуск и настройка Gateway
Настройка настольной версии
Откройте пункт «Платформы обмена сообщениями» в левом меню, чтобы увидеть поддерживаемые платформы. Щёлкните соответствующую платформу, чтобы настроить её:

Настройка в интерактивном режиме
Используйте интерактивный мастер, чтобы выполнить начальную настройку для всех платформ:
hermes gateway setup

Мастер проведёт вас через настройку каждой платформы: выбор платформы, заполнение Bot Token, настройка списка разрешённых пользователей и т. д.
Например, после выбора Feishu можно создать бота, отсканировав QR-код или используя APP ID:

Команды управления шлюзом
Пример
hermes gateway
# Установить как системную службу уровня пользователя (Linux systemd / macOS launchd)
hermes gateway install
# Linux: Установить как системную службу, запускающуюся при загрузке
sudo hermes gateway install --system
# Управление службой
hermes gateway start # Запуск службы
hermes gateway stop # Остановка службы
hermes gateway restart # Перезапуск службы
hermes gateway status # Просмотр состояния службы
Практическая интеграция Telegram-бота
На примере Telegram выполните полный процесс интеграции бота.
Шаг 1: Создайте Telegram-бота.
В Telegram найдите @BotFather, отправьте команду /newbot и задайте имя бота и имя пользователя, как будет предложено.
BotFather вернёт токен Bot API примерно такого формата:1234567890:ABCdefGHIjklMNOpqrsTUVwxyz。
Шаг 2: Настройте Hermes Gateway.
Пример
# Конфигурация платформы Telegram
platforms:
telegram:
enabled: true
bot_token: "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
# Необязательно: список разрешённых ID пользователей (режим белого списка).
allowed_users:
- "123456789"
# Необязательно: нужно ли @упоминать его в группе, чтобы он отвечал
require_mention: true
# Необязательно: список каналов, в которых не требуется @упоминание
free_response_channels:
- "-1001234567890"
Шаг 3: Запуск и тестирование.
Пример
hermes gateway start
# Отправьте тестовое сообщение своему боту в Telegram
Для первоначальной интеграции рекомендуется использовать режим белого списка (allowed_users), разрешив взаимодействовать с Агентом только вашей собственной учётной записи, а затем открыть доступ другим после проверки, что всё работает правильно.
Слэш-команды, доступные на платформе
Следующие команды доступны на любой платформе обмена сообщениями:
| Команда | Особенности |
|---|---|
| /new или /reset | Начать новый сеанс |
| /model [name] | Просмотр или переключение моделей |
| /retry | Повторить последнее сообщение |
| /undo | Отменить последний ход диалога |
| /stop | Прервать текущую задачу |
| /approve / /deny | Одобрить/отклонить опасные команды |
| /background <задача> | Запускать задачи в фоновых сессиях |
| /status | Показать информацию о текущей сессии |
| /usage | Отобразить использование токенов для этой сессии. |
| /voice [on/off/tts] | Управление голосовыми ответами |
| /compress | Вручную сжать контекст беседы |
| /resume [название] | Возобновить ранее именованную сессию |
| /<skill-name> | Вызвать любой установленный навык |
| /reload-mcp | Перезагрузить сервер MCP |
| /update | Обновить Hermes до последней версии |
| /help | Показать все доступные команды |
Жизненный цикл сессии
Сессия — ключевая концепция в Hermes Gateway для управления диалогами.
Понимание того, как работает Session, помогает настроить подходящие политики изоляции сессий и правила сброса.
SessionSource: дескриптор источника сообщения
Каждое сообщение, входящее в Gateway, содержит SessionSource, который фиксирует "откуда пришло это сообщение".
| Fields | Type | Описание |
|---|---|---|
| платформа | string | Название платформы (telegram, discord, slack и т. д.) |
| chat_id | string | Идентификатор сессии (ID личного чата, ID группы, ID канала) |
| chat_type | string | Типы сессий: dm (личное сообщение), group, channel, thread |
| user_id | string | ID отправителя сообщения на платформе |
| user_name | string | Отображаемое имя отправителя сообщения |
| thread_id | string | ID темы форума (форум Telegram) / ID ветки Discord |
| guild_id | string | ID сервера Discord (используется для изоляции серверов) |
Правила генерации ключа сессии
Ключ сессии — это детерминированная строка, состоящая из полей SessionSource.
Он определяет, какие сообщения принадлежат одной сессии. Формат следующий:
agent:main:{platform}:{chat_type}:{chat_id}:{thread_id}:{user_id}
Примеры ключей сессий в различных сценариях:
| Сценарии | Ключ сессии |
|---|---|
| Личный чат Telegram | agent:main:telegram:dm:12345 |
| Группа Telegram | agent:main:telegram:group:-10012345:user_abc |
| Темы форума Telegram | agent:main:telegram:group:-10012345:thread_678:user_abc |
| Личный чат Discord | agent:main:discord:dm:12345 |
| Каналы сервера Discord | agent:main:discord:channel:12345:user_abc |
| Ветка Discord | agent:main:discord:thread:12345:thread_678 |
Правило генерации Session Key — одна из важнейших конфигураций Gateway. При неверной настройке это может вызвать перекрёстное смешивание сессий разных пользователей — когда два разных человека видят содержимое разговора друг друга.
SessionEntry: запись активной сессии
Каждый Session Key соответствует одному SessionEntry, который хранит метаданные и состояние сессии.
| Fields | Описание |
|---|---|
| session_id | Уникальный идентификатор сессии, формат: YYYYMMDD_HHMMSS_8-значный случайный hex |
| created_at | Время создания сессии |
| updated_at | Время последней активности (используется для определения тайм-аута простоя) |
| total_tokens | Суммарное потребление токенов |
| estimated_cost_usd | Совокупная оценка стоимости (USD) |
| suspended | Был ли он принудительно приостановлен (команда /stop или аномальный цикл) |
| resume_pending | Ожидает ли он восстановления (флаг восстановления после перезапуска после сбоя) |
Политика многопользовательской изоляции
Многопользовательская изоляция определяет, используют ли несколько пользователей в одной группе или канале общую сессию или имеют собственные независимые сессии.
Эта конфигурация напрямую влияет на пользовательский опыт — общая сессия означает, что пользователь A может видеть контекст переписки пользователя B.
Настройка политики изоляции
| Элемент конфигурации | Значение по умолчанию | Значение |
|---|---|---|
| group_sessions_per_user | истина | У каждого пользователя в группе/канале независимая сессия |
| thread_sessions_per_user | false | Все пользователи в ветке используют одну и ту же сессию |
Поведение в различных сценариях
| Сценарии | Поведение по умолчанию | Описание |
|---|---|---|
| Личный чат (DM) | Всегда независимо | Личный чат всегда приватный и не настраивается |
| Группы/Каналы | У каждого пользователя независимая сессия | Пользователь A и пользователь B имеют независимые контексты сессий в одной и той же группе |
| Ветка (тема форума) | Все пользователи используют одну общую сессию | В темах форума Telegram и ветках Discord все участники используют один и тот же контекст |
Изменения системного промпта для общих сессий
Когда сессия находится в общем режиме (shared_multi_user_session = true), системный промпт изменится:
- Вместо фиксированного имени пользователя в нём указано «Многопользовательская сессия — префикс сообщения включает имя отправителя»
- Каждое сообщение пользователя снабжается префиксом с отображаемым именем отправителя, чтобы Агент знал, кто говорит
- Такая архитектура сохраняет эффективность кэширования промптов (системный промпт не меняется в зависимости от отправителя)
Политика изоляции по умолчанию (для каждого пользователя в группах, общая для веток) — это лучшая практика, проверенная масштабным реальным использованием. Если у вас нет особых требований, не рекомендуется её менять.
Конфигурация безопасности шлюза
Управление доступом пользователей
По умолчанию шлюз отклоняет всех пользователей, которых нет в белом списке—Это безопасная настройка по умолчанию для бота с привилегиями доступа к терминалу.
Настройте разрешённых пользователей (в файле .env):
Пример
# Белый список пользователей для конкретных платформ
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
SLACK_ALLOWED_USERS=U012AB3CD,U012EF4GH
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
WECOM_ALLOWED_USERS=user-id-1,user-id-2
TEAMS_ALLOWED_USERS=aad-object-id-1
# Белый список, применяемый ко всем платформам
GATEWAY_ALLOWED_USERS=123456789,987654321
# Разрешить всех пользователей (не рекомендуется для ботов с доступом к терминалу)
GATEWAY_ALLOW_ALL_USERS=true
Сопряжение в личных сообщениях (альтернатива белому списку)
Не нужно вручную настраивать ID пользователей. Когда новый пользователь напишет боту в личные сообщения, он получит одноразовый код сопряжения:
Пример
# Вы одобряете доступ пользователя
hermes pairing approve telegram XKGH5N7P
# Просмотреть список ожидающих + одобренных пользователей
hermes pairing list
# Отозвать права доступа пользователя
hermes pairing revoke telegram 123456789
Код сопряжения истекает через 1 час, имеет ограничение частоты и генерируется с использованием криптографических случайных чисел.
Тихий токен
Используется в групповых чатах, Hooks и автоматизированных рабочих процессах, чтобы Агент не отправлял сообщения при определённых условиях:
# Agent 回复中仅包含以下内容之一时,网关不会向平台发送任何消息: [SILENT] SILENT NO_REPLY NO REPLY
молчание — этоРешение о доставке, не влияя на запись сессии — ответ всё ещё сохраняется в истории сессии, обеспечивая нормальную работу логики очерёдности реплик в разговоре.
Политика сброса сессии
Настройте, когда сессия автоматически сбрасывается, чтобы предотвратить неограниченный рост контекста:
Пример
"reset_by_platform": {
"telegram": { "mode": "idle", "idle_minutes": 240 },
"discord": { "mode": "idle", "idle_minutes": 60 },
"slack": { "mode": "daily", "reset_hour": 4 }
}
}
| Политика | Значение по умолчанию | Описание |
|---|---|---|
| daily | 4:00 AM | Сброс сессии в определённое время каждый день |
| idle | 1440 минут | Сброс сессии после тайм-аута бездействия |
| both | комбинация | То, что сработает первым, сбрасывает сессию |
Краткая справка по типовым командам
Пример
hermes gateway setup # Интерактивная настройка платформы
hermes gateway # Запуск на переднем плане (отладка)
hermes gateway install # Установить как пользовательскую службу
hermes gateway start / stop / restart # Управление службой
hermes gateway status # Просмотр состояния службы
# ─── Сопряжение пользователей ────────────────────────────────────────────────
hermes pairing list # Просмотр списка сопряжений
hermes pairing approve <platform> <code> # Одобрить сопряжение
hermes pairing revoke <platform> <user_id> # Отозвать доступ
# ─── Слэш-команды внутри сессии ──────────────────────────────────────────
/new # Начать новую сессию
/model [Name] # Просмотр или переключение модели
/retry # Повторить последнее сообщение
/undo # Отменить предыдущий ход
/stop # Прервать текущую задачу
/approve / /deny # Одобрить/Отклонить опасные команды
/background <Task> # Запустить задачу в фоне
/status # Информация о текущей сессии
/usage # Использование токенов
/voice [on/off/tts] # Управление голосом
/compress # Сжать контекст
/resume [Заголовок] # Восстановить сессию
/<skill-name> # Вызвать навык
/reload-mcp # Перезагрузить MCP
/update # Обновить Hermes
/help # Все команды