--- read_when: - Работа над функциями Telegram или вебхуками summary: Статус поддержки, возможности и настройка бота Telegram title: Telegram x-i18n: generated_at: "2026-07-13T19:32:25Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 8aa81fb0a1bc2953305591f5b616e5caebfee24c5fab04737c5e2eaa02be4559 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 включён **Privacy Mode**, ограничивающий получение сообщений из групп. Чтобы получать все сообщения группы: - отключите режим конфиденциальности через `/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`. Маршрутизация тем личных чатов теперь следует данным Telegram `getMe.has_topics_enabled` (управляется режимом потоков 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.1 (встроенные таблицы, подробности, расширенные медиафайлы, формулы). Включить расширенные сообщения Bot API 10.1: ```json5 { channels: { telegram: { richMessages: true, }, }, } ``` Когда эта функция включена: агенту сообщается, что для данного бота или учётной записи доступны расширенные сообщения; текст Markdown преобразуется через Markdown IR OpenClaw в расширенный HTML Telegram; явные полезные нагрузки расширенного HTML сохраняют поддерживаемые теги Bot API 10.1 (заголовки, таблицы, подробности, расширенные медиафайлы, формулы); подписи к медиафайлам по-прежнему используют 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" }], ], } ``` Пример кнопки Mini App: ```json5 { action: "send", channel: "telegram", to: "123456789", message: "Открыть приложение:", presentation: { blocks: [ { type: "buttons", buttons: [{ label: "Запустить", web_app: { url: "https://example.com/app" } }], }, ], }, } ``` Кнопки `web_app` работают только в личных чатах между пользователем и ботом. Нажатия кнопок обратного вызова, не обработанные зарегистрированным интерактивным обработчиком плагина, передаются агенту как текст: `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` означает, что встроенное меню содержит слишком много элементов; сократите количество команд плагинов, Skills или пользовательских команд либо отключите встроенные меню. - Вызовы запуска `deleteMyCommands` / `setMyCommands` и вызовы индикатора набора `sendChatAction` ограничены по времени и при превышении времени ожидания запроса повторяются один раз через резервный транспорт Telegram. Постоянные ошибки сети или получения данных обычно означают, что DNS/HTTPS-доступ к `api.telegram.org` отсутствует. - `getMe returned 401` — это ошибка аутентификации Telegram для настроенного токена бота. Снова скопируйте или создайте токен в BotFather, затем обновите `channels.telegram.botToken`, `tokenFile`, `accounts..botToken` или `TELEGRAM_BOT_TOKEN` (учётная запись по умолчанию). - `deleteWebhook 401 Unauthorized` во время запуска также является ошибкой аутентификации; интерпретация её как «Webhook отсутствует» лишь отложит ту же ошибку неверного токена до последующего вызова API. - Node 22+ с пользовательской реализацией получения данных или прокси-сервером может вызвать немедленное прерывание, если типы `AbortSignal` не совпадают. - Некоторые серверы сначала разрешают `api.telegram.org` в IPv6; неисправный исходящий IPv6-трафик вызывает периодические сбои API. - Ошибки в журналах с `TypeError: fetch failed` или `Network request for 'getUpdates' failed!` повторяются как устранимые сетевые ошибки. - При запуске опроса OpenClaw повторно использует успешную стартовую проверку `getMe` для grammY, чтобы среде выполнения не требовался второй `getMe` перед первым `getUpdates`. - Если `deleteWebhook` завершается с временной сетевой ошибкой при запуске опроса, OpenClaw переходит к длительному опросу вместо выполнения ещё одного вызова плоскости управления перед опросом. Если 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` - пользовательский корневой URL API: `apiRoot` (только корневой URL Bot API; не включайте `/bot`), `trustedLocalFileRoots` (абсолютные корневые URL `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. Поведение списков разрешённых групп и тем. Направляйте входящие сообщения агентам. Модель угроз и усиление защиты. Сопоставляйте группы и темы с агентами. Диагностика разных каналов.