Hermes Agent — это открытый AI-агент от Nous Research, который работает в терминале и мессенджерах. Telegram — самый популярный способ общения с Hermes: бот отвечает на сообщения, транскрибирует голосовые, принимает файлы и выполняет задачи с полным доступом к инструментам. Подключение занимает 5 шагов и не требует программирования.
Что такое Telegram-интеграция в Hermes Agent?
Telegram-интеграция в Hermes Agent — это шлюз (gateway), который соединяет вашего AI-агента с мессенджером Telegram через Bot API. Шлюз построен на библиотеке python-telegram-bot и поддерживает текст, голосовые сообщения, изображения, файлы и групповые чаты.
В отличие от обычных Telegram-ботов, которые отвечают по заранее написанным сценариям, Hermes — это полноценный AI-агент с доступом к терминалу, файловой системе, веб-поиску и десяткам других инструментов. Бот в Telegram становится окном к этому агенту.
Как создать бота в BotFather?
BotFather — официальный инструмент Telegram для управления ботами. Каждый бот получает уникальный API-токен, который нужен для подключения к Hermes.
Пошаговая инструкция:
/newbotbot (например, my_hermes_bot)123456789:ABCdefGHIjklMNOpqrSTUvwxYZ> ⚠️ Токен бота — это пароль. Любой, кто получит токен, сможет управлять ботом. Если токен скомпрометирован, немедленно отзовите его командой /revoke в BotFather.
Настройка бота (опционально)
После создания бота можно улучшить его через BotFather:
| Команда | Назначение |
|---|---|
| `/setdescription` | Текст «Что умеет этот бот?» перед началом чата |
| `/setabouttext` | Краткое описание на странице профиля бота |
| `/setuserpic` | Аватар для бота |
| `/setcommands` | Меню команд (кнопка `/` в чате) |
| `/setprivacy` | Управление видимостью сообщений в группах |
Полезный набор команд для /setcommands:
help - Показать справку
new - Начать новый разговор
sethome - Сделать этот чат домашним
Как получить Telegram User ID?
Hermes использует числовые идентификаторы пользователей (user ID) для управления доступом. Это не @username, а число вида 123456789, которое не меняется при смене имени.
Способ 1 (рекомендуемый): Отправьте сообщение боту @userinfobot — он мгновенно ответит вашим числовым ID.
Способ 2: Бот @get_id_bot — ещё один надёжный вариант.
Сохраните это число — оно понадобится для настройки шлюза.
Как настроить шлюз Hermes для Telegram?
Вариант A: Интерактивная настройка (рекомендуется)
hermes gateway setup
Мастер предложит выбрать платформу. Выберите Telegram и вставьте:
Вариант B: Ручная настройка
Добавьте в файл ~/.hermes/.env:
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789
Для нескольких пользователей — перечислите ID через запятую:
TELEGRAM_ALLOWED_USERS=123456789,987654321
Как запустить Telegram-бота?
После настройки запустите шлюз:
hermes gateway start
Бот должен стать онлайн за несколько секунд. Откройте Telegram, найдите бота по имени пользователя и отправьте тестовое сообщение. Ответ от Hermes придёт через 2–10 секунд в зависимости от скорости LLM-провайдера.
Проверка подключения
Если бот не отвечает, проверьте:
hermes model для проверки провайдераhermes gateway logsАвтозапуск при перезагрузке сервера
Для постоянной работы на VPS установите шлюз как системный сервис:
hermes gateway install
Это создаст systemd-сервис, который автоматически запускается при старте сервера. Проверить статус:
hermes gateway status
Как использовать голосовые сообщения?
Hermes автоматически транскрибирует голосовые сообщения из Telegram. Отправьте голосовое — агент получит текст и ответит. Никакая дополнительная настройка не нужна.
Провайдеры распознавания речи (STT):
| Провайдер | Ключ | Бесплатный? |
|---|---|---|
| Local faster-whisper | Нет | Да |
| Groq Whisper | `GROQ_API_KEY` | Да (ограниченно) |
| OpenAI Whisper | `VOICE_TOOLS_OPENAI_KEY` | Платный |
| Mistral Voxtral | `MISTRAL_API_KEY` | Платный |
Локальный faster-whisper работает без API-ключей. Установка:
pip install faster-whisper
Настройка в ~/.hermes/config.yaml:
stt:
enabled: true
provider: local
local:
model: base # tiny, base, small, medium, large-v3
Как настроить групповые чаты?
По умолчанию Telegram-боты работают в режиме приватности — видят только команды /, ответы на свои сообщения и сообщения от администраторов каналов. Для работы в группах нужно отключить приватность.
Отключение режима приватности
/mybots в @BotFather> ⚠️ После отключения приватности нужно удалить и заново добавить бота в группу. Telegram кэширует настройку приватности при добавлении бота.
Альтернатива: сделать бота администратором
Если назначить бота администратором группы, он будет видеть все сообщения независимо от настройки приватности.
Наблюдение за группой без автоответов
Чтобы бот видел сообщения в группе, но отвечал только при упоминании @botname:
telegram:
allowed_chats:
- "-1001234567890"
group_allowed_chats:
- "-1001234567890"
require_mention: true
observe_unmentioned_group_messages: true
В этом режиме бот накапливает контекст из всех сообщений группы, но реагирует только на явные упоминания. Это полезно для мониторинга обсуждений и ответов по запросу.
Как отправлять файлы через бота?
Hermes поддерживает отправку файлов из терминала через Telegram. Агент генерирует файл на сервере и отправляет его пользователю как вложение.
Поддерживаемые форматы:
| Категория | Форматы |
|---|---|
| Изображения | png, jpg, jpeg, gif, webp, bmp, tiff, svg |
| Аудио | mp3, wav, ogg, m4a, opus, flac, aac |
| Видео | mp4, mov, webm, mkv, avi |
| Документы | pdf, txt, md, csv, json, xml, html, yaml |
| Офисные | docx, xlsx, pptx, odt, ods, odp |
| Архивы | zip, rar, 7z, tar, gz, bz2 |
Для отправки файла агент использует тег MEDIA:/path/to/file в ответе. Gateway автоматически доставляет файл как нативное вложение Telegram.
Отправка файлов из Docker-контейнера
Если терминал работает в Docker, файлы пишутся внутри контейнера, но отправляются шлюзом на хосте. Нужен общий том:
terminal:
backend: docker
docker_volumes:
- "/home/user/.hermes/cache/documents:/output"
Агент пишет файлы в /output/..., а в ответе указывает хостовый путь: MEDIA:/home/user/.hermes/cache/documents/report.txt.
Webhook-режим для облачных развёртываний
По умолчанию Hermes подключается к Telegram через long polling — шлюз делает исходящие запросы к серверам Telegram. Это работает для локальных серверов.
Для облачных платформ (Fly.io, Railway, Render) эффективнее webhook-режим: Telegram отправляет обновления на URL вашего бота. Это позволяет машине засыпать между сообщениями и экономить ресурсы.
| Polling (по умолчанию) | Webhook | |
|---|---|---|
| Направление | Шлюз → Telegram (исходящий) | Telegram → Шлюз (входящий) |
| Подходит для | Локальные, always-on серверы | Облака с автобуждением |
| Настройка | Без доп. конфигурации | `TELEGRAM_WEBHOOK_URL` |
| Стоимость в простое | Сервер должен работать | Машина может спать |
Настройка webhook в ~/.hermes/.env:
TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"
Как автоматизировать задачи через Telegram?
Hermes поддерживает запланированные задачи (cron jobs), результаты которых автоматически доставляются в Telegram. Это позволяет получать дайджесты, отчёты и уведомления без ручного вмешательства.
Примеры автоматизации:
Создание cron-задачи:
hermes cron create "every day at 9am"
Мастер предложит ввести промпт, указать доставку (в Telegram или локально) и настроить расписание.
Ограничения и нюансы
Лимиты Telegram Bot API. Telegram ограничивает ботов примерно 30 сообщениями в секунду глобально и 1 сообщением в секунду в один чат. При высокочастотных автоматических ответах можно упираться в эти лимиты.
Шифрование. Разговоры с ботами не имеют сквозного шифрования. Сообщения проходят через серверы Telegram. Не отправляйте через бота конфиденциальные данные и пароли.
Задержка ответа. Время ответа зависит от LLM-провайдера. Облачные API (Anthropic, OpenAI) отвечают за 2–10 секунд. Локальные модели через Ollama могут быть медленнее.
Точность транскрипции. Качество распознавания голосовых зависит от STT-движка и качества аудио. Фоновый шум, акценты и плохие микрофоны снижают точность.
Постоянная работа. Шлюз должен работать непрерывно для получения сообщений. Если сервер упадёт, сообщения, отправленные во время простоя, будут поставлены в очередь Telegram, но могут быть потеряны, если очередь превысит лимит хранения.
FAQ
Можно ли подключить Telegram и Discord одновременно?
Да. Несколько шлюзов могут работать параллельно на одном экземпляре Hermes. Настройте каждый шлюз отдельно через hermes gateway setup, затем запустите все: hermes gateway start. Каждая платформа ведёт свои цепочки разговоров, разделяя общую память и навыки агента.
Как ограничить доступ к боту?
Hermes использует числовые Telegram user ID для контроля доступа. При настройке шлюза введите свой ID (узнать через @userinfobot). Только пользователи из списка TELEGRAM_ALLOWED_USERS смогут общаться с ботом. Для команды — добавьте несколько ID через запятую.
Бот не отвечает в группе — что делать?
Проверьте три вещи: (1) отключён ли режим приватности в BotFather, (2) добавлен ли ID группы в TELEGRAM_ALLOWED_CHATS, (3) был ли бот удалён и заново добавлен в группу после смены настроек приватности. Telegram кэширует настройку при первом добавлении бота.
Можно ли использовать существующий Telegram-бот?
Да. Запустите hermes gateway setup, выберите Telegram, вставьте токен существующего бота из BotFather, добавьте свой user ID и запустите шлюз. Бот начнёт отвечать через Hermes, заменив предыдущую логику.
Как передать файл боту?
Просто отправьте файл в чат с ботом. Hermes получит файл и сможет его обработать — прочитать, проанализировать, преобразовать. Поддерживаются изображения, документы, архивы и медиафайлы.
*Статья опубликована на hermeswiki.ru — русскоязычная энциклопедия по Hermes Agent. Официальная документация: hermes-agent.nousresearch.com.*