Как подключить OpenClaw к Telegram в 2026 году: бот, pairing и безопасные доступы

Подключение OpenClaw к Telegram выглядит простым: создать бота, вставить токен и запустить gateway. Технически этого иногда хватает, чтобы увидеть первый ответ. Но безопасная настройка начинается как раз после этого. Нужно решить, кто имеет право писать боту в личные сообщения, кто может запускать команды в группе, должен ли бот реагировать без упоминания и где хранится токен, который даёт полный контроль над ботом.

В этой статье разберём не только «как завести Telegram-бота», а как собрать нормальный канал для OpenClaw: с pairing на первом входе, явной allowlist для владельца, отдельным разрешением групп и коротким smoke test после перезапуска.

Короткий маршрут подключения OpenClaw к Telegram

Если сжать всю настройку до одной линии, нормальный порядок выглядит так:

BotFather -> tokenFile -> OpenClaw channel -> gateway -> DM pairing -> numeric allowlist -> group ID -> mention test -> security audit

Что понадобится до начала

• работающий OpenClaw и запущенный gateway
• доступ к серверу или VM через SSH
• Telegram-аккаунт владельца
• бот, созданный через официальный @BotFather
• понимание, будет бот работать только в личке или ещё и в группах
• возможность посмотреть логи OpenClaw

Если сам OpenClaw ещё не установлен, сначала пригодится материал про безопасный запуск OpenClaw на VM. Telegram лучше подключать уже после того, как gateway стабильно запускается и переживает restart.

Шаг 1. Создайте Telegram-бота через BotFather

Откройте Telegram и найдите официальный аккаунт @BotFather. Проверьте написание имени, затем выполните команду /newbot. BotFather попросит указать отображаемое имя и username. После создания он выдаст токен вида 123456789:AA....

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

Шаг 2. Добавьте Telegram-канал в OpenClaw

Самый быстрый CLI-вариант:

openclaw channels add --channel telegram --token <BOT_TOKEN>
openclaw gateway restart
openclaw channels status --probe
openclaw logs --follow

Команда openclaw channels add добавляет канал, после чего gateway нужно перезапустить и проверить через openclaw channels status --probe. Для Telegram не используется команда openclaw channels login telegram. Здесь нет QR-входа: OpenClaw получает доступ через bot token.

Быстрый CLI-путь удобен для первого теста. Для постоянного сервера я предпочитаю отделить секрет от основной конфигурации и использовать tokenFile. Так токен меньше рискует попасть в diff, backup конфигурации или случайный вывод команды.

Как сохранить токен в отдельный файл

mkdir -p ~/.config/openclaw/secrets
chmod 700 ~/.config/openclaw/secrets
read -rsp "Bot token: " TELEGRAM_TOKEN; echo
printf '%s' "$TELEGRAM_TOKEN" > ~/.config/openclaw/secrets/telegram-token
unset TELEGRAM_TOKEN
chmod 600 ~/.config/openclaw/secrets/telegram-token

Файл должен быть обычным файлом с ограниченными правами. В актуальной конфигурации OpenClaw символические ссылки для tokenFile не принимаются. Также проверьте, что пользователь, под которым работает gateway, действительно может читать этот файл.

Шаг 3. Первый вход через pairing

Для первого подключения удобно оставить dmPolicy: "pairing". Неизвестный пользователь пишет боту, получает короткий код, а владелец подтверждает этот код на сервере. Пока запрос не одобрен, сообщение пользователя не передаётся агенту как обычная команда.

{
  channels: {
    telegram: {
      enabled: true,
      tokenFile: "/home/<user>/.config/openclaw/secrets/telegram-token",
      dmPolicy: "pairing"
    }
  }
}

После перезапуска gateway напишите боту в личные сообщения, затем выполните:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Pairing-код действует один час. Если код устарел, отправьте боту новое сообщение и повторите проверку списка запросов.

Шаг 4. Узнайте числовой Telegram user ID

Для устойчивой настройки лучше использовать числовой Telegram user ID, а не username. Username можно изменить, а числовой идентификатор остаётся привязанным к аккаунту.

Самый спокойный способ без сторонних ботов:

1. откройте отдельный SSH-сеанс;
2. запустите openclaw logs --follow;
3. отправьте сообщение своему боту;
4. найдите поле from.id в событии Telegram.

Альтернативный официальный способ - запрос Bot API getUpdates. Но токен в URL может остаться в истории shell, поэтому для личного сервера логи OpenClaw обычно аккуратнее. Сторонние боты для определения ID работают, но передают часть информации дополнительному сервису, поэтому это не мой первый выбор.

Шаг 5. Переведите личного бота на явную allowlist

Pairing удобен для первого входа, но для личного бота с одним владельцем лучше явно записать числовой ID в allowFrom и использовать dmPolicy: "allowlist". Тогда доступ не зависит только от старых pairing-записей в state.

{
  channels: {
    telegram: {
      enabled: true,
      tokenFile: "/home/<user>/.config/openclaw/secrets/telegram-token",
      dmPolicy: "allowlist",
      allowFrom: ["123456789"],
      groupPolicy: "allowlist",
      groups: {
        "-1001234567890": {
          requireMention: true
        }
      }
    }
  },
  commands: {
    ownerAllowFrom: ["telegram:123456789"]
  }
}

В примере нужно заменить:

• /home/<user>/... на реальный путь пользователя gateway;
• 123456789 на ваш Telegram user ID;
• -1001234567890 на ID вашей группы или временно удалить блок groups, если группы не нужны.

Отдельная запись commands.ownerAllowFrom задаёт оператора для owner-only команд и подтверждений. Если первый pairing выполнялся на чистой конфигурации, OpenClaw может добавить владельца автоматически, но явная запись делает модель доступа понятнее при переносе, восстановлении и аудите.

Шаг 6. Добавьте OpenClaw в Telegram-группу

Для группы нужны два разных идентификатора, и именно здесь чаще всего начинается путаница:

• Telegram user ID - кто из людей имеет право запускать бота;
• group chat ID - в какой группе бот вообще принимает сообщения.

ID супергруппы обычно отрицательный и начинается с -100. Он указывается как ключ внутри channels.telegram.groups. Его нельзя помещать в groupAllowFrom. В allowlist пользователей идут положительные числовые user ID.

Как узнать group chat ID

1. добавьте бота в нужную группу;
2. запустите openclaw logs --follow;
3. упомяните бота в группе, например @bot_username ping;
4. найдите числовой chat.id;
5. добавьте этот ID в channels.telegram.groups и перезапустите gateway.

После того как группа разрешена, командой /whoami@bot_username можно дополнительно проверить user ID и group ID прямо из Telegram.

Pairing в личке не разрешает команды в группе

Это важная граница безопасности. Подтверждённый DM pairing означает, что пользователь может общаться с ботом в личке. Он не получает автоматическое право командовать ботом в любой группе. Для групп OpenClaw смотрит на явную конфигурацию: список групп, groupPolicy, groupAllowFrom или fallback на allowFrom.

Для одного владельца удобный шаблон такой: ваш user ID находится в allowFrom, отдельный groupAllowFrom не задан, а разрешённые chat ID перечислены в groups. Тогда тот же владелец может работать и в личке, и в выбранных группах.

Privacy Mode и requireMention: что выбрать

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

Для личного рабочего контура это хороший дефолт. Оставьте requireMention: true и обращайтесь к боту через @bot_username. Так агент не реагирует на случайный разговор и не расходует модельный контекст на весь чат.

Когда нужно отключать Privacy Mode

Только если OpenClaw должен видеть обычные сообщения группы без упоминания. Тогда в BotFather используется /setprivacy -> Disable. После изменения режима удалите бота из каждой группы и добавьте снова, иначе Telegram может не применить новое поведение к уже добавленному участнику.

Второй вариант - сделать бота администратором группы. Администратор получает более широкую видимость сообщений. Но не выдавайте административные права «на всякий случай». Права должны соответствовать реальным действиям, которые бот выполняет.

Обязательный smoke test после настройки

Сначала проверьте состояние самого OpenClaw:

openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw security audit
openclaw logs --follow

Затем пройдите живой сценарий:

1. владелец пишет боту в личку и получает ответ;
2. неразрешённый пользователь не получает доступ к агенту;
3. в разрешённой группе бот отвечает на @mention;
4. обычное сообщение без упоминания игнорируется при requireMention: true;
5. после openclaw gateway restart канал поднимается снова;
6. openclaw channels status --probe показывает рабочее соединение;
7. в логах нет постоянных ошибок Telegram API.

Почему OpenClaw не отвечает в Telegram

1. В личке появился код, но ответа нет

Проверьте openclaw pairing list telegram и подтвердите запрос. При политике pairing первое сообщение неизвестного пользователя не обрабатывается как обычный запрос до одобрения.

2. Ошибка getMe returned 401

Telegram отклонил токен. Скопируйте актуальный токен из BotFather или перевыпустите его, обновите tokenFile, botToken или переменную окружения и перезапустите gateway.

3. Бот отвечает в личке, но молчит в группе

Проверьте сразу четыре слоя: есть ли group ID в groups, разрешён ли ваш user ID, требуется ли упоминание и видит ли бот нужные сообщения при текущем Privacy Mode.

4. В groupAllowFrom записан отрицательный ID

Это group chat ID, а не user ID. Перенесите его в channels.telegram.groups. В groupAllowFrom должны находиться числовые ID пользователей, которым разрешено запускать бота внутри группы.

5. После обновления старая allowlist перестала работать

Современная конфигурация ожидает числовые Telegram user ID. Если в старом конфиге остались записи вида @username, выполните openclaw doctor --fix, проверьте результат и замените их явными числами. После обновлений полезно также пройти чеклист безопасного обновления OpenClaw.

6. Ошибки сети, DNS или IPv6

Если в логах появляются fetch failed, ошибки getUpdates или setMyCommands, проверьте доступ сервера к api.telegram.org. Причиной может быть DNS, нерабочий IPv6-маршрут, firewall или неверно настроенный proxy. Не лечите сетевую ошибку изменением allowlist - это другой слой.

7. Ошибка BOT_COMMANDS_TOO_MUCH

В меню Telegram зарегистрировано слишком много native, plugin или custom commands. Сократите меню либо отключите native command menu для Telegram. Сами команды навыков могут продолжить работать при ручном вводе, даже если их нет в меню.

Безопасная конфигурация для одного владельца

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

• токен хранится отдельно и доступен только пользователю gateway;
• в личке используется dmPolicy: "allowlist";
• в allowFrom записан только ваш числовой user ID;
• owner-only команды привязаны через commands.ownerAllowFrom;
• группы перечислены явными chat ID;
• в группах включён requireMention: true;
• Privacy Mode остаётся включённым, пока нет реальной причины читать весь чат;
• после изменений запускаются probe, security audit и живой smoke test.

Частые вопросы

Нужен ли webhook для Telegram?

Нет. OpenClaw использует long polling по умолчанию. Для обычного личного бота не нужен публичный HTTPS endpoint и не нужно открывать дополнительный порт. Webhook имеет смысл только в осознанной инфраструктурной схеме.

Pairing или allowlist - что лучше?

Pairing удобен для первого входа и разовой выдачи доступа. Для личного бота с одним владельцем явная числовая allowlist проще для аудита, переноса и восстановления.

Можно ли разрешить бота всей группе?

Можно задать открытый режим внутри конкретной разрешённой группы, но тогда любой участник этой группы сможет запускать бота. Для рабочего агента с файловыми, shell или административными инструментами это обычно слишком широкое доверие.

Что делать при утечке токена?

Сразу перевыпустите токен через BotFather, замените секрет, перезапустите gateway и проверьте логи. Простая смена allowFrom не обезвреживает украденный bot token.

Итог

Подключить OpenClaw к Telegram несложно. Сложнее не перепутать транспорт и доступ. Bot token подключает самого бота, pairing разрешает первый DM, allowFrom фиксирует конкретных пользователей, а groups определяет разрешённые чаты. Когда эти слои разделены, настройка становится понятной и нормально переживает restart, обновление и перенос на другую VM.

Если сжать всё до одного правила: сначала сделайте закрытый контур для одного владельца, проверьте его в личке и только потом добавляйте группы, постоянное чтение сообщений и других пользователей.

Официальные источники

• Документация OpenClaw по Telegram
• Документация OpenClaw по pairing
• Официальная документация Telegram Bots