Telegram

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

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

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

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

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

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

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

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

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

Требование:

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

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

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

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

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

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

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

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

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

Для ответов только с текстом:

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

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

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

Поведение потока reasoning:

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

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

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

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

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

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

Это удерживает текст модели подальше от сигилов Telegram Rich Markdown, поэтому суммы вроде $400-600K не разбираются как математика. Длинный насыщенный текст автоматически разделяется по лимитам насыщенного текста и rich block 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/Skills все еще могут работать при вводе, даже если они не показаны в меню Telegram

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

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

• setMyCommands failed с BOT_COMMANDS_TOO_MUCH означает, что меню Telegram все еще переполнено после обрезки; уменьшите число команд Plugin/Skills/пользовательских команд или отключите 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 с ошибками network/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 по коду настройки предназначен только для узлов: первое подключение создает ожидающий запрос узла, а после подтверждения Gateway возвращает долговечный токен узла с scopes: []. Он не возвращает переданный токен оператора; доступ оператора требует отдельного подтвержденного сопряжения оператора или потока токена.

Если устройство повторяет попытку с измененными деталями аутентификации (например, ролью/областями/публичным ключом), предыдущий ожидающий запрос заменяется, а новый запрос использует другой 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 передаются агенту как текст: 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" },      // Общая тема → основной агент            "3": { agentId: "zu" },        // Тема разработки → агент zu            "5": { agentId: "coder" }      // Проверка кода → агент coder          }        }      }    }  }}

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

Постоянная привязка темы ACP: Темы форума могут закреплять сессии обвязки 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,}

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

Стикеры

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

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

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

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

Описания стикеров кэшируются в состоянии Plugin OpenClaw SQLite, чтобы сократить повторные вызовы 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 не предоставляет идентификаторы тем в обновлениях реакций.
  • группы без форумов направляются в сеанс группового чата
  • группы с форумами направляются в сеанс общей темы группы (: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,},},}

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

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

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

Режим Webhook проверяет защитные условия запроса, секретный токен Telegram и тело JSON перед возвратом 200 в Telegram. Затем OpenClaw обрабатывает обновление асинхронно через те же дорожки бота для каждого чата/темы, что используются длинным опросом, поэтому медленные ходы агента не задерживают 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 не прерывал доставку видимого ответа до того, как сработают транспортная защита и резервный механизм 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 для inline-клавиатур, когда 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 как запасной вариант)
• 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 минут.

Inline-кнопки одобрения также требуют, чтобы 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 ограничены по времени и повторяются один раз через транспортный резерв 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 вместо еще одного pre-poll вызова control plane. Все еще активный webhook проявляется как конфликт getUpdates; затем OpenClaw пересоздает транспорт Telegram и повторяет очистку webhook.
• Если сокеты Telegram пересоздаются с коротким фиксированным интервалом, проверьте низкое значение channels.telegram.timeoutSeconds; клиенты бота ограничивают настроенные значения ниже защитных ограничений исходящих запросов и getUpdates, но более старые выпуски могли прерывать каждый poll или ответ, когда это значение было задано ниже этих ограничений.
• Если журналы содержат Polling stall detected, OpenClaw перезапускает polling и пересоздает транспорт Telegram после 120 секунд без завершенной проверки работоспособности long-poll по умолчанию.
• openclaw channels status --probe и openclaw doctor предупреждают, когда запущенный polling-аккаунт не завершил getUpdates после льготного периода запуска, когда запущенный webhook-аккаунт не завершил setWebhook после льготного периода запуска или когда последняя успешная активность транспорта 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

• Такой же явный opt-in доступен для каждой учетной записи по адресу 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