Telegram

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

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

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

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

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

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

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

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

• прямые чаты: сообщение предпросмотра + editMessageText
• группы/темы: сообщение предпросмотра + editMessageText

Требование:

• channels.telegram.streaming — off | partial | block | progress (по умолчанию: partial)
• короткие начальные предпросмотры ответа подавляются debounce, затем материализуются после ограниченной задержки, если запуск все еще активен
• progress сохраняет один редактируемый черновик статуса для хода выполнения инструментов, показывает стабильную метку статуса, когда активность ответа приходит до хода выполнения инструментов, очищает его при завершении и отправляет финальный ответ как обычное сообщение
• streaming.preview.toolProgress управляет тем, используют ли обновления инструментов/прогресса то же редактируемое сообщение предпросмотра (по умолчанию: true, когда активна потоковая передача предпросмотра)
• streaming.preview.commandText управляет деталями command/exec внутри этих строк прогресса инструмента: raw (по умолчанию, сохраняет поведение выпущенной версии) или status (только метка инструмента)
• streaming.progress.commentary (по умолчанию: false) включает текст комментария/преамбулы ассистента во временном черновике прогресса
• устаревшие channels.telegram.streamMode, булевы значения streaming и выведенные из использования ключи нативного черновика предпросмотра обнаруживаются; запустите openclaw doctor --fix, чтобы перенести их в текущую конфигурацию потоковой передачи

Обновления предпросмотра прогресса инструмента — это короткие строки статуса, показываемые во время выполнения инструментов, например выполнение команд, чтение файлов, обновления планирования, сводки патчей или текст преамбулы/комментариев Codex в режиме Codex app-server. Telegram оставляет их включенными по умолчанию, чтобы соответствовать поведению OpenClaw, выпущенному в v2026.4.22 и позже.

Чтобы оставить редактируемый предпросмотр для текста ответа, но скрыть строки прогресса инструмента, задайте:

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

Чтобы оставить прогресс инструмента видимым, но скрыть текст command/exec, задайте:

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

Используйте режим progress, когда хотите видеть прогресс инструмента без редактирования финального ответа в то же сообщение. Поместите политику текста команд в streaming.progress:

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

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

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

• короткие предпросмотры DM/группы/темы: OpenClaw сохраняет то же сообщение предпросмотра и выполняет финальную правку на месте
• длинные финальные тексты, разбиваемые на несколько сообщений Telegram, по возможности повторно используют существующий предпросмотр как первый финальный фрагмент, затем отправляют только оставшиеся фрагменты
• финальные ответы в режиме progress очищают черновик статуса и используют обычную финальную доставку вместо редактирования черновика в ответ
• если финальная правка завершается ошибкой до подтверждения завершенного текста, OpenClaw использует обычную финальную доставку и очищает устаревший предпросмотр

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

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

Поведение потока рассуждений:

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

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

Задайте channels.telegram.richMessages: true, чтобы включить расширенные сообщения Bot API 10.1:

{channels: {telegram: {  richMessages: true,},},}

Когда включено:

• Агенту сообщается, что расширенные сообщения Telegram доступны для этого бота/аккаунта.
• Текст Markdown рендерится через Markdown IR OpenClaw и отправляется как расширенный HTML Telegram.
• Явные расширенные HTML-payload сохраняют поддерживаемые теги Bot API 10.1, такие как заголовки, таблицы, подробности, расширенные медиа и формулы.
• Подписи к медиа все еще используют HTML-подписи Telegram, потому что расширенные сообщения не заменяют подписи.

Это удерживает текст модели от сигилов Telegram Rich Markdown, поэтому суммы вроде $400-600K не разбираются как математика. Длинный расширенный текст автоматически разделяется с учетом лимитов Telegram на расширенный текст и расширенные блоки. Таблицы, превышающие лимит Telegram по столбцам, отправляются как блоки кода.

По умолчанию: выключено для совместимости клиентов. Расширенные сообщения требуют совместимых клиентов Telegram; некоторые актуальные клиенты Desktop, Web, Android и сторонние клиенты отображают принятые расширенные сообщения как неподдерживаемые. Оставляйте эту опцию отключенной, если каждый клиент, используемый с ботом, не может их отобразить. /status показывает, включены или выключены расширенные сообщения для текущего сеанса Telegram.

Предпросмотры ссылок включены по умолчанию. channels.telegram.linkPreview: false пропускает автоматическое обнаружение сущностей для расширенного текста.

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

Значения нативных команд по умолчанию:

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

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

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

Правила:

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

Примечания:

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

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

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

• setMyCommands failed с BOT_COMMANDS_TOO_MUCH означает, что меню Telegram все еще переполнилось после обрезки; сократите команды plugin/skill/пользовательские команды или отключите channels.telegram.commands.native.
• Сбой deleteWebhook, deleteMyCommands или setMyCommands с 404: Not Found, когда прямые команды curl к Bot API работают, может означать, что channels.telegram.apiRoot был задан как полный endpoint /bot<TOKEN>. apiRoot должен быть только корнем Bot API, а openclaw doctor --fix удаляет случайный хвостовой /bot<TOKEN>.
• getMe returned 401 означает, что Telegram отклонил настроенный токен бота. Обновите botToken, tokenFile или TELEGRAM_BOT_TOKEN текущим токеном BotFather; OpenClaw останавливается до polling, поэтому это не сообщается как ошибка очистки webhook.
• setMyCommands failed с сетевыми/fetch-ошибками обычно означает, что исходящие DNS/HTTPS к api.telegram.org заблокированы.

Команды сопряжения устройств (plugin device-pair)

Когда plugin device-pair установлен:

1. /pair генерирует код настройки
2. вставьте код в приложение iOS
3. /pair pending перечисляет ожидающие запросы (включая роль/области доступа)
4. подтвердите запрос:
   • /pair approve <requestId> для явного подтверждения
   • /pair approve, когда есть только один ожидающий запрос
   • /pair approve latest для самого последнего

Код настройки содержит короткоживущий bootstrap-токен. Встроенный bootstrap кода настройки возвращает долговечный токен узла с scopes: [] плюс ограниченный токен передачи управления оператору для доверенного мобильного онбординга. Этот токен оператора может читать нативную конфигурацию во время настройки, но не предоставляет области доступа для мутации сопряжения или operator.admin.

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

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

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

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

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

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

Области действия:

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

Устаревшее capabilities: ["inlineButtons"] сопоставляется с inlineButtons: "all".

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

{action: "send",channel: "telegram",to: "123456789",message: "Choose an option:",buttons: [[  { text: "Yes", callback_data: "yes" },  { text: "No", callback_data: "no" },],[{ text: "Cancel", callback_data: "cancel" }],],}

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

{action: "send",channel: "telegram",to: "123456789",message: "Open app:",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "Launch", web_app: { url: "https://example.com/app" } }],  },],},}

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

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

Действия инструмента Telegram включают:

• 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
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (по умолчанию: отключено)

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

Семантика удаления реакций: /tools/reactions

Telegram поддерживает явные теги цепочек ответов в сгенерированном выводе:

• [[reply_to_current]] отвечает на вызвавшее сообщение
• [[reply_to:<id>]] отвечает на конкретный ID сообщения Telegram

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

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

Когда цепочки ответов включены и исходный текст или подпись Telegram доступны, OpenClaw автоматически включает фрагмент нативной цитаты Telegram. 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."*" задает значения по умолчанию для каждой темы в этой группе; точные ID тем все равно имеют приоритет над "*".

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

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

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

Постоянная привязка тем ACP: форумные темы могут закреплять сессии ACP harness через типизированные привязки ACP верхнего уровня (bindings[] с type: "acp" и match.channel: "telegram", peer.kind: "group" и квалифицированным по теме ID, например -1001234567890:topic:42). Сейчас область действия ограничена форумными темами в группах/супергруппах. См. Агенты ACP.

Запуск ACP, привязанный к цепочке, из чата: /acp spawn <agent> --thread here|auto привязывает текущую тему к новой сессии ACP; последующие сообщения маршрутизируются туда напрямую. OpenClaw закрепляет подтверждение запуска внутри темы. Требуется, чтобы channels.telegram.threadBindings.spawnSessions оставался включенным (по умолчанию: true).

Контекст шаблона предоставляет MessageThreadId и IsForum. DM-чаты с 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,}

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

Стикеры

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

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

Поля контекста стикера:

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

Описания стикеров кэшируются в состоянии Plugin SQLite OpenClaw, чтобы сократить повторные вызовы vision.

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

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

Действие отправки стикера:

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

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

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

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

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

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

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

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

Примечания:

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

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

ackReaction отправляет emoji подтверждения, пока OpenClaw обрабатывает входящее сообщение. ackReactionScope определяет, когда этот emoji фактически отправляется.

Порядок разрешения emoji (ackReaction):

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

Примечания:

• Telegram ожидает unicode emoji (например, "👀").
• Используйте "", чтобы отключить реакцию для канала или аккаунта.

Область действия (messages.ackReactionScope):

Провайдер Telegram читает область действия из messages.ackReactionScope (по умолчанию "group-mentions"). На сегодня переопределения на уровне аккаунта Telegram или канала 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,},},}

По умолчанию используется long polling. Для режима webhook задайте channels.telegram.webhookUrl и channels.telegram.webhookSecret; необязательные webhookPath, webhookHost, webhookPort (по умолчанию /telegram-webhook, 127.0.0.1, 8787).

В режиме long polling OpenClaw сохраняет свой watermark перезапуска только после успешной отправки обновления. Если обработчик завершается ошибкой, это обновление остается доступным для повтора в том же процессе и не записывается как завершенное для дедупликации при перезапуске.

Локальный слушатель привязывается к 127.0.0.1:8787. Для публичного входящего трафика либо поместите reverse proxy перед локальным портом, либо намеренно задайте webhookHost: "0.0.0.0".

Режим Webhook проверяет request guards, секретный токен Telegram и тело JSON перед возвратом 200 в Telegram. Затем OpenClaw обрабатывает обновление асинхронно через те же bot lanes для каждого чата/темы, которые используются long polling, поэтому медленные ходы агента не удерживают delivery ACK Telegram.

• Значение channels.telegram.textChunkLimit по умолчанию — 4000.
• channels.telegram.chunkMode="newline" предпочитает границы абзацев (пустые строки) перед разделением по длине.
• channels.telegram.mediaMaxMb (по умолчанию 100) ограничивает размер входящих и исходящих медиа Telegram.
• channels.telegram.mediaGroupFlushMs (по умолчанию 500) управляет тем, как долго альбомы/медиагруппы Telegram буферизуются перед тем, как OpenClaw отправит их как одно входящее сообщение. Увеличьте значение, если части альбома приходят с задержкой; уменьшите его, чтобы снизить задержку ответа на альбом.
• channels.telegram.timeoutSeconds переопределяет тайм-аут клиента Telegram API (если не задано, применяется значение grammY по умолчанию). Клиенты бота ограничивают настроенные значения ниже 60-секундного ограничения исходящих запросов текста/индикатора ввода, чтобы grammY не прервал доставку видимого ответа до того, как смогут сработать транспортное ограничение и fallback OpenClaw. Long polling по-прежнему использует 45-секундное ограничение запроса getUpdates, чтобы простаивающие опросы не оставались брошенными бессрочно.
• channels.telegram.pollingStallThresholdMs по умолчанию равно 120000; настраивайте в диапазоне от 30000 до 600000 только при ложноположительных перезапусках из-за зависания polling.
• история контекста группы использует channels.telegram.historyLimit или messages.groupChat.historyLimit (по умолчанию 50); 0 отключает.
• дополнительный контекст ответа/цитаты/пересылки нормализуется в одно выбранное окно контекста беседы, когда Gateway наблюдал родительские сообщения; кэш наблюдаемых сообщений хранится в состоянии Plugin в SQLite OpenClaw, а openclaw doctor --fix импортирует устаревшие sidecar-файлы. Telegram включает в обновления только один неглубокий reply_to_message, поэтому цепочки старше кэша ограничены текущей полезной нагрузкой обновления Telegram.
• allowlist Telegram в первую очередь ограничивают, кто может запускать агента, а не являются полноценной границей редактирования дополнительного контекста.
• элементы управления историей личных сообщений:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• конфигурация channels.telegram.retry применяется к помощникам отправки Telegram (CLI/инструменты/действия) для восстанавливаемых исходящих ошибок API. Доставка финального входящего ответа также использует ограниченную безопасную повторную отправку при сбоях Telegram до подключения, но не повторяет неоднозначные сетевые оболочки после отправки, которые могут продублировать видимые сообщения.

Цели отправки CLI и message-tool могут быть числовым ID чата, именем пользователя или целью темы форума:

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"

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

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

Флаги опросов только для Telegram:

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

Отправка Telegram также поддерживает:

• --presentation с блоками buttons для встроенных клавиатур, когда это разрешает channels.telegram.capabilities.inlineButtons
• --pin или --delivery '{"pin":true}', чтобы запросить закрепленную доставку, когда бот может закреплять сообщения в этом чате
• --force-document, чтобы отправлять исходящие изображения, GIF и видео как документы вместо сжатых фото, анимированных медиа или видео-загрузок

Ограничение действий:

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

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

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

• channels.telegram.execApprovals.enabled (автоматически включается, когда можно разрешить хотя бы одного утверждающего)
• channels.telegram.execApprovals.approvers (использует числовые ID владельцев из commands.ownerAllowFrom как fallback)
• channels.telegram.execApprovals.target: dm (по умолчанию) | channel | both
• agentFilter, sessionFilter

channels.telegram.allowFrom, groupAllowFrom и defaultTo управляют тем, кто может общаться с ботом и куда он отправляет обычные ответы. Они не делают кого-либо утверждающим exec. Первое одобренное сопряжение через личные сообщения начально заполняет commands.ownerAllowFrom, когда владелец команд еще не существует, поэтому настройка с одним владельцем по-прежнему работает без дублирования ID в execApprovals.approvers.

Доставка в канал показывает текст команды в чате; включайте channel или both только в доверенных группах/темах. Когда запрос попадает в тему форума, OpenClaw сохраняет тему для запроса подтверждения и последующего сообщения. Подтверждения exec по умолчанию истекают через 30 минут.

Кнопки встроенного подтверждения также требуют, чтобы channels.telegram.capabilities.inlineButtons разрешал целевую поверхность (dm, group или all). ID подтверждений с префиксом plugin: разрешаются через подтверждения Plugin; остальные сначала разрешаются через подтверждения exec.

См. Подтверждения exec.

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

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

• авторизуйте идентификатор отправителя (сопряжение и/или числовой allowFrom)
• авторизация команд по-прежнему применяется, даже когда политика группы — open
• setMyCommands failed с BOT_COMMANDS_TOO_MUCH означает, что в нативном меню слишком много пунктов; уменьшите число команд Plugin/skill/пользовательских команд или отключите нативные меню
• стартовые вызовы deleteMyCommands / setMyCommands и вызовы индикатора ввода sendChatAction ограничены и повторяются один раз через транспортный fallback Telegram при тайм-ауте запроса. Постоянные сетевые ошибки/fetch обычно указывают на проблемы доступности DNS/HTTPS до api.telegram.org

• getMe returned 401 — это сбой аутентификации Telegram для настроенного токена бота.
• Снова скопируйте или заново сгенерируйте токен бота в BotFather, затем обновите channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken или TELEGRAM_BOT_TOKEN для учетной записи по умолчанию.
• deleteWebhook 401 Unauthorized во время запуска — тоже сбой аутентификации; трактовка этого как «webhook не существует» только отложила бы тот же сбой из-за плохого токена до последующих вызовов API.

• Node 22+ и пользовательский fetch/proxy могут вызывать немедленное прерывание, если типы AbortSignal не совпадают.
• Некоторые хосты сначала разрешают api.telegram.org в IPv6; неработающий исходящий IPv6 может вызывать периодические сбои Telegram API.
• Если логи содержат TypeError: fetch failed или Network request for 'getUpdates' failed!, OpenClaw теперь повторяет их как восстанавливаемые сетевые ошибки.
• Во время запуска polling OpenClaw повторно использует успешную стартовую проверку getMe для grammY, поэтому runner не нуждается во втором getMe перед первым getUpdates.
• Если deleteWebhook завершается временной сетевой ошибкой во время запуска polling, OpenClaw переходит к long polling вместо выполнения еще одного управляющего вызова перед polling. Все еще активный webhook проявляется как конфликт getUpdates; затем OpenClaw пересоздает транспорт Telegram и повторяет очистку webhook.
• Если сокеты Telegram пересоздаются по короткому фиксированному интервалу, проверьте низкое значение channels.telegram.timeoutSeconds; клиенты бота ограничивают настроенные значения ниже ограничений исходящих запросов и запросов getUpdates, но более старые выпуски могли прерывать каждый polling или ответ, когда это значение было установлено ниже этих ограничений.
• Если логи содержат Polling stall detected, OpenClaw перезапускает polling и пересоздает транспорт Telegram после 120 секунд без завершенной проверки живости long-poll по умолчанию.
• openclaw channels status --probe и openclaw doctor предупреждают, когда работающая учетная запись polling не завершила getUpdates после стартового grace-периода, когда работающая учетная запись webhook не завершила setWebhook после стартового grace-периода или когда последняя успешная активность транспорта polling устарела.
• Увеличивайте channels.telegram.pollingStallThresholdMs только когда долгие вызовы getUpdates исправны, но ваш хост все еще сообщает о ложных перезапусках из-за зависания polling. Постоянные зависания обычно указывают на проблемы proxy, DNS, IPv6 или исходящего TLS между хостом и api.telegram.org.
• Telegram также учитывает переменные окружения proxy процесса для транспорта Bot API, включая HTTP_PROXY, HTTPS_PROXY, ALL_PROXY и их варианты в нижнем регистре. NO_PROXY / no_proxy все еще могут обходить api.telegram.org.
• Если управляемый proxy OpenClaw настроен через OPENCLAW_PROXY_URL для сервисного окружения и стандартные переменные окружения proxy отсутствуют, Telegram также использует этот URL для транспорта Bot API.
• На VPS-хостах с нестабильным прямым исходящим соединением/TLS маршрутизируйте вызовы Telegram API через channels.telegram.proxy:

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 по умолчанию. Если доверенный fake-IP или прозрачный прокси переписывает api.telegram.org на какой-либо другой частный/внутренний/специальный адрес во время загрузок медиа, можно явно включить обход только для Telegram:

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

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

• Переопределения через окружение (временные):
  • 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