---
title: "Telegram Bot"
id: "985"
type: "page"
slug: "telegram"
published_at: "2026-06-23T15:04:22+00:00"
modified_at: "2026-08-16T13:53:17+00:00"
url: "https://pastukhov.com/agents/agent/docs/telegram"
markdown_url: "https://pastukhov.com/agents/agent/docs/telegram.md"
excerpt: "Pastukhov Agent может работать как Telegram-бот, позволяя вам взаимодействовать с AI через Telegram. Бот создаёт,…"
---

# Telegram Bot

[https://pastukhov.com/agents/agent/docs/telegram.md](https://pastukhov.com/agents/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](/agents/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>`** — Возобновляет конкретный чат по 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](https://www.anthropic.com/news/introducing-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 события инструментов коалесцируются — отправляется только последнее состояние.

**← Назад:** [Удалённое управление](/agents/agent/docs/remote-control)

**Далее:** [Настройки](/agents/agent/docs/settings)
 →