Telegram

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

Быстрая настройка

Шаг 1: Создание токена бота в BotFather

Откройте Telegram и напишите @BotFather (убедитесь, что это именно @BotFather). Выполните /newbot, следуйте подсказкам и сохраните токен.

Шаг 2: Настройка токена и политики личных сообщений

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

Резервный вариант через переменные окружения: TELEGRAM_BOT_TOKEN=... (только для аккаунта по умолчанию). Telegram не использует openclaw channels login telegram; настройте токен в конфиге/env, затем запустите шлюз.

Шаг 3: Запуск шлюза и подтверждение первого личного сообщения

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Коды связывания истекают через 1 час.

Шаг 4: Добавление бота в группу

Добавьте бота в свою группу, затем настройте channels.telegram.groups и groupPolicy в соответствии с вашей моделью доступа.

ℹ️ Порядок разрешения токена учитывает аккаунт. На практике значения из конфига имеют приоритет над резервным вариантом из переменных окружения, а TELEGRAM_BOT_TOKEN применяется только к аккаунту по умолчанию.

Настройки на стороне Telegram

Контроль доступа и активация

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

Поведение в runtime

• Telegram управляется процессом шлюза.
• Маршрутизация детерминирована: входящие сообщения из Telegram возвращаются в Telegram (модель не выбирает каналы).
• Входящие сообщения нормализуются в общий конверт канала с метаданными ответа и заполнителями медиа.
• Групповые сессии изолированы по ID группы. Темы форума добавляют :topic:<threadId> для изоляции топиков.
• Личные сообщения могут содержать message_thread_id; OpenClaw маршрутизирует их с использованием ключей сессии, учитывающих тред, и сохраняет ID треда для ответов.
• Long polling использует grammY runner с последовательной обработкой для каждого чата/треда. Общая конкурентность sink runner использует agents.defaults.maxConcurrent.
• Telegram Bot API не поддерживает квитанции о прочтении (sendReadReceipts не применяется).

Справочник по функциям

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

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

Указатели на справочник конфигурации Telegram

Основной справочник:

• channels.telegram.enabled: включить/отключить запуск канала.
• channels.telegram.botToken: токен бота (BotFather).
• channels.telegram.tokenFile: читать токен из пути к файлу.
• channels.telegram.dmPolicy: pairing | allowlist | open | disabled (по умолчанию: pairing).
• channels.telegram.allowFrom: белый список личных сообщений (числовые ID пользователей Telegram). allowlist требует хотя бы одного ID отправителя. open требует "*". openclaw doctor --fix может разрешить устаревшие записи @username в ID и может восстановить записи белого списка из файлов хранилища связывания при миграции на белый список.
• channels.telegram.actions.poll: включить или отключить создание опросов Telegram (по умолчанию: включено; все еще требует sendMessage).
• channels.telegram.defaultTo: цель Telegram по умолчанию, используемая CLI --deliver, когда явный --reply-to не предоставлен.
• channels.telegram.groupPolicy: open | allowlist | disabled (по умолчанию: allowlist).
• channels.telegram.groupAllowFrom: белый список отправителей группы (числовые ID пользователей Telegram). openclaw doctor --fix может разрешить устаревшие записи @username в ID. Нечисловые записи игнорируются во время авторизации. Авторизация группы не использует резервный вариант хранилища связывания личных сообщений (2026.2.25+).
• Приоритет нескольких аккаунтов:
  • Когда настроены два или более ID аккаунта, установите channels.telegram.defaultAccount (или включите channels.telegram.accounts.default), чтобы сделать маршрутизацию по умолчанию явной.
  • Если ни то, ни другое не установлено, OpenClaw возвращается к первому нормализованному ID аккаунта, и openclaw doctor предупреждает.
  • channels.telegram.accounts.default.allowFrom и channels.telegram.accounts.default.groupAllowFrom применяются только к аккаунту default.
  • Именованные аккаунты наследуют channels.telegram.allowFrom и channels.telegram.groupAllowFrom, когда значения на уровне аккаунта не установлены.
  • Именованные аккаунты не наследуют channels.telegram.accounts.default.allowFrom / groupAllowFrom.
• channels.telegram.groups: настройки по умолчанию для каждой группы + белый список (используйте "*" для глобальных настроек по умолчанию).
  • channels.telegram.groups.<id>.groupPolicy: переопределение groupPolicy для каждой группы (open | allowlist | disabled).
  • channels.telegram.groups.<id>.requireMention: управление упоминаниями по умолчанию.
  • channels.telegram.groups.<id>.skills: фильтр навыков (опустить = все навыки, пусто = ни одного).