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

> Узнайте, как создать бота через BotFather, настроить токен и список разрешённых пользователей в Hermes Agent и запустить шлюз. Настройте голосовые сообщения, задачи по расписанию и управление агентом с телефона.

Source: https://ailoot.ai/blog/ru/hermes-agent-telegram-setup/
Canonical: https://ailoot.ai/blog/ru/hermes-agent-telegram-setup/
Language: ru
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-118
Revision: sha256-d9526770f730982bf865d4c16e9ca133ad84ec47567a3bb30ba00610cea635be


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

Если Hermes ещё не установлен, сначала прочитайте [об агенте и его установке](https://ailoot.ai/blog/ru/hermes-agent-install-setup/), затем вернитесь к настройке Telegram.

Дополнительные инструкции доступны в [документации Ailoot](https://ailoot.ai/docs/).

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Ключевые сведения">

Главное

Понадобятся установленный Hermes Agent с подключённой моделью и аккаунт Telegram. Создать бота в Telegram можно бесплатно, а Hermes — проект с открытым исходным кодом. Возможны отдельные расходы на модель, облачное распознавание речи и сервер, если бот должен быть доступен круглосуточно.

</div>

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Ключевые сведения">

Главное

Найдите в Telegram @BotFather и отправьте ему команду /newbot. Затем задайте отображаемое имя и уникальный юзернейм, оканчивающийся на `bot`. В ответ BotFather пришлёт токен формата 123456789:ABCdef... — секретный ключ управления ботом. Сохраните его и никому не передавайте.

</div>

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

1.  ### Найдите @BotFather

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

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

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

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

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

<div class="aside" data-semantic="callout" role="note" aria-label="Важно">

Внимание

Владелец токена получает полный контроль над ботом. Если токен оказался у посторонних, немедленно отзовите его командой `/revoke` в диалоге с BotFather, а затем получите новый.

</div>

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Ключевые сведения">

Главное

Быстрый способ «Create with QR», описанный выше, автоматически определяет ваш ID. Запишите числовой ID, например 123456789, рядом с токеном. Это номер аккаунта: публичный юзернейм с символом @ не подойдёт для списка доступа. Hermes сверяет с ID разрешённых пользователей; если список не настроен, шлюз не отвечает никому, в том числе вам.

</div>

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

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Ключевые сведения">

Главное

Для автоматической настройки выполните `hermes gateway setup` и выберите Telegram. Мастер запросит токен и ваш ID, затем сохранит параметры. Вручную можно внести две строки в `~/.hermes/.env`. После настройки запустите шлюз командой `hermes gateway`; обычно через несколько секунд бот готов отвечать.

</div>

|  | Мастер настройки | Вручную |
|----|----|----|
| Что запускается | `hermes gateway setup` | Редактор файла `~/.hermes/.env` |
| Какие данные вводятся | Токен и ID в ответ на вопросы мастера | Две переменные в файл |
| Где сохраняются данные | Мастер записывает их в настройки | Параметры задаются непосредственно в `.env` |
| Для кого подходит | Рекомендуемый вариант для всех | Для тех, кто предпочитает редактировать конфигурацию или настраивать её скриптом |

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-бота на телефоне?

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Ключевые сведения">

Главное

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

</div>

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

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

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

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

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

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Ключевые сведения">

Главное

Чтобы получать результаты задач по расписанию в домашний чат, откройте диалог с ботом и отправьте `/sethome`. Фоновая задача, запущенная из темы, вернёт результат в эту же тему. Для ответа бота шлюз должен постоянно работать: при выключенном компьютере он недоступен.

</div>

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

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

Бот отвечает только при работающем шлюзе. Если компьютер с Hermes выключен или перешёл в спящий режим, бот останется недоступен до возобновления работы машины. Чтобы поддерживать соединение круглосуточно, перенесите агента на сервер; порядок настройки описан в [инструкции по постоянной работе Hermes Agent](https://ailoot.ai/blog/ru/hermes-agent-vps-24-7/). По умолчанию шлюз сам запрашивает Telegram о новых сообщениях. Для облачных платформ, которые переходят в спящий режим без входящего трафика, в документации предусмотрен режим webhook: направление соединения меняется, и Telegram сам обращается к боту.

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Ключевые сведения">

Главное

`TELEGRAM_ALLOWED_USERS` разрешает указанным отправителям личные и групповые чаты. Группы также можно разрешить отдельно: `TELEGRAM_GROUP_ALLOWED_CHATS` предоставляет доступ каждому участнику перечисленных групп. Храните токен в секрете и отзывайте утёкший через `/revoke` в BotFather. Фильтры упоминаний определяют момент ответа, а не право доступа.

</div>

Бота можно найти в 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`. На остальные сообщения группы он не отвечает.

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Ключевые сведения">

Главное

Частая причина — включённый режим приватности Telegram: по умолчанию бот в группе получает только команды и ответы на свои сообщения. Отключите его в BotFather: /mybots → Bot Settings → Group Privacy → Turn off. Затем удалите бота из группы и добавьте снова, чтобы Telegram применил изменение. Другой вариант — назначить бота администратором группы.

</div>

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

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

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

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

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Ключевые сведения">

Главное

Убедитесь, что шлюз запущен, токен верен, а ваш ID включён в список доступа. Для проблем в группах проверьте режим приватности. Если не распознаются голосовые, настройте провайдер STT; для отправки голосового ответа через Edge TTS установите ffmpeg.

</div>

| Симптом | Возможная причина | Решение |
|----|----|----|
| Бот совсем не отвечает | Токен указан неверно или шлюз не запущен | Проверьте токен в `.env`, выполните `hermes gateway` и изучите сообщения в том же терминале |
| Бот отвечает «unauthorized» | Вашего ID нет в списке разрешённых | Проверьте числовой ID, внесите его в `TELEGRAM_ALLOWED_USERS` и перезапустите шлюз |
| В личном чате бот отвечает, а в группе молчит | Включён режим приватности | Выберите «Turn off» в настройках BotFather, затем удалите и заново добавьте бота; либо назначьте его администратором |
| Голосовые сообщения не преобразуются в текст | Не настроено распознавание речи | Для локальной обработки установите пакет faster-whisper; для облачного провайдера укажите требуемый ключ |
| Ответ через Edge TTS приходит файлом, а не обычным голосовым сообщением | Не установлен ffmpeg | Установите ffmpeg: Edge TTS использует его для преобразования аудио в формат голосовых сообщений Telegram |
| Токен больше не принимается | Его отозвали | Получите новый через `/revoke` и `/newbot` (или `/token`) в BotFather, обновите значение в `.env` и перезапустите шлюз |

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Ключевые сведения">

Главное

Сервер для начала не требуется, но бот доступен только при работающем шлюзе. Подключение бесплатно; отдельная плата может взиматься за модель. Нескольким людям можно разрешить доступ через список ID. Бот не видит личные переписки. Для файлов больше 20 МБ нужна дополнительная настройка.

</div>

<div class="section">

### Вопросы и ответы

Нужен ли сервер для работы бота?

Нет, сначала достаточно компьютера, на котором установлен Hermes. Бот работает, пока запущен шлюз: выключите компьютер или переведите его в спящий режим — и бот перестанет отвечать до возобновления работы машины. Для круглосуточной доступности перенесите агента на сервер; этому посвящена отдельная инструкция.

Сколько стоит подключение бота?

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

Можно ли разрешить доступ супруге или команде?

Да. В `TELEGRAM_ALLOWED_USERS` можно перечислить через запятую ID нескольких людей — каждый из них сможет писать боту в личный чат. Если разрешить чат через `TELEGRAM_GROUP_ALLOWED_CHATS`, бот станет доступен всем участникам этой группы; именно так в документации описана настройка разрешённых чатов.

Может ли бот читать мои личные переписки?

Нет. Bot API передаёт ему личные сообщения, адресованные самому боту. В группах действует описанный выше режим приватности Telegram. Переписки с другими людьми бот не получает.

Почему бот не принимает длинное голосовое сообщение?

Публичный Bot API ограничивает скачивание файлов размером 20 МБ; файлы большего размера отклоняются. В документации Hermes описан вариант с локальным сервером Bot API, который увеличивает предел до 2 ГБ. Это потребуется только для файлов свыше 20 МБ. Ссылка на документацию приведена в разделе источников.

Можно ли расширить возможности бота?

Да. В Hermes предусмотрены скиллы и плагины — дополнительные навыки для агента. Установка плагинов в Telegram-бота на базе ИИ разобрана в отдельной инструкции.

</div>

<div class="section" role="doc-bibliography" aria-label="Официальные источники">

### Официальные источники

- [Hermes Agent: настройка Telegram](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram) — основная документация, сверенная 12.09.2026
- [Hermes Agent: шлюз мессенджеров](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)
- [Hermes Agent: установка](https://hermes-agent.nousresearch.com/docs/getting-started/installation)
- [Hermes Agent: быстрый старт](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)
- [Hermes Agent: задачи по расписанию](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)
- [BotFather](https://t.me/BotFather) — официальный бот Telegram для создания ботов

</div>



Узнайте больше о [Ailoot](https://ailoot.ai/).

## Вопросы и ответы

### Блокирует ли личный список неуказанных людей в разрешённой группе?

Если весь чат разрешён через TELEGRAM_GROUP_ALLOWED_CHATS, доступен каждый его участник. TELEGRAM_ALLOWED_USERS разрешает отдельных отправителей. До открытия группе проверьте обе настройки.

### Делает ли требование @-упоминания группу доступной только выбранным людям?

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


## Ailoot · Компания и портфель её проектов

Ailoot опирается на накопленный опыт работы, большую клиентскую базу, стабильный сервис и постоянный контроль KPI.

Компания и портфель её проектов: миллионы клиентов; продажи на миллиарды ежемесячно.

Этот опыт Ailoot использует для API-доступа к нейросетям в продуктах клиентов, агентах, приложениях и автоматизациях.