🏠 Главная › user guide › telegram

Настройка Телеграм

Hermes Agent интегрируется с Telegram как полнофункциональный диалоговый бот. После подключения вы можете связаться с агентом на любом устройстве, передать голосовые сообщения для автоматического расшифровки, получить результаты запланированных задач и использовать агента в групповых чатах. Интеграция построена на python-telegram-bot и поддерживает приложения для текста, голоса, изображения и файлов.

Шаг 1: Создание бота через BotFather

Каждому Telegram-боту требуется выданный API-токен @BotFather — возможности управления ботами Telegram.

  1. Откройте Telegram и зайдите @BotFather, или задержитесь по ссылке t.me/BotFather
  2. Отправьте /newbot
  3. Выберите отображаемое имя (например, «Агент Hermes») — может быть любое.
  4. Выберите имя пользователя — необходимо добиться успеха и завершить работу с bot (например, my_hermes_bot).
  5. BotFather отвечает за ваш API-токен. Он выглядит так:
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
```<div class="admonition admonition-warning"><p class="admonition-title">⚠️ Warning</p>
Храните токен бота в секрете. Любой, у кого есть этот токен, может управлять вашим ботом. Если он утек, немедленно отзовите его через `/revoke` в BotFather.</div>
## Шаг 2: Настройка бота (опционально)

Эти команды BotFather улучшают пользовательский опыт. Напишите @BotFather и вскормите:

| Команда | Назначение |
|---------|-----------|
| `/setdescription` | Текст «Что умеет этот бот?», пока называется до того, как пользователь начал общаться в чате |
| `/setabouttext` | Короткий текст на странице профиля бота |
| `/setuserpic` | Загрузить аватар для бота |
| `/setcommands` | Определить меню команды (кнопка `/` в чате) |
| `/setprivacy` | Управление тем, видит ли бот все сообщения в группе (см. Шаг 3) |<div class="admonition admonition-tip"><p class="admonition-title">💡 Tip</p>
Для полезного начального набора `/setcommands`:

help - Показать справку new - Начать новый разговор sethome - Установить этот чат как домашний канал ```

Шаг 3: Режим конфиденциальности (критично для группы)

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

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

С выключенным режимом конфиденциальности бот получает каждое сообщение в группе.

Как отключить режим конфиденциальности

  1. Напишите @BotFather
  2. Отправьте /mybots
  3. Выберите свою обувь
  4. Перейдите в ** Настройки бота → Конфиденциальность группы → Выключить.

    ⚠️ Warning

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

    💡 Tip

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

Шаг 4: Поиск вашего идентификатора пользователя

Агент Hermes использует числовые идентификаторы пользователя Telegram для контроля доступа. Ваш идентификатор пользователя — не ваше имя пользователя, это число, например 123456789.

Метод 1 (рекомендуемый): Напишите @userinfobot — он мгновенно ответит на ваш идентификатор пользователя.

Метод 2: Напишите @get_id_bot — еще один надежный вариант.

Сохраните это число; это понадобится на следующем шаге.

Шаг 5: Настройка Hermesа

Вариант A: Интерактивная настройка (рекомендуется)

hermes gateway setup

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

Вариант Б: Ручная настройка

Добавьте следующее в ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # Разделенные запятыми для нескольких пользователей

Запуск шлюза

hermes gateway

Бот должен появиться онлайн через несколько секунд. Отправьте ему сообщение в Telegram для проверки.

Отправка сгенерированных файлов из терминалов на базе Docker

Если ваш бэкенд-терминал — «докер», имейте в виду, что приложения Telegram отправляются процессом шлюза, а не из контейнера. Это означает, что конечный путь MEDIA:/... должен быть прочитан на хосте, где работает шлюз.

Частая ошибка:

Рекомендуемый шаблон:

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/.hermes/cache/documents:/output"

Затем:

Если у вас уже есть раздел docker_volumes:, страницы новый монтируемый том в том же списке. Дублирующиеся ключи YAML молча переопределяют звук.

Поддерживаемые расширения файлов MEDIA:

Шлюз извлекает теги MEDIA:/path/to/file из ответов агента и отправляет указанный файл как родное вложение платформы. Поддерживаемые расширения для всех платформенных шлюзов:

Категория Расширение
Изображения 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, yml, log
Офис docx, xlsx, pptx, odt, ods, odp
Архивы zip, rar, 7z, tar, gz, bz2
Книги / пакеты epub, apk, ipa

Все, что есть в этом списке, представляет собой родное приложение на платформах, которые применяются (Telegram, Discord, Signal, Slack, WhatsApp, Feishu, Matrix и т.д.); на платформах без родной поддержки используется запасной вариант в виде видеоссылок или текстового индикатора. Жирные категории были добавлены в последних релизах — если вы указали, что модель говорила «вот файл: /path/to/report.docx», замените на «MEDIA:/path/to/report.docx» для родной доставки.

Режим вебхука

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

Для облачных развертываний (Fly.io, Railway, Render и т.д.) режим вебхука более экономичен. Эта платформа может автоматически активировать беспроводные машины при передаче HTTP-трафика, но не при исходящих соединениях. Поскольку опрос исходит, опрашивающий бот никогда не сможет «уснуть». Режим вебхука меняет направление — Telegram отправляет обновления по HTTPS URL вашего бота, что позволяет развертываниям «заливать» в режиме ожидания.

Опрос (по умолчанию) Вебхук
Направление Шлюз → Telegram (приходит) Telegram → Шлюз (в ближайшее время)
Лучше всего для Локальные, постоянно работающие серверы Облачные платформы с автопробуждением
Настройка Нет дополнительной конфигурации Установить TELEGRAM_WEBHOOK_URL
Стоимость простоя Машина значит включенной Машина может спать между сообщениями

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

Добавьте следующее в ~/.hermes/.env:

TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"  # обязательно
# TELEGRAM_WEBHOOK_PORT=8443        # опционально, по умолчанию 8443
Переменная Обязательно Описание
TELEGRAM_WEBHOOK_URL Да Публичный URL-адрес HTTPS, куда Telegram будет публиковать обновления. Путь URL извлекается автоматически (например, /telegram из примера выше).
TELEGRAM_WEBHOOK_SECRET Да (когда установлен TELEGRAM_WEBHOOK_URL) Секретный токен, который Telegram повторяет при каждом запросе вебхуки для проверки. Шлюз отказывается запускаться без него — см. GHSA-3vpc-7q5r-276h. Сгенерируйте с помощью openssl rand -hex 32.
TELEGRAM_WEBHOOK_PORT Нет Локальный порт, на котором слушает сервер вебхука (по умолчанию: 8443).

Когда установлен TELEGRAM_WEBHOOK_URL, шлюз запускает HTTP-сервер вебхука вместо опроса. Если не выбрано, используется режим опроса — поведение не изменяется по сравнению с физическими версиями.

Пример облачного развертывания (Fly.io)

  1. Добавьте переменные окружения в секреты вашего приложения на Fly.io:
fly secrets set TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
fly secrets set TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32)
  1. Откройте порт вебхука в fly.toml:
[[services]]
  internal_port = 8443
  protocol = "tcp"

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443
  1. Развернуть:
fly deploy

В логе шлюза должно появиться: [telegram] Connected to Telegram (режим веб-перехватчика).

Поддержка прокси

Если API Telegram заблокирован или вам нужно направлять трафик через прокси, установите URL-прокси, специально для Telegram. Он имеет приоритет над общими переменными окружениями HTTPS_PROXY/HTTP_PROXY.

Вариант 1: config.yaml (рекомендуется)

telegram:
  proxy_url: "socks5://127.0.0.1:1080"

Вариант 2: переменное окружение

TELEGRAM_PROXY=socks5://127.0.0.1:1080

Поддерживаемые схемы: http://, https://, socks5://.

Прокси применяется как к главному соединению Telegram, так и к запасному IP-транспорту. Если прокси, специальный для Telegram, не установлен, шлюз использует HTTPS_PROXY / HTTP_PROXY / ALL_PROXY (или процент определения системного прокси macOS).

Домашний канал

Используйте команду /sethome в любом Telegram-чате (личном или групповом), чтобы назначить его домашним каналом. Запланированные задачи (cron) публикуют свои результаты на этом канале.

Вы также можете установить его вручную в ~/.hermes/.env:

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Мои заметки"
```<div class="admonition admonition-tip"><p class="admonition-title">💡 Tip</p>
ID групповых чатов — отрицательные числа (например, `-1001234567890`). Идентификатор вашего личного чата соответствует вашему идентификатору пользователя.</div>
## Голосовые сообщения

### Входящие голосовые (распознавание речи)

Голосовые сообщения, которые рассылаются в Telegram, автоматически расшифровываются настроенным STT-провайдером Hermes и озвучиваются в виде текста.

- `local` использует `faster-whisper` на машине, где запущен Hermes — ключ API не требуется
- `groq` использует Groq Whisper и требует `GROQ_API_KEY`
- `openai` использует OpenAI Whisper и требует `VOICE_TOOLS_OPENAI_KEY`

### Исходящие голосовые (синтез речи)

Когда агент передает аудио через TTS, он представляет собой родные Telegram **голосовые пузырьки** — круглые, воспроизводимые в строке.

- **OpenAI и ElevenLabs** создают Opus нативно — дополнительная настройка не требуется.
- **Edge TTS** (бесплатный провайдер по умолчанию) воспроизводит MP3 и требует **ffmpeg** для конвертации в Opus:
```bash
# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

Без ffmpeg аудио Edge TTS воспроизводится как обычный аудиофайл (все еще воспроизводится, но вместо голосового пузырька используется прямоугольный плеер).

Настройте TTS-провайдера в config.yaml под ключом tts.provider.

Использование в групповых чатах

Hermes Agent работает в групповых чатах Telegram с некоторыми особенностями:

Устранение неполадок: работает в личных сообщениях, но не в группах

Если бот отвечает в личном чате, молчит в группе, проверьте эти барьеры в порядке:

  1. Доставка Telegram: отключите режим конфиденциальности в BotFather, сделайте бота администратором или упомяните бота напрямую. Hermes не может использовать в групповых сообщениях, которые Telegram никогда не доставляет.
  2. Повторное добавление после изменения конфиденциальности: удалить бота из групп и страниц снова после изменения настроек конфиденциальности в BotFather. Telegram может сохранить старое качество доставки для нынешних участников.
  3. Авторизация Hermes: убедитесь, что отправитель задан в TELEGRAM_ALLOWED_USERS или TELEGRAM_GROUP_ALLOWED_USERS, или разрешите с помощью группового чата с TELEGRAM_GROUP_ALLOWED_CHATS.
  4. Фильтры упоминаний: если найдены telegram.require_mention: true, обычно групповой чат меняется, если сообщение не является слэш-командой, ответом боту, упоминанием @botusername или совпадением с настроенными mention_patterns.

Отрицательные ID чатов нормальны для групп и супергрупп Telegram. Если вы используете авторизацию на уровне чата, поместите эти идентификаторы в TELEGRAM_GROUP_ALLOWED_CHATS, а не в список разрешенных пользователей-отправителей.

Пример конфигурации триггера в группе

Добавьте это в ~/.hermes/config.yaml:

telegram:
  require_mention: true
  mention_patterns:
    - "^\\s*chompy\\b"
  ignored_threads:
    - 31
    - "42"

Этот пример разрешает все обычные прямые триггеры, а также сообщения, начинающим с chompy, даже если они не используют @упоминание. Сообщения в темах Telegram 31 и 42 всегда игнорируются ссылки на ссылки и ответы.

Примечания к mention_patterns

Темы личных чатов (API бота 9.4)

Bot API Telegram 9.4 (февраль 2026 г.) Представлены темы личных чатов — боты могут создавать темы-форумы непосредственно в индивидуальных чатах 1-на-1, без необходимости в супергруппе. Это позволяет включить несколько изолированных рабочих помещений в существующем личном чате с Hermesом.

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

Если вы работаете над несколькими долгосрочными проектами, темы содержат их контекстный раздел:

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

Конфигурация:::Внимание Предварительные требования

Перед добавлением темы в конфигурацию пользователь должен переключить режим в личном чате с низом:

  1. Откройте свой личный чат с ботом Hermes в Telegram.
  2. Нажмите на имя бота вверх, чтобы открыть информацию о чате.
  3. Включите Темы (переключатель, превращающий чат в форум)

Без этого Hermes при запуске запишет Чат не является форумом и пропустит создание темы. Эта настройка на стороне клиента Telegram — бот не может включить ее программно. Добавьте темы в раздел platforms.telegram.extra.dm_topics в ~/.hermes/config.yaml:

platforms:
  telegram:
    extra:
      dm_topics:
      - chat_id: 123456789        # Ваш Telegram user ID
        topics:
        - name: Общее
          icon_color: 7322096
        - name: Вебсайт
          icon_color: 9367192
        - name: Исследования
          icon_color: 16766590
          skill: arxiv              # Автоматически загружать навык в этой теме

Поля:

Поле Обязательно Описание
name Да Отображаемое имя темы
icon_color Нет Код цвета иконки Telegram (целое число)
icon_custom_emoji_id Нет ID пользовательского эмодзи для иконки темы
skill Нет Навык для автоматической загрузки при новых сессиях в этой теме
thread_id Нет Автоматически заполняется после создания темы — не устанавливать вручную

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

  1. При запуске шлюза Hermes вызывает createForumTopic для каждой темы, у которой еще нет thread_id
  2. thread_id автоматически сохраняется обратно в config.yaml — последующие перезапуски пропускают вызов API
  3. Каждая тема сопоставляется с изолированным ключом сессии: agent:main:telegram:dm:{chat_id}:{thread_id}
  4. Сообщения в каждой теме имеют свою историю разговора, сброс памяти и контекстное окно

Привязка навыка

Темы с полем skill автоматически загружают этот навык при запуске новой сессии в теме. Это работает точно так же, как ввод /skill-name в начале разговора — содержимое навыка внедряется в первое сообщение, а последующие сообщения видят его в истории разговора.

Например, тема с skill: arxiv будет иметь предварительно загруженный навык arxiv всякий раз, когда ее сессия сбрасывается (из-за таймаута бездействия, ежедневного сброса или ручного /reset).

💡 Tip

Темы, созданные вне конфигурации (например, ручным вызовом API Telegram), обнаруживаются автоматически, когда приходит служебное сообщение forum_topic_created. Вы также можете добавлять темы в конфигурацию, пока шлюз работает — они будут подхвачены при следующем промахе кэша.

Режим мультисессионного DM (/topic)

Мультисессионный DM в стиле ChatGPT — один бот, много параллельных разговоров. В отличие от управляемых оператором extra.dm_topics выше, этот режим управляется пользователем: никакой конфигурации, никаких предварительно объявленных имен тем. Конечный пользователь включает его с помощью /topic, затем нажимает кнопку + в Telegram, чтобы создать столько тем, сколько захочет, каждая из которых является полностью независимой сессией Hermes.

Подкоманды /topic

Форма Контекст Эффект
/topic Корневой DM, еще не включен Проверить возможности BotFather, включить мультисессионный режим, создать закрепленную системную тему
/topic Корневой DM, уже включен Показать статус: несвязанные сессии, доступные для восстановления
/topic Внутри темы Показать текущую привязку сессии темы
/topic help Любой Встроенное использование
/topic off Корневой DM Отключить мультисессионный режим и очистить все привязки тем для этого чата
/topic <session-id> Внутри темы Восстановить предыдущую сессию Telegram в текущей теме

Только авторизованные пользователи (белый список через TELEGRAM_ALLOWED_USERS / конфигурация авторизации платформы) могут выполнять /topic. Неавторизованный отправитель получает отказ вместо активации.

DM темы vs мультисессионный DM режим

extra.dm_topics (на основе конфигурации) /topic (управляется пользователем)
Кто активирует Оператор в config.yaml Конечный пользователь, отправив /topic
Список тем Фиксированный набор, объявленный в конфиге Пользователь свободно создает/удаляет темы
Имена тем Выбраны оператором Выбраны пользователем; автоматически переименовываются в соответствии с названием сессии Hermes
Поведение корневого DM Без изменений — обычный чат Становится системным лобби (некомандные сообщения отклоняются)
Основной вариант использования Постоянные рабочие пространства с опциональной привязкой навыков Ад-хок параллельные сессии
Постоянство extra.dm_topics в конфиге Таблицы SQLite telegram_dm_topic_mode + telegram_dm_topic_bindings

Обе функции могут сосуществовать на одном боте — вы запускаете /topic из DM пользователя, а extra.dm_topics продолжает управлять объявленными оператором темами для других чатов.

Предварительные требования

В @BotFather откройте своего бота → Bot Settings → Threads Settings:

  1. Включите Threaded Mode (включает has_topics_enabled)
  2. Не отключайте возможность пользователям создавать темы (оставляет allows_users_to_create_topics включенным)

Когда пользователь впервые запускает /topic, Hermes вызывает getMe для проверки обоих флагов. Если хотя бы один выключен, Hermes отправляет скриншот страницы Threads Settings BotFather и объясняет, что нужно переключить — активация не происходит, пока не выполнены предварительные условия.

Процесс активации

Из корневого DM отправьте:

/topic

Hermes:

  1. Проверьте getMe().has_topics_enabled и allows_users_to_create_topics
  2. Если оба истинны, включите мультисессионный темный режим для этого в DM.
  3. Создаст и закрепит Системную тему для воздействий/команд (наилучшим образом)
  4. Ответить списком предыдущих несвязанных сессий Telegram, которые пользователь может восстановить

После активации корневой DM является лоббистом: обычный запрос отклоняется с надписью Все сообщения. Системные команды (/status, /sessions, /usage, /help и т.д.) все еще работают в корневом чате.

Создание новой темы (пользовательский процесс)

  1. Откройте DM бота в Telegram.
  2. Нажмите Все сообщения вверх по интерфейсу бота, а затем отредактируйте любое сообщение.
  3. Telegram предлагает новую тему для этих сообщений.
  4. Hermes отвечает за эту тему — теперь это отдельная сессия.

каждая тема получает свою собственную историю разговора, состояние модели, инструменты выполнения и идентификатор сеанса. Ключ выполнения: agent:main:telegram:dm:{chat_id}:{thread_id} — идентичен выполнению DM темы на основе структуры.

Автоматическое переименование темы

Когда Hermes выдает название сессии для темы (через конвейер автоназвания, после первого обмена), сама тема Telegram переименовывается в соответствии с ним — например, «Новая тема» становится «План ограничений базы данных». Результат переименования по возможности: регистрируются ошибки, но не нарушают работу сессии.

/new внутри темы

Сбрасывает сессию текущей темы (новый идентификатор сессии, свежая история), не затрагивая другие темы. Hermes отвечает напоминаниям, что для параллельной работы обычно лучше создать другую тему (через Все сообщения).

Восстановление предыдущей сессии

Внутри темы отредактировать:

/topic <session-id>

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

Hermes поддерживает название сессии и воспроизводит последнее сообщение ассистента для контекста.

Чтобы узнать ID сессий, отправьте /topic (без аргументов) в корневом DM — Hermes перечислит несвязанные сессии Telegram пользователя.

/topic внутри темы (без аргументов)

Показывает текущую привязку темы: название сессии, идентификатор сессии и подсказки для /new vs создание другой темы.

Как это работает под капотом

Отключение мультисессионного режима

Отправьте /topic off в корневой DM. Hermes переключает сигнал в выключенное состояние, очищает привязки (thread_id → session_id) для чата, и корневой DM возвращается к обычному чату Hermesа. Существующие темы в Telegram не удаляются — они просто перестают управляться как независимая сессия. Повторный запуск /topic позже снова включает режим.

Если необходимо удалить порошок вручную (например, слить массу для многих чатов), удалите смесь напрямую:

sqlite3 ~/.hermes/state.db \
  "UPDATE telegram_dm_topic_mode SET enabled = 0 WHERE chat_id = '<your_chat_id>'; \
   DELETE FROM telegram_dm_topic_bindings WHERE chat_id = '<your_chat_id>';"

Понижение версии Hermes

Если вы понизите версию Hermes до той, которая была до /topic, функция просто перестанет работать — таблицы telegram_dm_topic_mode и telegram_dm_topic_bindings будут выполняться в state.db, но это будут альтернативные стандартные коды. DM возвращается к родному отправке по потоку (каждый message_thread_id все еще получает свою сессию через build_session_key), поэтому ваши временные темы Telegram продолжают работать как виртуальная сессия. Корневой ДМ больше не является лоббистом — сообщения там обращаются к агенту как раньше. Повторное обновление новой версии возобновляет мультисессионный режим ровно в том состоянии, в котором находился.

Привязка навыка к теме форума группы

Супергруппы с включенным режимом темы (также называемые «темами форума») уже имеют изоляцию сессий по темам — каждый thread_id сопоставляется со своим разговором. Но вы можете захотеть автоматически загрузить навыки, когда приходят сообщения по определенной теме группы, точно так же, как работает привязка навыков к теме DM.

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

Командная супергруппа с темами форума для разных рабочих потоков:

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

Добавьте привязки тем в раздел platforms.telegram.extra.group_topics в ~/.hermes/config.yaml:

platforms:
  telegram:
    extra:
      group_topics:
      - chat_id: -1001234567890       # ID супергруппы
        topics:
        - name: Инженерия
          thread_id: 5
          skill: software-development
        - name: Исследования
          thread_id: 12
          skill: arxiv
        - name: Общее
          thread_id: 1
          # Нет навыка — общего назначения

Поля:

Поле Обязательно Описание
chat_id Да Числовой ID супергруппы (отрицательное число, начинающееся с -100)
имя Нет Человекочитаемая метка для темы (только информация)
thread_id Да ID темы форума Telegram — виден в ссылках вида t.me/c/<group_id>/<thread_id>
умение Нет Навык для автоматической загрузки при новых сессиях в этой теме

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

  1. Когда сообщение приходит в парламентскую группу по теме, Hermes ищет chat_id и thread_id в конфиге group_topics
  2. Если соответствующая запись имеет поле skill, этот навык автоматически загружается для сессии — идентично привязке навыка к теме в DM.
  3. Темы без ключа skill получают только изоляционные сессии (существующее поведение, без изменений)
  4. Несопоставленные значения thread_id или chat_id молчание о результате — без ошибок, без функций

Отличия от DM тем

DM темы Темы группы
Ключ конфига extra.dm_topics extra.group_topics
Создание темы Hermes создает темы через API, если thread_id отсутствует Администратор создает темы в интерфейсе Telegram
thread_id Автоматически выполняется после создания Должен быть установлен вручную
icon_color / icon_custom_emoji_id Поддерживается Непринуждение (администратор руководит выездным видом)
Привязка навыка ✓ ✓
Изоляция сессий ✓ ✓ (уже встроена для тем форума)
Чтобы найти тему thread_id, внедрите тему в Telegram Web или Desktop и просмотрите URL-адрес: https://t.me/c/1234567890/5 — последнее число (5) и есть thread_id. chat_id для супергрупп — это идентификатор группы с префиксом -100 (например, группа 1234567890 становится -1001234567890).
## Последние функции API ботов

Транспорт потоковой передачи (gateway.streaming.transport)

Когда потоковая передача включена (gateway.streaming.enabled: true), Hermes выбирает один из четырех транспортов:

Значение Поведение
авто (по умолчанию) Нативная потоковая связь черновиков в терапевтических чатах (в настоящее время Telegram в DM); окончательный путь на основе редактирования в прошедшем случае. Изящно переключается, если кадр черновика не требуется.
черновик Принудительно вручать родные черновики. Логирует понижение и переключается на редактирование, если чат не поддерживает черновики (например, группы/темы).
редактировать Устаревший прогрессивный опрос editMessageText для каждого типа чата.
выключено Полностью отключите потоковую передачу (только финальный ответ, без прогрессивных обновлений).

В ~/.hermes/config.yaml:

gateway:
  streaming:
    enabled: true
    transport: auto    # auto | draft | edit | off

Что вы показываете в DM с auto (по умолчанию) — при ответе агента Telegram показывает анимированный предварительный просмотр черновика, который обновляется по токену за токеном. Когда ответ будет завершен, он будет представлен, как обычное сообщение, и предварительный просмотр черновика будет очищаться клиентом таким образом. У Черновикова нет идентификатора сообщения, поэтому окончательный ответ остается в истории чата.

А как насчет группы, супергруппы, тем форума? Telegram ограничивает sendMessageDraft личными чатами (DM). Шлюз прозрачности переключается на путь создания основ для всего остального — такого же UX, как и раньше.

Что, если кадр черновика не возник? Любая ошибка (временная сетевая ошибка, отклонение на стороне сервера, старая версия python-telegram-bot) переключает этот ответ обратно на путь на основе редактирования на оставшуюся часть потока. Следующий ответ получает новый город.

Рендеринг: таблицы и предварительные просмотры ссылок

MarkdownV2 Telegram не имеет родного синтаксиса таблиц — таблицы с разделителями (табличными элементами) представляют собой зашумленный текст с обратной косой чертой, если передаются как есть. Hermes автоматически нормализует markdown-таблицы:

Нечего настраивать — адаптер подбирает подходящий запасной вариант для каждого сообщения. Если вы хотите старое поведение «всегда код-блок», отключите нормализацию таблицы, установив telegram.pretty_tables: false в config.yaml (по умолчанию: true).

** Предварительный просмотр ссылок.** Telegram автоматически включает предварительный просмотр ссылок для URL в сообщениях бота. Если вы хотите отключить их (длинный вывод /tools, ответ агента, упоминающий десять ссылок и т.д.):

gateway:
  platforms:
    telegram:
      extra:
        disable_link_previews: true

Когда это включено, Hermes прикрепляет LinkPreviewOptions(is_disabled=True) к каждому обращению к сообщению и возвращает постоянный параметр disable_web_page_preview в старой версии python-telegram-bot.

Белый список группы

Telegram-группы и чаты форума имеют два ортогональных барьера, которые вы можете настроить:

gateway:
  platforms:
    telegram:
      extra:
        # Глобальный доступ (DM + группы). Пользователи здесь могут всегда вызывать бота.
        allow_from:
          - "123456789"
        # ID отправителей, разрешенных только в группах/форумах. НЕ предоставляет доступ к DM.
        group_allow_from:
          - "987654321"
        # Целые группы/форумы — любой участник авторизован.
        group_allowed_chats:
          - "-1001234567890"

Эквивалентные переменные окружения:

TELEGRAM_ALLOWED_USERS="123456789"
TELEGRAM_GROUP_ALLOWED_USERS="987654321"
TELEGRAM_GROUP_ALLOWED_CHATS="-1001234567890"

Поведение:

Миграция с версии до PR #17686

В этом разделе TELEGRAM_GROUP_ALLOWED_USERS был один параметр, и пользователи сохраняли его ID чатов. Для обратной совместимости в виде ID чата (начинающиеся с -) в TELEGRAM_GROUP_ALLOWED_USERS все еще воспринимаются как ID чата, и один раз регистрируется предупреждение об устаревании. Миграция:

# Старое (все еще работает, но устарело)
TELEGRAM_GROUP_ALLOWED_USERS="-1001234567890"

# Новое
TELEGRAM_GROUP_ALLOWED_CHATS="-1001234567890"

Контроль доступа к слеш-командам

По умолчанию каждый разрешенный пользователь может настроить любую слеш-команду. Чтобы просмотреть список администраторов (полный доступ к слэш-командам) и обычных пользователей (только команды, которые вы явно разрешили), разделите allow_admin_from и user_allowed_commands в блоке extra платформы:

gateway:
  platforms:
    telegram:
      extra:
        # Существующие белые списки (без изменений)
        allow_from:
          - "123456789"     # администратор
          - "555555555"     # обычный пользователь
          - "777777777"     # обычный пользователь

        # НОВОЕ — администраторы получают все слеш-команды (встроенные + плагинов)
        allow_admin_from:
          - "123456789"

        # НОВОЕ — неадминистративные разрешенные пользователи могут выполнять только эти слеш-команды.
        # /help и /whoami всегда разрешены, чтобы пользователи могли видеть свой доступ.
        user_allowed_commands:
          - status
          - model
          - history

        # Опционально: отдельные списки администраторов/команд для групп
        group_allow_admin_from:
          - "123456789"
        group_user_allowed_commands:
          - status

Поведение:

Используйте /whoami, чтобы увидеть активную область, ваш уровень (администратор/пользователь/неограниченный) и какие слеш-команды вы можете настроить.

Интерактивный выбор моделей

Когда вы отправляете /model без аргументов в Telegram-чат, Hermes показывает встроенную интерактивную клавиатуру для переключения моделей:

  1. Выбор провайдера — кнопки, показывающие каждого доступного провайдера с указанием модели (например, «OpenAI(15)», «✓ Anthropic(12)» для конкретного провайдера).
  2. Выбор модели — постраничный список моделей с навигацией Предыдущая/Следующая, нажмите Назад для возврата провайдерам и Отмена.

Текущая модель и поставщик представлены вверху. Вся навигация происходит путем редактирования того же сообщения на месте (без засорения чата).

💡 Tip

Если вы знаете точное имя модели, введите /model <имя> напрямую, чтобы проголосовать за выбор. Вы также можете ввести /model <name> --global, чтобы сохранить изменения для всех сессий.

Запасные IP-адреса через DNS-over-HTTPS

В некоторых ограниченных сетях api.telegram.org может быть разрешено использование IP, что является недоступен. Адаптер Telegram включает механизм запасных IP, который четко повторяет соединения с альтернативными IP, сохраняя правильное имя хоста TLS и SNI.

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

  1. Если установлен TELEGRAM_FALLBACK_IPS, эти IP используются напрямую.
  2. В противном случае адаптер автоматически запрашивает Google DNS и Cloudflare DNS через DNS-over-HTTPS (DoH) для определения альтернативных IP-адресов для api.telegram.org.
  3. IP-адреса, возвращенные DoH, которые соответствуют результатам системного DNS и используются как резервные.
  4. Если DoH также заблокирован, жестко заданный запасной IP (149.154.167.220) используется в качестве средства.
  5. Как только реализуется запасной IP, он становится «липким» — источник запроса использует его напрямую, без повторной попытки основного пути.

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

# Явные запасные IP (через запятую)
TELEGRAM_FALLBACK_IPS=149.154.167.220,149.154.167.221

Или в ~/.hermes/config.yaml:

platforms:
  telegram:
    extra:
      fallback_ips:
        - "149.154.167.220"
```<div class="admonition admonition-tip"><p class="admonition-title">💡 Tip</p>
Обычно вам не нужно настраивать это вручную. Автообнаружение через DoH осуществляется в большинстве случаев в ограниченных сетях. Переменное окружение `TELEGRAM_FALLBACK_IPS` потребуется только в том случае, если DoH также заблокирован в вашей сети.</div>
## Поддержка прокси

Если вашей сети требуется HTTP-прокси для доступа в Интернет (обычно в корпоративной среде), адаптер Telegram автоматически считывает стандартные переменные прокси-серверы в окружении и направляет все соединения через прокси.

### Поддерживаемые переменные

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

1. `HTTPS_PROXY`
2. `HTTP_PROXY`
3. `ALL_PROXY`
4. `https_proxy` / `http_proxy` / `all_proxy` (строчные варианты)

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

Установите прокси-сервер перед запуском шлюза:
```bash
export HTTPS_PROXY=http://proxy.example.com:8080
hermes gateway

Или добавьте в ~/.hermes/.env:

HTTPS_PROXY=http://proxy.example.com:8080

Прокси применяется как к сетевому транспорту, так и ко всем запасным IP-транспортам. Никакой дополнительной конфигурации Hermes не требуется — если установлена переменная окружность, она используется автоматически.

📝 Note

Это закрывает пользовательский запас транспортного средства, который Hermes использует для подключения Telegram. Стандартный клиент httpx, прогноз в других точках, уже поддерживает переменные прокси-окружения.

Реакции на сообщения

Бот может добавлять эмодзи-реакции на сообщения в виде визуальной обратной связи при обработке:

Реакции отключены по умолчанию. Включите их в config.yaml:

telegram:
  reactions: true

Или через переменное окружение:

TELEGRAM_REACTIONS=true
```<div class="admonition admonition-note"><p class="admonition-title">📝 Note</p>
В отличие от Discord (где включается), Bot API Telegram заменяет все состояния бота одним вызовом. Переход от 👀 к ✅/❌ происходит атомарно — вы не увидите оба сразу.:::<div class="admonition admonition-tip"><p class="admonition-title">💡 Tip</p>
Если у бота нет разрешения на изменение в группе, вызовы молчат, терпят неудачу, и обработка сообщений продолжается нормально.</div>
## Промпты для каналов

Назначайте эфемерные системные подсказки, с помощью Telegram-групп или тем форума. Подсказка применяется во время выполнения каждого шага — никогда не сохраняется в истории транскриптов, поэтому изменения вступают в силу немедленно.
```yaml
telegram:
  channel_prompts:
    "-1001234567890": |
      Ты — исследовательский ассистент. Сосредоточься на академических
      источниках, цитатах и лаконичном синтезе.
    "42":  |
      Эта тема предназначена для обратной связи по творческому письму.
      Будь теплым и конструктивным.

Ключи — это ID чатов (группы/супергруппы) или ID тем форума. Для групп-форумов промпты уровней темы переопределяют промпты уровней группы:

Несколько ключей YAML автоматически нормализуются в строках.

Устранение неполадок

Проблема Решение
Бот вообще не отвечает Проверьте, что TELEGRAM_BOT_TOKEN верен. Проверьте наличие логи гермес шлюз на наличие ошибок.
Бот отвечает «несанкционировано» Ваш идентификатор пользователя отсутствует в TELEGRAM_ALLOWED_USERS. Перепроверьте с помощью @userinfobot.
Бот игнорирует групповые сообщения Скорее всего, включен режим конфиденциальности. Отключите его (Шаг 3) или сделайте бота администратором группы. Не забудьте удалить и заново добавить бота после изменения конфиденциальности.
Голосовые сообщения не расшифровываются Проверьте, что STT доступен: установите faster-whisper для локальной расшифровки или установите GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY в ~/.hermes/.env.
Голосовые ответы — файлы, а не пузырьки Установите ffmpeg (нужен для конвертации Opus в Edge TTS).
Токен бота отозван/недействителен Сгенерируйте новый токен через /revoke, затем /newbot или /token в BotFather. Обновите файл .env.
Вебхук не получает обновлений Проверьте, что TELEGRAM_WEBHOOK_URL общедоступен (проверьте с помощью curl). Убедитесь, что ваша платформа/обратный прокси направляет входящий HTTPS-трафик с URL-адресом порта на локальный порт, настроенный в TELEGRAM_WEBHOOK_PORT (они не обязательно должны совпадать). Убедитесь, что SSL/TLS активирован — Telegram отправляет данные только по URL-адресу HTTPS. Ознакомьтесь с правилами брандмауэра.

Подтверждение выполнения

Когда агент сможет выполнить проверку опасной команды, он запросит ваше подтверждение в чате:

⚠️ Эта команда контролирует опасность (рекурсивное удаление). Ответьте «да», чтобы быть надежным.

Ответьте «да»/«y», чтобы исправить, или «no»/«n», чтобы отклонить.

Интерактивные запросы (уточнение)

Когда агент предлагает инструмент «уточнить» — чтобы узнать, какой подход вы предпочитаете, получить обратную связь после задачи или проверить перед нетривиальным решением — Telegram отображает вопрос с кнопками встроенной розетки:

❓ Какой фреймворк мне использовать для панели управления?

[1. Next.js] [2. Ремикс] [3. Астро] [✏️ Другое (ввести ответ)]

Нажмите кнопку, чтобы ответить, или нажмите Другое, чтобы ввести свободный ответ (следующее отправленное вам сообщение станет ответом). Открытые вызовы clarify (без предустановленных опций) пропускают кнопку и просто перехватывают ваше следующее сообщение.

Настроить таймаут ответа через agent.clarify_timeout в ~/.hermes/config.yaml (по умолчанию 600 секунд). Если вы не ответите в течение таймаута, агент разблокируется с сообщением-маркером и адаптируется, и это не зависит.

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

⚠️ Warning

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

Для получения дополнительной информации см. Документация по безопасности. Вы также можете использовать Сопряжение DM для более динамичного режима авторизации пользователей.