Перейти к основному содержанию

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 для общего шаблона.
  1. Запустите Gateway (шлюз). Telegram запускается, когда токен определён (сначала конфиг, затем fallback из env).
  2. Доступ к личным сообщениям по умолчанию — через сопряжение. Подтвердите код при первом обращении к боту.
  3. Для групп: добавьте бота, определите поведение приватности/администратора (см. ниже), затем установите 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:
    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: /setprivacyDisable (затем удалите и заново добавьте бота в группу)
  • 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.