Telegram

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

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

• 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 для их миграции

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

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

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

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Резервное копирование Git" },
        { command: "generate", description: "Создать изображение" },
      ],
    },
  },
}

• 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

• sendMessage (to, content, необязательный mediaUrl, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content или caption, необязательные встроенные кнопки presentation; изменения только кнопок обновляют разметку ответа)
• createForumTopic (chatId, name, необязательный iconColor, iconCustomEmojiId)

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

​

Аудиосообщения

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

​

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

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

​

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

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

​

Стикеры

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

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

{
  action: "sticker-search",
  channel: "telegram",
  query: "машущий кот",
  limit: 5,
}

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

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

• 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. Для доставки итогового ответа на входящее сообщение используется ограниченное число безопасных повторных попыток при сбоях до подключения, но неоднозначные сетевые ответы после отправки не повторяются, поскольку это может привести к дублированию видимых сообщений.

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

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

• Если 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 A
dig +short api.telegram.org AAAA