Telegram

По умолчанию для ботов Telegram включён Privacy Mode, ограничивающий получение сообщений из групп.

Чтобы получать все сообщения группы:

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

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

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

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

Те же настройки доступны в веб-приложении BotFather, если вы предпочитаете интерфейс командам чата.

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+).

Сохранить редактирование предпросмотра ответа, но скрыть строки хода выполнения инструментов:

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "toolProgress": false }      }    }  }}

Сохранить отображение хода выполнения инструментов, но скрыть текст команд и их выполнения:

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "commandText": "status" }      }    }  }}

Режим progress показывает ход выполнения инструментов, не вставляя окончательный ответ в это сообщение путём редактирования. Разместите политику текста команд в streaming.progress:

{  "channels": {    "telegram": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

streaming.mode: "off" отключает редактирование предпросмотра и подавляет общие сообщения инструментов и хода выполнения вместо их отправки как отдельных сообщений состояния; запросы подтверждения, медиафайлы и ошибки по-прежнему передаются через обычную доставку окончательного ответа. streaming.preview.toolProgress: false сохраняет только редактирование предпросмотра ответа.

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

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

Рассуждения: /reasoning stream передаёт рассуждения в потоковом режиме в предварительный просмотр в реальном времени во время генерации, а после доставки окончательного ответа удаляет предпросмотр рассуждений (используйте /reasoning on, чтобы оставить его видимым). Окончательный ответ отправляется без текста рассуждений.

По умолчанию исходящий текст использует стандартные HTML-сообщения Telegram, доступные для чтения в актуальных клиентах: полужирный шрифт, курсив, ссылки, код, скрытый текст, цитаты — без расширенных блоков, доступных только в Bot API 10.1 (встроенные таблицы, подробности, расширенные медиафайлы, формулы).

Включить расширенные сообщения Bot API 10.1:

{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.

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

{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<TOKEN>. apiRoot должен содержать только корневой адрес Bot API; openclaw doctor --fix удаляет случайно добавленный в конце /bot<TOKEN>.
• 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 <requestId>, /pair approve (единственный ожидающий запрос) или /pair approve latest

Если устройство повторяет попытку с изменёнными данными аутентификации (ролью, областями доступа, открытым ключом), предыдущий ожидающий запрос заменяется новым requestId; перед подтверждением снова выполните /pair pending.

Подробнее: Сопряжение.

Настройка области действия встроенной клавиатуры:

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

Переопределение для отдельной учётной записи:

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

Области действия: off, dm, group, all, allowlist (по умолчанию). Устаревшее значение capabilities: ["inlineButtons"] сопоставляется с "all".

Пример действия с сообщением:

{action: "send",channel: "telegram",to: "123456789",message: "Выберите вариант:",buttons: [[  { text: "Да", callback_data: "yes" },  { text: "Нет", callback_data: "no" },],[{ text: "Отмена", callback_data: "cancel" }],],}

Пример кнопки Mini App:

{action: "send",channel: "telegram",to: "123456789",message: "Открыть приложение:",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "Запустить", web_app: { url: "https://example.com/app" } }],  },],},}

Кнопки web_app работают только в личных чатах между пользователем и ботом.

Нажатия кнопок обратного вызова, не обработанные зарегистрированным интерактивным обработчиком плагина, передаются агенту как текст: callback_data: <value>.

Действия:

• 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.

Явные теги веток ответов в сгенерированном выводе:

• [[reply_to_current]] — ответ на сообщение, запустившее обработку
• [[reply_to:<id>]] — ответ на сообщение с указанным идентификатором

channels.telegram.replyToMode: off (по умолчанию), first, all.

Когда ветки ответов включены и исходный текст или подпись доступны, OpenClaw автоматически добавляет нативную цитату. Telegram ограничивает текст нативной цитаты 1024 кодовыми единицами UTF-16; в более длинных сообщениях цитируется начало, а если Telegram отклоняет цитату, используется обычный ответ.

off отключает только неявные ветки ответов; явные теги [[reply_to_*]] по-прежнему учитываются.

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

Общая тема (threadId=1) — особый случай: при отправке сообщений message_thread_id опускается (Telegram отклоняет sendMessage(...thread_id=1) с сообщением «ветка не найдена»), но действия набора текста всё равно включают message_thread_id (как показывает практика, это необходимо для появления индикатора набора).

Записи тем наследуют настройки группы, если они не переопределены (requireMention, allowFrom, skills, systemPrompt, enabled, groupPolicy). agentId применяется только к теме и не наследуется из настроек группы по умолчанию. topics."*" задаёт значения по умолчанию для всех тем этой группы; точные идентификаторы тем по-прежнему имеют приоритет над "*".

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

{  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.

Запуск ACP из чата с привязкой к ветке: /acp spawn <agent> --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]] в ответ агента, чтобы принудительно отправить голосовое сообщение. Расшифровки входящих голосовых сообщений передаются в контекст агента как машинно созданный недоверенный текст, но обнаружение упоминаний по-прежнему использует необработанную расшифровку, поэтому голосовые сообщения, требующие упоминания, продолжают работать.

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

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

Telegram различает видеофайлы и видеосообщения. Видеосообщения не поддерживают подписи; указанный текст сообщения отправляется отдельно.

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

Местоположения и места

Используйте существующее действие send с одним отдельным объектом location. Координаты отправляют нативную отметку на карте; добавление одновременно name и address отправляет нативную карточку места. Отправку местоположения нельзя объединять с текстом сообщения или медиафайлом.

{action: "send",channel: "telegram",to: "123456789",location: {latitude: 48.858844,longitude: 2.294351,accuracy: 12,name: "Эйфелева башня",address: "Марсово поле, Париж",},}

Стикеры

Входящие данные: статические файлы WEBP скачиваются и обрабатываются (заполнитель <media:sticker>); анимированные TGS и видео WEBM пропускаются.

Поля контекста стикера: Sticker.emoji, Sticker.setName, Sticker.fileId, Sticker.fileUniqueId, Sticker.cachedDescription. Описания кэшируются в состоянии плагина OpenClaw в SQLite, чтобы сократить количество повторных вызовов компьютерного зрения.

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

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

Отправка:

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

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

{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.<accountId>.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 (отключено).

Запись конфигурации канала включена по умолчанию (configWrites !== false). К операциям записи, инициированным Telegram, относятся события миграции групп (migrate_to_chat_id, обновляет channels.telegram.groups) и /config set / /config unset (требуется включить команды).

Отключение:

{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["<user_id>"].historyLimit.
• channels.telegram.retry применяется к вспомогательным средствам отправки Telegram (CLI/инструменты/действия) при устранимых ошибках исходящего API. Для доставки окончательного ответа на входящее сообщение используется ограниченное число безопасных повторных попыток при сбоях до подключения, но неоднозначные сетевые результаты после отправки не повторяются, поскольку это может привести к дублированию видимых сообщений.

Цели отправки CLI и инструмента сообщений принимают числовой идентификатор чата, имя пользователя или цель темы форума:

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 и поддерживают темы форума:

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: разрешаются через подтверждения плагинов; остальные сначала разрешаются через подтверждения выполнения команд.

См. Подтверждения выполнения команд.

• Если 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.<id>.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 через прокси-сервер:

channels:telegram:proxy: socks5://<user>:<password>@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 принудительно задайте выбор семейства адресов:

channels:telegram:network:  autoSelectFamily: false

• Ответы из тестового диапазона RFC 2544 (198.18.0.0/15) уже по умолчанию разрешены для скачивания медиафайлов Telegram. Если во время скачивания медиафайлов доверенный прокси-сервер с подменой IP-адресов или прозрачный прокси-сервер заменяет api.telegram.org каким-либо другим частным, внутренним или специальным адресом, явно включите обход только для Telegram:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• Такое же явное включение доступно для каждой учётной записи в channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Если ваш прокси-сервер разрешает имена хостов медиафайлов Telegram в 198.18.x.x, сначала не включайте опасный флаг — этот диапазон уже разрешён по умолчанию.

• Временные переопределения через переменные окружения: OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1, OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first.
• Проверьте ответы DNS:

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