Telegram (Bot API)

По умолчанию Telegram-боты работают в **режиме конфиденциальности**, который ограничивает получение сообщений в группах.

Если бот должен видеть все сообщения группы, либо:

- отключите режим конфиденциальности через `/setprivacy`, либо
- сделайте бота администратором группы.

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

Статус администратора управляется в настройках группы Telegram.

Боты-администраторы получают все сообщения группы, что полезно для постоянно активного режима.

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

OpenClaw может стримить частичные ответы в реальном времени:

- прямые чаты: превью-сообщение + `editMessageText`
- группы/темы: превью-сообщение + `editMessageText`

Требования:

- `channels.telegram.streaming`: `off | partial | block | progress` (по умолчанию: `partial`)
- `progress` соответствует `partial` в Telegram (для совместимости кросс-канальных названий)
- устаревшие `channels.telegram.streamMode` и булевые значения `streaming` автоматически мигрируются

Для текстовых ответов:

- ЛС: OpenClaw сохраняет то же превью-сообщение и делает финальное редактирование на месте (без второго сообщения)
- группа/тема: OpenClaw сохраняет то же превью-сообщение и делает финальное редактирование на месте (без второго сообщения)

Для сложных ответов (например, медиа) OpenClaw откатывается к стандартной финальной доставке и затем удаляет превью-сообщение.

Потоковый предпросмотр и блочный стриминг — разные вещи. Если блочный стриминг явно включён для Telegram, OpenClaw пропускает предпросмотр, чтобы избежать двойного стриминга.

Если нативный транспорт черновиков недоступен/отклонён, OpenClaw автоматически откатывается к `sendMessage` + `editMessageText`.

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

- `/reasoning stream` отправляет рассуждения в живой предпросмотр во время генерации
- финальный ответ отправляется без текста рассуждений

Исходящий текст использует `parse_mode: "HTML"` Telegram.

- Текст в стиле Markdown рендерится в HTML, безопасный для Telegram.
- Сырой HTML модели экранируется для снижения ошибок парсинга Telegram.
- Если Telegram отклоняет HTML, OpenClaw повторяет отправку как обычный текст.

Предпросмотр ссылок включён по умолчанию и может быть отключён через `channels.telegram.linkPreview: false`.

Регистрация меню команд Telegram обрабатывается при запуске через `setMyCommands`.

Настройки нативных команд по умолчанию:

- `commands.native: "auto"` включает нативные команды для Telegram

Добавление пользовательских пунктов меню:

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}

Правила:

- имена нормализуются (удаляется начальный `/`, приводятся к нижнему регистру)
- допустимый паттерн: `a-z`, `0-9`, `_`, длина `1..32`
- пользовательские команды не могут переопределять нативные
- конфликты/дубликаты пропускаются и логируются

Замечания:

- пользовательские команды — это только пункты меню; они не реализуют поведение автоматически
- команды плагинов/навыков могут работать при вводе, даже если не отображаются в меню Telegram

При отключении нативных команд встроенные удаляются. Пользовательские/плагинные команды могут по-прежнему регистрироваться при настройке.

Типичные ошибки настройки:

- `setMyCommands failed` с `BOT_COMMANDS_TOO_MUCH` означает, что меню Telegram переполнилось после обрезки; уменьшите количество плагинных/скилловых/пользовательских команд или отключите `channels.telegram.commands.native`.
- `setMyCommands failed` с ошибками сети обычно означает, что исходящий DNS/HTTPS к `api.telegram.org` заблокирован.

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

При установленном плагине `device-pair`:

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

Подробнее: [Спаривание](/docs/channels/pairing#pair-via-telegram-recommended-for-ios).

Настройка области inline keyboard:

{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
      },
    },
  },
}

Переопределение для аккаунта:

{
  channels: {
    telegram: {
      accounts: {
        main: {
          capabilities: {
            inlineButtons: "allowlist",
          },
        },
      },
    },
  },
}

Области:

- `off`
- `dm`
- `group`
- `all`
- `allowlist` (по умолчанию)

Устаревшее `capabilities: ["inlineButtons"]` соответствует `inlineButtons: "all"`.

Пример действия message:

{
  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 включают:

- `sendMessage` (`to`, `content`, опционально `mediaUrl`, `replyToMessageId`, `messageThreadId`)
- `react` (`chatId`, `messageId`, `emoji`)
- `deleteMessage` (`chatId`, `messageId`)
- `editMessage` (`chatId`, `messageId`, `content`)
- `createForumTopic` (`chatId`, `name`, опционально `iconColor`, `iconCustomEmojiId`)

Действия с сообщениями канала предоставляют эргономичные алиасы (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).

Шлюзы управления:

- `channels.telegram.actions.sendMessage`
- `channels.telegram.actions.deleteMessage`
- `channels.telegram.actions.reactions`
- `channels.telegram.actions.sticker` (по умолчанию: отключено)

> **Примечание:** `edit` и `topic-create` включены по умолчанию и не имеют отдельных переключателей `channels.telegram.actions.*`.
Отправки в рантайме используют активный снимок конфигурации/секретов (при запуске/перезагрузке), поэтому пути действий не выполняют повторное разрешение SecretRef при каждой отправке.

Семантика удаления реакций: [/tools/reactions](/docs/tools/reactions)

Telegram поддерживает явные теги тредирования в генерируемом выводе:

- `[[reply_to_current]]` — ответ на вызвавшее сообщение
- `[[reply_to:<id>]]` — ответ на конкретное сообщение Telegram по ID

`channels.telegram.replyToMode` управляет обработкой:

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

> **Примечание:** `off` отключает неявное тредирование ответов. Явные теги `[[reply_to_*]]` по-прежнему обрабатываются.

Форумные супергруппы:

- ключи сессий тем добавляют `:topic:<threadId>`
- ответы и индикатор набора текста нацелены на тред темы
- путь конфигурации тем:
  `channels.telegram.groups.<chatId>.topics.<threadId>`

Особый случай General topic (`threadId=1`):

- отправка сообщений опускает `message_thread_id` (Telegram отклоняет `sendMessage(...thread_id=1)`)
- действия typing по-прежнему включают `message_thread_id`

Наследование тем: записи тем наследуют настройки группы, если не переопределены (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
`agentId` — только для темы и не наследуется от группы.

**Маршрутизация агентов по темам**: Каждая тема может направляться к другому агенту через `agentId` в конфигурации темы. Это даёт каждой теме изолированное рабочее пространство, память и сессию. Пример:

```json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // General topic → main agent
            "3": { agentId: "zu" },        // Dev topic → zu agent
            "5": { agentId: "coder" }      // Code review → coder agent
          }
        }
      }
    }
  }
}
```

Каждая тема получает собственный ключ сессии: `agent:zu:telegram:group:-1001234567890:topic:3`

**Постоянная ACP-привязка темы**: Темы форума могут закреплять ACP harness-сессии через типизированные ACP-привязки верхнего уровня:

- `bindings[]` с `type: "acp"` и `match.channel: "telegram"`

Пример:

```json5
{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}
```

Пока область привязки ограничена темами форумов в группах и супергруппах.

**Порождение ACP с привязкой к треду из чата**:

- `/acp spawn <agent> --thread here|auto` может привязать текущую тему Telegram к новой ACP-сессии.
- Последующие сообщения в теме маршрутизируются напрямую в привязанную ACP-сессию (без необходимости `/acp steer`).
- OpenClaw закрепляет сообщение подтверждения порождения в теме после успешной привязки.
- Требует `channels.telegram.threadBindings.spawnAcpSessions=true`.

Контекст шаблонов включает:

- `MessageThreadId`
- `IsForum`

Поведение тредов в ЛС:

- приватные чаты с `message_thread_id` сохраняют маршрутизацию ЛС, но используют ключи сессий и адресаты ответов с учётом тредов.

### Аудиосообщения

Telegram различает голосовые заметки и аудиофайлы.

- по умолчанию: поведение аудиофайла
- тег `[[audio_as_voice]]` в ответе агента для принудительной отправки голосовой заметкой

Пример действия message:

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/voice.ogg",
  asVoice: true,
}

### Видеосообщения

Telegram различает видеофайлы и видеозаметки.

Пример действия message:

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/video.mp4",
  asVideoNote: true,
}

Видеозаметки не поддерживают подписи; текст сообщения отправляется отдельно.

### Стикеры

Обработка входящих стикеров:

- статичные WEBP: загружаются и обрабатываются (placeholder `<media:sticker>`)
- анимированные TGS: пропускаются
- видео WEBM: пропускаются

Контекстные поля стикеров:

- `Sticker.emoji`
- `Sticker.setName`
- `Sticker.fileId`
- `Sticker.fileUniqueId`
- `Sticker.cachedDescription`

Файл кэша стикеров:

- `~/.openclaw/telegram/sticker-cache.json`

Стикеры описываются один раз (при возможности) и кэшируются для снижения повторных обращений к vision.

Включение действий со стикерами:

{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}

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

{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}

Поиск кэшированных стикеров:

{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}

Реакции Telegram приходят как обновления `message_reaction` (отдельно от полезных нагрузок сообщений).

При включении OpenClaw ставит в очередь системные события:

- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`

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

- `channels.telegram.reactionNotifications`: `off | own | all` (по умолчанию: `own`)
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (по умолчанию: `minimal`)

Замечания:

- `own` означает только реакции пользователей на сообщения бота (best-effort через кэш отправленных сообщений).
- События реакций по-прежнему подчиняются правилам доступа Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизованные отправители отбрасываются.
- Telegram не предоставляет ID тредов в обновлениях реакций.
  - не-форумные группы маршрутизируют в сессию группового чата
  - форумные группы маршрутизируют в сессию общей темы группы (`:topic:1`), а не в точную исходную тему

`allowed_updates` для polling/webhook автоматически включают `message_reaction`.

`ackReaction` отправляет эмодзи подтверждения, пока OpenClaw обрабатывает входящее сообщение.

Порядок разрешения:

- `channels.telegram.accounts.<accountId>.ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- резервный эмодзи из идентичности агента (`agents.list[].identity.emoji`, иначе "👀")

Замечания:

- Telegram ожидает unicode-эмодзи (например "👀").
- Используйте `""` для отключения реакции для канала или аккаунта.

Запись конфигурации из канала включена по умолчанию (`configWrites !== false`).

Записи, инициируемые Telegram:

- события миграции групп (`migrate_to_chat_id`) для обновления `channels.telegram.groups`
- `/config set` и `/config unset` (требуется включение команд)

Отключение:

{
  channels: {
    telegram: {
      configWrites: false,
    },
  },
}

По умолчанию: long polling.

Режим webhook:

- установите `channels.telegram.webhookUrl`
- установите `channels.telegram.webhookSecret` (обязательно при установке webhook URL)
- опционально `channels.telegram.webhookPath` (по умолчанию `/telegram-webhook`)
- опционально `channels.telegram.webhookHost` (по умолчанию `127.0.0.1`)
- опционально `channels.telegram.webhookPort` (по умолчанию `8787`)

Локальный слушатель webhook-режима по умолчанию привязывается к `127.0.0.1:8787`.

Если публичный эндпоинт отличается, поставьте обратный прокси перед ним и укажите `webhookUrl` на публичный URL.
Установите `webhookHost` (например `0.0.0.0`) когда вам намеренно нужен внешний ingress.

- `channels.telegram.textChunkLimit` по умолчанию 4000.
- `channels.telegram.chunkMode="newline"` предпочитает границы абзацев (пустые строки) перед разделением по длине.
- `channels.telegram.mediaMaxMb` (по умолчанию 100) ограничивает входящие и исходящие медиа Telegram.
- `channels.telegram.timeoutSeconds` переопределяет таймаут клиента Telegram API (если не задан, применяется значение grammY по умолчанию).
- контекст истории групп использует `channels.telegram.historyLimit` или `messages.groupChat.historyLimit` (по умолчанию 50); `0` — отключить.
- управление историей ЛС:
  - `channels.telegram.dmHistoryLimit`
  - `channels.telegram.dms["<user_id>"].historyLimit`
- конфигурация `channels.telegram.retry` применяется к хелперам отправки Telegram (CLI/инструменты/действия) при восстановимых ошибках исходящего API.

Адресат отправки CLI может быть числовым chat ID или username:

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

Опросы Telegram используют `openclaw message poll` и поддерживают темы форумов:

openclaw message poll --channel telegram --target 123456789 \
  --poll-question "Ship it?" --poll-option "Yes" --poll-option "No"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \
  --poll-duration-seconds 300 --poll-public

Telegram-специфичные флаги опросов:

- `--poll-duration-seconds` (5-600)
- `--poll-anonymous`
- `--poll-public`
- `--thread-id` для тем форумов (или используйте адресат `:topic:`)

Шлюзы действий:

- `channels.telegram.actions.sendMessage=false` отключает исходящие сообщения Telegram, включая опросы
- `channels.telegram.actions.poll=false` отключает создание опросов Telegram, оставляя обычную отправку

Telegram поддерживает одобрения exec в ЛС одобряющих и может опционально отправлять запросы на одобрение в исходный чат или тему.

Путь в конфигурации:

- `channels.telegram.execApprovals.enabled`
- `channels.telegram.execApprovals.approvers`
- `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, по умолчанию: `dm`)
- `agentFilter`, `sessionFilter`

Одобряющие должны быть числовыми Telegram user ID. При `enabled: false` или пустом `approvers` Telegram не выступает клиентом одобрений exec. Запросы одобрения откатываются к другим настроенным маршрутам или политике по умолчанию.

Правила доставки:

- `target: "dm"` отправляет запросы одобрения только в ЛС настроенных одобряющих
- `target: "channel"` отправляет запрос обратно в исходный чат/тему Telegram
- `target: "both"` отправляет в ЛС одобряющих и в исходный чат/тему

Только настроенные одобряющие могут одобрять или отклонять. Остальные не могут использовать `/approve` и кнопки одобрения Telegram.

При доставке в канал текст команды виден в чате, поэтому включайте `channel` или `both` только в доверенных группах/темах. Если запрос попадает в тему форума, OpenClaw сохраняет тему для запроса одобрения и для последующего сообщения.

Inline-кнопки одобрения также зависят от настройки `channels.telegram.capabilities.inlineButtons`, разрешающей соответствующую поверхность (`dm`, `group` или `all`).

Связанная документация: [Одобрения exec](/docs/tools/exec-approvals)

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

- если `channels.telegram.groups` существует, группа должна быть в списке (или включите `"*"`)
- проверьте членство бота в группе
- просмотрите логи: `openclaw logs --follow` для причин пропуска

- авторизуйте свою идентичность отправителя (спаривание и/или числовые `allowFrom`)
- авторизация команд применяется даже при `groupPolicy: "open"`
- `setMyCommands failed` с `BOT_COMMANDS_TOO_MUCH` означает переполнение нативного меню; уменьшите количество плагинных/скилловых/пользовательских команд или отключите нативные меню
- `setMyCommands failed` с ошибками сети обычно указывает на проблемы доступности DNS/HTTPS к `api.telegram.org`

- Node 22+ + кастомный fetch/proxy может вызвать немедленное прерывание при несовпадении типов AbortSignal.
- Некоторые хосты разрешают `api.telegram.org` сначала в IPv6; неработающий IPv6-выход может вызывать периодические ошибки Telegram API.
- Если в логах `TypeError: fetch failed` или `Network request for 'getUpdates' failed!`, OpenClaw повторяет их как восстановимые сетевые ошибки.
- На VPS-хостах с нестабильным прямым выходом/TLS направляйте вызовы Telegram API через `channels.telegram.proxy`:

channels:
  telegram:
    proxy: socks5://<user>:<password>@proxy-host:1080

- Node 22+ по умолчанию использует `autoSelectFamily=true` (кроме WSL2) и `dnsResultOrder=ipv4first`.
- Если ваш хост — WSL2 или лучше работает только с IPv4, принудительно задайте выбор семейства:

channels:
  telegram:
    network:
      autoSelectFamily: false

- Переопределения через переменные окружения (временные):
  - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
  - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
  - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
- Проверка DNS-ответов:

dig +short api.telegram.org A
dig +short api.telegram.org AAAA