Telegram (Bot API)¶

Статус: готово к промышленному использованию для личных сообщений бота и групп через grammY. По умолчанию используется long-polling; вебхук — опционально.

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

1. Создайте бота с помощью @BotFather (прямая ссылка). Убедитесь, что хэндл точно @BotFather, затем скопируйте токен.
2. Установите токен: - Env: TELEGRAM_BOT_TOKEN=... - Или в конфиге: channels.telegram.botToken: "...". - Если заданы оба варианта, приоритет у конфига (env используется как fallback только для аккаунта по умолчанию).
3. Запустите Gateway (шлюз).
4. Доступ к личным сообщениям по умолчанию — через сопряжение; подтвердите код сопряжения при первом контакте.

Минимальный конфиг:

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

Что это такое¶

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

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

1. Создание токена бота (BotFather)¶

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

Необязательные настройки 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 для общего шаблона.

3. Запустите Gateway (шлюз). Telegram запускается, когда токен определён (сначала конфиг, затем fallback из env).
4. Доступ к личным сообщениям по умолчанию — через сопряжение. Подтвердите код при первом обращении к боту.
5. Для групп: добавьте бота, определите поведение приватности/администратора (см. ниже), затем установите channels.telegram.groups для управления требованиями упоминаний и allowlist.

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

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

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

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

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

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

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

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

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

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

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

Трансляция черновика¶

OpenClaw может стримить частичные ответы в личных сообщениях Telegram с использованием sendMessageDraft.

Требования:

• Для бота включён Threaded Mode в @BotFather (режим форумных тем).
• Только приватные чаты с темами (Telegram включает message_thread_id во входящих сообщениях).
• channels.telegram.streamMode не установлен в "off" (по умолчанию: "partial", "block" включает обновления черновиков блоками).

Черновой стриминг доступен только в личных сообщениях; Telegram не поддерживает его в группах или каналах.

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

• Исходящий текст Telegram использует parse_mode: "HTML" (подмножество поддерживаемых тегов Telegram).
• Входной Markdown-подобный текст рендерится в безопасный для Telegram HTML (жирный/курсив/зачёркнутый/код/ссылки); блочные элементы преобразуются в текст с переводами строк/маркерами.
• Сырой HTML от моделей экранируется, чтобы избежать ошибок парсинга Telegram.
• Если Telegram отклоняет HTML-пейлоад, 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.

Дополнительная помощь: Устранение неполадок каналов.

Примечания:

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

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

Если плагин device-pair установлен, он добавляет ориентированный на Telegram процесс сопряжения нового телефона:

1. /pair генерирует код настройки (отправляется отдельным сообщением для удобного копирования/вставки).
2. Вставьте код настройки в приложение iOS для подключения.
3. /pair approve одобряет последний ожидающий запрос устройства.

Подробнее: Pairing.

Ограничения¶

• Исходящий текст разбивается на блоки по 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), с fallback на 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 }, // always respond in this group
      },
    },
  },
}

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

Чтобы разрешить все группы с режимом «всегда отвечать»:

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false }, // all groups, always respond
      },
    },
  },
}

Чтобы оставить режим «только по упоминанию» для всех групп (поведение по умолчанию):

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true }, // or omit groups entirely
      },
    },
  },
}

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

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

• /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, автоответ, системные подсказки, отключение).
• Конфиги тем наследуют настройки группы (requireMention, allowlists, skills, prompts, enabled), если не переопределены для темы.

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

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

Telegram поддерживает встроенные клавиатуры с callback-кнопками.

{
  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 отправляются агенту как сообщение в формате: 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>
• Сопряжение — механизм обмена токенами по умолчанию для личных сообщений Telegram. Подробнее: Pairing
• channels.telegram.allowFrom принимает числовые ID пользователей (рекомендуется) или записи @username. Это не имя пользователя бота; используйте ID человека-отправителя. Мастер принимает @username и, когда возможно, разрешает его в числовой ID.

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

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

1. Запустите шлюз и БМ.
2. Выполните openclaw logs --follow и найдите from.id.

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

1. ТМ ваш бот.
2. Получите обновления с токеном бота и прочитайте message.from.id:

bash curl "https://api.telegram.org/bot<bot_token>/getUpdates"

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

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

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

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

1. Какие группы разрешены (allowlist групп через 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.

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

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}

Long-polling vs вебхук¶

• По умолчанию: long-polling (публичный URL не требуется).
• Режим вебхука: установите 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 с совместимым для голоса аудио-URL media (message необязателен при наличии медиа):

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

Видеосообщения (видео vs видеозаметка)¶

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

Для отправки через инструмент сообщений установите asVideoNote: true вместе с URL видео в media:

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

(Примечание: видеозаметки не поддерживают подписи. Если вы укажете текст сообщения, он будет отправлен отдельным сообщением.)

Стикеры¶

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

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

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

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

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

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

Кэш стикеров¶

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

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

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

Расположение кэша: ~/.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: обновлять черновой пузырёк крупными блоками (chunked).
• off: отключить черновой стриминг.
• Необязательно (только для streamMode: "block"):
• channels.telegram.draftChunk: { minChars?, maxChars?, breakPreference? }
  • значения по умолчанию: minChars: 200, maxChars: 800, breakPreference: "paragraph" (ограничены channels.telegram.textChunkLimit).

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

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

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

Политика повторных попыток¶

Исходящие вызовы Telegram API повторяются при временных сетевых ошибках/429 с экспоненциальной задержкой и jitter. Настраивается через 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, а не как свойства в полезной нагрузке сообщений. Когда пользователь добавляет реакцию, OpenClaw:

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

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

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

• 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", // See all reactions
      reactionLevel: "minimal", // Agent can react sparingly
    },
  },
}

Требования:

• Боты Telegram должны явно запрашивать message_reaction в allowed_updates (настраивается автоматически OpenClaw)
• В режиме вебхука реакции включаются в вебхук 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
• Убедитесь, что бот действительно является участником (а не просто администратором без доступа к чтению)
• Проверьте логи шлюза: openclaw logs --follow (ищите «skipping group message»)

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

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

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

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

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

• Node 22+ строже относится к экземплярам AbortSignal; сторонние сигналы могут немедленно прерывать вызовы fetch.
• Обновитесь до сборки OpenClaw, которая нормализует abort-сигналы, или запускайте Gateway (шлюз) на Node 20, пока не сможете обновиться.

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

• Некоторые хосты сначала резолвят api.telegram.org в IPv6. Если у вашего сервера нет рабочего IPv6-выхода, grammY может зависать на IPv6-only запросах.
• Исправление: включите IPv6-выход или принудительно используйте 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)¶

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

Параметры провайдера:

• channels.telegram.enabled: включить/выключить запуск канала.
• channels.telegram.botToken: токен бота (BotFather).
• channels.telegram.tokenFile: читать токен из пути к файлу.
• channels.telegram.dmPolicy: pairing | allowlist | open | disabled (по умолчанию: сопряжение).
• channels.telegram.allowFrom: allowlist личных сообщений (ids/usernames). open требует "*".
• channels.telegram.groupPolicy: open | allowlist | disabled (по умолчанию: allowlist).
• channels.telegram.groupAllowFrom: allowlist отправителей в группах (ids/usernames).
• channels.telegram.groups: значения по умолчанию для групп + allowlist (используйте "*" для глобальных значений).
• channels.telegram.groups.<id>.groupPolicy: переопределение groupPolicy для группы (open | allowlist | disabled).
• channels.telegram.groups.<id>.requireMention: поведение требований упоминаний по умолчанию.
• channels.telegram.groups.<id>.skills: фильтр skills (не указано = все skills, пусто = ни одного).
• channels.telegram.groups.<id>.allowFrom: переопределение allowlist отправителей для группы.
• channels.telegram.groups.<id>.systemPrompt: дополнительный системный prompt для группы.
• channels.telegram.groups.<id>.enabled: отключить группу, когда false.
• channels.telegram.groups.<id>.topics.<threadId>.*: переопределения для тем (те же поля, что и у группы).
• channels.telegram.groups.<id>.topics.<threadId>.groupPolicy: переопределение groupPolicy для темы (open | allowlist | disabled).
• 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: лимит входящих/исходящих медиа (МБ).
• 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: включить режим вебхука (требует channels.telegram.webhookSecret).
• channels.telegram.webhookSecret: секрет вебхука (обязателен, когда задан webhookUrl).
• channels.telegram.webhookPath: локальный путь вебхука (по умолчанию /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 (глобальный fallback).
• commands.native (по умолчанию "auto" → включено для Telegram/Discord, выключено для Slack), commands.text, commands.useAccessGroups (поведение команд). Переопределяется через channels.telegram.commands.native.
• messages.responsePrefix, messages.ackReaction, messages.ackReactionScope, messages.removeAckAfterReply.