Настройка Telegram

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

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

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

1. Откройте Telegram и найдите @BotFather или перейдите по ссылке t.me/BotFather

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

3. Выберите отображаемое имя (например, "Hermes Agent") — это может быть любое имя

4. Выберите username — он должен быть уникальным и заканчиваться на bot (например, my_hermes_bot)

5. BotFather ответит вашим API-токеном. Он выглядит так:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Шаг 2: Настройка бота (опционально)

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

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. Перейдите в Bot Settings → Group Privacy → Turn off

Шаг 4: Поиск вашего User ID

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

Метод 1 (рекомендуется): Напишите @userinfobot — он мгновенно ответит вашим User ID.

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

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

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

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

hermes gateway setup

Выберите Telegram при запросе. Мастер запросит токен бота и разрешенные User ID, после чего запишет конфигурацию за вас.

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

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

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # Через запятую для нескольких пользователей

Запуск Gateway

hermes gateway

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

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

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

Частая проблема:

• агент записывает файл внутри Docker в /workspace/report.txt

• модель выдает MEDIA:/workspace/report.txt

• доставка в Telegram не удается, потому что /workspace/report.txt существует только внутри контейнера, а не на хосте

Рекомендуемый паттерн:

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

Затем:

• записывайте файлы внутри Docker в /output/...

• указывайте видимый на хосте путь в MEDIA:, например: MEDIA:/home/user/.hermes/cache/documents/report.txt

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

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

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

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

Режим Webhook

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

Для облачных развертываний (Fly.io, Railway, Render и т.д.) режим webhook более экономичен. Эти платформы могут автоматически пробуждать приостановленные машины при входящем HTTP-трафике, но не при исходящих соединениях. Поскольку polling является исходящим, polling-бот никогда не может заснуть. Режим webhook меняет направление — Telegram отправляет обновления на HTTPS-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, gateway запускает HTTP-сервер webhook вместо polling. Когда не установлен, используется режим polling — поведение не изменилось по сравнению с предыдущими версиями.

Пример облачного развертывания (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. Откройте порт webhook в вашем fly.toml:

[[services]]
  internal_port = 8443
  protocol = "tcp"

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443

1. Разверните:

fly deploy

В логе gateway должно появиться: [telegram] Connected to Telegram (webhook mode).

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

Если 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, не установлен, gateway использует HTTPS_PROXY / HTTP_PROXY / ALL_PROXY (или автоопределение системного прокси macOS).

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

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

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

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="My Notes"

Голосовые сообщения

Входящие голосовые (Speech-to-Text)

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

• local использует faster-whisper на машине, запускающей Hermes — API-ключ не требуется

• groq использует Groq Whisper и требует GROQ_API_KEY

• openai использует OpenAI Whisper и требует VOICE_TOOLS_OPENAI_KEY

Исходящие голосовые (Text-to-Speech)

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

• OpenAI и ElevenLabs изначально выдают Opus — дополнительная настройка не требуется

• Edge TTS (бесплатный провайдер по умолчанию) выдает MP3 и требует ffmpeg для конвертации в Opus:

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

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

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

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

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

• Приватный режим определяет, какие сообщения может видеть бот (см. Шаг 3)

• TELEGRAM_ALLOWED_USERS всё ещё применяется — только авторизованные пользователи могут активировать бота, даже в группах

• Вы можете запретить боту отвечать на обычный групповой чат с помощью telegram.require_mention: true

• С telegram.require_mention: true групповые сообщения принимаются, когда они являются:

• ответами на сообщения бота
• упоминаниями @botusername
• /command@botusername (команда из меню бота Telegram, включающая имя бота)

• совпадениями с одним из настроенных regex-слов-триггеров в telegram.mention_patterns

• Используйте telegram.ignored_threads, чтобы держать Hermes в тишине в определенных темах форума Telegram, даже если группа в остальном разрешает свободные ответы или ответы по упоминанию

• Если telegram.require_mention оставлен не установленным или равен false, Hermes сохраняет предыдущее поведение открытой группы и отвечает на обычные групповые сообщения, которые может видеть

Устранение неполадок: работает в ЛС, но не в группах

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

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. Если вы используете авторизацию на уровне чата, поместите эти ID в 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

• Шаблоны используют регулярные выражения Python

• Сравнение регистронезависимое

• Шаблоны проверяются как для текстовых сообщений, так и для подписей к медиа

• Невалидные regex-шаблоны игнорируются с предупреждением в логах gateway, а не вызывают падение бота

• Если вы хотите, чтобы шаблон срабатывал только в начале сообщения, заякорите его с помощью ^

Приватные Темы Чатов (Bot API 9.4)

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

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

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

• Тема "Website" — работа над вашим продакшн-веб-сервисом

• Тема "Research" — обзор литературы и исследование статей

• Тема "General" — разносторонние задачи и быстрые вопросы

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

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

Добавьте темы в раздел platforms.telegram.extra.dm_topics в ~/.hermes/config.yaml:

platforms:
  telegram:
    extra:
      dm_topics:
      - chat_id: 123456789        # Ваш Telegram User ID
        topics:
        - name: General
          icon_color: 7322096
        - name: Website
          icon_color: 9367192
        - name: Research
          icon_color: 16766590
          skill: arxiv              # Автоматически загружать навык в этой теме

Поля:

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

1. При запуске gateway 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).

Мульти-сессионный режим ЛС (/topic)

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

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

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

DM Topics vs Мульти-сессионный режим ЛС

Обе функции могут сосуществовать на одном боте — вы запускаете /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. Если оба равны true, включит мульти-сессионный режим тем для этого DM

3. Создаст и закрепит тему System для статуса/команд (best-effort)

4. Ответит списком предыдущих несвязанных Telegram-сессий, которые пользователь может восстановить

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

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

1. Откройте DM бота в Telegram

2. Нажмите All Messages вверху интерфейса бота, затем отправьте любое сообщение

3. Telegram создаёт новую тему для этого сообщения

4. Hermes отвечает внутри этой темы — тема теперь является самостоятельной сессией

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

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

Когда Hermes генерирует название сессии для темы (через конвейер авто-названий, после первого обмена), сама тема Telegram переименовывается соответствующим образом — например, "New Topic" становится "Database migration plan". Переименование выполняется по принципу best-effort: сбои логируются, но не нарушают работу сессии.

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

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

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

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

/topic <session-id>

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

• Целевая сессия должна принадлежать тому же пользователю Telegram

• Целевая сессия не должна быть уже привязана к другой теме

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

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

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

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

Под капотом

• Активация сохраняется в telegram_dm_topic_mode(chat_id, user_id, enabled, ...) в state.db

• Каждая привязка темы сохраняется в telegram_dm_topic_bindings(chat_id, thread_id, session_id, ...) с ON DELETE CASCADE по session_id — удаление сессии автоматически очищает её привязку к теме

• Миграция SQLite для режима тем является opt-in: она выполняется при первом вызове /topic, никогда при запуске gateway. Пока пользователь не запустит /topic в этом профиле, state.db не изменяется

• Каждое входящее DM-сообщение ищет свою привязку (chat_id, thread_id). Если она есть, поиск направляет сообщение в привязанную сессию через SessionStore.switch_session(), чтобы сопоставление ключа сессии с ID сессии оставалось согласованным на диске

• /new внутри темы перезаписывает строку привязки, указывая на новый ID сессии, чтобы следующее сообщение оставалось на свежей сессии

• Темы, объявленные в extra.dm_topics, никогда не переименовываются автоматически — выбранное оператором имя сохраняется, даже если мульти-сессионный режим включён

• Общая тема (закреплённая вверху) в DM с включённым форумом обрабатывается как корневое лобби, независимо от того, доставляет ли Telegram её сообщения с message_thread_id=1 или без thread_id

• Напоминания о корневом лобби ограничены по частоте: одно сообщение каждые 30 секунд на чат — пользователь, который забыл, что режим тем включён, и ввёл десять запросов в корневой DM, не получит десять ответов

• Скриншоты настроек BotFather ограничены по частоте: одна отправка каждые 5 минут на чат — повторные попытки /topic, пока Threads Settings всё ещё отключены, не будут повторно загружать то же изображение

• /background <prompt>, запущенный внутри темы, доставляет результат обратно в ту же тему; фоновые сессии не вызывают авто-переименование родительской темы

• /topic сам по себе ограничен проверкой авторизации пользователя бота — неавторизованные DM получают отказ вместо активации

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

Отправьте /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 продолжают работать как параллельные сессии. Корневой DM больше не является лобби — сообщения там отправляются агенту как раньше. Повторное обновление реактивирует мульти-сессионный режим точно в том же состоянии.

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

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

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

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

• Тема Engineering → автоматически загружает навык software-development

• Тема Research → автоматически загружает навык arxiv

• Тема General → без навыка, ассистент общего назначения

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

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

platforms:
  telegram:
    extra:
      group_topics:
      - chat_id: -1001234567890       # ID супергруппы
        topics:
        - name: Engineering
          thread_id: 5
          skill: software-development
        - name: Research
          thread_id: 12
          skill: arxiv
        - name: General
          thread_id: 1
          # Без навыка — общего назначения

Поля:

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

1. Когда сообщение поступает в сопоставленную тему группы, Hermes ищет chat_id и thread_id в конфигурации group_topics

2. Если найдена запись с полем skill, этот навык автоматически загружается для сессии — идентично привязке навыков в DM темах

3. Темы без ключа skill получают только изоляцию сессии (существующее поведение, без изменений)

4. Несопоставленные значения thread_id или chat_id молча пропускаются — без ошибки, без навыка

Отличия от DM Topics

Новые возможности Bot API

• Bot API 9.4 (Фев 2026): Приватные Темы Чатов — боты могут создавать форумные темы в личных DM-чатах через createForumTopic. Hermes использует это для двух различных функций: управляемые оператором Приватные Темы Чатов (на основе конфига, фиксированный список тем) и управляемый пользователем Мульти-сессионный режим ЛС (активируется /topic, неограниченное количество создаваемых пользователем тем).

• Политика конфиденциальности: Telegram теперь требует, чтобы у ботов была политика конфиденциальности. Установите её через BotFather с помощью /setprivacy_policy, иначе Telegram может автоматически сгенерировать заглушку. Это особенно важно, если ваш бот открыт для публики.

• Стриминг сообщений: Bot API 9.x добавил поддержку стриминга длинных ответов, что может улучшить воспринимаемую задержку для длинных ответов агента.

Отображение: таблицы и превью ссылок

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

• Небольшие таблицы преобразуются в маркированные списки по группам строк — каждая строка становится читаемым маркированным списком под заголовками столбцов. Хорошо для 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-группы и форумные чаты имеют два ортогональных шлюза, которые вы можете настроить:

• ID отправителей (group_allow_from / TELEGRAM_GROUP_ALLOWED_USERS) — белый список отправителей, применяемый только к сообщениям в группах/форумах. Используйте это, когда хотите, чтобы определённые пользователи могли вызывать бота в группах, не добавляя их в TELEGRAM_ALLOWED_USERS (что также дало бы им доступ в ЛС).

• ID чатов (group_allowed_chats / TELEGRAM_GROUP_ALLOWED_CHATS) — белый список на уровне чата. Любой участник этих групп/форумов может взаимодействовать с ботом. Полезно для командных/поддерживающих ботов, где само членство в группе является сигналом доступа.

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

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

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

Поведение:

• TELEGRAM_ALLOWED_USERS охватывает все типы чатов (ЛС, группы, форумы).

• TELEGRAM_GROUP_ALLOWED_USERS авторизует только перечисленных отправителей в группах/форумах. Они всё ещё не могут писать боту в ЛС, если не указаны в TELEGRAM_ALLOWED_USERS.

• Чат в TELEGRAM_GROUP_ALLOWED_CHATS авторизует каждого участника этого чата, независимо от отправителя.

• Используйте * в любом из этих параметров, чтобы разрешить любого отправителя/чат.

• Это работает поверх существующих триггеров упоминаний/шаблонов и поверх group_topics + ignored_threads.

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

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

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

# Новый способ
TELEGRAM_GROUP_ALLOWED_CHATS="-1001234567890"

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

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

1. Выбор провайдера — кнопки, показывающие каждого доступного провайдера с количеством моделей (например, "OpenAI (15)", "✓ Anthropic (12)" для текущего провайдера).

2. Выбор модели — постраничный список моделей с навигацией Prev/Next, кнопкой Back для возврата к провайдерам и Cancel.

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

Резервные 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"

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

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

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

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

1. HTTPS_PROXY

2. HTTP_PROXY

3. ALL_PROXY

4. https_proxy / http_proxy / all_proxy (варианты в нижнем регистре)

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

Установите прокси в вашем окружении перед запуском gateway:

export HTTPS_PROXY=http://proxy.example.com:8080
hermes gateway

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

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

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

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

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

• 👀 когда бот начинает обработку вашего сообщения

• ✅ когда ответ успешно доставлен

• ❌ если произошла ошибка во время обработки

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

telegram:
  reactions: true

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

TELEGRAM_REACTIONS=true

Подсказки для каналов

Назначайте эфемерные системные подсказки для конкретных групп Telegram или форумных тем. Подсказка вставляется во время выполнения на каждом шаге — никогда не сохраняется в истории транскрипта — поэтому изменения вступают в силу немедленно.

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.

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

• Сообщение в теме 42 внутри группы -1001234567890 → использует подсказку темы 42

• Сообщение в теме 99 (без явной записи) → возвращается к подсказке группы -1001234567890

• Сообщение в группе без записи → никакая подсказка канала не применяется

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

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

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

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

⚠️ Эта команда потенциально опасна (рекурсивное удаление). Ответьте "yes" для подтверждения.

Ответьте "yes"/"y" для подтверждения или "no"/"n" для отказа.

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

Никогда не делитесь токеном бота публично. Если он скомпрометирован, немедленно отзовите его через команду /revoke в BotFather.

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