Telegram-агент в группе: полная настройка

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

1. Режим приватности Telegram (самый частый источник проблем)

У каждого Telegram-бота по умолчанию включён режим приватности. Это значит, что бот в группе видит только:

Сообщения, начинающиеся с команды /
Ответы (replies) на сообщения самого бота
Сервисные сообщения (вход/выход участников, закрепления и т.д.)
Все сообщения в каналах, где бот — админ

Обычные текстовые сообщения участников группы бот не видит вообще. Это не баг Hermes — так устроен Telegram.

Как отключить приватность

Откройте @BotFather в Telegram
Отправьте /mybots
Выберите вашего бота
Перейдите в Bot Settings → Group Privacy → Turn off

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

Альтернатива: сделать бота админом группы

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

2. Управление доступом: кто и где может общаться с ботом

Hermes использует две независимые шлюзы доступа для групп:

Шлюз	Что контролирует	Когда использовать
Отправители (`group_allow_from`)	Какие конкретные пользователи могут вызывать бота в группах	Когда нужно дать доступ определённым людям, но не давать им доступ к личке бота
Чаты (`group_allowed_chats`)	В каких группах бот вообще работает	Когда любой участник указанной группы может общаться с ботом

Эти шлюзы работают независимо от allow_from (доступ к личным сообщениям). Пользователь, указанный только в group_allow_from, сможет общаться с ботом в группах, но не сможет писать ему в личку.

Настройка в config.yaml

gateway:
  platforms:
    telegram:
      extra:
        # Глобальный доступ (личка + группы).
        # Эти пользователи всегда могут обратиться к боту.
        allow_from:
          - "123456789"

        # Только группы. Не даёт доступа к личке.
        group_allow_from:
          - "987654321"

        # Целые группы — любой участник может общаться.
        group_allowed_chats:
          - "-1001234567890"

Эквивалент в переменных окружения (.env)

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 — авторизует всех участников указанного чата, независимо от того, кто отправил сообщение.
Значение * в любом из этих параметров разрешает доступ всем.

Как узнать ID группы

ID группы — это отрицательное число вида -1001234567890. Чтобы узнать ID:

Добавьте бота @getmyid_bot в группу
Отправьте любое сообщение в группу
Бот ответит с ID чата

Или: если бот уже в группе, отправьте /start@getmyid_bot в группе.

3. Когда бот отвечает: управление триггерами

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

Режим «только по вызову» (рекомендуется)

telegram:
  require_mention: true

С этой настройкой бот отвечает в группе только когда:

Сообщение начинается с /команда
Сообщение — ответ (reply) на сообщение бота
В сообщении есть упоминание @username_бота
Сообщение совпадает с настроенным шаблоном (см. ниже)

Свои триггеры (mention_patterns)

Можно настроить дополнительные слова-триггеры, по которым бот будет реагировать в группе:

telegram:
  require_mention: true
  mention_patterns:
    - "^\\s*помощь\\b"
    - "^\\s*бот\\b"

Это регулярные выражения Python. Сопоставление регистронезависимое. Паттерны проверяются как по текстовым сообщениям, так и по подписям к медиафайлам.

Если нужен триггер только в начале сообщения — используйте ^ в начале паттерна.

Невалидные регулярные выражения игнорируются с предупреждением в логах — бот не падает.

4. Режим наблюдателя: бот слушает, но молчит

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

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

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

Обычные сообщения из разрешённых групп добавляются в контекст сессии как «наблюдаемые», но не запускают ответ бота.
Когда кто-то явно упоминает бота (@botname), отвечает на его сообщение или использует команду — бот отвечает, используя накопленный контекст.
Каждое наблюдаемое сообщение помечается как [имя|user_id], чтобы бот различал участников.

Важно: для этого режима нужно, чтобы Telegram доставлял обычные сообщения боту — значит, приватность должна быть отключена или бот должен быть админом (см. раздел 1).

5. Несколько ботов в одной группе

Если в одной группе работают несколько Hermes-агентов (несколько профилей), каждый должен использовать свой уникальный токен бота. Telegram не позволяет нескольким экземплярам опрачивать один и тот же токен одновременно.

Запуск нескольких профилей

# Профиль по умолчанию
hermes gateway start
hermes gateway stop

# Именованные профили
hermes -p research gateway start
hermes -p research gateway stop

hermes -p ops gateway start
hermes -p ops gateway stop

Каждый профиль запускается и останавливается отдельно. Нет единой команды «запустить все» — используйте скрипт-обёртку, если нужно управлять несколькими профилями.

6. Гостевой доступ (guest_mode)

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

Для более свободного сценария — бот молчит по умолчанию, но отвечает на прямое упоминание @botname в любой группе — включите гостевой режим:

gateway:
  platforms:
    telegram:
      extra:
        group_allowed_chats:
          - "-1001234567890"   # основная группа (полный доступ)
        guest_mode: true       # остальные группы: только по @упоминанию

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

TELEGRAM_GUEST_MODE=true

В гостевом режиме бот обрабатывает сообщение только если в нём есть явное @упоминание бота. Упоминание требуется в каждом сообщении — «сессионной липкости» нет, бот не включается в разговор после первого пинга.

Личные сообщения и разрешённые группы работают как обычно.

7. Управление доступом к командам (Slash Command ACL)

По умолчанию все авторизованные пользователи могут выполнять любые команды. Чтобы разделить доступ — администраторы с полным набором команд и обычные пользователи только с разрешёнными:

gateway:
  platforms:
    telegram:
      extra:
        allow_from:
          - "123456789"     # админ
          - "555555555"     # обычный пользователь

        # Админы — полный доступ ко всем командам
        allow_admin_from:
          - "123456789"

        # Обычные пользователи — только эти команды
        user_allowed_commands:
          - status
          - model
          - history

        # Отдельные списки для групп (необязательно)
        group_allow_admin_from:
          - "123456789"
        group_user_allowed_commands:
          - status

Как работает

Пользователь из allow_admin_from может выполнять все зарегистрированные команды — встроенные и плагиновые.
Пользователь из allow_from, но не из allow_admin_from — только команды из user_allowed_commands, плюс всегда доступные /help и /whoami.
Обычные текстовые сообщения (не команды) не затрагиваются. Обычные пользователи могут разговаривать с агентом — просто не могут вызывать произвольные команды.
Если allow_admin_from не задан для области (личка или группа) — ограничение команд отключено. Существующие установки продолжают работать без изменений.
Статус админа в личке не означает статус админа в группе. У каждой области свой список.

Команда /whoami показывает текущую область, ваш уровень (admin / user / unrestricted) и какие команды доступны.

8. Игнорирование отдельных топиков форума

В супергруппах с включёнными топиками (форумами) можно запретить боту отвечать в конкретных топиках:

telegram:
  require_mention: true
  ignored_threads:
    - 31
    - "42"

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

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

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

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

Как узнать thread_id: откройте топик в Telegram Web или Desktop и посмотрите на URL: https://t.me/c/1234567890/5 — последнее число (5) это thread_id. ID группы для супергрупп — это ID группы с префиксом -100 (группа 1234567890 становится -1001234567890).

Топики без поля skill получают только изоляцию сессии (стандартное поведение форумов).

10. Привязка навыков к топикам в личке (DM Topics)

Telegram Bot API 9.4 (февраль 2026) позволяет создавать форум-топики прямо в личном чате с ботом. Каждый топик — отдельная сессия с собственной историей.

Предварительная настройка

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

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

Бот не может включить это программно — это настройка клиента Telegram.

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

platforms:
  telegram:
    extra:
      dm_topics:
      - chat_id: 123456789
        topics:
        - name: Общее
          icon_color: 7322096
        - name: Сайт
          icon_color: 9367192
        - name: Исследования
          icon_color: 16766590
          skill: arxiv

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

При запуске gateway Hermes вызывает createForumTopic для каждого топика без thread_id. После создания thread_id сохраняется обратно в конфиг — повторные запуски пропускают вызов API.

Режим лобби (игнорирование корневого чата)

По умолчанию сообщения в корневом DM (вне топиков) обрабатываются нормально. Чтобы превратить корневой чат в лобби — обычные сообщения игнорируются, работают только системные команды (/start, /help, /status):

platforms:
  telegram:
    extra:
      ignore_root_dm: true
      dm_topics:
        - chat_id: 123456789
          topics:
            - name: Общее

Проверка идёт по chat_id: только пользователи с хотя бы одной записью в dm_topics попадают под это правило. Остальные не затронуты.

11. Решение проблем

Проблема	Решение
Бот не отвечает в группе, но работает в личке	Отключите приватность в @BotFather (раздел 1) и переаддите бота в группу
Бот отвечает на каждое сообщение в группе	Добавьте `require_mention: true` в конфиг
Бот игнорирует @упоминания	Проверьте, что username бота указан верно. Проверьте `TELEGRAM_ALLOWED_USERS` — отправитель должен быть в списке
Бот молчит после переаддывания	Проверьте, что отправитель в `TELEGRAM_ALLOWED_USERS` или `TELEGRAM_GROUP_ALLOWED_USERS`, или группа в `TELEGRAM_GROUP_ALLOWED_CHATS`
Бот отвечает только на команды /, но не на текст	Приватность не отключена. См. раздел 1
Бот не видит сообщения, хотя приватность выключена	Удалите бота из группы и добавьте заново. Telegram кеширует настройку
Один бот перехватывает сообщения другого	Включите `exclusive_bot_mentions: true` и убедитесь, что у каждого бота свой токен

Шпаргалка: минимальная конфигурация для группы

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

В @BotFather:

Отключите Group Privacy (или сделайте бота админом группы)
Переаддьте бота в группу

В config.yaml:

gateway:
  platforms:
    telegram:
      extra:
        allow_from:
          - "123456789"           # ваш Telegram ID
        group_allowed_chats:
          - "-1001234567890"      # ID группы
        require_mention: true     # отвечать только по @упоминанию

В .env:

TELEGRAM_BOT_TOKEN=123456789:ABCdef...
TELEGRAM_ALLOWED_USERS=123456789
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890

Проверка:

Напишите @username_бота привет в группе
Бот должен ответить
Напишите обычное сообщение без упоминания — бот должен молчать

AI-агенты за 5 минут

Telegram-агент в группе: полная настройка