Telegram (Bot API)

Статус: production-ready для личных сообщений бота + групп через grammY. Long-polling по умолчанию; webhook опционально.

Быстрая настройка (для начинающих)

Создайте бота с @BotFather и скопируйте токен.
Установите токен:
- Env: TELEGRAM_BOT_TOKEN=...
- Или конфигурация: channels.telegram.botToken: "...".
- Если установлены оба, конфигурация имеет приоритет (env резерв только для аккаунта по умолчанию).
Запустите gateway.
Доступ к личным сообщениям - pairing по умолчанию; одобрите код сопряжения при первом контакте.

Минимальная конфигурация:

\{
  channels: \{
    telegram: \{
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing"
    \}
  \}
\}

Что это такое

Канал Telegram Bot API, принадлежащий Gateway.
Детерминированная маршрутизация: ответы возвращаются в Telegram; модель никогда не выбирает каналы.
Личные сообщения делят основную сессию агента; группы остаются изолированными (agent:<agentId>:telegram:group:<chatId>).

Настройка (быстрый путь)

1) Создать токен бота (BotFather)

Откройте Telegram и напишите @BotFather.
Выполните /newbot, затем следуйте подсказкам (имя + имя пользователя, заканчивающееся на bot).
Скопируйте токен и сохраните его безопасно.

Опциональные настройки BotFather:

/setjoingroups — разрешить/запретить добавление бота в группы.
/setprivacy — контролировать, видит ли бот все сообщения в группе.

2) Настроить токен (env или конфигурация)

Пример:

\{
  channels: \{
    telegram: \{
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: \{ "*": \{ requireMention: true \} \}
    \}
  \}
\}

Опция Env: TELEGRAM_BOT_TOKEN=... (работает для аккаунта по умолчанию). Если установлены оба env и конфигурация, конфигурация имеет приоритет.

Поддержка нескольких аккаунтов: используйте channels.telegram.accounts с токенами для каждого аккаунта и опциональным name. См. gateway/configuration для общего паттерна.

Запустите gateway. Telegram запускается когда токен разрешен (конфигурация первая, env резерв).
Доступ к личным сообщениям по умолчанию pairing. Одобрите код когда бот впервые контактирует.
Для групп: добавьте бота, решите поведение приватности/администратора (ниже), затем установите channels.telegram.groups для контроля блокировки упоминаний + списков разрешений.

Токен + приватность + права (сторона Telegram)

Создание токена (BotFather)

/newbot создает бота и возвращает токен (держите его в секрете).
Если токен утекает, отзовите/сгенерируйте заново через @BotFather и обновите конфигурацию.

Видимость групповых сообщений (Privacy Mode)

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

Отключите режим приватности с помощью /setprivacy или
Добавьте бота как администратора группы (боты-администраторы получают все сообщения).

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

Права группы (права администратора)

Статус администратора устанавливается внутри группы (UI Telegram). Боты-администраторы всегда получают все групповые сообщения, поэтому используйте администратора, если нужна полная видимость.

Как это работает (поведение)

Входящие сообщения нормализуются в общий конверт канала с контекстом ответа и заполнителями медиа.
Ответы группы требуют упоминания по умолчанию (нативное @упоминание или agents.list[].groupChat.mentionPatterns / messages.groupChat.mentionPatterns).
Переопределение мультиагента: установите паттерны для агента через agents.list[].groupChat.mentionPatterns.
Ответы всегда маршрутизируются обратно в тот же чат Telegram.
Long-polling использует grammY runner с последовательностью по чату; общая конкурентность ограничена agents.defaults.maxConcurrent.
Telegram Bot API не поддерживает уведомления о прочтении; нет опции sendReadReceipts.

Форматирование (Telegram HTML)

Исходящий текст Telegram использует parse_mode: "HTML" (поддерживаемое подмножество тегов Telegram).
Markdown-подобный ввод рендерится в безопасный HTML для Telegram (жирный/курсив/зачеркнутый/код/ссылки); блочные элементы сглаживаются в текст с новыми строками/маркерами.
Сырой HTML от моделей экранируется для избежания ошибок парсинга Telegram.
Если Telegram отклоняет HTML payload, OpenClaw повторяет то же сообщение как обычный текст.

Команды (нативные + пользовательские)

OpenClaw регистрирует нативные команды (как /status, /reset, /model) в меню бота Telegram при запуске. Вы можете добавить пользовательские команды в меню через конфигурацию:

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

Устранение неполадок

setMyCommands failed в логах обычно означает, что исходящий HTTPS/DNS блокируется к api.telegram.org.
Если видите сбои sendMessage или sendChatAction, проверьте маршрутизацию IPv6 и DNS.

Больше помощи: Channel troubleshooting.

Примечания:

Пользовательские команды это только записи меню; OpenClaw не реализует их, если вы не обработаете их в другом месте.
Имена команд нормализуются (ведущий / удален, в нижнем регистре) и должны соответствовать a-z, 0-9, _ (1–32 символа).
Пользовательские команды не могут переопределять нативные команды. Конфликты игнорируются и логируются.
Если commands.native отключен, регистрируются только пользовательские команды (или очищаются, если нет).

Лимиты

Исходящий текст разбивается на части по channels.telegram.textChunkLimit (по умолчанию 4000).
Опциональное разбиение по новым строкам: установите channels.telegram.chunkMode="newline" для разделения по пустым строкам (границам абзацев) перед разбиением по длине.
Загрузки/выгрузки медиа ограничены channels.telegram.mediaMaxMb (по умолчанию 5).
Запросы Telegram Bot API таймаутятся после channels.telegram.timeoutSeconds (по умолчанию 500 через grammY). Установите ниже для избежания долгих зависаний.
Контекст истории группы использует channels.telegram.historyLimit (или channels.telegram.accounts.*.historyLimit), откатываясь на messages.groupChat.historyLimit. Установите 0 для отключения (по умолчанию 50).
История личных сообщений может быть ограничена с помощью channels.telegram.dmHistoryLimit (пользовательские ходы). Переопределения для каждого пользователя: channels.telegram.dms["<user_id>"].historyLimit.

Режимы активации группы

По умолчанию бот отвечает только на упоминания в группах (@botname или паттерны в agents.list[].groupChat.mentionPatterns). Чтобы изменить это поведение:

Через конфигурацию (рекомендуется)

\{
  channels: \{
    telegram: \{
      groups: \{
        "-1001234567890": \{ requireMention: false \}  // всегда отвечать в этой группе
      \}
    \}
  \}
\}

Важно: Установка channels.telegram.groups создает список разрешений - будут приняты только перечисленные группы (или "*"). Темы форума наследуют конфигурацию родительской группы (allowFrom, requireMention, skills, prompts), если вы не добавите переопределения для темы под channels.telegram.groups.<groupId>.topics.<topicId>.

Чтобы разрешить все группы с always-respond:

\{
  channels: \{
    telegram: \{
      groups: \{
        "*": \{ requireMention: false \}  // все группы, всегда отвечать
      \}
    \}
  \}
\}

Чтобы оставить mention-only для всех групп (поведение по умолчанию):

\{
  channels: \{
    telegram: \{
      groups: \{
        "*": \{ requireMention: true \}  // или опустите groups полностью
      \}
    \}
  \}
\}

Через команду (уровень сессии)

Отправьте в группе:

/activation always - отвечать на все сообщения
/activation mention - требовать упоминания (по умолчанию)

Примечание: Команды обновляют только состояние сессии. Для постоянного поведения после перезапусков используйте конфигурацию.

Получение ID чата группы

Перешлите любое сообщение из группы в @userinfobot или @getidsbot в Telegram, чтобы увидеть ID чата (отрицательное число вроде -1001234567890).

Совет: Для вашего собственного ID пользователя, напишите боту в личку и он ответит с вашим ID пользователя (сообщение сопряжения), или используйте /whoami после включения команд.

Примечание о приватности: @userinfobot - это сторонний бот. Если предпочитаете, добавьте бота в группу, отправьте сообщение и используйте openclaw logs --follow для чтения chat.id, или используйте Bot API getUpdates.

Записи конфигурации

По умолчанию Telegram разрешено записывать обновления конфигурации, вызванные событиями канала или /config set|unset.

Это происходит когда:

Группа обновляется до супергруппы и Telegram генерирует migrate_to_chat_id (ID чата меняется). OpenClaw может автоматически мигрировать channels.telegram.groups.
Вы выполняете /config set или /config unset в чате Telegram (требует commands.config: true).

Отключите с:

\{
  channels: \{ telegram: \{ configWrites: false \} \}
\}

Темы (супергруппы форума)

Темы форума Telegram включают message_thread_id для каждого сообщения. OpenClaw:

Добавляет :topic:<threadId> к ключу сессии группы Telegram, чтобы каждая тема была изолирована.
Отправляет индикаторы набора и ответы с message_thread_id, чтобы ответы оставались в теме.
Общая тема (thread id 1) особенная: отправки сообщений опускают message_thread_id (Telegram отклоняет его), но индикаторы набора все равно включают его.
Предоставляет MessageThreadId + IsForum в контексте шаблона для маршрутизации/шаблонирования.
Конфигурация для конкретной темы доступна под channels.telegram.groups.<chatId>.topics.<threadId> (skills, allowlists, auto-reply, system prompts, disable).
Конфигурации тем наследуют настройки группы (requireMention, allowlists, skills, prompts, enabled), если не переопределены для темы.

Приватные чаты могут включать message_thread_id в некоторых крайних случаях. OpenClaw сохраняет ключ сессии личного сообщения неизменным, но все равно использует thread id для ответов/потоковой передачи черновиков, когда он присутствует.

Встроенные кнопки

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

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

Для конфигурации по аккаунту:

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

Области:

off — встроенные кнопки отключены
dm — только личные сообщения (цели групп блокируются)
group — только группы (цели личных сообщений блокируются)
all — личные сообщения + группы
allowlist — личные сообщения + группы, но только отправители разрешенные через allowFrom/groupAllowFrom (те же правила, что для команд управления)

По умолчанию: allowlist. Устаревшее: capabilities: ["inlineButtons"] = inlineButtons: "all".

Отправка кнопок

Используйте инструмент сообщений с параметром buttons:

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

Когда пользователь нажимает кнопку, данные обратного вызова отправляются обратно агенту как сообщение с форматом: callback_data: value

Опции конфигурации

Возможности Telegram могут быть настроены на двух уровнях (форма объекта показана выше; устаревшие строковые массивы все еще поддерживаются):

channels.telegram.capabilities: Глобальная конфигурация возможностей по умолчанию, применяемая ко всем аккаунтам Telegram, если не переопределена.
channels.telegram.accounts.<account>.capabilities: Возможности для каждого аккаунта, которые переопределяют глобальные по умолчанию для этого конкретного аккаунта.

Используйте глобальную настройку, когда все боты/аккаунты Telegram должны вести себя одинаково. Используйте конфигурацию для каждого аккаунта, когда разным ботам нужно разное поведение (например, один аккаунт обрабатывает только личные сообщения, в то время как другой разрешен в группах).

Контроль доступа (личные сообщения + группы)

Доступ к личным сообщениям

По умолчанию: channels.telegram.dmPolicy = "pairing". Неизвестные отправители получают код сопряжения; сообщения игнорируются до одобрения (коды истекают через 1 час).
Одобрить через:
- openclaw pairing list telegram
- openclaw pairing approve telegram <CODE>
Pairing - это обмен токенами по умолчанию, используемый для личных сообщений Telegram. Подробности: Pairing
channels.telegram.allowFrom принимает числовые ID пользователей (рекомендуется) или записи @username. Это не имя пользователя бота; используйте ID отправителя-человека. Мастер принимает @username и разрешает его в числовой ID, когда возможно.

Поиск вашего ID пользователя Telegram

Безопаснее (без стороннего бота):

Запустите gateway и напишите вашему боту в личку.
Выполните openclaw logs --follow и ищите from.id.

Альтернатива (официальный Bot API):

Напишите вашему боту в личку.
Получите обновления с вашим токеном бота и прочтите message.from.id:
```
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
```

Сторонний (менее приватный):

Напишите в личку @userinfobot или @getidsbot и используйте возвращенный id пользователя.

Доступ к группам

Два независимых контроля:

1. Какие группы разрешены (список разрешений групп через channels.telegram.groups):

Нет конфигурации groups = все группы разрешены
С конфигурацией groups = только перечисленные группы или "*" разрешены
Пример: "groups": \{ "-1001234567890": \{\}, "*": \{\} \} разрешает все группы

2. Какие отправители разрешены (фильтрация отправителей через channels.telegram.groupPolicy):

"open" = все отправители в разрешенных группах могут писать
"allowlist" = только отправители в channels.telegram.groupAllowFrom могут писать
"disabled" = никакие групповые сообщения не принимаются вообще По умолчанию groupPolicy: "allowlist" (блокируется, если не добавить groupAllowFrom).

Большинство пользователей хотят: groupPolicy: "allowlist" + groupAllowFrom + конкретные группы, перечисленные в channels.telegram.groups

Long-polling vs webhook

По умолчанию: long-polling (не требуется публичный URL).
Режим webhook: установите channels.telegram.webhookUrl (опционально channels.telegram.webhookSecret + channels.telegram.webhookPath).
- Локальный слушатель привязывается к 0.0.0.0:8787 и обслуживает POST /telegram-webhook по умолчанию.
- Если ваш публичный URL отличается, используйте reverse proxy и укажите channels.telegram.webhookUrl на публичную конечную точку.

Треды ответов

Telegram поддерживает опциональные треды ответов через теги:

[[reply_to_current]] -- ответить на исходное сообщение.
[[reply_to:<id>]] -- ответить на конкретное сообщение по id.

Контролируется channels.telegram.replyToMode:

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

Аудиосообщения (голос vs файл)

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

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

[[audio_as_voice]] — отправить аудио как голосовую заметку вместо файла.

Тег удаляется из доставленного текста. Другие каналы игнорируют этот тег.

Для отправок инструмента сообщений установите asVoice: true с совместимым с голосом аудио media URL (message опционально, когда присутствует медиа):

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

Стикеры

OpenClaw поддерживает получение и отправку стикеров Telegram с интеллектуальным кэшированием.

Получение стикеров

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

Статические стикеры (WEBP): Загружаются и обрабатываются через vision. Стикер появляется как заполнитель <media:sticker> в содержимом сообщения.
Анимированные стикеры (TGS): Пропускаются (формат Lottie не поддерживается для обработки).
Видео стикеры (WEBM): Пропускаются (видеоформат не поддерживается для обработки).

Поле контекста шаблона доступно при получении стикеров:

Sticker — объект с:
- emoji — эмодзи, связанный со стикером
- setName — название набора стикеров
- fileId — Telegram file ID (отправить тот же стикер обратно)
- fileUniqueId — стабильный ID для поиска в кэше
- cachedDescription — кэшированное описание vision, когда доступно

Кэш стикеров

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

Как это работает:

Первая встреча: Изображение стикера отправляется в AI для анализа vision. AI генерирует описание (например, "Мультяшный кот энергично машет").
Хранение кэша: Описание сохраняется вместе с file ID стикера, эмодзи и названием набора.
Последующие встречи: Когда тот же стикер встречается снова, используется кэшированное описание напрямую. Изображение не отправляется в AI.

Расположение кэша: ~/.openclaw/telegram/sticker-cache.json

Формат записи кэша:

\{
  "fileId": "CAACAgIAAxkBAAI...",
  "fileUniqueId": "AgADBAADb6cxG2Y",
  "emoji": "👋",
  "setName": "CoolCats",
  "description": "A cartoon cat waving enthusiastically",
  "cachedAt": "2026-01-15T10:30:00.000Z"
\}

Преимущества:

Снижает затраты API, избегая повторных вызовов vision для того же стикера
Более быстрое время ответа для кэшированных стикеров (без задержки обработки vision)
Включает функциональность поиска стикеров на основе кэшированных описаний

Кэш заполняется автоматически при получении стикеров. Ручное управление кэшем не требуется.

Отправка стикеров

Агент может отправлять и искать стикеры, используя действия sticker и sticker-search. По умолчанию они отключены и должны быть включены в конфигурации:

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

Отправить стикер:

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

Параметры:

fileId (обязательно) — Telegram file ID стикера. Получите это из Sticker.fileId при получении стикера или из результата sticker-search.
replyTo (опционально) — ID сообщения для ответа.
threadId (опционально) — ID треда сообщения для тем форума.

Поиск стикеров:

Агент может искать кэшированные стикеры по описанию, эмодзи или названию набора:

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

Возвращает совпадающие стикеры из кэша:

\{
  "ok": true,
  "count": 2,
  "stickers": [
    \{
      "fileId": "CAACAgIAAxkBAAI...",
      "emoji": "👋",
      "description": "A cartoon cat waving enthusiastically",
      "setName": "CoolCats"
    \}
  ]
\}

Поиск использует нечеткое совпадение по тексту описания, символам эмодзи и названиям наборов.

Пример с тредингом:

\{
  "action": "sticker",
  "channel": "telegram",
  "to": "-1001234567890",
  "fileId": "CAACAgIAAxkBAAI...",
  "replyTo": 42,
  "threadId": 123
\}

Потоковая передача (черновики)

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

Требования (Telegram Bot API 9.3+):

Приватные чаты с включенными темами (режим темы форума для бота).
Входящие сообщения должны включать message_thread_id (приватный тред темы).
Потоковая передача игнорируется для групп/супергрупп/каналов.

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

channels.telegram.streamMode: "off" | "partial" | "block" (по умолчанию: partial)
- partial: обновить пузырь черновика с последним потоковым текстом.
- block: обновить пузырь черновика крупными блоками (разбитыми на части).
- off: отключить потоковую передачу черновиков.
Опционально (только для streamMode: "block"):
- channels.telegram.draftChunk: \{ minChars?, maxChars?, breakPreference? \}
  - по умолчанию: minChars: 200, maxChars: 800, breakPreference: "paragraph" (ограничено channels.telegram.textChunkLimit).

Примечание: потоковая передача черновиков отделена от блочной потоковой передачи (сообщения каналов). Блочная потоковая передача по умолчанию выключена и требует channels.telegram.blockStreaming: true если хотите ранние сообщения Telegram вместо обновлений черновиков.

Поток рассуждений (только Telegram):

/reasoning stream передает рассуждения в пузырь черновика, пока генерируется ответ, затем отправляет финальный ответ без рассуждений.
Если channels.telegram.streamMode равен off, поток рассуждений отключен. Больше контекста: Streaming + chunking.

Политика повторов

Исходящие вызовы Telegram API повторяются при переходных сетевых/429 ошибках с экспоненциальной отсрочкой и дрожанием. Настройте через channels.telegram.retry. См. Retry policy.

Инструмент агента (сообщения + реакции)

Инструмент: telegram с действием sendMessage (to, content, опционально mediaUrl, replyToMessageId, messageThreadId).
Инструмент: telegram с действием react (chatId, messageId, emoji).
Инструмент: telegram с действием deleteMessage (chatId, messageId).
Семантика удаления реакций: см. /tools/reactions.
Блокировка инструментов: channels.telegram.actions.reactions, channels.telegram.actions.sendMessage, channels.telegram.actions.deleteMessage (по умолчанию: включено), и channels.telegram.actions.sticker (по умолчанию: отключено).

Уведомления о реакциях

Как работают реакции: Реакции Telegram приходят как отдельные события message_reaction, а не как свойства в payload сообщений. Когда пользователь добавляет реакцию, OpenClaw:

Получает обновление message_reaction из Telegram API
Преобразует его в системное событие с форматом: "Telegram reaction added: \{emoji\} by \{user\} on msg \{id\}"
Ставит системное событие в очередь, используя тот же ключ сессии, что и обычные сообщения
Когда следующее сообщение приходит в этот разговор, системные события дренируются и добавляются в начало контекста агента

Агент видит реакции как системные уведомления в истории разговора, а не как метаданные сообщения.

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

channels.telegram.reactionNotifications: Контролирует, какие реакции вызывают уведомления
- "off" — игнорировать все реакции
- "own" — уведомлять, когда пользователи реагируют на сообщения бота (best-effort; в памяти) (по умолчанию)
- "all" — уведомлять обо всех реакциях
channels.telegram.reactionLevel: Контролирует возможность реакции агента
- "off" — агент не может реагировать на сообщения
- "ack" — бот отправляет реакции подтверждения (👀 во время обработки) (по умолчанию)
- "minimal" — агент может реагировать скупо (рекомендация: 1 на 5-10 обменов)
- "extensive" — агент может реагировать свободно, когда уместно

Группы форума: Реакции в группах форума включают message_thread_id и используют ключи сессий вроде agent:main:telegram:group:\{chatId\}:topic:\{threadId\}. Это обеспечивает, что реакции и сообщения в одной теме остаются вместе.

Пример конфигурации:

\{
  channels: \{
    telegram: \{
      reactionNotifications: "all",  // Видеть все реакции
      reactionLevel: "minimal"        // Агент может реагировать скупо
    \}
  \}
\}

Требования:

Боты Telegram должны явно запрашивать message_reaction в allowed_updates (настраивается автоматически OpenClaw)
Для режима webhook реакции включены в webhook allowed_updates
Для режима polling реакции включены в getUpdates allowed_updates

Цели доставки (CLI/cron)

Используйте id чата (123456789) или имя пользователя (@name) как цель.
Пример: openclaw message send --channel telegram --target 123456789 --message "hi".

Устранение неполадок

Бот не отвечает на сообщения без упоминания в группе:

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

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

Если установлен channels.telegram.groups, группа должна быть перечислена или использовать "*"
Проверьте настройки приватности в @BotFather → "Group Privacy" должна быть OFF
Убедитесь, что бот действительно является участником (не просто администратором без доступа на чтение)
Проверьте логи gateway: openclaw logs --follow (ищите "skipping group message")

Бот отвечает на упоминания, но не на /activation always:

Команда /activation обновляет состояние сессии, но не сохраняется в конфигурацию
Для постоянного поведения добавьте группу в channels.telegram.groups с requireMention: false

Команды вроде /status не работают:

Убедитесь, что ваш ID пользователя Telegram авторизован (через pairing или channels.telegram.allowFrom)
Команды требуют авторизации даже в группах с groupPolicy: "open"

Long-polling прерывается сразу на Node 22+ (часто с прокси/пользовательским fetch):

Node 22+ строже к экземплярам AbortSignal; иностранные сигналы могут прервать вызовы fetch сразу.
Обновитесь до сборки OpenClaw, которая нормализует сигналы прерывания, или запустите gateway на Node 20, пока не сможете обновиться.

Бот запускается, затем тихо перестает отвечать (или логирует HttpError: Network request ... failed):

Некоторые хосты разрешают api.telegram.org в IPv6 первыми. Если ваш сервер не имеет работающего IPv6 egress, grammY может застрять на запросах только IPv6.
Исправьте, включив IPv6 egress или принудительно разрешив IPv4 для api.telegram.org (например, добавьте запись /etc/hosts, используя IPv4 A запись, или предпочтите IPv4 в стеке DNS вашей ОС), затем перезапустите gateway.
Быстрая проверка: dig +short api.telegram.org A и dig +short api.telegram.org AAAA для подтверждения, что возвращает DNS.

Справочник по конфигурации (Telegram)

Полная конфигурация: Configuration

Опции провайдера:

channels.telegram.enabled: включить/отключить запуск канала.
channels.telegram.botToken: токен бота (BotFather).
channels.telegram.tokenFile: читать токен из пути к файлу.
channels.telegram.dmPolicy: pairing | allowlist | open | disabled (по умолчанию: pairing).
channels.telegram.allowFrom: список разрешений для личных сообщений (ids/usernames). open требует "*".
channels.telegram.groupPolicy: open | allowlist | disabled (по умолчанию: allowlist).
channels.telegram.groupAllowFrom: список разрешений отправителей группы (ids/usernames).
channels.telegram.groups: значения по умолчанию для группы + список разрешений (используйте "*" для глобальных значений по умолчанию).
- channels.telegram.groups.<id>.requireMention: значение по умолчанию для блокировки упоминаний.
- channels.telegram.groups.<id>.skills: фильтр навыков (опустить = все навыки, пустой = нет).
- channels.telegram.groups.<id>.allowFrom: переопределение списка разрешений отправителей для группы.
- channels.telegram.groups.<id>.systemPrompt: дополнительный системный промпт для группы.
- channels.telegram.groups.<id>.enabled: отключить группу когда false.
- channels.telegram.groups.<id>.topics.<threadId>.*: переопределения для темы (те же поля, что и для группы).
- channels.telegram.groups.<id>.topics.<threadId>.requireMention: переопределение блокировки упоминаний для темы.
channels.telegram.capabilities.inlineButtons: off | dm | group | all | allowlist (по умолчанию: allowlist).
channels.telegram.accounts.<account>.capabilities.inlineButtons: переопределение для аккаунта.
channels.telegram.replyToMode: off | first | all (по умолчанию: first).
channels.telegram.textChunkLimit: размер исходящего куска (символы).
channels.telegram.chunkMode: length (по умолчанию) или newline для разделения по пустым строкам (границам абзацев) перед разбиением по длине.
channels.telegram.linkPreview: переключить превью ссылок для исходящих сообщений (по умолчанию: true).
channels.telegram.streamMode: off | partial | block (потоковая передача черновиков).
channels.telegram.mediaMaxMb: лимит входящих/исходящих медиа (MB).
channels.telegram.retry: политика повторов для исходящих вызовов Telegram API (attempts, minDelayMs, maxDelayMs, jitter).
channels.telegram.network.autoSelectFamily: переопределить Node autoSelectFamily (true=включить, false=отключить). По умолчанию отключено на Node 22 для избежания таймаутов Happy Eyeballs.
channels.telegram.proxy: URL прокси для вызовов Bot API (SOCKS/HTTP).
channels.telegram.webhookUrl: включить режим webhook.
channels.telegram.webhookSecret: секрет webhook (опционально).
channels.telegram.webhookPath: локальный путь webhook (по умолчанию /telegram-webhook).
channels.telegram.actions.reactions: блокировать реакции инструмента Telegram.
channels.telegram.actions.sendMessage: блокировать отправки сообщений инструмента Telegram.
channels.telegram.actions.deleteMessage: блокировать удаления сообщений инструмента Telegram.
channels.telegram.actions.sticker: блокировать действия стикеров Telegram — отправка и поиск (по умолчанию: false).
channels.telegram.reactionNotifications: off | own | all — контролировать, какие реакции вызывают системные события (по умолчанию: own, когда не установлено).
channels.telegram.reactionLevel: off | ack | minimal | extensive — контролировать возможность реакции агента (по умолчанию: minimal, когда не установлено).

Связанные глобальные опции:

agents.list[].groupChat.mentionPatterns (паттерны блокировки упоминаний).
messages.groupChat.mentionPatterns (глобальный резерв).
commands.native (по умолчанию "auto" → включено для Telegram/Discord, выключено для Slack), commands.text, commands.useAccessGroups (поведение команд). Переопределить с channels.telegram.commands.native.
messages.responsePrefix, messages.ackReaction, messages.ackReactionScope, messages.removeAckAfterReply.