Канал
Интеграции

Подключение Telegram к OpenClaw

open-claw.su · 6 февраля 2026 г. · Обновлено: 11 февраля 2026 г.

telegramмессенджерыинтеграциинастройкаботtelegram-бот

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

Создание Telegram-бота

Шаг 1. Откройте BotFather

Найдите @BotFather в Telegram и начните диалог.

Шаг 2. Создайте бота

Отправьте команду /newbot и следуйте инструкциям:

  1. Придумайте имя бота (например, «Мой ассистент»)
  2. Придумайте username — уникальный идентификатор, заканчивающийся на bot (например, my_assistant_bot)

Шаг 3. Получите токен

BotFather пришлёт токен вида:

123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Сохраните его — это ключ доступа к вашему боту.

Шаг 4. Настройте бота (опционально)

Полезные команды BotFather:

КомандаЧто делает
/setdescriptionОписание бота (видно при первом открытии)
/setabouttextТекст «О боте» в профиле
/setuserpicАватарка бота
/setcommandsМеню команд

Базовая настройка OpenClaw

Добавьте токен в openclaw.json

Источник: конфигурация каналов из официальной документации и страницы Telegram.

// ~/.openclaw/openclaw.json
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      dmPolicy: "pairing",    // pairing | allowlist | open | disabled
    },
  },
}

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

Альтернативный способ: через CLI

Если вы используете Docker, канал можно добавить через командную строку:

openclaw-cli channels add --channel telegram --token "<ваш-токен-бота>"

Ограничьте доступ

Для режима allowlist — только указанные пользователи могут общаться с ботом:

{
  channels: {
    telegram: {
      botToken: "YOUR_TOKEN",
      dmPolicy: "allowlist",
      allowFrom: [
        123456789,      // Ваш Telegram ID
        987654321,      // ID друга/коллеги
      ],
    },
  },
}

Как узнать свой Telegram ID:

  1. Напишите боту @userinfobot
  2. Он пришлёт ваш числовой ID

Запустите агента

openclaw gateway --port 18789

Напишите что-нибудь боту — он должен ответить.

Продвинутые настройки

Примечание: настройки ниже описывают возможности Telegram-интеграции OpenClaw. Полный список полей конфигурации смотрите в официальной документации.

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

// ~/.openclaw/openclaw.json
{
  channels: {
    telegram: {
      botToken: "YOUR_TOKEN",

      // Контроль доступа
      allowFrom: [123456789],
      allowedGroups: [],          // ID групп, где бот может работать
      adminUsers: [123456789],    // Могут управлять ботом

      // Поведение
      typingIndicator: true,      // Показывать «печатает...»
      readReceipts: true,         // Отмечать сообщения прочитанными
      replyInThread: true,        // Отвечать в тредах (если это ответ)

      // Обработка сообщений
      handleEdits: true,          // Реагировать на редактирование
      handleForwards: false,      // Игнорировать пересланные сообщения
      maxMessageLength: 4096,     // Разбивать длинные ответы

      // Медиа
      handlePhotos: true,         // Принимать фото
      handleDocuments: true,      // Принимать файлы
      handleVoice: true,          // Принимать голосовые (требует whisper)

      // Rate limiting
      rateLimit: {
        messagesPerMinute: 20,
        cooldownMessage: "Слишком много сообщений, подождите немного.",
      },
    },
  },
}

Несколько пользователей

{
  channels: {
    telegram: {
      botToken: "YOUR_TOKEN",
      allowFrom: [
        123456789,    // Алексей
        234567890,    // Мария
        345678901,    // Иван
      ],

      // Разные права
      adminUsers: [
        123456789,    // Только Алексей — админ
      ],
    },
  },
}

Админы могут:

  • Перезапускать агента командой /restart
  • Очищать память командой /clear
  • Смотреть логи командой /logs

Работа в группах

{
  channels: {
    telegram: {
      botToken: "YOUR_TOKEN",
      allowedGroups: [
        -1001234567890,    // ID группы (начинается с -100)
      ],

      groupSettings: {
        trigger: "@",              // Реагировать только на упоминание
        replyToAll: false,         // Не отвечать на все сообщения
        mentionRequired: true,     // Требовать @username бота
      },
    },
  },
}

Как узнать ID группы:

  1. Добавьте бота @getidsbot в группу
  2. Он покажет ID группы

Команды бота

Настройте меню команд через BotFather (/setcommands):

start - Начать диалог
help - Справка
clear - Очистить контекст
status - Статус агента

И обработайте их в SOUL.md:

# Команды

- /start — поприветствуй пользователя и расскажи о своих возможностях
- /help — покажи список доступных команд
- /clear — очисти контекст текущего разговора, подтверди очистку
- /status — покажи свой статус (модель, версия, время работы)

Работа с медиафайлами

Приём фото

{
  channels: {
    telegram: {
      handlePhotos: true,
      photoSettings: {
        analyze: true,           // Анализировать через vision
        saveTo: "./media/",      // Сохранять локально
        maxSizeMb: 10,
      },
    },
  },
}

С включённым analyze: true агент сможет «видеть» и описывать фотографии (требуется модель с vision, например Claude).

Отправка файлов

Агент может отправлять файлы через скилл:

// skills/send-file.js
export const manifest = {
  name: "send_file",
  description: "Отправляет файл пользователю в Telegram"
};

export async function execute({ path }, context) {
  await context.gateway.sendDocument(context.chatId, path);
  return { sent: true };
}

Голосовые сообщения

{
  channels: {
    telegram: {
      handleVoice: true,
      voiceSettings: {
        transcribe: true,        // Расшифровывать в текст
        provider: "whisper",     // whisper | google | azure
        language: "ru",
      },
    },
  },
}

Агент получит текст голосового сообщения и сможет ответить.

Webhook vs Polling

Polling (по умолчанию)

Агент периодически спрашивает Telegram: «Есть новые сообщения?»

{
  channels: {
    telegram: {
      mode: "polling",
      pollingInterval: 1000,    // мс между запросами
    },
  },
}

Плюсы: работает за NAT, не нужен домен Минусы: небольшая задержка, нагрузка на сеть

Webhook

Telegram сам присылает сообщения на ваш сервер.

{
  channels: {
    telegram: {
      mode: "webhook",
      webhookUrl: "https://your-domain.com/telegram/webhook",
      webhookPort: 8443,
      sslCert: "/path/to/cert.pem",
      sslKey: "/path/to/key.pem",
    },
  },
}

Плюсы: мгновенная доставка, меньше трафика Минусы: нужен публичный IP и SSL-сертификат

Для большинства случаев polling — оптимальный выбор.

Несколько ботов

Можно запустить несколько Telegram-ботов:

{
  channels: {
    telegramPersonal: {
      type: "telegram",
      botToken: "BOT_1_TOKEN",
      allowFrom: [123456789],
    },

    telegramWork: {
      type: "telegram",
      botToken: "BOT_2_TOKEN",
      allowFrom: [234567890, 345678901],
    },
  },
}

Каждый бот будет работать независимо, но использовать общую память и скиллы.

Отладка

Тестовый режим

{
  channels: {
    telegram: {
      debug: true,    // Подробные логи
      dryRun: true,   // Не отправлять сообщения (только логировать)
    },
  },
}

Типичные проблемы

«Unauthorized» или «Token invalid»

  • Проверьте токен — скопируйте заново из BotFather
  • Убедитесь, что бот не заблокирован

Бот не отвечает в группе

  • Добавьте ID группы в allowed_groups
  • Проверьте mentionRequired — возможно, нужно упомянуть бота

«Too many requests»

  • Telegram ограничивает частоту запросов
  • Увеличьте pollingInterval или настройте rateLimit

Сообщения приходят с задержкой

  • Нормально для polling — задержка 1-2 секунды
  • Для мгновенной доставки используйте webhook

Безопасность

Не публикуйте токен

Токен бота — это полный доступ к нему. Если токен утёк:

  1. Откройте BotFather
  2. Отправьте /revoke
  3. Выберите бота
  4. Получите новый токен
  5. Обновите openclaw.json

Ограничивайте доступ

Всегда используйте allowFrom или allowedGroups. Публичный бот без ограничений — риск.

Храните токен безопасно

Используйте переменные окружения вместо хранения токена в конфигурации:

export TELEGRAM_BOT_TOKEN="123456789:ABCdef..."
openclaw gateway --port 18789

Что дальше

Следите за OpenClaw на русском

Разбираем обновления, пишем гайды, делимся кейсами

Подписаться на канал Задать вопрос в чате
Присоединяйтесь к сообществу
Канал
Обновления и гайды
Чат
Вопросы и обсуждения