Шлюз сообщений

Hermes доступен из Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), QQ, Yuanbao, Microsoft Teams, LINE, ntfy или прямо из браузера. Шлюз — это один фоновый процесс: он подключается ко всем настроенным платформам, ведёт сессии, запускает cron-задачи и доставляет голосовые сообщения.

Полный набор голосовых возможностей — режим микрофона в CLI, озвученные ответы в мессенджерах, разговоры в голосовых каналах Discord — описан на страницах Голосовой режим и Используем голосовой режим с Hermes.

Сравнение платформ

Голос — озвученные ответы (TTS) и/или расшифровка голосовых сообщений. Изображения — приём и отправка картинок. Файлы — приём и отправка вложений. Треды — ветки обсуждений. Реакции — эмодзи-реакции на сообщения. Печать — индикатор набора текста во время обработки. Стриминг — постепенное обновление сообщения через редактирование.

Архитектура

flowchart TB
    subgraph Gateway["Hermes Gateway"]
        subgraph Adapters["Platform adapters"]
            tg[Telegram]
            dc[Discord]
            wa[WhatsApp]
            sl[Slack]
            gc[Google Chat]
            sig[Signal]
            sms[SMS]
            em[Email]
            ha[Home Assistant]
            mm[Mattermost]
            mx[Matrix]
            dt[DingTalk]
    fs[Feishu/Lark]
    wc[WeCom]
    wcb[WeCom Callback]
    wx[Weixin]
    bb[BlueBubbles]
    qq[QQ]
    yb[Yuanbao]
    ms[Microsoft Teams]
    api["API Server<br/>(OpenAI-compatible)"]
    wh[Webhooks]
        end

        store["Session store<br/>per chat"]
        agent["AIAgent<br/>run_agent.py"]
        cron["Cron scheduler<br/>ticks every 60s"]
    end

    tg --> store
    dc --> store
    wa --> store
    sl --> store
    gc --> store
    sig --> store
    sms --> store
    em --> store
    ha --> store
    mm --> store
    mx --> store
    dt --> store
    fs --> store
    wc --> store
    wcb --> store
    wx --> store
    bb --> store
    qq --> store
    yb --> store
    ms --> store
    api --> store
    wh --> store
    store --> agent
    cron --> store

Каждый адаптер платформы принимает сообщения, направляет их через хранилище сессий (своё на каждый чат) и передаёт в AIAgent на обработку. Здесь же крутится планировщик cron: каждые 60 секунд он проверяет очередь и запускает задачи, время которых подошло.

Токены намеренного молчания

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

Поддерживаемые токены:

• [SILENT]
• SILENT
• NO_REPLY
• NO REPLY

Пробелы и регистр нормализуются, но весь финальный ответ целиком должен быть токеном. Фраза вроде «Use [SILENT] when nothing changed» доставляется как обычно.

Молчание — это лишь решение о доставке. Ход молчания ассистента Hermes всё равно сохраняет в стенограмму сессии, поэтому разговор продолжает нормально чередоваться:

user: side-channel chatter
assistant: [SILENT]   # сохранено, не доставлено
user: next message

Упавшие ходы по-прежнему всплывают как ошибки; Hermes не прячет сбои только потому, что текст похож на токен молчания.

Быстрая настройка

Проще всего настроить мессенджеры через интерактивный мастер:

hermes gateway setup        # Интерактивная настройка всех мессенджеров

Мастер проведёт вас по каждой платформе с выбором стрелками, покажет, что уже настроено, и в конце предложит запустить или перезапустить шлюз.

Команды шлюза

hermes gateway              # Запуск в переднем плане
hermes gateway setup        # Интерактивная настройка мессенджеров
hermes gateway install      # Установка как пользовательский сервис (Linux) / служба launchd (macOS)
sudo hermes gateway install --system   # Только Linux: системная служба, стартующая при загрузке
hermes gateway start        # Запуск службы по умолчанию
hermes gateway stop         # Остановка службы по умолчанию
hermes gateway status       # Статус службы по умолчанию
hermes gateway status --system         # Только Linux: явная проверка системной службы

Команды чата (внутри мессенджера)

Управление сессиями

Сохранение сессии

Сессия живёт от сообщения к сообщению, пока не произойдёт сброс. Агент держит в памяти контекст вашего разговора.

Политики сброса

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

Переопределения для отдельных платформ задаются в ~/.hermes/gateway.json:

{
  "reset_by_platform": {
    "telegram": { "mode": "idle", "idle_minutes": 240 },
    "discord": { "mode": "idle", "idle_minutes": 60 }
  }
}

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

По умолчанию шлюз отклоняет всех, кого нет в списке разрешений и кто не прошёл сопряжение через личку. Для бота с доступом к терминалу это безопасное поведение по умолчанию.

# Ограничить доступ конкретными пользователями (рекомендуется):
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
SIGNAL_ALLOWED_USERS=+155****4567,+155****6543
SMS_ALLOWED_USERS=+155****4567,+155****6543
EMAIL_ALLOWED_USERS=trusted@example.com,colleague@work.com
MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c
MATRIX_ALLOWED_USERS=@alice:matrix.org
DINGTALK_ALLOWED_USERS=user-id-1
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
WECOM_ALLOWED_USERS=user-id-1,user-id-2
WECOM_CALLBACK_ALLOWED_USERS=user-id-1,user-id-2
TEAMS_ALLOWED_USERS=aad-object-id-1,aad-object-id-2

# Либо общий список разрешений
GATEWAY_ALLOWED_USERS=123456789,987654321

# Либо явно разрешить всех (НЕ рекомендуется для ботов с доступом к терминалу):
GATEWAY_ALLOW_ALL_USERS=true

Сопряжение через личку (альтернатива спискам разрешений)

Чтобы не прописывать ID вручную, можно положиться на сопряжение: неизвестный пользователь, написавший боту в личку, получает одноразовый код:

# Пользователь видит: "Pairing code: XKGH5N7P"
# Вы подтверждаете его командой:
hermes pairing approve telegram XKGH5N7P

# Другие команды сопряжения:
hermes pairing list          # Показать ожидающих + одобренных пользователей
hermes pairing revoke telegram 123456789  # Отозвать доступ

Коды сопряжения действуют 1 час, защищены ограничением частоты запросов и генерируются криптостойким случайным образом.

Администраторы и обычные пользователи

Список разрешений отвечает на вопрос «может ли этот человек вообще достучаться до бота?». Разделение на администраторов и пользователей отвечает на другой: «он уже внутри — а что ему позволено делать?»

Каждый допущенный пользователь попадает в один из двух уровней в пределах своего контекста (личка против группы/канала):

• Администратор — полный доступ. Может выполнять любую зарегистрированную слэш-команду (встроенную и из плагинов) и пользоваться всеми возможностями за стеной доступа.
• Обычный пользователь — ограниченный доступ. Свободно общается с агентом, но запускает только те слэш-команды, которые вы явно разрешили. Минимум, доступный всегда, — это /help и /whoami.

Уровни настраиваются отдельно для каждой платформы и каждого контекста. Статус администратора в личке не даёт статуса администратора в группе или канале — у каждого контекста свой собственный список администраторов.

Что уровни ограничивают сегодня: слэш-команды. Разделение работает через живой реестр команд, поэтому покрывает и встроенные команды, и команды от плагинов без отдельной обвязки под каждую функцию. Обычное общение не затрагивается — не-администраторы по-прежнему могут разговаривать с агентом.

Что может попасть под ограничения в будущем: новые поверхности возможностей (доступ к инструментам, переключение моделей, дорогие операции) по мере появления будут опираться на то же разделение admin / user. Настроив разделение сейчас, вы избавитесь от лишней работы потом: будущие ограничения встанут на место без переразметки того, кто у вас администратор.

Конфигурация

gateway:
  platforms:
    discord:
      extra:
        allow_from: ["111", "222", "333"]
        allow_admin_from: ["111"]                    # администраторы → все слэш-команды
        user_allowed_commands: [status, model]       # что могут запускать не-администраторы
        # Опционально: отдельный контекст для группы/канала
        group_allow_admin_from: ["111"]
        group_user_allowed_commands: [status]

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

Проверка своего доступа

Команда /whoami на любой платформе покажет активный контекст, ваш уровень (admin / user / unrestricted) и список слэш-команд, которые вам доступны. Примеры под конкретные платформы смотрите на страницах Telegram и Discord.

Прерывание агента

Чтобы прервать работающего агента, отправьте ему любое сообщение. Что при этом происходит:

• Выполняющиеся команды терминала убиваются немедленно (SIGTERM, затем SIGKILL через 1 с)
• Вызовы инструментов отменяются — доработает только тот, что выполняется прямо сейчас, остальные пропускаются
• Несколько сообщений склеиваются — всё, что вы прислали во время прерывания, собирается в один промпт
• Команда /stop — прерывает без постановки следующего сообщения в очередь

Очередь, прерывание или подсказка (режим ввода при занятости)

По умолчанию сообщение занятому агенту прерывает его. Доступны ещё два режима:

• queue — последующие сообщения ждут и выполняются следующим ходом, как только текущая задача завершится.
• steer — последующие сообщения вставляются в текущий запуск через /steer и доходят до агента после очередного вызова инструмента. Без прерывания и без нового хода. Если агент ещё не начал работу, режим откатывается к поведению queue.

display:
  busy_input_mode: steer   # или queue, или interrupt (по умолчанию)
  busy_ack_enabled: true   # поставьте false, чтобы полностью убрать ответ ⚡/⏳/⏩ в чате

При первом сообщении занятому агенту на любой платформе Hermes добавляет к подтверждению занятости однострочную подсказку про этот переключатель ("💡 First-time tip — …"). Подсказка показывается один раз на установку — её удерживает флаг onboarding.seen.busy_input_prompt. Удалите этот ключ, чтобы увидеть подсказку снова.

Если подтверждения занятости кажутся шумными — особенно при голосовом вводе или очередях сообщений вдогонку — поставьте display.busy_ack_enabled: false. Ваш ввод всё так же ставится в очередь, направляется или прерывает агента, просто ответ в чате при этом молчит.

Уведомления о ходе работы инструментов

Объём активности инструментов, который отображается, настраивается в ~/.hermes/config.yaml:

display:
  tool_progress: all    # off | new | all | verbose
  tool_progress_command: false  # поставьте true, чтобы включить /verbose в мессенджере
  # Как группируется прогресс на платформах, поддерживающих редактирование сообщений:
  #   accumulate (по умолчанию) — править один пузырёк на месте по мере работы инструментов
  #   separate                  — слать по сообщению на инструмент (стиль до v0.9; шумнее)
  # Действует только там, где tool_progress уже включён.
  tool_progress_grouping: accumulate   # accumulate | separate

Временные метки сообщений в контексте модели

По умолчанию выключено. Когда включено, Hermes добавляет в начало каждого пользовательского сообщения в контексте модели читаемую временную метку (например, [Tue 2026-04-28 13:40:53 CEST]), чтобы агент знал, когда сообщения были отправлены — это пригождается для рассуждений о времени («вы спрашивали утром…», замечать долгий перерыв). К сообщениям ассистента и к системному промпту метка не добавляется.

gateway:
  message_timestamps:
    enabled: false   # поставьте true, чтобы показывать модели время отправки

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

Когда уведомления о ходе работы включены, бот шлёт статусы по мере работы:

💻 `ls -la`...
🔍 web_search...
📄 web_extract...
🐍 execute_code...

Фоновые сессии

Запустите промпт в отдельной фоновой сессии — агент возьмётся за него независимо, пока ваш основной чат остаётся отзывчивым:

/background Check all servers in the cluster and report any that are down

Hermes тут же подтверждает:

🔄 Background task started: "Check all servers in the cluster..."
   Task ID: bg_143022_a1b2c3

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

Каждый промпт /background порождает отдельный экземпляр агента, работающий асинхронно:

• Изолированная сессия — у фонового агента своя сессия с собственной историей разговора. О контексте вашего текущего чата он ничего не знает и получает только тот промпт, который вы дали.
• Та же конфигурация — наследует вашу модель, провайдера, наборы инструментов, настройки рассуждений и маршрутизацию провайдеров из текущей конфигурации шлюза.
• Не блокирует — основной чат остаётся полностью интерактивным. Пишите сообщения, запускайте другие команды или новые фоновые задачи, пока он трудится.
• Доставка результата — когда задача завершается, результат приходит в тот же чат или канал, откуда вы дали команду, с префиксом «✅ Background task complete». Если задача упала, увидите «❌ Background task failed» вместе с ошибкой.

Уведомления о фоновых процессах

Когда агент в фоновой сессии запускает длительные процессы через terminal(background=true) (серверы, сборки и т. п.), шлюз умеет присылать статусы в чат. Поведение задаётся параметром display.background_process_notifications в ~/.hermes/config.yaml:

display:
  background_process_notifications: all    # all | result | error | off

То же самое можно задать через переменную окружения:

HERMES_BACKGROUND_NOTIFICATIONS=result

Сценарии использования

• Мониторинг серверов — «/background Check the health of all services and alert me if anything is down»
• Долгие сборки — «/background Build and deploy the staging environment», пока вы продолжаете переписку
• Исследовательские задачи — «/background Research competitor pricing and summarize in a table»
• Операции с файлами — «/background Organize the photos in ~/Downloads by date into folders»

Управление службой

Linux (systemd)

hermes gateway install               # Установка как пользовательский сервис
hermes gateway start                 # Запуск службы
hermes gateway stop                  # Остановка службы
hermes gateway status                # Проверка статуса
journalctl --user -u hermes-gateway -f  # Просмотр логов

# Включить lingering (служба продолжит работать после выхода из системы)
sudo loginctl enable-linger $USER

# Либо установить системную службу, стартующую при загрузке, но всё равно работающую от вашего пользователя
sudo hermes gateway install --system
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

На ноутбуках и машинах для разработки используйте пользовательский сервис. На VPS и headless-хостах, которые должны подниматься при загрузке без оглядки на systemd linger, — системную службу.

hermes gateway install          # пользовательский сервис
sudo loginctl enable-linger $USER   # однократно: старт при загрузке, переживает выход из системы

hermes ALL=(root) NOPASSWD: /usr/bin/systemctl --no-ask-password reset-failed hermes-gateway*, /usr/bin/systemctl --no-ask-password start hermes-gateway*, /usr/bin/systemctl --no-ask-password restart hermes-gateway*

Не держите пользовательский и системный юнит шлюза установленными одновременно, если только вам это не нужно осознанно. Hermes предупредит, если обнаружит оба: поведение start/stop/status становится неоднозначным.

macOS (launchd)

hermes gateway install               # Установка как агент launchd
hermes gateway start                 # Запуск службы
hermes gateway stop                  # Остановка службы
hermes gateway status                # Проверка статуса
tail -f ~/.hermes/logs/gateway.log   # Просмотр логов

Сгенерированный plist лежит в ~/Library/LaunchAgents/ai.hermes.gateway.plist. В нём три переменные окружения:

• PATH — ваш полный shell-PATH на момент установки, в начало которого добавлены bin/ виртуального окружения и node_modules/.bin. За счёт этого инструменты, установленные пользователем (Node.js, ffmpeg и т. д.), будут доступны дочерним процессам шлюза вроде моста WhatsApp.
• VIRTUAL_ENV — указывает на виртуальное окружение Python, чтобы инструменты корректно находили пакеты.
• HERMES_HOME — привязывает шлюз к вашей установке Hermes.

Наборы инструментов по платформам

У каждой платформы свой набор инструментов:

Эксплуатация многоплатформенного шлюза

Обычно шлюз держит сразу несколько адаптеров (Telegram + Discord + Slack и т. д.). Разделы ниже — про повседневную эксплуатацию, которая затрагивает все платформы.

Команда /platform

Когда шлюз запущен, слэш-команда /platform из любой подключённой CLI-сессии или чата позволяет осмотреть и подрулить отдельными адаптерами, не перезапуская весь шлюз:

/platform list                  # показать все адаптеры и их состояние
/platform pause <name>          # перестать отправлять новые сообщения одному адаптеру
/platform resume <name>         # снова включить поставленный на паузу адаптер

/platform list показывает, в каком состоянии каждый адаптер: running, paused (вручную) или paused-by-breaker (см. ниже). Пауза не выгружает адаптер и не глушит его фоновые циклы — входящие сообщения отбрасываются, но само соединение остаётся открытым, поэтому возобновление происходит мгновенно.

Смотрите также более общую сводную команду статуса /platforms.

Автоматический предохранитель

Каждый адаптер обёрнут в предохранитель (circuit breaker). Повторяющиеся восстановимые сбои (сетевые провалы, ответы с ограничением частоты, ответы 5xx от вышестоящего сервиса, обрывы websocket) приводят к срабатыванию предохранителя: адаптер автоматически ставится на паузу, оператору уходит уведомление в домашний канал другой живой платформы (если такая настроена), а в лог попадает структурированная запись.

Предохранитель не возобновляется сам — он остаётся разомкнутым, пока вы вручную не выполните /platform resume <name>. Это сделано намеренно: при затяжном сбое платформы вам не нужно, чтобы шлюз молотил переподключения вхолостую.

Куда смотреть, когда платформа на паузе

Если адаптер встал на паузу, проверьте:

1. Лог шлюза (~/.hermes/logs/gateway.log или лог юнита systemd / launchd). Ищите имя платформы и слова circuit breaker, paused или disabled. В записи о срабатывании есть счётчик сбоев и последняя ошибка.
2. Вывод /platform list — показывает текущее состояние и последнюю причину.
3. Страницу статуса провайдера (статус Telegram bot API, статус Discord и т. д.). Предохранитель сработал потому, что платформа была нездорова; не пытайтесь возобновлять, пока она не восстановится.

Как только вышестоящий сервис придёт в норму, /platform resume <name> сбросит предохранитель и снова взведёт адаптер.

Уведомления о перезапуске

Когда шлюз перезапускается (или его выключают с незавершёнными сессиями), он умеет отправлять однократное сообщение «агент снова в строю» / «агент был прерван» в домашний канал каждой платформы. Управляется это для каждой платформы флагом gateway_restart_notification в gateway-config.yaml, который по умолчанию равен true:

gateway:
  platforms:
    telegram:
      home_chat_id: "123456789"
      gateway_restart_notification: false   # отказаться от уведомления на этой платформе
    discord:
      home_chat_id: "987654321"
      # gateway_restart_notification опущен → по умолчанию true

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

Возобновление сессий после перезапуска шлюза

Когда шлюз выключается посреди вызова инструмента или генерации, затронутые сессии помечаются как restart_interrupted. При следующем старте шлюз планирует автоматическое возобновление для каждой из них: пользователь получает короткое уведомление в чате («Send any message after restart and I’ll try to resume where you left off.»), а сессия подхватывается с последнего зафиксированного хода, как только он ответит.

Это поведение включено по умолчанию и фиксируется в логе при старте шлюза:

Scheduled auto-resume for N restart-interrupted session(s)

Никакой настройки не требуется. Если уведомление вам не нужно, поставьте gateway_restart_notification: false для платформы.

Прогресс с прицелом на мобильные

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

• tool_progress по умолчанию off — никакого потока хлебных крошек по каждому инструменту, забивающего чат.
• busy_ack_detail по умолчанию off — подтверждения занятости и сигналы о долгой работе остаются лаконичными (без отладочных подробностей вроде iteration 21/60).
• interim_assistant_messages остаётся on — настоящие промежуточные реплики ассистента (модель буквально сообщает, что собирается сделать) — это сигнал, а не шум.
• long_running_notifications остаётся on — один редактируемый на месте пузырёк «⏳ Working — N min» обновляется раз в несколько минут, так что у вас есть пульс работы вместо получасового созерцания typing….

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

display:
  platforms:
    telegram:
      # Снова включить поток прогресса по инструментам
      tool_progress: new
      # Показывать "iteration N/M, running: tool" в сигналах и подтверждениях занятости
      busy_ack_detail: true
      # Либо заглушить их полностью
      interim_assistant_messages: false
      long_running_notifications: false

Очистка пузырьков прогресса (по желанию)

Сообщения о ходе работы инструментов, сигнал «всё ещё работаю…» и пузырьки статус-колбэков можно автоматически удалять после того, как придёт финальный ответ. Включается для каждой платформы через display.platforms.<platform>.cleanup_progress:

display:
  platforms:
    telegram:
      cleanup_progress: true
    discord:
      cleanup_progress: true

По умолчанию false. Настройку учитывают только платформы, чей адаптер умеет delete_message (сейчас это Telegram и Discord). Для упавших запусков очистка пропускается, чтобы пузырьки остались хлебными крошками.

Дальнейшие шаги

• Настройка Telegram
• Настройка Discord
• Настройка Slack
• Настройка Google Chat
• Настройка WhatsApp
• Настройка WhatsApp Business Cloud API
• Настройка Signal
• Настройка SMS (Twilio)
• Настройка Email
• Интеграция с Home Assistant
• Настройка Mattermost
• Настройка Matrix
• Настройка DingTalk
• Настройка Feishu/Lark
• Настройка WeCom
• Настройка WeCom Callback
• Настройка Weixin (WeChat)
• Настройка BlueBubbles (iMessage)
• Настройка QQBot
• Настройка Yuanbao
• Настройка Microsoft Teams
• Конвейер встреч Teams
• Open WebUI + API-сервер
• Настройка Raft
• Вебхуки