Pastukhov Agent > Документация > Telegram Bot

Telegram Bot

Pastukhov Agent может работать как Telegram-бот, позволяя вам взаимодействовать с AI через Telegram. Бот создаёт, управляет и возобновляет чаты, пересылает ответы AI, поддерживает AskUserQuestion с inline-кнопками и отображает прогресс вызовов инструментов — всё внутри Telegram.

Интерфейс Telegram бота Pastukhov Agent

Обзор

Интеграция работает как фоновый сервис внутри Pastukhov Agent. Бот использует long polling для получения обновлений от Telegram API и подписывается на события чата для пересылки ответов AI в Telegram.

  • Двусторонний обмен — промпты из Telegram попадают в очередь сообщений, ответы AI пересылаются обратно в Telegram
  • Управление чатами — создание, остановка, возобновление и просмотр чатов через команды
  • AskUserQuestion — вопросы Claude отображаются с inline-кнопками для выбора ответа
  • Прогресс инструментов — опциональное отображение вызовов инструментов с индикаторами состояния
  • Рассуждения модели — опциональная отправка thinking-сообщений курсивом
  • Выбор навыков — команда /skill для переключения активного навыка

Настройка

Настроить бота можно двумя способами: через диалог настроек (рекомендуется) или вручную через файл конфигурации.

Через диалог настроек

Откройте настройки → секция «Telegram». Включите бота, введите токен от @BotFather, укажите веб-URL и настройте ограничения доступа. Подробнее см. Настройки → Telegram.

Через telegram.yml

Создайте файл .pastukhov/telegram.yml в корне проекта:

telegram:
  enabled: true
  botToken: $TELEGRAM_BOT_TOKEN    # или прямое значение токена
  webUrl: https://code.example.com
  allowedUserIds:                    # пусто = доступ заблокирован
    - 123456789
  showToolCalls: false
  showThinking: false

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

Бот перезапускается автоматически при сохранении конфигурации. Ошибки подключения не блокируют запуск приложения — бот просто отключается, а Pastukhov Agent продолжает работать.

HTTP-прокси

Если ваш сервер не имеет прямого доступа к Telegram API, вы можете настроить HTTP-прокси через переменную окружения:

# Поддерживается формат с авторизацией
AGENT_TELEGRAM_HTTP_PROXY=http://user:password@proxy.example.com:8080

Бот автоматически определяет и применяет прокси при подключении к Telegram API.

Команды

Бот автоматически регистрирует меню команд в Telegram — начните вводить / для автодополнения.

  • /new [заголовок] — Создаёт новый чат. Опциональный заголовок задаёт название чата. Возвращает ссылку на чат в веб-интерфейсе. Новый чат автоматически становится активным.
  • /stop — Останавливает текущий активный чат. Отправляет сигнал остановки экземпляру Claude Code.
  • /resume — Показывает список из 20 последних чатов. Каждый чат отображается как /resume {id} для быстрого возобновления.
  • /resume <id> — Возобновляет конкретный чат по ID. Возвращает ссылку на чат в веб-интерфейсе.
  • /skill — Показывает список активированных навыков с текущим выбором (✅).
  • /skill <имя> — Устанавливает активный навык. Этот навык будет автоматически загружен при следующем сообщении.
  • /help — Показывает справку со всеми командами.

Любое сообщение, не начинающееся с /, отправляется как промпт в активный чат. Если активного чата нет, бот просит создать его через /new.

Взаимодействие

Ответы AI

Ответы Claude автоматически пересылаются в Telegram. Markdown-форматирование (жирный, курсив, код, ссылки, блоки кода, цитаты) конвертируется в Telegram HTML. Длинные сообщения автоматически разбиваются на части по параграфам.

Индикатор набора

Когда Claude обрабатывает запрос, бот отправляет индикатор «печатает» каждые 4 секунды, показывая, что процесс активен.

AskUserQuestion

Когда Claude вызывает AskUserQuestion, бот отображает вопросы с inline-кнопками. Каждая опция вопроса — отдельная кнопка. Радио-вопросы (один выбор) и multi-select вопросы поддерживаются. После выбора кнопка помечается галочкой ✓. Кнопка «▶ Продолжить» отправляет выбранные ответы Claude.

Вызовы инструментов

При включённом параметре showToolCalls бот отображает прогресс вызовов инструментов в одном редактируемом сообщении. Каждый инструмент показывается с коротким описанием (путь файла для Read/Write/Edit, команда для Bash, шаблон для Grep) и индикатором состояния: ⏳ (выполняется), ✅ (завершён), ❌ (ошибка).

Ошибки и запросы разрешений также отправляются в Telegram с соответствующими иконками (⚠️ для ошибок, 🔐 для разрешений).

Telegram Tag: управление агентом в групповых чатах

Бота можно добавить в любой групповой чат и управлять агентом, обращаясь к нему по @username бота или по никнеймам, которые вы задаёте сами. Это аналог Claude Tag от Anthropic: один общий агент на группу, любой авторизованный участник может поставить ему задачу, а работает он асинхронно с общим контекстом. Можно добавить в один чат несколько ботов (по одному на каждый Pastukhov Agent/проект) и обращаться к каждому по его имени — так в одном общем чате вы управляете несколькими агентами одновременно, с независимыми настройками доступа.

  • Обращение по имени — агент реагирует на упоминание @username бота или на один из ваших никнеймов в начале сообщения
  • Один общий чат на группу — все участники работают с единым контекстом; навык и модель хранятся на уровне группы
  • Гибкий доступ — видят переписку все, а управлять агентом могут только разрешённые пользователи
  • Совместная работа — агент может читать историю чата группы через дневные транскрипты

Как обратиться к агенту

В групповом чате бот реагирует, когда вы упоминаете его в начале сообщения — по @username бота (если включено matchBotUsername) или по одному из настроенных никнеймов. Всё, что идёт после триггера, становится командой или свободным промптом:

john напиши релиз-ноут            # john — никнейм → задача в общий чат
john new                          # новый общий чат для группы
john stop                         # остановить текущий запуск
@mybot подведи итоги за сегодня   # обращение по @username бота

Никнеймы должны соответствовать ^[A-Za-z0-9_]+$ и сопоставляются по границам слов (johnny ≠ john); регистр по умолчанию не учитывается. Голый триггер без текста (например, просто john) выводит справку.

Доступ и видимость

Главное правило общих чатов — кто видит, а кто может управлять:

  • Добавить может любой — любой участник может добавить бота в чат. Бот открыт в любой группе и получает все сообщения.
  • Управляют только разрешённые — давать задачи и команды могут только пользователи из allowedUserIds (тот же список, что и для личных чатов). Пустой список означает, что бот в группе не реагирует ни на кого.
  • Видят все — все участники видят запросы и ответы агента прямо в чате. Неавторизованные упоминания игнорируются молча, без лишних сообщений.
  • Записывается всё — вся переписка группы попадает в транскрипты независимо от того, кто пишет (см. ниже).

Команды в группе

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

  • <триггер> new [заголовок] — новый общий чат для группы; навык и модель переносятся автоматически
  • <триггер> stop — остановить текущий запуск
  • <триггер> resume — список последних чатов группы (каждый — как <триггер> resume <id>)
  • <триггер> resume <id> — возобновить конкретный чат по ID
  • <триггер> skill — показать активированные навыки группы (текущий отмечен ✅)
  • <триггер> skill <имя> — выбрать навык группы
  • <триггер> model / <триггер> model <имя> — показать или выбрать модель
  • <триггер> help — справка по командам группы

Любой другой текст после триггера отправляется как промпт в общий чат. Ответы публикуются ответом (reply) на ваше сообщение. В группе одновременно выполняется только один запрос — обращения выстраиваются в очередь, по одной задаче за раз.

История чата и совместная работа

Чтобы агенты могли по-настоящему совместно работать, бот ведёт дневные транскрипты всей переписки группы: каждое сообщение (включая ответы самого агента, медиа, ответы и пересланные сообщения) дописывается в markdown-файл .pastukhov/tag/{ID группы}/{дата}.md. Эти файлы добавляются в .gitignore и никогда не попадают в коммиты.

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

If required by the task, management chat transcripts are at .pastukhov/tag/{ID группы}

Поэтому можно ставить задачи вида «напиши релиз-ноут по тому, что мы обсуждали сегодня» — и агент сам найдёт нужный контекст в истории группы. Суффикс добавляется только к свободным промптам в группе; личные чаты и веб-интерфейс не затрагиваются. Текст суффикса настраивается параметром transcriptContextSuffix — в нём должен быть токен {path}.

⚠️ Для накопления транскриптов у бота должен быть отключён Privacy Mode — иначе бот в группе получает только команды, упоминания и ответы, а не всю переписку. Отключите Privacy Mode в @BotFather (/setprivacy → Disable) или сделайте бота администратором группы.

Настройка Telegram Tag

Telegram Tag включается отдельным блоком tag в telegram.yml:

telegram:
  enabled: true
  botToken: $TELEGRAM_BOT_TOKEN
  allowedUserIds:               # кто может управлять ботом (и в ЛС, и в группах)
    - 123456789
  tag:
    enabled: true               # включить Telegram Tag
    nicknames: [john, dev]      # триггер-слова (буквы, цифры, _)
    matchBotUsername: true      # реагировать на @<username бота>
    caseSensitive: false        # учитывать регистр никнеймов
    recordTranscripts: true     # вести дневные транскрипты
    transcriptContextSuffix: "If required by the task, management chat transcripts are at {path}"
    respondInReply: true        # отвечать reply на триггер

Те же параметры доступны в диалоге настроек → секция «Telegram» → блок «Telegram Tag»: редактор никнеймов, переключатели и предупреждение о Privacy Mode. Изменения применяются автоматически при сохранении.

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

  • White-list доступ — поле allowedUserIds ограничивает доступ к боту конкретным пользователям по Telegram user ID. Неавторизованные пользователи получают сообщение с инструкцией для администратора.
  • Пустой список — если allowedUserIds не задан или пуст, бот отклоняет все запросы с сообщением, содержащим user ID для передачи администратору.
  • Токен через переменные окружения — рекомендуется хранить токен бота в переменной окружения ($TELEGRAM_BOT_TOKEN) вместо прямого указания в файле конфигурации.
  • Изоляция сессий — каждый Telegram-пользователь имеет свою сессию с отдельным активным чатом. Один чат может быть привязан к нескольким Telegram-пользователям, но каждый пользователь работает только со своим активным чатом.

Справочник конфигурации telegram.yml

  • enabled (bool, по умолчанию: false) — включение интеграции
  • botToken (string) — токен бота от @BotFather, поддерживает $ENV_VAR
  • webUrl (string) — базовый URL для ссылок на чаты (по умолчанию: http://localhost:5173)
  • allowedUserIds (list[string]) — список разрешённых Telegram user ID
  • showToolCalls (bool, по умолчанию: false) — отображать прогресс вызовов инструментов
  • showThinking (bool, по умолчанию: false) — отображать рассуждения модели

tag (object) — настройки режима Telegram Tag для групповых чатов (подробности — в разделе выше). Подполя:

  • tag.enabled (bool, по умолчанию: false) — включить Telegram Tag
  • tag.nicknames (list[string]) — триггер-слова; должны соответствовать ^[A-Za-z0-9_]+$
  • tag.matchBotUsername (bool, по умолчанию: true) — реагировать на @<username бота>
  • tag.caseSensitive (bool, по умолчанию: false) — учитывать регистр никнеймов
  • tag.recordTranscripts (bool, по умолчанию: true) — вести дневные транскрипты переписки группы
  • tag.transcriptContextSuffix (string) — суффикс-указатель на папку транскриптов; должен содержать токен {path}
  • tag.respondInReply (bool, по умолчанию: true) — публиковать ответы ответом (reply) на триггер

Конфигурация автоматически перезагружается при изменении файла. Также можно управлять ботом через REST API (GET/POST /api/telegram/config, GET /api/telegram/status).

Переменные окружения

  • AGENT_TELEGRAM_HTTP_PROXY — URL HTTP-прокси для подключения к Telegram API (опционально). Поддерживает авторизацию в URL.

Внутреннее устройство

Бот использует отдельную SQLite-базу данных .pastukhov/telegram.db для хранения маппингов между Telegram-чатами и чатами Pastukhov Agent, а также пользовательских сессий (активный чат, выбранный навык). Для групповых чатов (Telegram Tag) в этой же базе хранится общий маппинг группы с её навыком и моделью, а дневные транскрипты переписки пишутся в отдельную папку .pastukhov/tag/. Данные из этой базы не синхронизируются с основной базой проекта.

Все Telegram API-вызовы проходят через очередь обновлений на чат, обеспечивающую уважение лимитов Telegram (~1 запрос в секунду на чат). Rapid-fire события инструментов коалесцируются — отправляется только последнее состояние.

← Назад: Удалённое управление

Далее: Настройки →