Как подключить Hermes Agent к Telegram

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

Если Hermes ещё не установлен, сначала прочитайте об агенте и его установке, затем вернитесь к настройке Telegram.

Дополнительные инструкции доступны в документации Ailoot.

Что понадобится для подключения Hermes Agent к Telegram?#

Проверьте установку Hermes и подключение модели командой hermes doctor. Бота создайте в приложении Telegram, а команды настройки выполняйте в терминале на компьютере.

Как создать бота с помощью BotFather?#

Каждому Telegram-боту соответствует токен — секретный ключ для управления. Его выдаёт официальный бот Telegram @BotFather.

1. Найдите @BotFather

   Введите @BotFather в поиске Telegram или перейдите по адресу t.me/BotFather. У официального аккаунта BotFather есть синяя отметка верификации. Начните диалог кнопкой «Start».

2. Отправьте /newbot

   BotFather попросит указать два названия. Первое — имя, которое будут видеть пользователи; оно может быть произвольным, например «Мой агент». Второе — юзернейм. Он должен быть уникальным и завершаться на bot, например moy_agent_bot.

3. Скопируйте токен

   BotFather пришлёт поздравительное сообщение и длинную строку наподобие 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ. Это токен бота; скопируйте его полностью.

Создать бота можно и без ручной переписки с BotFather. В веб-панели Hermes (hermes dashboard) и в десктопном приложении на странице «Messaging → Telegram» предусмотрена кнопка «Create with QR». Отсканируйте код телефоном: Hermes создаст бота, автоматически определит ваш ID, сохранит токен в настройках и перезапустит шлюз. Далее описан ручной вариант; если вы воспользовались QR-кодом, сразу переходите к проверке подключения.

Как найти свой ID в Telegram и для чего он нужен?#

В Telegram у аккаунта есть публичный юзернейм, начинающийся с @, и внутренний числовой идентификатор. Для настройки Hermes нужен именно числовой ID.

Запишите найденный ID рядом с токеном. Также можно определить его автоматически с помощью описанного выше способа «Create with QR».

Как указать токен в Hermes Agent и запустить шлюз?#

1. Откройте мастер настройки

   hermes gateway setup
   

   Выполните эту команду на компьютере с установленным Hermes. Мастер предложит выбрать мессенджер.

2. Выберите Telegram и укажите параметры

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

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

   hermes gateway
   

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

При ручной настройке откройте ~/.hermes/.env и добавьте две строки, подставив токен, полученный у BotFather, и свой числовой ID:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

Вторая строка разрешает этим людям личные и групповые сообщения; отдельное разрешение группового чата также может предоставлять доступ. Несколько ID перечисляются через запятую. Сохраните файл и запустите шлюз командой hermes gateway.

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

Какие функции доступны у Telegram-бота на телефоне?#

На телефоне особенно полезны пять функций.

Текстовые и голосовые сообщения. Напишите поручение или отправьте голосовое. Если распознавание речи настроено, Hermes преобразует запись в текст и обработает запрос. При использовании локального провайдера ключи не нужны: обработка выполняется на компьютере, где запущен агент.

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

Подтверждение рискованных действий. Перед потенциально опасной операцией, например удалением файлов, агент спросит разрешение прямо в чате. Ответьте «yes» или «y», чтобы продолжить, либо «no» или «n», чтобы отменить действие.

Кнопки для выбора. Если агенту нужно уточнение, он отправит вопрос с вариантами в виде встроенных кнопок. Выберите вариант, и работа продолжится. Команда /model, отправленная без аргументов, открывает такое же меню выбора модели.

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

Как получать в чате результаты фоновых задач?#

Домашний чат для запланированных задач. Hermes выполняет задачи по расписанию, например может собирать сводку каждое утро в 7:43. Один раз назначьте домашний чат командой /sethome в диалоге с ботом. Пока шлюз запущен, результаты будут приходить туда автоматически.

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

Бот отвечает только при работающем шлюзе. Если компьютер с Hermes выключен или перешёл в спящий режим, бот останется недоступен до возобновления работы машины. Чтобы поддерживать соединение круглосуточно, перенесите агента на сервер; порядок настройки описан в инструкции по постоянной работе Hermes Agent. По умолчанию шлюз сам запрашивает Telegram о новых сообщениях. Для облачных платформ, которые переходят в спящий режим без входящего трафика, в документации предусмотрен режим webhook: направление соединения меняется, и Telegram сам обращается к боту.

Как ограничить доступ к боту?#

Бота можно найти в Telegram по юзернейму. Поэтому защита зависит от списка доступа и сохранности токена.

Настройте доступ отправителей через TELEGRAM_ALLOWED_USERS. Для групп проверьте и TELEGRAM_GROUP_ALLOWED_CHATS: запись чата разрешает любого его участника, даже без ID в личном списке. Пустой личный список поэтому не доказывает закрытость всех групп.

Не допускайте попадания токена на снимки экрана, в пересланные сообщения или репозитории. Если токен раскрыт, отзовите его командой /revoke у BotFather, задайте новый в настройках и перезапустите шлюз.

В группах различайте разрешение отправителя и целого чата. Участник группы, разрешённой через TELEGRAM_GROUP_ALLOWED_CHATS, может пользоваться ботом без ID в TELEGRAM_ALLOWED_USERS. Для индивидуального доступа не разрешайте целую группу: настройте и проверьте ограничения отправителей установленной версии. Чтобы бот отвечал в группе только при обращении к нему, настройте telegram.require_mention. В таком режиме он реагирует на упоминание через @, ответ на собственное сообщение, команду формата /command@твойбот и совпадения с заданными вами шаблонами telegram.mention_patterns. На остальные сообщения группы он не отвечает.

Почему бот не отвечает в группе и как это исправить?#

У новых Telegram-ботов режим приватности включён изначально. В документации Hermes этот режим указан как частая причина недопонимания при настройке ботов в группах. Бот получает команды, начинающиеся с /, ответы на свои сообщения и системные уведомления. Остальные сообщения Telegram ему не передаёт, поэтому изменить ситуацию настройками самого агента нельзя.

Чтобы отключить режим:

1. Откройте @BotFather и отправьте /mybots.
2. Выберите нужного бота.
3. Перейдите в «Bot Settings» → «Group Privacy» → «Turn off».
4. Удалите бота из группы и добавьте его туда повторно.

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

Если вы не хотите отключать приватность, назначьте бота администратором группы. Администратор получает все сообщения независимо от режима приватности.

Распространённые ошибки подключения и их решение#

Частые вопросы о Hermes Agent в Telegram#

Узнайте больше о Ailoot.