🏠 Главная › User Guide › telegram

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

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

Шаг 1. Создайте бота через BotFather

Каждому боту Telegram требуется токен API, выданный @BotFather, официальным инструментом управления ботами Telegram.

  1. Откройте Telegram и найдите @BotFather или посетите t.me/BotFather
  2. Отправьте /newbot
  3. Выберите отображаемое имя (например, «Агент Гермеса») — это может быть что угодно.
  4. Выберите имя пользователя — оно должно быть уникальным и заканчиваться на «bot» (например, «my_hermes_bot»).
  5. BotFather отвечает вашим токеном API. Это выглядит так:
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
```:::предупреждение
Держите свой токен бота в секрете. Любой, у кого есть этот токен, может управлять вашим ботом. Если утечка произошла, немедленно отзовите ее через `/revoke` в BotFather.</div>
## Шаг 2. Настройте своего бота (необязательно)

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

| Команда | Цель |
|---------|---------|
| `/setdescription` | Вопрос «Что может этот бот?» текст, отображаемый перед тем, как пользователь начинает общение |
| `/setabouttext` | Краткий текст на странице профиля бота |
| `/setuserpic` | Загрузите аватарку для своего бота |
| `/setcommands` | Определить командное меню (кнопка `/` в чате) |
| `/setprivacy` | Контролируйте, видит ли бот все групповые сообщения (см. Шаг 3) |:::совет
Для `/setcommands` полезный стартовый набор:

help - Show help information new - Start a new conversation sethome - Set this chat as the home channel ```

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

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

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

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

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

  1. Сообщение @BotFather
  2. Отправьте /mybots
  3. Выберите своего бота
  4. Откройте Настройки бота → Конфиденциальность группы → Выключить.:::предупреждение Вы должны удалить и повторно добавить бота в любую группу после изменения настроек конфиденциальности. Telegram кэширует состояние конфиденциальности, когда бот присоединяется к группе, и оно не будет обновляться до тех пор, пока бот не будет удален и повторно добавлен.::::::совет Альтернатива отключению режима конфиденциальности: назначьте бота администратором группы. Боты-администраторы всегда получают все сообщения независимо от настроек конфиденциальности, и это позволяет избежать необходимости переключать глобальный режим конфиденциальности.

Шаг 4. Найдите свой идентификатор пользователя

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

Метод 1 (рекомендуется): Сообщение @userinfobot — он мгновенно отвечает с вашим идентификатором пользователя.

Способ 2: Сообщение @get_id_bot — еще один надежный вариант.

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

Шаг 5: Настройте Гермес

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

hermes gateway setup

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

Вариант Б: настройка вручную

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

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # Comma-separated for multiple users

Запуск шлюза

hermes gateway

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

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

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

Распространенная ошибка:

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

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

Тогда:

— записывать файлы внутри Docker в /output/... - указать путь host-visible в MEDIA:, например: МЕДИА:/home/user/.hermes/cache/documents/report.txt

Если у вас уже есть раздел 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-трафике, но не при исходящих соединениях. Поскольку опрос является исходящим, бот-опрос никогда не может спать. Режим Webhook меняет направление: Telegram отправляет обновления на URL-адрес HTTPS вашего бота, позволяя развертывать его в режиме сна во время простоя.

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

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

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

TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
TELEGRAM_WEBHOOK_SECRET="$(openssl rand -hex 32)"  # required
# TELEGRAM_WEBHOOK_PORT=8443        # optional, default 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. Добавьте переменные env в секреты вашего приложения 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] подключено к 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="My Notes"
```:::совет
Идентификаторы групповых чатов представляют собой отрицательные числа (например, `-1001234567890`). Ваш личный идентификатор чата DM совпадает с вашим идентификатором пользователя.</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 работает в групповых чатах Telegram с некоторыми соображениями:

Пример настройки группового триггера

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

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

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

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

— В шаблонах используются регулярные выражения Python. - Сопоставление нечувствительно к регистру - Шаблоны проверяются как по текстовым сообщениям, так и по заголовкам мультимедиа. - Неверные шаблоны регулярных выражений игнорируются с предупреждением в журналах шлюза, а не приводят к сбою бота. - Если вы хотите, чтобы шаблон соответствовал только в начале сообщения, привяжите его с помощью ^

Темы приватного чата (API бота 9.4)

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

Вариант использования

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

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

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

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

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

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

platforms:
  telegram:
    extra:
      dm_topics:
      - chat_id: 123456789        # Your Telegram user ID
        topics:
        - name: General
          icon_color: 7322096
        - name: Website
          icon_color: 9367192
        - name: Research
          icon_color: 16766590
          skill: arxiv              # Auto-load a skill in this topic

Поля:

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

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

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

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

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

Например, в теме с skill: arxiv навык arxiv будет предварительно загружен при каждом сбросе сеанса (из-за тайм-аута простоя, ежедневного сброса или ручного /reset).:::совет Темы, созданные вне конфигурации (например, путем ручного вызова Telegram API), обнаруживаются автоматически при поступлении служебного сообщения 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 <идентификатор-сеанса> Внутри темы Восстановить предыдущую сессию Telegram в текущей теме

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

Темы DM против многосессионного режима DM

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

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

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

В @BotFather откройте своего бота → Настройки бота → Настройки тем:

  1. Включите Режим резьбы (включает has_topics_enabled`)
  2. не отключать пользователей, создающих темы (оставив allows_users_to_create_topics включенным)

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

Порядок активации

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

/topic

Гермес будет:

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

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

Создание новой темы (поток конечного пользователя)

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

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

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

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

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

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

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

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

/topic <session-id>

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

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

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

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

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

Под капотом

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

Отправьте /topic off в корневой DM. Гермес отключает строку, очищает привязки чата (thread_id → session_id), и корневой DM возвращается к обычному чату Гермеса. Существующие темы в 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, предшествующую /topic, эта функция просто перестанет работать — таблицы telegram_dm_topic_mode и telegram_dm_topic_bindings останутся в state.db, но будут игнорироваться старым кодом. DM возвращаются к встроенной изоляции каждого потока (каждый message_thread_id по-прежнему получает свой собственный сеанс через build_session_key), поэтому ваши существующие темы Telegram продолжают работать как параллельные сеансы. Корневой DM больше не является лобби — сообщения оттуда поступают агенту, как раньше. Повторное обновление активирует многосессионный режим именно там, где он был.

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

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

Вариант использования

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

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

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

platforms:
  telegram:
    extra:
      group_topics:
      - chat_id: -1001234567890       # Supergroup ID
        topics:
        - name: Engineering
          thread_id: 5
          skill: software-development
        - name: Research
          thread_id: 12
          skill: arxiv
        - name: General
          thread_id: 1
          # No skill — general purpose

Поля:

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

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

  1. Когда сообщение поступает в сопоставленную групповую тему, Hermes ищет chat_id и thread_id в конфигурации group_topics.
  2. Если в соответствующей записи есть поле «навык», этот навык автоматически загружается для сеанса — аналогично привязке навыка к теме DM.
  3. Темы без ключа навыка получают только изоляцию сеанса (существующее поведение без изменений).
  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 ботов

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

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

– Небольшие таблицы объединяются в маркеры групп строк — каждая строка становится читаемым маркированным списком под заголовками столбцов. Подходит для 2–4 столбцов и коротких ячеек. – Большие или более широкие таблицы возвращаются к огороженному блоку кода с выровненными столбцами, чтобы ничего не схлопывалось. Добавлена ​​однострочная подсказка, чтобы агент знал, что предпочитает прозаические последующие действия большему количеству таблиц в Telegram.

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

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

gateway:
  platforms:
    telegram:
      extra:
        disable_link_previews: true

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

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

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

gateway:
  platforms:
    telegram:
      extra:
        # Global access (DMs + groups). Users here can always invoke the bot.
        allow_from:
          - "123456789"
        # Sender IDs allowed in groups/forums only. Does NOT grant DM access.
        group_allow_from:
          - "987654321"
        # Entire groups/forums — any member is authorized.
        group_allowed_chats:
          - "-1001234567890"

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

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

Поведение:

Миграция с предыдущего PR #17686

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

# Old (still works, but deprecated)
TELEGRAM_GROUP_ALLOWED_USERS="-1001234567890"

# New
TELEGRAM_GROUP_ALLOWED_CHATS="-1001234567890"

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

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

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

Текущая модель и поставщик отображаются вверху. Вся навигация происходит путем редактирования одного и того же сообщения на месте (без беспорядка в чате).:::совет Если вы знаете точное название модели, введите /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-адрес успешен, он становится «прикрепленным» — последующие запросы используют его напрямую, не повторяя сначала основной путь.

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

# Explicit fallback IPs (comma-separated)
TELEGRAM_FALLBACK_IPS=149.154.167.220,149.154.167.221

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

platforms:
  telegram:
    extra:
      fallback_ips:
        - "149.154.167.220"
```:::совет
Обычно вам не нужно настраивать это вручную. Автоматическое обнаружение через 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 не требуется — если переменная среды установлена, она используется автоматически.:::примечание Здесь рассматривается пользовательский резервный транспортный уровень, который Hermes использует для соединений Telegram. Стандартный клиент httpx, используемый где-то еще, уже изначально учитывает переменные окружения прокси.

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

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

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

telegram:
  reactions: true

Или через переменную среды:

TELEGRAM_REACTIONS=true
```:::примечание
В отличие от Discord (где реакции суммируются), API ботов Telegram заменяет все реакции ботов за один вызов. Переход от 👀 к ✅/❌ происходит атомарно — вы не увидите оба сразу.::::::совет
Если у бота нет разрешения на добавление реакций в группу, вызовы реакций завершаются автоматически, и обработка сообщений продолжается в обычном режиме.</div>
## Подсказки для каждого канала

Назначайте временные системные подсказки конкретным группам Telegram или темам форума. Приглашение вводится во время выполнения на каждом ходу и никогда не сохраняется в истории расшифровки, поэтому изменения вступают в силу немедленно.
```yaml
telegram:
  channel_prompts:
    "-1001234567890": |
      You are a research assistant. Focus on academic sources,
      citations, and concise synthesis.
    "42":  |
      This topic is for creative writing feedback. Be warm and
      constructive.

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

Числовые ключи YAML автоматически нормализуются в строки.

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

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

Утверждение исполнительного директора

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

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

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

Безопасность:::предупреждение

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

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