--- title: "Telegram Bot" id: "985" type: "page" slug: "telegram" published_at: "2026-06-23T15:04:22+00:00" modified_at: "2026-06-30T21:07:26+00:00" url: "https://pastukhov.com/agent/docs/telegram" markdown_url: "https://pastukhov.com/agent/docs/telegram.md" excerpt: "Pastukhov Agent может работать как Telegram-бот, позволяя вам взаимодействовать с AI через Telegram. Бот создаёт,…" --- # Telegram Bot [https://pastukhov.com/agent/docs/telegram.md](https://pastukhov.com/agent/docs/telegram.md) Pastukhov Agent может работать как Telegram-бот, позволяя вам взаимодействовать с AI через Telegram. Бот создаёт, управляет и возобновляет чаты, пересылает ответы AI, поддерживает AskUserQuestion с inline-кнопками и отображает прогресс вызовов инструментов — всё внутри Telegram. ![Интерфейс Telegram бота Pastukhov Agent](https://pastukhov.com/wp-content/uploads/2026/06/telegram-bot-interface.png)## Обзор Интеграция работает как фоновый сервис внутри Pastukhov Agent. Бот использует **long polling** для получения обновлений от Telegram API и подписывается на события чата для пересылки ответов AI в Telegram. - **Двусторонний обмен** — промпты из Telegram попадают в очередь сообщений, ответы AI пересылаются обратно в Telegram - **Управление чатами** — создание, остановка, возобновление и просмотр чатов через команды - **AskUserQuestion** — вопросы Claude отображаются с inline-кнопками для выбора ответа - **Прогресс инструментов** — опциональное отображение вызовов инструментов с индикаторами состояния - **Рассуждения модели** — опциональная отправка thinking-сообщений курсивом - **Выбор навыков** — команда `/skill` для переключения активного навыка ## Настройка Настроить бота можно двумя способами: через диалог настроек (рекомендуется) или вручную через файл конфигурации. ### Через диалог настроек Откройте настройки → секция «Telegram». Включите бота, введите токен от `@BotFather`, укажите веб-URL и настройте ограничения доступа. Подробнее см. [Настройки → Telegram](/agent/docs/settings) . ### Через 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. Возвращает ссылку на чат в веб-интерфейсе. - **`/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 события инструментов коалесцируются — отправляется только последнее состояние. **← Назад:** [Удалённое управление](/agent/docs/remote-control) **Далее:** [Настройки](/agent/docs/settings) →