Telegram

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

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

• отключите режим конфиденциальности через /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.2 (нативные таблицы, подробности, расширенные медиа, формулы).

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

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

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

{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" }],],}

Пример кнопки мини-приложения:

{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: <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 означает, что нативное меню содержит слишком много пунктов; сократите количество команд плагинов, навыков или пользовательских команд либо отключите нативные меню.
• Вызовы запуска deleteMyCommands / setMyCommands и вызовы индикатора набора sendChatAction ограничены по времени и при тайм-ауте запроса повторяются один раз через резервный транспорт Telegram. Постоянные ошибки сети или fetch обычно означают, что api.telegram.org недоступен по DNS/HTTPS.

• getMe returned 401 — это ошибка аутентификации Telegram для настроенного токена бота. Повторно скопируйте или сгенерируйте токен в BotFather, затем обновите channels.telegram.botToken, tokenFile, accounts.<id>.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 через прокси:

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