OpenClaw Telegram Channel Setup

Short answer

To connect Telegram to OpenClaw:

1. Talk to @BotFather on Telegram to create a bot and get an API token.
2. Add the token to your OpenClaw .env file (TELEGRAM_TOKEN=123...).
3. Configure the TELEGRAM_ALLOWLIST in the dashboard or .env so only you can talk to the bot.
4. Restart the Gateway.

When is Telegram the right channel?

Telegram is the recommended first channel for OpenClaw users, especially in India, because:

• It is free and instant: No API approval processes (unlike WhatsApp Business).
• It has built-in security: You can easily restrict access using Telegram User IDs.
• It handles rich media: Sending images, files, and code blocks works cleanly.
• No phone number exposure: You do not need a dedicated SIM card to run a Telegram bot.

If you are building an internal tool, a personal assistant, or testing a concept, start with Telegram.

Step 1: Create the Bot via BotFather

BotFather is the official Telegram bot that creates other bots.

1. Open Telegram and search for @BotFather (look for the verified blue tick).
2. Send the message /newbot.
3. Give your bot a name (e.g., “My OpenClaw Agent”). This is what users see.
4. Give your bot a username (e.g., my_claw_agent_bot). This must end in “bot” and must be globally unique.
5. BotFather will reply with a long string of characters. This is your HTTP API Token.

Step 2: Add the token to your OpenClaw workspace

You must inject the token into the Gateway’s environment. The safest way to do this is via the .env file.

SSH into your VPS and open your OpenClaw workspace:

1 cd ~/openclaw-workspace

Open the .env file in a text editor like nano:

1 nano .env

Add or update the Telegram token line. Make sure there are no spaces around the equals sign:

TELEGRAM_TOKEN=1234567890:ABCdefGhIJKlmNoPQRstuVwXyz

Save and exit (Ctrl+O, Enter, Ctrl+X).

Step 3: Configure the Allowlist (Critical)

By default, any Telegram user who finds your bot’s username can send it messages. If your agent has tools enabled (like web search or shell execution), a random user could use your API credits or execute commands on your server.

You must configure an allowlist.

1. Find your personal Telegram User ID. You can do this by messaging a bot like @userinfobot. It will reply with a numeric ID (e.g., 987654321).
2. Open your .env file again.
3. Add the allowlist variable, using your User ID:

TELEGRAM_ALLOWLIST=987654321

If you want to allow multiple users, separate their IDs with commas (no spaces): TELEGRAM_ALLOWLIST=987654321,112233445

Step 4: Restart the Gateway and Verify

For the .env changes to take effect, you must restart the OpenClaw Gateway.

If you are running manually:

1 npx openclaw start

If you are using PM2:

1 pm2 restart openclaw

Verification:

1. Open Telegram and search for your bot’s username.
2. Click Start or send a message like “Hello”.
3. If everything is configured correctly, OpenClaw should receive the message, send it to the AI model, and reply to you in Telegram.

Common Mistakes

• Spaces in the .env file: Writing TELEGRAM_TOKEN = 123... (with spaces) will break the configuration.
• Using @username for the allowlist: The allowlist requires the numeric User ID, not your text @handle.
• Forgetting to restart: Changes to .env never apply until the Gateway process restarts.
• Bot Privacy Mode: By default, Telegram bots cannot read messages in group chats unless they are mentioned. If you add your bot to a group, you must use /setprivacy in BotFather to disable privacy mode.

Token Rotation

If you accidentally share your token, or if you suspect your server was compromised, you must rotate the token immediately.

1. Go to @BotFather in Telegram.
2. Send /revoke.
3. Select your bot.
4. BotFather will issue a new token and invalidate the old one.
5. Update your .env file with the new token.
6. Restart the OpenClaw Gateway.

What not to do

• Do not hardcode the token into any custom scripts. Always read from environment variables.
• Do not commit .env to Git. If you are tracking your workspace with Git, ensure .env is in your .gitignore file.
• Do not disable the allowlist if your agent has file access or shell execution tools enabled.

Bot not replying?

If you send a message and the bot ignores you, check the Telegram Bot Not Replying troubleshooting guide to diagnose webhook vs polling issues, API key failures, and log inspection.

Redaction Warning: If you ask for help in the community or via Setup Help, do not share your raw Telegram token or unredacted .env file. Replace sensitive data with XXX.