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 с соответствующими иконками (⚠️ для ошибок, 🔐 для разрешений).

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

  • 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) — отображать рассуждения модели

Конфигурация автоматически перезагружается при изменении файла. Также можно управлять ботом через 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 API-вызовы проходят через очередь обновлений на чат, обеспечивающую уважение лимитов Telegram (~1 запрос в секунду на чат). Rapid-fire события инструментов коалесцируются — отправляется только последнее состояние.

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

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