Telegram

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

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

• прямые чаты: сообщение предпросмотра + 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

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

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

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

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

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

• 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

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

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

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

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

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

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

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

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

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (по умолчанию: отключено)

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

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

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

• отправки сообщений опускают message_thread_id (Telegram отклоняет sendMessage(...thread_id=1))
• действия набора текста все равно включают message_thread_id

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // Общая тема → основной агент
            "3": { agentId: "zu" },        // Тема разработки → агент zu
            "5": { agentId: "coder" }      // Проверка кода → агент coder
          }
        }
      }
    }
  }
}

​

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

• по умолчанию: поведение аудиофайла
• тег [[audio_as_voice]] в ответе агента принудительно отправляет голосовую заметку
• входящие расшифровки голосовых заметок оформляются в контексте агента как машинно сгенерированный, недоверенный текст; обнаружение упоминаний все равно использует необработанную расшифровку, поэтому голосовые сообщения с ограничением по упоминанию продолжают работать.

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

​

Стикеры

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

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

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

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

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

• 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), а не в точную исходную тему

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

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

• события миграции групп (migrate_to_chat_id) для обновления channels.telegram.groups
• /config set и /config unset (требуется включение команд)

{
  channels: {
    telegram: {
      configWrites: false,
    },
  },
}

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

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

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

• --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, оставляя обычные отправки включенными

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

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