Интеграция платформенных сообщений 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ПоддерживаетсяПоддерживаетсяПоддерживаетсяПоддерживаетсяПоддерживаетсяПоддерживаетсяПоддерживается
WhatsApp—ПоддерживаетсяПоддерживается——ПоддерживаетсяПоддерживается
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.

Пример

# Путь к файлу: ~/.hermes/config.yaml
# Конфигурация платформы Telegram
platforms
:
  telegram
:
    enabled
: true
    bot_token
: "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
    # Необязательно: список разрешённых ID пользователей (режим белого списка).
    allowed_users
:
     - "123456789"
    # Необязательно: нужно ли @упоминать его в группе, чтобы он отвечал
    require_mention
: true
    # Необязательно: список каналов, в которых не требуется @упоминание
    free_response_channels
:
     - "-1001234567890"

Шаг 3: Запуск и тестирование.

Пример

# Запуск Gateway
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, который фиксирует "откуда пришло это сообщение".

FieldsTypeОписание
платформаstringНазвание платформы (telegram, discord, slack и т. д.)
chat_idstringИдентификатор сессии (ID личного чата, ID группы, ID канала)
chat_typestringТипы сессий: dm (личное сообщение), group, channel, thread
user_idstringID отправителя сообщения на платформе
user_namestringОтображаемое имя отправителя сообщения
thread_idstringID темы форума (форум Telegram) / ID ветки Discord
guild_idstringID сервера Discord (используется для изоляции серверов)

Правила генерации ключа сессии

Ключ сессии — это детерминированная строка, состоящая из полей SessionSource.

Он определяет, какие сообщения принадлежат одной сессии. Формат следующий:

agent:main:{platform}:{chat_type}:{chat_id}:{thread_id}:{user_id}

Примеры ключей сессий в различных сценариях:

СценарииКлюч сессии
Личный чат Telegramagent:main:telegram:dm:12345
Группа Telegramagent:main:telegram:group:-10012345:user_abc
Темы форума Telegramagent:main:telegram:group:-10012345:thread_678:user_abc
Личный чат Discordagent:main:discord:dm:12345
Каналы сервера Discordagent:main:discord:channel:12345:user_abc
Ветка Discordagent: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_userfalseВсе пользователи в ветке используют одну и ту же сессию

Поведение в различных сценариях

СценарииПоведение по умолчаниюОписание
Личный чат (DM)Всегда независимоЛичный чат всегда приватный и не настраивается
Группы/КаналыУ каждого пользователя независимая сессияПользователь A и пользователь B имеют независимые контексты сессий в одной и той же группе
Ветка (тема форума)Все пользователи используют одну общую сессиюВ темах форума Telegram и ветках Discord все участники используют один и тот же контекст

Изменения системного промпта для общих сессий

Когда сессия находится в общем режиме (shared_multi_user_session = true), системный промпт изменится:

  • Вместо фиксированного имени пользователя в нём указано «Многопользовательская сессия — префикс сообщения включает имя отправителя»
  • Каждое сообщение пользователя снабжается префиксом с отображаемым именем отправителя, чтобы Агент знал, кто говорит
  • Такая архитектура сохраняет эффективность кэширования промптов (системный промпт не меняется в зависимости от отправителя)

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


Конфигурация безопасности шлюза

Управление доступом пользователей

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

Настройте разрешённых пользователей (в файле .env):

Пример

# Путь к файлу: ~/.hermes/.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 пользователей. Когда новый пользователь напишет боту в личные сообщения, он получит одноразовый код сопряжения:

Пример

# После того как пользователь напишет боту в личные сообщения, он увидит: "Код сопряжения: XKGH5N7P"
# Вы одобряете доступ пользователя
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 }
  }
}
ПолитикаЗначение по умолчаниюОписание
daily4:00 AMСброс сессии в определённое время каждый день
idle1440 минутСброс сессии после тайм-аута бездействия
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                                 # Все команды
Другие расширения