---
read_when:
- Работа с функциями Telegram или вебхуками
summary: Статус поддержки, возможности и настройка бота Telegram
title: Telegram
x-i18n:
generated_at: "2026-07-16T16:09:20Z"
model: gpt-5.6
postprocess_version: locale-links-v1
prompt_version: 32
provider: openai
source_hash: 51c155afeb147b92a55f181be269ce13c4fd6b609a94d680cd7e091cd4a7c236
source_path: channels/telegram.md
workflow: 16
---
Готово к промышленной эксплуатации для личных сообщений с ботом и групп через grammY. По умолчанию используется длительный опрос; режим webhook необязателен.
По умолчанию для личных сообщений в Telegram используется политика сопряжения.
Сценарии диагностики и устранения неполадок для разных каналов.
Полные шаблоны и примеры конфигурации каналов.
## Быстрая настройка
В обоих вариантах вы получите токен, который нужно вставить в OpenClaw. Выберите один из них:
- **Через чат**: откройте Telegram, начните чат с **@BotFather** (убедитесь, что имя пользователя в точности совпадает с `@BotFather`), выполните `/newbot`, следуйте подсказкам и сохраните токен.
- **Через веб-интерфейс**: откройте [веб-приложение BotFather](https://t.me/BotFather?startapp) — оно работает во всех клиентах Telegram, включая [web.telegram.org](https://web.telegram.org), — создайте бота в интерфейсе и скопируйте его токен.
```json5
{
channels: {
telegram: {
enabled: true,
botToken: "123:abc",
dmPolicy: "pairing",
groups: { "*": { requireMention: true } },
},
},
}
```
Резервное значение из переменной окружения: `TELEGRAM_BOT_TOKEN` (только для учётной записи по умолчанию; именованные учётные записи должны использовать `botToken` или `tokenFile`).
Telegram **не** использует `openclaw channels login telegram`; задайте токен в конфигурации или переменной окружения, затем запустите Gateway.
```bash
openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram
```
Коды сопряжения действительны в течение 1 часа.
Добавьте бота в группу, затем получите два идентификатора, необходимых для доступа к группе:
- ваш идентификатор пользователя Telegram для `allowFrom` / `groupAllowFrom`
- идентификатор группового чата Telegram в качестве ключа в `channels.telegram.groups`
Получите идентификатор группового чата с помощью `openclaw logs --follow`, бота для определения идентификаторов пересланных сообщений или `getUpdates` Bot API. После разрешения группы команда `/whoami@` подтвердит идентификаторы пользователя и группы.
Отрицательные идентификаторы супергрупп, начинающиеся с `-100`, являются идентификаторами групповых чатов. Их следует указывать в `channels.telegram.groups`, а не в `groupAllowFrom`.
Разрешение токена учитывает учётную запись: `tokenFile` имеет приоритет над `botToken`, а тот — над переменной окружения; конфигурация всегда имеет приоритет над `TELEGRAM_BOT_TOKEN` (который разрешается только для учётной записи по умолчанию). После успешного запуска OpenClaw кэширует идентификатор бота на срок до 24 часов, чтобы при перезапусках не выполнять дополнительный вызов `getMe`; изменение или удаление токена очищает этот кэш.
## Настройки на стороне Telegram
Для ботов Telegram по умолчанию включён **режим конфиденциальности**, ограничивающий получение групповых сообщений.
Чтобы бот видел все групповые сообщения:
- отключите режим конфиденциальности через `/setprivacy` или
- назначьте бота администратором группы.
После изменения режима конфиденциальности удалите бота из каждой группы и добавьте его снова, чтобы Telegram применил изменение.
Статус администратора задаётся в настройках группы Telegram. Боты-администраторы получают все групповые сообщения, что полезно для постоянной работы в группе.
- `/setjoingroups` — разрешить или запретить добавление в группы
- `/setprivacy` — поведение видимости в группах
Те же настройки доступны в [веб-приложении BotFather](https://t.me/BotFather?startapp), если вы предпочитаете графический интерфейс командам чата.
## Мини-приложение панели управления
Выполните `/dashboard` в личном чате с ботом, чтобы открыть панель управления OpenClaw внутри Telegram.
Требования:
- `gateway.tailscale.mode: "serve"` или `"funnel"` для опубликованного HTTPS-URL мини-приложения.
- Ваш числовой идентификатор пользователя Telegram должен находиться в действующем `allowFrom` выбранной учётной записи или в `commands.ownerAllowFrom`.
- Используйте личный чат. В группах `/dashboard` отвечает сообщением `open this in a DM with the bot` и не отправляет кнопку.
- Установки Docker: режимы Serve/Funnel требуют, чтобы Gateway был привязан к loopback-интерфейсу рядом с `tailscaled`, что невозможно обеспечить при использовании мостовой сети с опубликованными портами. Запустите контейнер Gateway с `network_mode: host` и подключите в контейнер сокет `tailscaled` хоста (`/var/run/tailscale`), а также CLI `tailscale`.
Мини-приложение представляет собой путь версии v1, доступный только через Tailscale, и не поддерживает iframe Telegram Web.
## Управление доступом и активация
### Идентификатор бота в группе
В группах и темах форумов явное упоминание настроенного имени пользователя бота (например, `@my_bot`) адресует сообщение выбранному агенту OpenClaw, даже если имя персонажа агента отличается от имени пользователя Telegram. Политика молчания в группе по-прежнему применяется к постороннему трафику, однако имя пользователя самого бота никогда не считается «кем-то другим».
`channels.telegram.dmPolicy` управляет доступом к личным сообщениям:
- `pairing` (по умолчанию)
- `allowlist` (требуется хотя бы один идентификатор отправителя в `allowFrom`)
- `open` (требуется, чтобы `allowFrom` содержал `"*"`)
- `disabled`
`dmPolicy: "open"` с `allowFrom: ["*"]` позволяет любой учётной записи Telegram, которая найдёт или угадает имя пользователя бота, отправлять ему команды. Используйте эту конфигурацию только для намеренно общедоступных ботов с жёстко ограниченным набором инструментов; для ботов с одним владельцем следует использовать `allowlist` с числовыми идентификаторами пользователей.
`channels.telegram.allowFrom` принимает числовые идентификаторы пользователей Telegram. Префиксы `telegram:` / `tg:` принимаются и нормализуются.
В конфигурациях с несколькими учётными записями ограничивающий `channels.telegram.allowFrom` верхнего уровня служит границей безопасности: `allowFrom: ["*"]` на уровне учётной записи не делает её общедоступной, если объединённый действующий список разрешений по-прежнему не содержит явного подстановочного знака.
`dmPolicy: "allowlist"` с пустым `allowFrom` блокирует все личные сообщения и отклоняется при проверке конфигурации.
При настройке запрашиваются только числовые идентификаторы пользователей. Если в конфигурации остались записи списка разрешений `@username` от старой настройки, выполните `openclaw doctor --fix`, чтобы по возможности преобразовать их в числовые идентификаторы (требуется токен бота Telegram).
Если ранее вы использовали файлы списка разрешений хранилища сопряжений, `openclaw doctor --fix` может восстановить записи в `channels.telegram.allowFrom` для сценариев со списками разрешений (например, когда `dmPolicy: "allowlist"` ещё не содержит явных идентификаторов).
Для ботов с одним владельцем рекомендуется использовать `dmPolicy: "allowlist"` с явно заданными числовыми идентификаторами `allowFrom`, а не полагаться на предыдущие одобрения сопряжения.
Распространённое заблуждение: одобрение сопряжения для личных сообщений не означает, что «этот отправитель авторизован везде». Сопряжение предоставляет доступ только к личным сообщениям. Если владелец команд ещё не задан, первое одобренное сопряжение также устанавливает `commands.ownerAllowFrom`, назначая явную учётную запись оператора для команд, доступных только владельцу, и одобрений выполнения. Авторизация отправителей в группах по-прежнему определяется явными списками разрешений в конфигурации.
Чтобы одна и та же учётная запись была авторизована и для личных сообщений, и для групповых команд, добавьте свой числовой идентификатор пользователя Telegram в `channels.telegram.allowFrom`, а для команд, доступных только владельцу, убедитесь, что `commands.ownerAllowFrom` содержит `telegram:`.
### Как узнать свой идентификатор пользователя Telegram
Более безопасный способ (без стороннего бота): отправьте личное сообщение своему боту, выполните `openclaw logs --follow` и найдите `from.id`.
Способ через официальный Bot API:
```bash
curl "https://api.telegram.org/bot/getUpdates"
```
Сторонние сервисы (менее конфиденциально): `@userinfobot` или `@getidsbot`.
Совместно применяются два параметра:
1. **Какие группы разрешены** (`channels.telegram.groups`)
- конфигурация `groups` отсутствует, `groupPolicy: "open"`: любая группа проходит проверку идентификатора группы
- конфигурация `groups` отсутствует, `groupPolicy: "allowlist"` (по умолчанию): все группы заблокированы, пока не будут добавлены записи `groups` (или `"*"`)
- `groups` настроен: действует как список разрешений (явные идентификаторы или `"*"`)
2. **Каким отправителям разрешено взаимодействовать в группах** (`channels.telegram.groupPolicy`)
- `open` / `allowlist` (по умолчанию) / `disabled`
`groupAllowFrom` фильтрует отправителей в группах; если он не задан, Telegram использует `allowFrom` (а не хранилище сопряжений — авторизация отправителей в группах никогда не наследует одобрения из хранилища сопряжений личных сообщений; это граница безопасности начиная с `2026.2.25`).
Записи `groupAllowFrom` должны быть числовыми идентификаторами пользователей Telegram (префиксы `telegram:` / `tg:` нормализуются); нечисловые записи игнорируются. Не указывайте здесь идентификаторы групповых чатов или супергрупп — отрицательные идентификаторы чатов следует размещать в `channels.telegram.groups`.
Практичная схема для ботов с одним владельцем: задайте свой идентификатор пользователя в `channels.telegram.allowFrom`, не задавайте `groupAllowFrom` и разрешите целевые группы в `channels.telegram.groups`.
Если `channels.telegram` полностью отсутствует в конфигурации, во время выполнения по умолчанию применяется закрытый при сбое режим `groupPolicy="allowlist"`, если только `channels.defaults.groupPolicy` не задан явно.
Настройка группы только для владельца:
```json5
{
channels: {
telegram: {
enabled: true,
dmPolicy: "pairing",
allowFrom: [""],
groupPolicy: "allowlist",
groups: {
"": {
requireMention: true,
},
},
},
},
}
```
Проверьте работу из группы с помощью `@ ping`. Обычные групповые сообщения не активируют бота, пока действует `requireMention: true`.
Разрешить любому участнику одной конкретной группы:
```json5
{
channels: {
telegram: {
groups: {
"-1001234567890": {
groupPolicy: "open",
requireMention: false,
},
},
},
},
}
```
Разрешить только определённых пользователей в одной конкретной группе:
```json5
{
channels: {
telegram: {
groups: {
"-1001234567890": {
requireMention: true,
allowFrom: ["8734062810", "745123456"],
},
},
},
},
}
```
Распространённая ошибка: `groupAllowFrom` не является списком разрешённых групп.
- Отрицательные идентификаторы групповых чатов и супергрупп Telegram (`-1001234567890`) указываются в `channels.telegram.groups`.
- Идентификаторы пользователей Telegram (`8734062810`) указываются в `groupAllowFrom`, чтобы ограничить круг людей в разрешённой группе, которые могут активировать бота.
- Используйте `groupAllowFrom: ["*"]` только для того, чтобы любой участник разрешённой группы мог обращаться к боту.
По умолчанию для ответов в группах требуется упоминание. Упоминанием может быть:
- нативное упоминание `@botusername` или
- шаблон упоминания в `agents.list[].groupChat.mentionPatterns` или `messages.groupChat.mentionPatterns`
Переключатели уровня сеанса (меняют только состояние и не сохраняются): `/activation always`, `/activation mention`. Для постоянной настройки используйте конфигурацию:
```json5
{
channels: {
telegram: {
groups: {
"*": { requireMention: false },
},
},
},
}
```
Контекст истории группы всегда включён и ограничен параметром `historyLimit`. Задайте `channels.telegram.historyLimit: 0`, чтобы отключить окно истории группы. `openclaw doctor --fix` удаляет устаревший ключ `includeGroupHistoryContext`.
Как получить идентификатор группового чата: перешлите сообщение из группы в `@userinfobot` / `@getidsbot`, найдите `chat.id` в `openclaw logs --follow`, проверьте `getUpdates` Bot API или, после разрешения группы, выполните `/whoami@`.
## Поведение во время выполнения
- Telegram работает внутри процесса Gateway.
- Маршрутизация детерминирована: входящие ответы из Telegram возвращаются в Telegram (модель не выбирает каналы).
- Входящие сообщения нормализуются в общий конверт канала с метаданными ответа, заполнителями медиа и сохранённым контекстом цепочки ответов для ответов, замеченных Gateway.
- Групповые сеансы изолируются по идентификатору группы. Для тем форума добавляется `:topic:`.
- Сообщения в личных чатах могут содержать `message_thread_id`; OpenClaw сохраняет его для ответов. Сеансы тем в личных чатах разделяются, только когда Telegram `getMe` сообщает `has_topics_enabled: true` для бота; в противном случае личные чаты остаются в плоском сеансе.
- Длительный опрос использует исполнитель grammY с последовательной обработкой для каждого чата и каждой ветки. Параллелизм приёмника исполнителя задаётся через `agents.defaults.maxConcurrent`.
- При запуске нескольких учётных записей ограничивается число параллельных проверок `getMe`, чтобы большие парки ботов не запускали проверки всех учётных записей одновременно.
- Каждый процесс Gateway контролирует длительный опрос, чтобы токен бота одновременно мог использовать только один активный опрашивающий процесс. Постоянные конфликты 409 `getUpdates` указывают на другой Gateway OpenClaw, скрипт или внешний опрашивающий процесс, использующий тот же токен.
- По умолчанию сторожевой таймер опроса перезапускает его после 120 секунд без завершённой проверки работоспособности `getUpdates`. Увеличивайте `channels.telegram.pollingStallThresholdMs` (30000-600000, поддерживаются переопределения для отдельных учётных записей), только если в вашей среде возникают ложные перезапуски из-за зависания опроса во время длительной работы.
- Telegram Bot API не поддерживает подтверждения прочтения (`sendReadReceipts` неприменим).
`channels.telegram.dm.threadReplies` и `channels.telegram.direct..threadReplies` удалены. После обновления выполните `openclaw doctor --fix`, если эти ключи всё ещё присутствуют в конфигурации. Маршрутизация тем в личных чатах теперь следует `getMe.has_topics_enabled` Telegram (управляется режимом веток в BotFather): боты с включёнными темами используют сеансы личных чатов в рамках ветки, когда Telegram отправляет `message_thread_id`; остальные личные чаты остаются в плоском сеансе.
## Справочник возможностей
OpenClaw передаёт частичные ответы в реальном времени в личных чатах, группах и темах: отправляет сообщение предварительного просмотра, затем многократно выполняет `editMessageText`, завершая ответ на месте.
- `channels.telegram.streaming` имеет значение `off | partial | block | progress` (по умолчанию: `partial`)
- для коротких начальных предварительных ответов применяется устранение дребезга, после чего они материализуются спустя ограниченную задержку, если выполнение всё ещё активно
- `progress` сохраняет один редактируемый черновик состояния для отображения хода выполнения инструментов, показывает стабильную метку состояния, когда активность ответа начинается до выполнения инструментов, очищает его после завершения и отправляет окончательный ответ обычным сообщением
- `streaming.preview.toolProgress` определяет, будут ли обновления инструментов и хода выполнения повторно использовать то же редактируемое сообщение предварительного просмотра (по умолчанию: `true`, когда активна потоковая передача предварительного просмотра)
- `streaming.preview.commandText` управляет детализацией команд и выполнения в этих строках: `raw` (по умолчанию) или `status` (только метка инструмента)
- `streaming.progress.commentary` (по умолчанию: `false`) включает комментарии и вводный текст ассистента во временном черновике хода выполнения
- устаревшие `channels.telegram.streamMode`, логические значения `streaming` и выведенные из эксплуатации ключи нативного предварительного просмотра черновика обнаруживаются автоматически; выполните `openclaw doctor --fix` для их миграции
Строки хода выполнения инструментов — это краткие обновления состояния, отображаемые во время работы инструментов (выполнение команд, чтение файлов, обновление планов, сводки исправлений, вводный текст и комментарии Codex в режиме сервера приложений). В Telegram они по умолчанию включены (соответствует поведению, выпускаемому начиная с `v2026.4.22`+).
Чтобы сохранить редактирование предварительного ответа, но скрыть строки хода выполнения инструментов:
```json
{
"channels": {
"telegram": {
"streaming": {
"mode": "partial",
"preview": { "toolProgress": false }
}
}
}
}
```
Чтобы оставить ход выполнения инструментов видимым, но скрыть текст команд и выполнения:
```json
{
"channels": {
"telegram": {
"streaming": {
"mode": "partial",
"preview": { "commandText": "status" }
}
}
}
}
```
Режим `progress` показывает ход выполнения инструментов, не вставляя окончательный ответ в это сообщение путём редактирования. Разместите политику текста команд в `streaming.progress`:
```json
{
"channels": {
"telegram": {
"streaming": {
"mode": "progress",
"progress": {
"toolProgress": true,
"commandText": "status"
}
}
}
}
}
```
`streaming.mode: "off"` отключает редактирование предварительного просмотра и подавляет общие сообщения инструментов и хода выполнения вместо их отправки отдельными сообщениями состояния; запросы подтверждения, медиа и ошибки по-прежнему передаются через обычную доставку окончательного ответа. `streaming.preview.toolProgress: false` сохраняет только редактирование предварительного ответа.
Исключение составляют ответы на выделенные цитаты. Когда `replyToMode` имеет значение `first`, `all` или `batched`, а входящее сообщение содержит выделенный текст цитаты, OpenClaw отправляет окончательный ответ через нативный механизм ответа на цитату Telegram вместо редактирования предварительного ответа, поэтому `streaming.preview.toolProgress` не может отображать строки состояния в этом ходе. Ответы на текущее сообщение без выделенного текста цитаты по-прежнему передаются потоково. Установите `replyToMode: "off"`, если видимость хода выполнения инструментов важнее нативных ответов на цитаты, или `streaming.preview.toolProgress: false`, чтобы принять этот компромисс.
Для ответов только с текстом: короткие предварительные ответы окончательно редактируются на месте; длинные окончательные ответы, разделяемые на несколько сообщений, используют предварительный ответ как первый фрагмент, после чего отправляется только остаток; окончательные ответы в режиме хода выполнения очищают черновик состояния и используют обычную доставку окончательного ответа; если окончательное редактирование завершается с ошибкой до подтверждения завершения, OpenClaw переключается на обычную доставку окончательного ответа и удаляет устаревший предварительный ответ. Для сложных ответов (с полезной нагрузкой медиа) OpenClaw всегда переключается на обычную доставку окончательного ответа и удаляет предварительный ответ.
Потоковая передача предварительного просмотра и блочная потоковая передача взаимоисключающие — когда блочная потоковая передача явно включена, OpenClaw пропускает поток предварительного просмотра, чтобы избежать двойной потоковой передачи.
Рассуждения: `/reasoning stream` передаёт рассуждения в потоковом режиме в предварительный просмотр во время генерации, а затем удаляет предварительный просмотр рассуждений после доставки окончательного ответа (используйте `/reasoning on`, чтобы оставить его видимым). Окончательный ответ отправляется без текста рассуждений.
По умолчанию исходящий текст использует стандартные HTML-сообщения Telegram, читаемые во всех актуальных клиентах: полужирный текст, курсив, ссылки, код, спойлеры, цитаты — без блоков, доступных только в расширенном формате Bot API 10.2 (нативные таблицы, подробности, расширенные медиа, формулы).
Чтобы включить расширенные сообщения Bot API 10.2:
```json5
{
channels: {
telegram: {
richMessages: true,
},
},
}
```
Когда эта возможность включена: агенту сообщается, что расширенные сообщения доступны для этого бота или учётной записи (вместе с поддерживаемым контрактом создания содержимого Markdown и HTML-вставок); текст Markdown отображается через Markdown IR OpenClaw в виде типизированных расширенных блоков Bot API 10.2 (заголовки, таблицы, подробности, контрольные списки, расширенные медиа, формулы, карты, коллажи); подписи к медиа по-прежнему используют HTML-подписи Telegram (расширенные сообщения не заменяют подписи, а длина подписей ограничена 1024 символами).
Благодаря этому текст модели не содержит специальных обозначений расширенного Markdown Telegram, поэтому обозначения валют вроде `$400-600K` не интерпретируются как математические выражения. Длинный расширенный текст автоматически разделяется с учётом ограничений Telegram. Таблицы, превышающие ограничение в 20 столбцов, заменяются блоком кода.
По умолчанию: выключено для совместимости с клиентами — некоторые актуальные клиенты для Desktop, Web, Android и сторонние клиенты отображают принятые расширенные сообщения как неподдерживаемые. Не включайте эту возможность, если хотя бы один клиент, используемый с ботом, не может отображать такие сообщения. `/status` показывает, включены или выключены расширенные сообщения в текущем сеансе.
Предварительный просмотр ссылок включён по умолчанию. `channels.telegram.linkPreview: false` отключает автоматическое обнаружение сущностей в расширенном тексте.
Меню команд Telegram регистрируется при запуске с помощью `setMyCommands`. `commands.native: "auto"` включает нативные команды для Telegram.
Добавление пользовательских пунктов меню команд:
```json5
{
channels: {
telegram: {
customCommands: [
{ command: "backup", description: "Резервное копирование Git" },
{ command: "generate", description: "Создать изображение" },
],
},
},
}
```
Правила: имена нормализуются (удаляется начальный `/`, преобразуются в нижний регистр); допустимый шаблон `a-z`, `0-9`, `_`, длина 1-32; пользовательские команды не могут переопределять нативные команды; конфликты и дубликаты пропускаются и записываются в журнал.
Пользовательские команды — это только пункты меню, они не реализуют поведение автоматически. Команды плагинов и Skills могут работать при ручном вводе, даже если они не отображаются в меню Telegram. Если нативные команды отключены, встроенные команды удаляются; пользовательские команды и команды плагинов всё равно могут регистрироваться, если они настроены.
Распространённые ошибки настройки:
- `setMyCommands failed` с `BOT_COMMANDS_TOO_MUCH` после повторной попытки сокращения означает, что меню по-прежнему переполнено; уменьшите количество команд плагинов, Skills или пользовательских команд либо отключите `channels.telegram.commands.native`.
- Сбой `deleteWebhook`, `deleteMyCommands` или `setMyCommands` с `404: Not Found`, когда прямые команды curl к Bot API работают, обычно означает, что в `channels.telegram.apiRoot` указан полный адрес конечной точки `/bot`. В `apiRoot` должен быть указан только корневой адрес Bot API; `openclaw doctor --fix` удаляет случайный завершающий `/bot`.
- `getMe returned 401` означает, что Telegram отклонил настроенный токен бота. Обновите `botToken`, `tokenFile` или `TELEGRAM_BOT_TOKEN` (учётная запись по умолчанию), указав текущий токен BotFather; OpenClaw останавливается до начала опроса, поэтому эта ошибка не отображается как сбой очистки Webhook.
- `setMyCommands failed` с ошибками сети или получения данных обычно означает, что исходящие запросы DNS/HTTPS к `api.telegram.org` заблокированы.
### Команды сопряжения устройств (плагин `device-pair`)
После установки:
1. `/pair` создаёт код настройки
2. вставьте код в приложение iOS
3. `/pair pending` выводит список ожидающих запросов (включая роль и области действия)
4. подтверждение: `/pair approve `, `/pair approve` (единственный ожидающий запрос) или `/pair approve latest`
Если устройство повторяет попытку с изменёнными данными аутентификации (ролью, областями действия, открытым ключом), предыдущий ожидающий запрос заменяется новым `requestId`; перед подтверждением снова выполните `/pair pending`.
Подробнее: [Сопряжение](/ru/channels/pairing#pair-via-telegram).
Настройка области действия встроенной клавиатуры:
```json5
{
channels: {
telegram: {
capabilities: {
inlineButtons: "allowlist",
},
},
},
}
```
Переопределение для отдельной учётной записи:
```json5
{
channels: {
telegram: {
accounts: {
main: {
capabilities: {
inlineButtons: "allowlist",
},
},
},
},
},
}
```
Области действия: `off`, `dm`, `group`, `all`, `allowlist` (по умолчанию). Устаревшее значение `capabilities: ["inlineButtons"]` сопоставляется с `"all"`.
Пример действия с сообщением:
```json5
{
action: "send",
channel: "telegram",
to: "123456789",
message: "Выберите вариант:",
buttons: [
[
{ text: "Да", callback_data: "yes" },
{ text: "Нет", callback_data: "no" },
],
[{ text: "Отмена", callback_data: "cancel" }],
],
}
```
Пример кнопки мини-приложения:
```json5
{
action: "send",
channel: "telegram",
to: "123456789",
message: "Открыть приложение:",
presentation: {
blocks: [
{
type: "buttons",
buttons: [{ label: "Запустить", web_app: { url: "https://example.com/app" } }],
},
],
},
}
```
Кнопки `web_app` работают только в личных чатах между пользователем и ботом.
Нажатия на callback-кнопки, не обработанные зарегистрированным интерактивным обработчиком плагина, передаются агенту как текст: `callback_data: `.
Действия:
- `sendMessage` (`to`, `content`, необязательный `mediaUrl`, `replyToMessageId`, `messageThreadId`)
- `react` (`chatId`, `messageId`, `emoji`)
- `deleteMessage` (`chatId`, `messageId`)
- `editMessage` (`chatId`, `messageId`, `content` или `caption`, необязательные встроенные кнопки `presentation`; изменения только кнопок обновляют разметку ответа)
- `createForumTopic` (`chatId`, `name`, необязательный `iconColor`, `iconCustomEmojiId`)
Удобные псевдонимы: `send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`.
Ограничение доступа: `channels.telegram.actions.sendMessage`, `deleteMessage`, `reactions`, `sticker` (по умолчанию отключено). `edit`, `createForumTopic` и `editForumTopic` включены по умолчанию и не имеют отдельных переключателей.
При отправке во время выполнения используется активный снимок конфигурации и секретов, полученный при запуске или перезагрузке, поэтому пути действий не разрешают значения `SecretRef` заново при каждой отправке.
Семантика удаления реакций: [/tools/reactions](/ru/tools/reactions).
Явные теги ветвления ответов в сгенерированном выводе:
- `[[reply_to_current]]` — отвечает на сообщение, вызвавшее действие
- `[[reply_to:]]` — отвечает на сообщение с указанным идентификатором
`channels.telegram.replyToMode`: `off` (по умолчанию), `first`, `all`.
Когда ветвление ответов включено и исходный текст или подпись доступны, OpenClaw автоматически добавляет нативную цитату. Telegram ограничивает текст нативной цитаты 1024 кодовыми единицами UTF-16; для более длинных сообщений цитируется начало, а если Telegram отклоняет цитату, используется обычный ответ.
`off` отключает только неявное ветвление ответов; явные теги `[[reply_to_*]]` по-прежнему учитываются.
Супергруппы с форумами: к ключам сеансов тем добавляется `:topic:`; ответы и индикатор набора текста направляются в ветку темы; путь конфигурации темы — `channels.telegram.groups..topics.`.
Общая тема (`threadId=1`) — особый случай: при отправке сообщений `message_thread_id` опускается (Telegram отклоняет `sendMessage(...thread_id=1)` с сообщением «ветка не найдена»), но действия набора текста по-прежнему включают `message_thread_id` (согласно практическим наблюдениям, это необходимо для отображения индикатора набора текста).
Записи тем наследуют настройки группы, если они не переопределены (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). `agentId` применяется только к теме и не наследуется из настроек группы по умолчанию. `topics."*"` задаёт значения по умолчанию для каждой темы в этой группе; точные идентификаторы тем по-прежнему имеют приоритет над `"*"`.
**Маршрутизация агентов по темам**: каждую тему можно направить отдельному агенту через `agentId` в конфигурации темы, предоставив ей собственное рабочее пространство, память и сеанс:
```json5
{
channels: {
telegram: {
groups: {
"-1001234567890": {
topics: {
"1": { agentId: "main" }, // Общая тема -> основной агент
"3": { agentId: "zu" }, // Тема разработки -> агент zu
"5": { agentId: "coder" } // Проверка кода -> агент coder
}
}
}
}
}
}
```
После этого у каждой темы будет собственный ключ сеанса, например `agent:zu:telegram:group:-1001234567890:topic:3`.
**Постоянная привязка темы ACP**: темы форума могут закреплять сеансы среды ACP с помощью типизированных привязок верхнего уровня (`bindings[]` с `type: "acp"`, `match.channel: "telegram"`, `peer.kind: "group"` и идентификатором с указанием темы, например `-1001234567890:topic:42`). В настоящее время область действия ограничена темами форумов в группах и супергруппах. См. [Агенты ACP](/ru/tools/acp-agents).
**Запуск ACP из чата с привязкой к ветке**: `/acp spawn --thread here|auto` привязывает текущую тему к новому сеансу ACP; последующие сообщения направляются туда напрямую, а OpenClaw закрепляет подтверждение запуска в теме. Требуется `channels.telegram.threadBindings.spawnSessions` (по умолчанию: `true`).
В контексте шаблона доступны `MessageThreadId` и `IsForum`. Личные чаты с `message_thread_id` сохраняют метаданные ответа, но используют ключи сеансов с учётом веток только тогда, когда Telegram `getMe` сообщает `has_topics_enabled: true`.
Устаревшие переопределения `dm.threadReplies` и `direct.*.threadReplies` удалены; режим веток BotFather является единственным источником истины. Выполните `openclaw doctor --fix`, чтобы удалить устаревшие ключи конфигурации.
### Аудиосообщения
Telegram различает голосовые сообщения и аудиофайлы. По умолчанию используется поведение аудиофайла; добавьте тег `[[audio_as_voice]]` в ответ агента, чтобы принудительно отправить голосовое сообщение. Расшифровки входящих голосовых сообщений помещаются в контекст агента как машинно-сгенерированный недоверенный текст, однако обнаружение упоминаний по-прежнему использует необработанную расшифровку, поэтому голосовые сообщения, требующие упоминания, продолжают работать.
```json5
{
action: "send",
channel: "telegram",
to: "123456789",
media: "https://example.com/voice.ogg",
asVoice: true,
}
```
### Видеосообщения
Telegram различает видеофайлы и видеосообщения. Видеосообщения не поддерживают подписи; указанный текст сообщения отправляется отдельно.
```json5
{
action: "send",
channel: "telegram",
to: "123456789",
media: "https://example.com/video.mp4",
asVideoNote: true,
}
```
### Местоположения и места
Используйте существующее действие `send` с одним отдельным объектом `location`. Координаты отправляются как нативная метка; добавление одновременно `name` и `address` отправляет нативную карточку места. Отправку местоположения нельзя совмещать с текстом сообщения или медиафайлом.
```json5
{
action: "send",
channel: "telegram",
to: "123456789",
location: {
latitude: 48.858844,
longitude: 2.294351,
accuracy: 12,
name: "Эйфелева башня",
address: "Марсово поле, Париж",
},
}
```
### Стикеры
Входящие: статические WEBP-файлы загружаются и обрабатываются (заполнитель ``); анимированные TGS- и видеофайлы WEBM пропускаются.
Поля контекста стикера: `Sticker.emoji`, `Sticker.setName`, `Sticker.fileId`, `Sticker.fileUniqueId`, `Sticker.cachedDescription`. Описания кешируются в состоянии плагина OpenClaw в SQLite, чтобы сократить число повторных обращений к компьютерному зрению.
Включение действий со стикерами:
```json5
{
channels: {
telegram: {
actions: {
sticker: true,
},
},
},
}
```
Отправка:
```json5
{
action: "sticker",
channel: "telegram",
to: "123456789",
fileId: "CAACAgIAAxkBAAI...",
}
```
Поиск кешированных стикеров:
```json5
{
action: "sticker-search",
channel: "telegram",
query: "машущий кот",
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` означает только реакции пользователей на сообщения, отправленные ботом (по возможности определяется с помощью кеша отправленных сообщений). События реакций по-прежнему подчиняются правилам управления доступом Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); события от неавторизованных отправителей отбрасываются.
Telegram не предоставляет идентификаторы веток в обновлениях реакций: обычные группы направляются в сеанс группового чата, а группы с форумами — в сеанс общей темы (`:topic:1`), а не в конкретную исходную тему.
`allowed_updates` для опроса или webhook автоматически включают `message_reaction`.
`ackReaction` отправляет эмодзи подтверждения, пока OpenClaw обрабатывает входящее сообщение. `messages.ackReactionScope` определяет, *когда* оно отправляется.
**Порядок выбора эмодзи:**
- `channels.telegram.accounts..ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- резервный эмодзи идентичности агента (`agents.list[].identity.emoji`, иначе «👀»)
Telegram ожидает эмодзи Unicode (например, «👀»); используйте `""`, чтобы отключить реакцию для канала или учётной записи.
**Область действия (`messages.ackReactionScope`, по умолчанию `"group-mentions"`; переопределение для учётной записи или канала Telegram в настоящее время отсутствует):**
`all` (личные сообщения и группы, включая фоновые события комнат), `direct` (только личные сообщения), `group-all` (каждое групповое сообщение, кроме фоновых событий комнат; без личных сообщений), `group-mentions` (группы, когда бот упомянут; **без личных сообщений** — значение по умолчанию), `off` / `none` (отключено).
При области действия по умолчанию (`group-mentions`) реакции-подтверждения не срабатывают в личных сообщениях и для фоновых событий комнат. Для личных сообщений используйте `direct` или `all`; только `all` подтверждает фоновые события комнат. Это значение считывается при запуске провайдера Telegram, поэтому для вступления изменения в силу требуется перезапуск Gateway.
Запись конфигурации канала включена по умолчанию (`configWrites !== false`). К операциям записи, инициированным Telegram, относятся события миграции групп (`migrate_to_chat_id`, обновляет `channels.telegram.groups`) и `/config set` / `/config unset` (требуется включение команд).
Отключение:
```json5
{
channels: {
telegram: {
configWrites: false,
},
},
}
```
По умолчанию используется длительный опрос. Для режима webhook задайте `channels.telegram.webhookUrl` и `channels.telegram.webhookSecret`; необязательно: `webhookPath` (по умолчанию `/telegram-webhook`), `webhookHost` (по умолчанию `127.0.0.1`), `webhookPort` (по умолчанию `8787`), `webhookCertPath` (самоподписанный сертификат PEM для конфигураций с прямым IP-адресом или без домена).
В режиме длительного опроса OpenClaw сохраняет отметку перезапуска только после успешной передачи обновления; при сбое обработчика обновление остаётся доступным для повторной обработки в том же процессе и не помечается как завершённое.
По умолчанию локальный слушатель привязывается к `127.0.0.1:8787`. Для публичного входящего трафика разместите обратный прокси перед локальным портом или явно задайте `webhookHost: "0.0.0.0"`.
Режим webhook проверяет защитные условия запроса, секретный токен Telegram и тело JSON, а затем фиксирует обновление в устойчивой очереди входящих данных, прежде чем вернуть пустой `200`. Успешное принятие в устойчивую очередь включает `x-openclaw-delivery-accepted: durable`; ответы проверки работоспособности, маршрутизации, аутентификации, валидации и ошибок хранилища не содержат этот заголовок. Обратные прокси и контроллеры хоста могут требовать этот заголовок, чтобы отличать принятие OpenClaw от обычного пустого `200`, не определяя факт принятия по времени ответа.
Затем OpenClaw асинхронно обрабатывает обновление через те же очереди бота для каждого чата и каждой темы, которые используются при длительном опросе, поэтому медленные обращения к агенту не задерживают подтверждение доставки Telegram.
- `channels.telegram.textChunkLimit` по умолчанию равно 4000; `streaming.chunkMode="newline"` предпочитает границы абзацев (пустые строки) перед разделением по длине.
- `channels.telegram.mediaMaxMb` (по умолчанию 100) ограничивает размер входящих и исходящих медиафайлов.
- `channels.telegram.mediaGroupFlushMs` (по умолчанию 500, диапазон 10-60000) определяет, как долго альбомы и группы медиафайлов буферизуются, прежде чем OpenClaw передаст их как одно входящее сообщение. Увеличьте значение, если части альбома поступают с задержкой; уменьшите его, чтобы сократить задержку ответа на альбом.
- `channels.telegram.timeoutSeconds` переопределяет тайм-аут клиента API (если значение не задано, применяется значение по умолчанию grammY). Клиенты ботов ограничивают настроенные значения ниже 60-секундного защитного интервала для исходящих запросов текста и индикатора набора, чтобы grammY не прерывал доставку видимого ответа до того, как смогут сработать транспортный защитный механизм OpenClaw и резервный вариант. Для длительного опроса по-прежнему используется 45-секундный защитный интервал запроса `getUpdates`, чтобы бездействующие опросы не оставались незавершёнными бесконечно.
- `channels.telegram.pollingStallThresholdMs` по умолчанию равно 120000; настраивайте в диапазоне от 30000 до 600000 только при ложноположительных перезапусках из-за зависания опроса.
- история контекста группы использует `channels.telegram.historyLimit` или `messages.groupChat.historyLimit` (по умолчанию 50); `0` отключает её.
- дополнительный контекст ответа, цитаты или пересылки нормализуется в одно выбранное окно контекста беседы, если Gateway наблюдал родительские сообщения; кеш наблюдаемых сообщений хранится в состоянии плагина OpenClaw в SQLite, а `openclaw doctor --fix` импортирует устаревшие вспомогательные файлы. Telegram включает только один неглубокий `reply_to_message` в каждое обновление, поэтому цепочки старше кеша ограничены этими данными.
- списки разрешённых пользователей Telegram в первую очередь определяют, кто может запускать агента, а не служат полноценной границей редактирования дополнительного контекста.
- история личных сообщений: `channels.telegram.dmHistoryLimit`, `channels.telegram.dms[""].historyLimit`.
- `channels.telegram.retry` применяется к вспомогательным функциям отправки Telegram (CLI/инструменты/действия) при устранимых ошибках исходящего API. Для доставки итогового ответа на входящее сообщение используется ограниченное число безопасных повторных попыток при сбоях до подключения, но неоднозначные сетевые ответы после отправки не повторяются, поскольку это может привести к дублированию видимых сообщений.
Цели отправки CLI и инструмента сообщений принимают числовой идентификатор чата, имя пользователя или цель темы форума:
```bash
openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"
```
Опросы используют `openclaw message poll` и поддерживают темы форума:
```bash
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:`). `--poll-option` повторяется 2-12 раз (ограничение Telegram на количество вариантов).
Отправка в Telegram также поддерживает `--presentation` с блоками `buttons` для встроенных клавиатур (если это разрешено `channels.telegram.capabilities.inlineButtons`), `--pin` или `--delivery '{"pin":true}'` для запроса закреплённой доставки, если бот может закреплять сообщения в этом чате, и `--force-document` для отправки исходящих изображений, GIF-файлов и видео как документов вместо сжатых изображений, анимаций или видео.
Ограничение действий: `channels.telegram.actions.sendMessage=false` отключает все исходящие сообщения, включая опросы; `channels.telegram.actions.poll=false` отключает создание опросов, оставляя обычную отправку включённой.
Telegram поддерживает подтверждение выполнения команд в личных сообщениях подтверждающих лиц и при необходимости может публиковать запросы в исходном чате или теме. Подтверждающие лица должны быть указаны числовыми идентификаторами пользователей Telegram.
- `channels.telegram.execApprovals.enabled` (`"auto"` включает функцию, если можно определить хотя бы одно подтверждающее лицо)
- `channels.telegram.execApprovals.approvers` (если значение отсутствует, используются числовые идентификаторы владельцев из `commands.ownerAllowFrom`)
- `channels.telegram.execApprovals.target`: `dm` (по умолчанию) | `channel` | `both`
- `agentFilter`, `sessionFilter`
`channels.telegram.allowFrom`, `groupAllowFrom` и `defaultTo` определяют, кто может обращаться к боту и куда он отправляет обычные ответы, — они не наделяют пользователя правом подтверждать выполнение команд. Первое одобренное сопряжение в личных сообщениях инициализирует `commands.ownerAllowFrom`, если владелец команд ещё не существует, поэтому конфигурации с одним владельцем работают без дублирования идентификаторов в `execApprovals.approvers`.
При доставке в канал текст команды отображается в чате; включайте `channel` или `both` только в доверенных группах или темах. Если запрос поступает в тему форума, OpenClaw сохраняет тему для запроса подтверждения и последующих сообщений. По умолчанию срок действия подтверждений выполнения команд истекает через 30 минут.
Для встроенных кнопок подтверждения также требуется, чтобы `channels.telegram.capabilities.inlineButtons` разрешал целевую область (`dm`, `group` или `all`). Идентификаторы подтверждения с префиксом `plugin:` обрабатываются через подтверждения плагина; остальные сначала обрабатываются через подтверждения выполнения команд.
См. [Подтверждение выполнения команд](/ru/tools/exec-approvals).
## Управление ответами об ошибках
Когда агент сталкивается с ошибкой доставки или провайдера, политика ошибок определяет, будут ли сообщения об ошибках отправлены в чат Telegram:
| Ключ | Значения | По умолчанию | Описание |
| ----------------------------------- | -------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `channels.telegram.errorPolicy` | `always`, `once`, `silent` | `always` | `always` отправляет в чат каждое сообщение об ошибке. `once` отправляет каждое уникальное сообщение об ошибке один раз за период ожидания (повторяющиеся одинаковые ошибки подавляются). `silent` никогда не отправляет сообщения об ошибках в чат. |
| `channels.telegram.errorCooldownMs` | число (мс) | `14400000` (4 ч) | Период ожидания для политики `once`. После отправки ошибки такое же сообщение подавляется до истечения этого интервала. Предотвращает поток сообщений об ошибках во время сбоев. |
Поддерживаются переопределения для отдельных учётных записей, групп и тем (с тем же наследованием, что и у других ключей конфигурации Telegram).
```json5
{
channels: {
telegram: {
errorPolicy: "always",
errorCooldownMs: 120000,
groups: {
"-1001234567890": {
errorPolicy: "silent", // подавлять ошибки в этой группе
},
},
},
},
}
```
## Устранение неполадок
- Если `requireMention=false`, режим конфиденциальности Telegram должен обеспечивать полную видимость: BotFather `/setprivacy` -> Disable, затем удалите бота из группы и добавьте его снова.
- `openclaw channels status` предупреждает, когда конфигурация предполагает обработку сообщений группы без упоминания.
- `openclaw channels status --probe` проверяет явно указанные числовые идентификаторы групп; принадлежность по шаблону `"*"` проверить невозможно.
- Быстрая проверка сеанса: `/activation always`.
- Если существует `channels.telegram.groups`, группа должна быть указана в списке (либо список должен содержать `"*"`).
- Проверьте, состоит ли бот в группе.
- Причины пропуска см. в `openclaw logs --follow`.
- Авторизуйте идентификатор отправителя (через сопряжение и/или числовой `allowFrom`); авторизация команд применяется, даже если политика группы имеет значение `open`.
- `setMyCommands failed` вместе с `BOT_COMMANDS_TOO_MUCH` означает, что нативное меню содержит слишком много пунктов; сократите количество команд плагинов, навыков или пользовательских команд либо отключите нативные меню.
- Вызовы запуска `deleteMyCommands` / `setMyCommands` и вызовы индикатора набора `sendChatAction` ограничены по времени и при тайм-ауте запроса повторяются один раз через резервный транспорт Telegram. Постоянные ошибки сети или fetch обычно означают, что `api.telegram.org` недоступен по DNS/HTTPS.
- `getMe returned 401` — это ошибка аутентификации Telegram для настроенного токена бота. Повторно скопируйте или сгенерируйте токен в BotFather, затем обновите `channels.telegram.botToken`, `tokenFile`, `accounts..botToken` или `TELEGRAM_BOT_TOKEN` (учётная запись по умолчанию).
- `deleteWebhook 401 Unauthorized` во время запуска также является ошибкой аутентификации; если интерпретировать её как «Webhook отсутствует», это лишь отложит ту же ошибку некорректного токена до следующего вызова API.
- Node 22+ с пользовательским fetch или прокси может вызывать немедленное прерывание, если типы `AbortSignal` не совпадают.
- Некоторые хосты сначала разрешают `api.telegram.org` в IPv6; неисправный исходящий трафик IPv6 вызывает периодические сбои API.
- Ошибки в журналах с `TypeError: fetch failed` или `Network request for 'getUpdates' failed!` считаются устранимыми сетевыми ошибками и вызывают повторные попытки.
- Во время запуска опроса OpenClaw повторно использует успешную стартовую проверку `getMe` для grammY, поэтому среде выполнения не требуется второй `getMe` перед первым `getUpdates`.
- Если `deleteWebhook` завершается с временной сетевой ошибкой во время запуска опроса, OpenClaw переходит к длительному опросу вместо ещё одного вызова управляющего API перед опросом. Если Webhook всё ещё активен, возникает конфликт `getUpdates`; OpenClaw пересоздаёт транспорт и повторяет очистку Webhook.
- Если сокеты Telegram пересоздаются через короткие фиксированные интервалы, проверьте, не задано ли низкое значение `channels.telegram.timeoutSeconds`: клиенты ботов ограничивают настроенные значения ниже защитных интервалов исходящих запросов и запросов `getUpdates`, однако старые выпуски могли прерывать каждый опрос или ответ, если это значение было ниже указанных интервалов.
- `Polling stall detected` в журналах означает, что OpenClaw перезапускает опрос и пересоздаёт транспорт после 120 секунд без завершённой проверки активности длительного опроса по умолчанию.
- `openclaw channels status --probe` и `openclaw doctor` предупреждают, если работающая учётная запись с опросом не завершила `getUpdates` после льготного периода запуска, работающая учётная запись с Webhook не завершила `setWebhook` после льготного периода запуска либо последняя успешная активность транспорта опроса устарела.
- Увеличивайте `channels.telegram.pollingStallThresholdMs` только тогда, когда длительные вызовы `getUpdates` работают корректно, но хост по-прежнему сообщает о ложных перезапусках из-за зависания опроса. Постоянные зависания обычно указывают на проблемы прокси, DNS, IPv6 или исходящего TLS-соединения с `api.telegram.org`.
- Telegram учитывает переменные окружения прокси процесса для транспорта Bot API: `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` и варианты в нижнем регистре. `NO_PROXY` / `no_proxy` по-прежнему могут обходить `api.telegram.org`.
- Если для служебной среды задан `OPENCLAW_PROXY_URL`, а стандартные переменные окружения прокси отсутствуют, Telegram также использует этот URL для транспорта Bot API.
- На VPS-хостах с нестабильным прямым исходящим соединением или TLS направьте вызовы API Telegram через прокси:
```yaml
channels:
telegram:
proxy: socks5://:@proxy-host:1080
```
- Node 22+ по умолчанию использует `autoSelectFamily=true` (кроме WSL2). Порядок результатов DNS для Telegram учитывает сначала `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, затем `channels.telegram.network.dnsResultOrder`, а затем значение процесса по умолчанию (например, `NODE_OPTIONS=--dns-result-order=ipv4first`); если ни одно из них не применимо, в Node 22+ используется резервное значение `ipv4first`.
- В WSL2 или когда лучше работает режим только IPv4 принудительно задайте выбор семейства адресов:
```yaml
channels:
telegram:
network:
autoSelectFamily: false
```
- Ответы из диапазона для тестирования производительности RFC 2544 (`198.18.0.0/15`) уже по умолчанию разрешены для загрузки медиафайлов Telegram. Если доверенный прокси-сервер с подменой IP-адресов или прозрачный прокси-сервер при загрузке медиафайлов перенаправляет `api.telegram.org` на другой частный, внутренний или специальный адрес, включите обход только для Telegram:
```yaml
channels:
telegram:
network:
dangerouslyAllowPrivateNetwork: true
```
- Такую же возможность можно включить для отдельной учётной записи в `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`.
- Если ваш прокси-сервер разрешает имена хостов медиафайлов Telegram в `198.18.x.x`, сначала оставьте опасный флаг выключенным — этот диапазон уже разрешён по умолчанию.
`channels.telegram.network.dangerouslyAllowPrivateNetwork` ослабляет защиту от SSRF при работе с медиафайлами Telegram. Используйте его только в доверенных, контролируемых оператором прокси-средах (маршрутизация с подменой IP-адресов в Clash, Mihomo, Surge), которые создают ответы с частными или специальными адресами за пределами диапазона для тестирования производительности RFC 2544. Для обычного доступа к Telegram через общедоступный интернет оставьте его выключенным.
- Временные переопределения через переменные окружения: `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`, `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`, `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`.
- Проверьте ответы DNS:
```bash
dig +short api.telegram.org A
dig +short api.telegram.org AAAA
```
Дополнительная помощь: [Устранение неполадок каналов](/ru/channels/troubleshooting).
## Справочник по конфигурации
Основной справочник: [Справочник по конфигурации — Telegram](/ru/gateway/config-channels#telegram).
- запуск/аутентификация: `enabled`, `botToken`, `tokenFile` (должен быть обычным файлом; символьные ссылки отклоняются), `accounts.*`
- управление доступом: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхнеуровневый `bindings[]` (`type: "acp"`)
- значения тем по умолчанию: `groups..topics."*"` применяется к темам форума без совпадений; точные идентификаторы тем имеют приоритет
- подтверждения выполнения: `execApprovals`, `accounts.*.execApprovals`
- команды/меню: `commands.native`, `commands.nativeSkills`, `customCommands`
- ветки/ответы: `replyToMode`, `threadBindings`
- потоковая передача: `streaming` (режимы `off | partial | block | progress`), `streaming.preview.toolProgress`
- форматирование/доставка: `textChunkLimit`, `streaming.chunkMode`, `richMessages`, `markdown.tables` (`off | bullets | code | block`), `linkPreview`, `responsePrefix`
- медиафайлы/сеть: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
- пользовательский корневой адрес API: `apiRoot` (только корневой адрес Bot API; не включайте `/bot`), `trustedLocalFileRoots` (абсолютные корневые адреса `file_path` самостоятельно размещённого Bot API)
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`, `webhookPort`, `webhookCertPath`
- действия/возможности: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker|createForumTopic|editForumTopic`
- реакции: `reactionNotifications`, `reactionLevel`
- ошибки: `errorPolicy`, `errorCooldownMs`, `silentErrorReplies`
- запись/история: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
Приоритет нескольких учётных записей: если настроено два или более идентификатора учётных записей, задайте `channels.telegram.defaultAccount` (или включите `channels.telegram.accounts.default`), чтобы явно указать маршрутизацию по умолчанию. В противном случае OpenClaw использует первый нормализованный идентификатор учётной записи, а `openclaw doctor` выводит предупреждение. Именованные учётные записи наследуют `channels.telegram.allowFrom` / `groupAllowFrom`, но не значения `accounts.default.*`.
## Связанные разделы
Сопрягите пользователя Telegram с Gateway.
Поведение списков разрешений для групп и тем.
Направляйте входящие сообщения агентам.
Модель угроз и усиление защиты.
Сопоставляйте группы и темы с агентами.
Диагностика для разных каналов.