Connect OpenClaw to Telegram

📘 Recommended first channel: Telegram is the fastest way to get your OpenClaw agent talking. New to OpenClaw? Start with the Quick Start Guide and installation, then return here to add Telegram.

Overview

OpenClaw can run as a Telegram bot so you (and anyone you allow) can chat with your self-hosted AI agent directly in Telegram-private chats or groups. You get a bot token from BotFather (Telegram’s official bot) in under a minute, add it to OpenClaw’s config or Web UI, and your agent is live. Telegram is the easiest first channel for testing and daily use.

This guide covers:

  • Creating a Telegram bot with BotFather
  • Getting and storing your bot token securely
  • Configuring the Telegram channel in OpenClaw
  • Verification and common Telegram-specific issues
  • Best practices and where to get help

Prerequisites

  • OpenClaw installed and running - Gateway and CLI working. See the Quick Start Guide or installation hub for your platform.
  • Telegram account - You need the Telegram app (mobile or desktop) and an account. No developer portal sign-up required-everything is done inside Telegram via BotFather.
  • Basic terminal/CLI - You will run openclaw config edit and optionally openclaw status.

Step 1: Create a Telegram Bot with BotFather

  1. Open Telegram and search for @BotFather (or open t.me/BotFather). Start a chat.
  2. Send the command /newbot.
  3. BotFather will ask for a display name (e.g. “My OpenClaw Agent”). This can be changed later.
  4. Then it will ask for a username, which must end in bot (e.g. my_openclaw_agent_bot). Usernames are unique; if taken, try another.
  5. When the bot is created, BotFather will reply with a token (a long string like 123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx). Copy this token-you will add it to OpenClaw. Keep it secret; anyone with the token can control your bot.

Optional: Use /setdescription and /setabout in BotFather to add a short description and “About” text for your bot so users know it’s your OpenClaw agent.

Step 2: Store the Token Securely

Do not paste the bot token directly into your config file if it might be committed to version control. Use an environment variable instead (e.g. TELEGRAM_BOT_TOKEN) and reference it in the config. Set the variable in your shell or in a .env file that is not committed. See security best practices for more.

Step 3: Configure OpenClaw for Telegram

Add the Telegram channel to your OpenClaw configuration. Exact schema may vary by OpenClaw version; refer to the official Telegram channel documentation for the current structure.

  1. Open your config (e.g. openclaw config edit or edit the config file directly).
  2. Add a channel entry for Telegram. Typically you will set:
    • Channel type (e.g. telegram)
    • Bot token - Prefer an environment variable (e.g. TELEGRAM_BOT_TOKEN) and reference it in the config so the token is not stored in plain text in the file.
  3. Save the config and restart the gateway (or let it reload if it supports hot reload).

Example (illustrative; check docs for your version):

# In your OpenClaw config, under channels (or equivalent):
# telegram:
#   token: ${TELEGRAM_BOT_TOKEN}

Set TELEGRAM_BOT_TOKEN in your environment before starting OpenClaw. For more options (e.g. allowed chats, webhook vs long polling), see the advanced configuration guide and the official Telegram channel docs.

Step 4: Verify the Connection

  1. Run openclaw status (or your CLI’s status command) and confirm the Telegram channel is listed and connected.
  2. In Telegram, open a chat with your bot (search for its username or use the link BotFather gave you). Send a message. Your OpenClaw agent should receive it and respond according to your agent and model setup.
  3. If you added the bot to a group, ensure the bot has permission to read and send messages; then send a message in the group and confirm the agent replies.

If the bot does not respond, see Common Issues below and the troubleshooting hub (and channel issues if available).

Common Telegram Issues

Issue Solution
Bot doesn’t respond to messages Gateway may not be running or Telegram channel not enabled. Run openclaw status, check logs (openclaw logs), and ensure the bot token is correct and the gateway has restarted after config change.
Invalid token / 401 Unauthorized Confirm the token from BotFather (use /token in BotFather to see the current token or regenerate). Ensure no extra spaces or quotes in config or environment. Never commit the token to git.
Connection failed / network errors Check firewall and network: OpenClaw must be able to reach Telegram’s API (api.telegram.org). If you’re behind a proxy or in a restricted region, configure proxy or use a VPS. See VPS deployment if needed.
Bot works in private chat but not in group In groups, the bot may need to be added as admin to read all messages, or you may need to enable “Group Privacy” off in BotFather (/setprivacy → disable) so the bot receives every message. Check OpenClaw docs for group behavior.
Webhook conflicts If you previously set a webhook for this bot (e.g. with another script), remove it via Telegram API or BotFather so OpenClaw can use long polling (or set the webhook to your OpenClaw endpoint per official docs).
Rate limits or slow replies Telegram enforces rate limits. For heavy use, spread messages or ensure your Gateway has enough capacity. Check OpenClaw logs for errors or throttling messages.

For more fixes (gateway, config, other channels), see the full troubleshooting hub.

Best Practices

  • Keep the bot token secret. Use environment variables (e.g. TELEGRAM_BOT_TOKEN) and follow security best practices. Rotate the token in BotFather if it is ever exposed.
  • Test in a private chat first. Verify the agent responds in a 1:1 chat before adding the bot to groups or sharing with others.
  • Understand group privacy. By default, bots in groups only see messages that start with / or that mention the bot, unless you disable “Group Privacy” in BotFather. Adjust according to your use case.
  • Stay updated. Keep OpenClaw and your Telegram adapter up to date for compatibility with Telegram API changes.
  • Monitor logs. Use openclaw logs (or your log path) to catch connection and permission errors early.

Next Steps

Related Resources