> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

# Telegram (Bot API)

Статус: готово к промышленному использованию для личных сообщений бота и групп через grammY. По умолчанию используется long-polling; вебхук — опционально.

## Быстрая настройка (для начинающих)

1. Создайте бота с помощью **@BotFather** ([прямая ссылка](https://t.me/BotFather)). Убедитесь, что хэндл точно `@BotFather`, затем скопируйте токен.
2. Установите токен:
   * Env: `TELEGRAM_BOT_TOKEN=...`
   * Или в конфиге: `channels.telegram.botToken: "..."`.
   * Если заданы оба варианта, приоритет у конфига (env используется как fallback только для аккаунта по умолчанию).
3. Запустите Gateway (шлюз).
4. Доступ к личным сообщениям по умолчанию — через сопряжение; подтвердите код сопряжения при первом контакте.

Минимальный конфиг:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
    },
  },
}
```

## Что это такое

* Канал Telegram Bot API, принадлежащий Gateway (шлюзу).
* Детерминированная маршрутизация: ответы всегда возвращаются в Telegram; модель никогда не выбирает каналы.
* Личные сообщения используют основной сеанс агента; группы остаются изолированными (`agent:<agentId>:telegram:group:<chatId>`).

## Настройка (быстрый путь)

### 1. Создание токена бота (BotFather)

1. Откройте Telegram и начните чат с **@BotFather** ([прямая ссылка](https://t.me/BotFather)). Убедитесь, что хэндл точно `@BotFather`.
2. Выполните `/newbot`, затем следуйте подсказкам (имя + имя пользователя, оканчивающееся на `bot`).
3. Скопируйте токен и сохраните его в безопасном месте.

Необязательные настройки BotFather:

* `/setjoingroups` — разрешить/запретить добавление бота в группы.
* `/setprivacy` — управлять тем, видит ли бот все сообщения в группах.

### 2. Настройка токена (env или конфиг)

Пример:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}
```

Вариант через env: `TELEGRAM_BOT_TOKEN=...` (работает для аккаунта по умолчанию).
Если заданы и env, и конфиг, приоритет у конфига.

Поддержка нескольких аккаунтов: используйте `channels.telegram.accounts` с токенами для каждого аккаунта и необязательным `name`. [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) для общего шаблона.

3. Запустите Gateway (шлюз). Telegram запускается, когда токен определён (сначала конфиг, затем fallback из env).
4. Доступ к личным сообщениям по умолчанию — через сопряжение. Подтвердите код при первом обращении к боту.
5. Для групп: добавьте бота, определите поведение приватности/администратора (см. ниже), затем установите `channels.telegram.groups` для управления требованиями упоминаний и allowlist.

## Токен + приватность + права (со стороны Telegram)

### Создание токена (BotFather)

* `/newbot` создаёт бота и возвращает токен (держите его в секрете).
* Если токен скомпрометирован, отзовите/пересоздайте его через @BotFather и обновите конфиг.

### Видимость сообщений в группах (Privacy Mode)

Боты Telegram по умолчанию работают в **Privacy Mode**, который ограничивает, какие сообщения в группах они получают.
Если боту необходимо видеть *все* сообщения группы, есть два варианта:

* Отключить режим приватности с помощью `/setprivacy` **или**
* Добавить бота в группу как **администратора** (админ-боты получают все сообщения).

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

### Права в группах (администратор)

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

## Как это работает (поведение)

* Входящие сообщения нормализуются в общий конверт канала с контекстом ответа и плейсхолдерами медиа.
* Ответы в группах по умолчанию требуют упоминания (нативное @упоминание или `agents.list[].groupChat.mentionPatterns` / `messages.groupChat.mentionPatterns`).
* Переопределение для нескольких агентов: задайте шаблоны для каждого агента в `agents.list[].groupChat.mentionPatterns`.
* Ответы всегда маршрутизируются обратно в тот же чат Telegram.
* Long-polling использует runner grammY с последовательностью на чат; общая конкуррентность ограничена `agents.defaults.maxConcurrent`.
* Telegram Bot API не поддерживает уведомления о прочтении; опции `sendReadReceipts` не существует.

## Трансляция черновика

OpenClaw может стримить частичные ответы в личных сообщениях Telegram с использованием `sendMessageDraft`.

Требования:

* Для бота включён Threaded Mode в @BotFather (режим форумных тем).
* Только приватные чаты с темами (Telegram включает `message_thread_id` во входящих сообщениях).
* `channels.telegram.streamMode` не установлен в `"off"` (по умолчанию: `"partial"`, `"block"` включает обновления черновиков блоками).

Черновой стриминг доступен только в личных сообщениях; Telegram не поддерживает его в группах или каналах.

## Форматирование (Telegram HTML)

* Исходящий текст Telegram использует `parse_mode: "HTML"` (подмножество поддерживаемых тегов Telegram).
* Входной Markdown-подобный текст рендерится в **безопасный для Telegram HTML** (жирный/курсив/зачёркнутый/код/ссылки); блочные элементы преобразуются в текст с переводами строк/маркерами.
* Сырой HTML от моделей экранируется, чтобы избежать ошибок парсинга Telegram.
* Если Telegram отклоняет HTML-пейлоад, OpenClaw повторяет отправку того же сообщения как обычный текст.

## Команды (нативные + пользовательские)

OpenClaw регистрирует нативные команды (например, `/status`, `/reset`, `/model`) в меню бота Telegram при запуске.
Вы можете добавить пользовательские команды в меню через конфиг:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}
```

## Устранение неполадок настройки (команды)

* `setMyCommands failed` в логах обычно означает, что исходящие HTTPS/DNS заблокированы к `api.telegram.org`.
* Если вы видите сбои `sendMessage` или `sendChatAction`, проверьте маршрутизацию IPv6 и DNS.

Дополнительная помощь: [Устранение неполадок каналов](/channels/troubleshooting).

Примечания:

* Пользовательские команды — это **только пункты меню**; OpenClaw не реализует их, если вы не обрабатываете их где-то ещё.
* Некоторые команды могут обрабатываться плагинами/навыками без регистрации в меню команд Telegram. Они всё равно работают при вводе (просто не отображаются в `/commands` / меню).
* Имена команд нормализуются (удаляется ведущий `/`, приводятся к нижнему регистру) и должны соответствовать `a-z`, `0-9`, `_` (1–32 символа).
* Пользовательские команды **не могут переопределять нативные команды**. Конфликты игнорируются и логируются.
* Если `commands.native` отключён, регистрируются только пользовательские команды (или очищаются, если их нет).

### Команды сопряжения устройств (плагин `device-pair`)

Если плагин `device-pair` установлен, он добавляет ориентированный на Telegram процесс сопряжения нового телефона:

1. `/pair` генерирует код настройки (отправляется отдельным сообщением для удобного копирования/вставки).
2. Вставьте код настройки в приложение iOS для подключения.
3. `/pair approve` одобряет последний ожидающий запрос устройства.

Подробнее: [Pairing](/channels/pairing#pair-via-telegram-recommended-for-ios).

## Ограничения

* Исходящий текст разбивается на блоки по `channels.telegram.textChunkLimit` (по умолчанию 4000).
* Необязательное разбиение по переводам строк: установите `channels.telegram.chunkMode="newline"`, чтобы сначала делить по пустым строкам (границы абзацев), а затем по длине.
* Загрузка/выгрузка медиа ограничена `channels.telegram.mediaMaxMb` (по умолчанию 5).
* Запросы Telegram Bot API истекают по тайм-ауту через `channels.telegram.timeoutSeconds` (по умолчанию 500 через grammY). Установите меньшее значение, чтобы избежать длительных зависаний.
* Контекст истории группы использует `channels.telegram.historyLimit` (или `channels.telegram.accounts.*.historyLimit`), с fallback на `messages.groupChat.historyLimit`. Установите `0`, чтобы отключить (по умолчанию 50).
* Историю личных сообщений можно ограничить с помощью `channels.telegram.dmHistoryLimit` (ходы пользователя). Переопределения для отдельных пользователей: `channels.telegram.dms["<user_id>"].historyLimit`.

## Режимы активации в группах

По умолчанию бот отвечает в группах только на упоминания (`@botname` или шаблоны в `agents.list[].groupChat.mentionPatterns`). Чтобы изменить поведение:

### Через конфиг (рекомендуется)

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: false }, // always respond in this group
      },
    },
  },
}
```

**Важно:** Установка `channels.telegram.groups` создаёт **allowlist** — будут приниматься только перечисленные группы (или `"*"`).
Форумные темы наследуют конфигурацию родительской группы (allowFrom, requireMention, skills, prompts), если вы не добавите переопределения для тем в `channels.telegram.groups.<groupId>.topics.<topicId>`.

Чтобы разрешить все группы с режимом «всегда отвечать»:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false }, // all groups, always respond
      },
    },
  },
}
```

Чтобы оставить режим «только по упоминанию» для всех групп (поведение по умолчанию):

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true }, // or omit groups entirely
      },
    },
  },
}
```

### Через команду (уровень сеанса)

Отправьте в группе:

* `/activation always` — отвечать на все сообщения
* `/activation mention` — требовать упоминаний (по умолчанию)

**Примечание:** Команды обновляют только состояние сеанса. Для постоянного поведения между перезапусками используйте конфиг.

### Получение ID группового чата

Перешлите любое сообщение из группы в `@userinfobot` или `@getidsbot` в Telegram, чтобы увидеть ID чата (отрицательное число вроде `-1001234567890`).

**Совет:** Чтобы узнать свой ID пользователя, напишите боту в личные сообщения — он ответит вашим ID (сообщение сопряжения), или используйте `/whoami` после включения команд.

**Примечание о приватности:** `@userinfobot` — сторонний бот. Если предпочитаете, добавьте бота в группу, отправьте сообщение и используйте `openclaw logs --follow`, чтобы прочитать `chat.id`, либо используйте Bot API `getUpdates`.

## Запись конфига

По умолчанию Telegram разрешено записывать обновления конфига, инициированные событиями канала или `/config set|unset`.

Это происходит, когда:

* Группа обновляется до супергруппы, и Telegram отправляет `migrate_to_chat_id` (ID чата меняется). OpenClaw может автоматически мигрировать `channels.telegram.groups`.
* Вы выполняете `/config set` или `/config unset` в чате Telegram (требуется `commands.config: true`).

Отключение:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: { telegram: { configWrites: false } },
}
```

## Темы (форумные супергруппы)

Форумные темы Telegram включают `message_thread_id` для каждого сообщения. OpenClaw:

* Добавляет `:topic:<threadId>` к ключу сеанса группы Telegram, чтобы каждая тема была изолирована.
* Отправляет индикаторы набора текста и ответы с `message_thread_id`, чтобы ответы оставались в теме.
* Общая тема (thread id `1`) — особая: при отправке сообщений `message_thread_id` опускается (Telegram его отклоняет), но индикаторы набора текста всё равно включают его.
* Экспортирует `MessageThreadId` + `IsForum` в контекст шаблонов для маршрутизации/шаблонизации.
* Конфигурация для отдельных тем доступна в `channels.telegram.groups.<chatId>.topics.<threadId>` (skills, allowlists, автоответ, системные подсказки, отключение).
* Конфиги тем наследуют настройки группы (requireMention, allowlists, skills, prompts, enabled), если не переопределены для темы.

В приватных чатах в некоторых пограничных случаях может присутствовать `message_thread_id`. OpenClaw сохраняет ключ сеанса личных сообщений без изменений, но всё равно использует ID треда для ответов/чернового стриминга, если он присутствует.

## Встроенные кнопки

Telegram поддерживает встроенные клавиатуры с callback-кнопками.

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
      },
    },
  },
}
```

Для конфигурации на уровне аккаунта:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    telegram: {
      accounts: {
        main: {
          capabilities: {
            inlineButtons: "allowlist",
          },
        },
      },
    },
  },
}
```

Области:

* `off` — встроенные кнопки отключены
* `dm` — только личные сообщения (цели для групп заблокированы)
* `group` — только группы (цели для личных сообщений заблокированы)
* `all` — личные сообщения + группы
* `allowlist` — личные сообщения + группы, но только отправители, разрешённые `allowFrom`/`groupAllowFrom` (те же правила, что и для управляющих команд)

По умолчанию: `allowlist`.
Наследие: `capabilities: ["inlineButtons"]` = `inlineButtons: "all"`.

### Отправка кнопок

Используйте инструмент сообщений с параметром `buttons`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Choose an option:",
  buttons: [
    [
      { text: "Yes", callback_data: "yes" },
      { text: "No", callback_data: "no" },
    ],
    [{ text: "Cancel", callback_data: "cancel" }],
  ],
}
```

Когда пользователь нажимает кнопку, данные callback отправляются агенту как сообщение в формате:
`callback_data: value`

### Параметры конфигурации

Возможности Telegram можно настраивать на двух уровнях (выше показана объектная форма; устаревшие строковые массивы также поддерживаются):

* `channels.telegram.capabilities`: глобальная конфигурация возможностей по умолчанию, применяемая ко всем аккаунтам Telegram, если не переопределена.
* `channels.telegram.accounts.<account>.capabilities`: конфигурации возможностей на уровне аккаунта, которые переопределяют глобальные значения для конкретного аккаунта.

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

## Контроль доступа (личные сообщения + группы)

### Доступ к ЛС

* По умолчанию: `channels.telegram.dmPolicy = "pairing"`. Неизвестные отправители получают код сопряжения; сообщения игнорируются до подтверждения (коды истекают через 1 час).
* Подтверждение через:
  * `openclaw pairing list telegram`
  * `openclaw pairing approve telegram <CODE>`
* Сопряжение — механизм обмена токенами по умолчанию для личных сообщений Telegram. Подробнее: [Pairing](/channels/pairing)
* `channels.telegram.allowFrom` принимает числовые ID пользователей (рекомендуется) или записи `@username`. Это **не** имя пользователя бота; используйте ID человека-отправителя. Мастер принимает `@username` и, когда возможно, разрешает его в числовой ID.

#### Поиск вашего ID пользователя Telegram

Безопаснее (без стороннего бота):

1. Запустите шлюз и БМ.
2. Выполните `openclaw logs --follow` и найдите `from.id`.

Альтернатива (официальный Bot API):

1. ТМ ваш бот.
2. Получите обновления с токеном бота и прочитайте `message.from.id`:

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   curl "https://api.telegram.org/bot<bot_token>/getUpdates"
   ```

Сторонние варианты (менее приватно):

* Напишите `@userinfobot` или `@getidsbot` и используйте возвращённый ID пользователя.

### Доступ к группам

Два независимых механизма контроля:

**1. Какие группы разрешены** (allowlist групп через `channels.telegram.groups`):

* Нет конфига `groups` = разрешены все группы
* Есть конфиг `groups` = разрешены только перечисленные группы или `"*"`
* Пример: `"groups": { "-1001234567890": {}, "*": {} }` разрешает все группы

**2. Какие отправители разрешены** (фильтрация отправителей через `channels.telegram.groupPolicy`):

* `"open"` = все отправители в разрешённых группах могут писать
* `"allowlist"` = только отправители из `channels.telegram.groupAllowFrom` могут писать
* `"disabled"` = сообщения из групп не принимаются вообще
  Значение по умолчанию — `groupPolicy: "allowlist"` (заблокировано, если вы не добавили `groupAllowFrom`).

Большинству пользователей подходит: `groupPolicy: "allowlist"` + `groupAllowFrom` + конкретные группы, перечисленные в `channels.telegram.groups`.

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}
```

## Long-polling vs вебхук

* По умолчанию: long-polling (публичный URL не требуется).
* Режим вебхука: установите `channels.telegram.webhookUrl` и `channels.telegram.webhookSecret` (опционально `channels.telegram.webhookPath`).
  * Локальный слушатель привязывается к `0.0.0.0:8787` и по умолчанию обслуживает `POST /telegram-webhook`.
  * Если ваш публичный URL отличается, используйте reverse proxy и укажите `channels.telegram.webhookUrl` на публичную конечную точку.

## Поток ответов

Telegram поддерживает опциональные тредированные ответы с помощью тегов:

* `[[reply_to_current]]` — ответ на инициирующее сообщение.
* `[[reply_to:<id>]]` — ответ на конкретный ID сообщения.

Управляется параметром `channels.telegram.replyToMode`:

* `first` (по умолчанию), `all`, `off`.

## Аудиосообщения (голос vs файл)

Telegram различает **голосовые заметки** (круглый пузырёк) и **аудиофайлы** (карточка с метаданными).
OpenClaw по умолчанию использует аудиофайлы для обратной совместимости.

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

* `[[audio_as_voice]]` — отправлять аудио как голосовую заметку вместо файла.

Тег удаляется из доставленного текста. Другие каналы игнорируют этот тег.

Для отправок через инструмент сообщений установите `asVoice: true` с совместимым для голоса аудио-URL `media`
(`message` необязателен при наличии медиа):

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/voice.ogg",
  asVoice: true,
}
```

## Видеосообщения (видео vs видеозаметка)

Telegram различает **видеозаметки** (круглый пузырь) и **видеофайлы** (прямоугольные).
По умолчанию OpenClaw использует видеофайлы.

Для отправки через инструмент сообщений установите `asVideoNote: true` вместе с URL видео в `media`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/video.mp4",
  asVideoNote: true,
}
```

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

## Стикеры

OpenClaw поддерживает получение и отправку стикеров Telegram с интеллектуальным кэшированием.

### Получение стикеров

Когда пользователь отправляет стикер, OpenClaw обрабатывает его в зависимости от типа:

* **Статические стикеры (WEBP):** Загружаются и обрабатываются через vision. Стикер появляется как плейсхолдер `<media:sticker>` в содержимом сообщения.
* **Анимированные стикеры (TGS):** Пропускаются (формат Lottie не поддерживается для обработки).
* **Видео-стикеры (WEBM):** Пропускаются (видео-формат не поддерживается для обработки).

Поле контекста шаблонов, доступное при получении стикеров:

* `Sticker` — объект с:
  * `emoji` — эмодзи, связанный со стикером
  * `setName` — имя набора стикеров
  * `fileId` — Telegram file ID (для повторной отправки того же стикера)
  * `fileUniqueId` — стабильный ID для поиска в кэше
  * `cachedDescription` — кэшированное описание vision, если доступно

### Кэш стикеров

Стикеры обрабатываются через возможности vision ИИ для генерации описаний. Поскольку одни и те же стикеры часто отправляются повторно, OpenClaw кэширует эти описания, чтобы избежать повторных вызовов API.

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

1. **Первое появление:** Изображение стикера отправляется ИИ для анализа vision. ИИ генерирует описание (например, «Мультяшный кот, энергично машущий лапой»).
2. **Сохранение в кэше:** Описание сохраняется вместе с file ID стикера, эмодзи и именем набора.
3. **Последующие появления:** При повторном появлении того же стикера используется кэшированное описание. Изображение не отправляется ИИ.

**Расположение кэша:** `~/.openclaw/telegram/sticker-cache.json`

**Формат записи кэша:**

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "fileId": "CAACAgIAAxkBAAI...",
  "fileUniqueId": "AgADBAADb6cxG2Y",
  "emoji": "👋",
  "setName": "CoolCats",
  "description": "A cartoon cat waving enthusiastically",
  "cachedAt": "2026-01-15T10:30:00.000Z"
}
```

**Преимущества:**

* Снижает затраты на API за счёт исключения повторных вызовов vision для одного и того же стикера
* Более быстрое время отклика для кэшированных стикеров (без задержки на обработку vision)
* Обеспечивает возможность поиска стикеров на основе кэшированных описаний

Кэш наполняется автоматически по мере получения стикеров. Ручное управление кэшем не требуется.

### Отправка стикеров

Агент может отправлять и искать стикеры с помощью действий `sticker` и `sticker-search`. Они отключены по умолчанию и должны быть включены в конфиге:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}
```

**Отправка стикера:**

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}
```

Параметры:

* `fileId` (обязательно) — Telegram file ID стикера. Получите его из `Sticker.fileId` при получении стикера или из результата `sticker-search`.
* `replyTo` (необязательно) — ID сообщения, на которое нужно ответить.
* `threadId` (необязательно) — ID треда сообщения для форумных тем.

**Поиск стикеров:**

Агент может искать кэшированные стикеры по описанию, эмодзи или имени набора:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}
```

Возвращает подходящие стикеры из кэша:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  ok: true,
  count: 2,
  stickers: [
    {
      fileId: "CAACAgIAAxkBAAI...",
      emoji: "👋",
      description: "A cartoon cat waving enthusiastically",
      setName: "CoolCats",
    },
  ],
}
```

Поиск использует нечеткое сопоставление по тексту описания, эмодзи и именам наборов.

**Пример с тредингом:**

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  action: "sticker",
  channel: "telegram",
  to: "-1001234567890",
  fileId: "CAACAgIAAxkBAAI...",
  replyTo: 42,
  threadId: 123,
}
```

## Вещание (черновики)

Telegram может стримить **черновые пузырьки** во время генерации ответа агентом.
OpenClaw использует Bot API `sendMessageDraft` (не реальные сообщения), а затем отправляет
финальный ответ как обычное сообщение.

Требования (Telegram Bot API 9.3+):

* **Приватные чаты с включёнными темами** (режим форумных тем для бота).
* Входящие сообщения должны включать `message_thread_id` (приватный тред темы).
* Для групп/супергрупп/каналов стриминг игнорируется.

Конфиг:

* `channels.telegram.streamMode: "off" | "partial" | "block"` (по умолчанию: `partial`)
  * `partial`: обновлять черновой пузырёк последним стриминговым текстом.
  * `block`: обновлять черновой пузырёк крупными блоками (chunked).
  * `off`: отключить черновой стриминг.
* Необязательно (только для `streamMode: "block"`):
  * `channels.telegram.draftChunk: { minChars?, maxChars?, breakPreference? }`
    * значения по умолчанию: `minChars: 200`, `maxChars: 800`, `breakPreference: "paragraph"` (ограничены `channels.telegram.textChunkLimit`).

Примечание: черновой стриминг отличается от **block streaming** (сообщения канала).
Block streaming по умолчанию выключен и требует `channels.telegram.blockStreaming: true`,
если вы хотите получать ранние сообщения Telegram вместо обновлений черновиков.

Стрим рассуждений (только Telegram):

* `/reasoning stream` стримит рассуждения в черновой пузырёк во время генерации ответа,
  а затем отправляет финальный ответ без рассуждений.
* Если `channels.telegram.streamMode` = `off`, стрим рассуждений отключён.
  Подробнее: [Streaming + chunking](/concepts/streaming).

## Политика повторных попыток

Исходящие вызовы Telegram API повторяются при временных сетевых ошибках/429 с экспоненциальной задержкой и jitter. Настраивается через `channels.telegram.retry`. См. [Retry policy](/concepts/retry).

## Инструмент агента (сообщения + реакции)

* Инструмент: `telegram` с действием `sendMessage` (`to`, `content`, необязательные `mediaUrl`, `replyToMessageId`, `messageThreadId`).
* Инструмент: `telegram` с действием `react` (`chatId`, `messageId`, `emoji`).
* Инструмент: `telegram` с действием `deleteMessage` (`chatId`, `messageId`).
* Семантика удаления реакций: см. [/tools/reactions](/tools/reactions).
* Ограничение инструментов: `channels.telegram.actions.reactions`, `channels.telegram.actions.sendMessage`, `channels.telegram.actions.deleteMessage` (по умолчанию: включено) и `channels.telegram.actions.sticker` (по умолчанию: отключено).

## Уведомления о реакциях

**Как работают реакции:**
Реакции Telegram приходят как **отдельные события `message_reaction`**, а не как свойства в полезной нагрузке сообщений. Когда пользователь добавляет реакцию, OpenClaw:

1. Получает обновление `message_reaction` от Telegram API
2. Преобразует его в **системное событие** формата: `"Telegram reaction added: {emoji} by {user} on msg {id}"`
3. Ставит системное событие в очередь, используя **тот же ключ сеанса**, что и для обычных сообщений
4. Когда в этом разговоре приходит следующее сообщение, системные события извлекаются и добавляются в начало контекста агента

Агент видит реакции как **системные уведомления** в истории разговора, а не как метаданные сообщений.

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

* `channels.telegram.reactionNotifications`: управляет тем, какие реакции вызывают уведомления
  * `"off"` — игнорировать все реакции
  * `"own"` — уведомлять, когда пользователи реагируют на сообщения бота (best-effort; в памяти) (по умолчанию)
  * `"all"` — уведомлять обо всех реакциях

* `channels.telegram.reactionLevel`: управляет возможностями агента по реакциям
  * `"off"` — агент не может реагировать на сообщения
  * `"ack"` — бот отправляет подтверждающие реакции (👀 во время обработки) (по умолчанию)
  * `"minimal"` — агент может реагировать умеренно (рекомендация: 1 реакция на 5–10 обменов)
  * `"extensive"` — агент может реагировать свободно, когда уместно

**Форумные группы:** Реакции в форумных группах включают `message_thread_id` и используют ключи сеансов вида `agent:main:telegram:group:{chatId}:topic:{threadId}`. Это гарантирует, что реакции и сообщения в одной теме остаются вместе.

**Пример конфига:**

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    telegram: {
      reactionNotifications: "all", // See all reactions
      reactionLevel: "minimal", // Agent can react sparingly
    },
  },
}
```

**Требования:**

* Боты Telegram должны явно запрашивать `message_reaction` в `allowed_updates` (настраивается автоматически OpenClaw)
* В режиме вебхука реакции включаются в вебхук `allowed_updates`
* В режиме polling реакции включаются в `getUpdates` `allowed_updates`

## Цели доставки (CLI/cron)

* Используйте ID чата (`123456789`) или имя пользователя (`@name`) в качестве цели.
* Пример: `openclaw message send --channel telegram --target 123456789 --message "hi"`.

## Устранение неполадок

**Бот не отвечает на сообщения без упоминания в группе:**

* Если вы установили `channels.telegram.groups.*.requireMention=false`, **режим приватности** Bot API Telegram должен быть отключён.
  * BotFather: `/setprivacy` → **Disable** (затем удалите и заново добавьте бота в группу)
* `openclaw channels status` показывает предупреждение, когда конфиг ожидает групповые сообщения без упоминаний.
* `openclaw channels status --probe` может дополнительно проверять членство для явных числовых ID групп (не может аудитить правила с wildcard `"*"`).
* Быстрый тест: `/activation always` (только для сеанса; используйте конфиг для постоянства)

**Бот вообще не видит сообщения группы:**

* Если установлен `channels.telegram.groups`, группа должна быть в списке или использовать `"*"`
* Проверьте настройки приватности в @BotFather → «Group Privacy» должно быть **OFF**
* Убедитесь, что бот действительно является участником (а не просто администратором без доступа к чтению)
* Проверьте логи шлюза: `openclaw logs --follow` (ищите «skipping group message»)

**Бот отвечает на упоминания, но не на `/activation always`:**

* Команда `/activation` обновляет состояние сеанса, но не сохраняется в конфиг
* Для постоянного поведения добавьте группу в `channels.telegram.groups` с `requireMention: false`

**Команды вроде `/status` не работают:**

* Убедитесь, что ваш Telegram user ID авторизован (через сопряжение или `channels.telegram.allowFrom`)
* Команды требуют авторизации даже в группах с `groupPolicy: "open"`

**Long-polling немедленно прерывается на Node 22+ (часто с прокси/кастомным fetch):**

* Node 22+ строже относится к экземплярам `AbortSignal`; сторонние сигналы могут немедленно прерывать вызовы `fetch`.
* Обновитесь до сборки OpenClaw, которая нормализует abort-сигналы, или запускайте Gateway (шлюз) на Node 20, пока не сможете обновиться.

**Бот запускается, затем молча перестаёт отвечать (или пишет в логах `HttpError: Network request ... failed`):**

* Некоторые хосты сначала резолвят `api.telegram.org` в IPv6. Если у вашего сервера нет рабочего IPv6-выхода, grammY может зависать на IPv6-only запросах.
* Исправление: включите IPv6-выход **или** принудительно используйте IPv4 для `api.telegram.org` (например, добавьте запись `/etc/hosts` с IPv4 A-записью или отдайте приоритет IPv4 в DNS ОС), затем перезапустите Gateway (шлюз).
* Быстрая проверка: `dig +short api.telegram.org A` и `dig +short api.telegram.org AAAA`, чтобы подтвердить ответы DNS.

## Справочник конфигурации (Telegram)

Полная конфигурация: [Конфигурация](/gateway/configuration)

Параметры провайдера:

* `channels.telegram.enabled`: включить/выключить запуск канала.
* `channels.telegram.botToken`: токен бота (BotFather).
* `channels.telegram.tokenFile`: читать токен из пути к файлу.
* `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (по умолчанию: сопряжение).
* `channels.telegram.allowFrom`: allowlist личных сообщений (ids/usernames). `open` требует `"*"`.
* `channels.telegram.groupPolicy`: `open | allowlist | disabled` (по умолчанию: allowlist).
* `channels.telegram.groupAllowFrom`: allowlist отправителей в группах (ids/usernames).
* `channels.telegram.groups`: значения по умолчанию для групп + allowlist (используйте `"*"` для глобальных значений).
  * `channels.telegram.groups.<id>.groupPolicy`: переопределение groupPolicy для группы (`open | allowlist | disabled`).
  * `channels.telegram.groups.<id>.requireMention`: поведение требований упоминаний по умолчанию.
  * `channels.telegram.groups.<id>.skills`: фильтр skills (не указано = все skills, пусто = ни одного).
  * `channels.telegram.groups.<id>.allowFrom`: переопределение allowlist отправителей для группы.
  * `channels.telegram.groups.<id>.systemPrompt`: дополнительный системный prompt для группы.
  * `channels.telegram.groups.<id>.enabled`: отключить группу, когда `false`.
  * `channels.telegram.groups.<id>.topics.<threadId>.*`: переопределения для тем (те же поля, что и у группы).
  * `channels.telegram.groups.<id>.topics.<threadId>.groupPolicy`: переопределение groupPolicy для темы (`open | allowlist | disabled`).
  * `channels.telegram.groups.<id>.topics.<threadId>.requireMention`: переопределение требований упоминаний для темы.
* `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (по умолчанию: allowlist).
* `channels.telegram.accounts.<account>.capabilities.inlineButtons`: переопределение на уровне аккаунта.
* `channels.telegram.replyToMode`: `off | first | all` (по умолчанию: `first`).
* `channels.telegram.textChunkLimit`: размер исходящих блоков (символы).
* `channels.telegram.chunkMode`: `length` (по умолчанию) или `newline` для разбиения по пустым строкам (границы абзацев) перед разбиением по длине.
* `channels.telegram.linkPreview`: переключение предпросмотра ссылок для исходящих сообщений (по умолчанию: true).
* `channels.telegram.streamMode`: `off | partial | block` (черновой стриминг).
* `channels.telegram.mediaMaxMb`: лимит входящих/исходящих медиа (МБ).
* `channels.telegram.retry`: политика повторных попыток для исходящих вызовов Telegram API (attempts, minDelayMs, maxDelayMs, jitter).
* `channels.telegram.network.autoSelectFamily`: переопределение Node autoSelectFamily (true=включить, false=выключить). По умолчанию отключено на Node 22, чтобы избежать тайм-аутов Happy Eyeballs.
* `channels.telegram.proxy`: URL прокси для вызовов Bot API (SOCKS/HTTP).
* `channels.telegram.webhookUrl`: включить режим вебхука (требует `channels.telegram.webhookSecret`).
* `channels.telegram.webhookSecret`: секрет вебхука (обязателен, когда задан webhookUrl).
* `channels.telegram.webhookPath`: локальный путь вебхука (по умолчанию `/telegram-webhook`).
* `channels.telegram.actions.reactions`: ограничить реакции инструмента Telegram.
* `channels.telegram.actions.sendMessage`: ограничить отправку сообщений инструментом Telegram.
* `channels.telegram.actions.deleteMessage`: ограничить удаление сообщений инструментом Telegram.
* `channels.telegram.actions.sticker`: ограничить действия со стикерами Telegram — отправка и поиск (по умолчанию: false).
* `channels.telegram.reactionNotifications`: `off | own | all` — управляет тем, какие реакции вызывают системные события (по умолчанию: `own`, если не задано).
* `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — управляет возможностями агента по реакциям (по умолчанию: `minimal`, если не задано).

Связанные глобальные параметры:

* `agents.list[].groupChat.mentionPatterns` (шаблоны требований упоминаний).
* `messages.groupChat.mentionPatterns` (глобальный fallback).
* `commands.native` (по умолчанию `"auto"` → включено для Telegram/Discord, выключено для Slack), `commands.text`, `commands.useAccessGroups` (поведение команд). Переопределяется через `channels.telegram.commands.native`.
* `messages.responsePrefix`, `messages.ackReaction`, `messages.ackReactionScope`, `messages.removeAckAfterReply`.