Подключение Telegram к OpenClaw: полное руководство

Telegram как основной канал для AI-агента

Telegram — один из наиболее удобных каналов для взаимодействия с AI-агентом. В отличие от веб-интерфейсов, Telegram всегда под рукой на телефоне. В отличие от голосовых ассистентов, он позволяет отправлять файлы, ссылки и структурированный текст. OpenClaw поддерживает Telegram как канал первого класса: интеграция настраивается за несколько минут и открывает полный доступ ко всем возможностям агента.

Архитектурно Telegram-интеграция работает через компонент Gateway. Когда пользователь отправляет сообщение боту в Telegram, серверы Telegram передают его на Gateway через webhook или long polling. Gateway преобразует сообщение в формат, понятный Brain, отправляет его на обработку, получает ответ и возвращает его обратно в Telegram. Вся цепочка занимает от одной до нескольких секунд в зависимости от сложности запроса.

Шаг 1: создание бота через @BotFather

Начните с создания Telegram-бота. Откройте Telegram, найдите бота @BotFather и начните с ним диалог. @BotFather — это официальный инструмент Telegram для управления ботами.

Отправьте команду /newbot. @BotFather попросит ввести имя бота (отображаемое имя, может быть любым) и username (уникальный идентификатор, должен заканчиваться на «bot»). Например, имя «Мой AI Ассистент», username «my_ai_assistant_bot».

После создания @BotFather выдаст вам токен — строку вида 7123456789:AAF1xY2z.... Это ключ доступа к вашему боту. Сохраните его — он понадобится для настройки OpenClaw. Никому не показывайте этот токен: любой, кто его знает, может управлять вашим ботом.

Дополнительно настройте бота через @BotFather: задайте описание (команда /setdescription), аватар (/setuserpic) и список команд (/setcommands). Это необязательно для работы, но улучшает пользовательский опыт.

Шаг 2: настройка токена в OpenClaw

Откройте файл конфигурации OpenClaw:

nano ~/.openclaw/config.yaml

Добавьте или отредактируйте секцию Telegram-канала:

channels:
  telegram:
    enabled: true
    token: "7123456789:AAF1xY2z3W4v5U6t..."
    allowed_users:
      - 123456789  # ваш Telegram ID
    webhook:
      enabled: false
    polling:
      enabled: true
      interval: 1

Параметр allowed_users критически важен для безопасности. Укажите в нём ваш числовой Telegram ID (не username). Узнать свой ID можно, отправив сообщение боту @userinfobot в Telegram. Без этого ограничения любой пользователь Telegram сможет общаться с вашим агентом и потенциально получить доступ к вашим данным и инструментам.

Шаг 3: запуск и проверка

Перезапустите OpenClaw, чтобы применить конфигурацию:

openclaw restart

Или, если OpenClaw запущен через Docker:

docker restart openclaw

Откройте Telegram и найдите вашего бота по username. Отправьте тестовое сообщение, например «Привет, ты работаешь?». Если всё настроено правильно, вы получите ответ от агента в течение нескольких секунд. Если ответа нет, проверьте логи:

openclaw logs --channel telegram

Типичные причины проблем: неверный токен (опечатка при копировании), ваш Telegram ID не указан в allowed_users, или файрвол блокирует исходящие соединения к серверам Telegram.

Webhook против Polling

OpenClaw поддерживает два режима получения сообщений из Telegram. Polling (опрос) — Gateway периодически спрашивает серверы Telegram «есть ли новые сообщения?». Это простой в настройке режим, не требующий белого IP-адреса или домена. Подходит для домашних серверов и разработки.

Webhook — Telegram сам отправляет сообщения на указанный URL при их поступлении. Это более эффективный режим: нет лишних запросов, сообщения доставляются мгновенно. Но webhook требует публичного HTTPS-адреса. Если ваш сервер за NAT, потребуется обратный прокси (например, через Cloudflare Tunnel или ngrok).

Для настройки webhook укажите URL в конфигурации:

channels:
  telegram:
    enabled: true
    token: "7123456789:AAF1xY2z3W4v5U6t..."
    webhook:
      enabled: true
      url: "https://your-domain.com/webhook/telegram"
      secret: "random-secret-string-here"
    polling:
      enabled: false

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

Групповые чаты

OpenClaw-бот может работать в групповых чатах Telegram. Для этого добавьте бота в группу и включите поддержку в конфигурации:

channels:
  telegram:
    groups:
      enabled: true
      respond_to_mentions: true
      respond_to_replies: true
      respond_to_all: false

В групповом режиме бот по умолчанию реагирует только на сообщения, в которых он упомянут (@my_ai_assistant_bot) или на ответы (reply) на его сообщения. Параметр respond_to_all: true заставит бота отвечать на каждое сообщение в группе — используйте это с осторожностью, чтобы не засорять чат.

Для работы в группах боту потребуется отключить Privacy Mode через @BotFather (команда /setprivacy, выбрать Disable). По умолчанию боты в группах видят только сообщения, начинающиеся с «/», и упоминания. С отключённым Privacy Mode бот видит все сообщения, что необходимо для полноценной интеграции.

Inline-режим

Telegram-боты поддерживают inline-режим: вы набираете @username_bot в любом чате, затем запрос, и бот предлагает варианты ответа прямо в строке ввода. Для активации включите inline-режим через @BotFather (/setinline) и в конфигурации OpenClaw:

channels:
  telegram:
    inline:
      enabled: true
      cache_time: 60
      placeholder: "Спросите AI..."

Inline-режим полезен для быстрых запросов: перевод слова, расчёт, краткий ответ на вопрос — без необходимости переходить в чат с ботом. Ограничение: inline-ответы должны быть короткими, Telegram обрезает длинные тексты.

Обработка файлов и медиа

Агент OpenClaw через Telegram может принимать не только текстовые сообщения, но и файлы: документы, фотографии, голосовые сообщения. Gateway автоматически скачивает файл, определяет его тип и передаёт Brain вместе с контекстом. Для голосовых сообщений производится транскрибация через встроенный или внешний модуль распознавания речи.

Настройка обработки медиа в config.yaml:

channels:
  telegram:
    media:
      accept_photos: true
      accept_documents: true
      accept_voice: true
      max_file_size_mb: 20
      voice_transcription: whisper

Безопасность Telegram-интеграции

Безопасность Telegram-токена — ваша ответственность. Несколько ключевых правил. Во-первых, никогда не коммитьте токен в Git-репозиторий. Используйте переменные окружения или .env-файл:

# В .env файле:
TELEGRAM_TOKEN=7123456789:AAF1xY2z3W4v5U6t...

# В config.yaml:
channels:
  telegram:
    token: ${TELEGRAM_TOKEN}

Во-вторых, всегда ограничивайте список allowed_users. Если вам нужно дать доступ нескольким людям, добавьте их ID поимённо, а не отключайте проверку. В-третьих, регулярно проверяйте логи на предмет несанкционированных попыток доступа. Gateway записывает все входящие сообщения, включая Telegram ID отправителя.

Если токен скомпрометирован, немедленно отзовите его через @BotFather (команда /revoke) и сгенерируйте новый. Обновите конфигурацию OpenClaw с новым токеном и перезапустите сервис.

Управление несколькими ботами

OpenClaw поддерживает одновременную работу нескольких Telegram-ботов. Это полезно, если вы хотите разделить агентов по функциям: один бот для рабочих задач, другой — для личных, третий — для отслеживания новостей. Каждый бот подключается отдельной записью в конфигурации с уникальным именем и собственным SOUL.md:

channels:
  telegram_work:
    type: telegram
    token: ${TELEGRAM_TOKEN_WORK}
    soul: ~/.openclaw/souls/work.md
    allowed_users: [123456789]
  telegram_personal:
    type: telegram
    token: ${TELEGRAM_TOKEN_PERSONAL}
    soul: ~/.openclaw/souls/personal.md
    allowed_users: [123456789]

Каждый бот будет использовать свой файл SOUL.md, что позволяет создать совершенно разные «личности» для разных контекстов. При этом все боты работают на одном экземпляре OpenClaw и могут использовать общие инструменты и память.

Итог

Telegram-интеграция превращает OpenClaw из серверного приложения в карманного AI-ассистента. Создайте бота через @BotFather, добавьте токен в конфигурацию, ограничьте доступ по Telegram ID — и через минуту вы сможете общаться с агентом из любой точки мира. Для продвинутых сценариев используйте webhook, групповые чаты и inline-режим. И никогда не забывайте о безопасности токенов.