OpenClaw Telegram Bot: Build a Fully Automated Agent in Minutes

Most developers waste an afternoon fighting Telegram's bot API documentation when the OpenClaw Telegram channel abstracts all of it. Three commands and a bot token are all that stand between you and a 24/7 AI agent that your users can reach from any device on the planet.

Why Telegram Is the Best First Channel for OpenClaw

Telegram has 950 million monthly active users as of early 2025, but that's not the reason to start here. The reason is the bot API. Telegram's bot platform is mature, stable, free, and requires zero payment setup or business verification. WhatsApp requires a Meta Business account and API approval. Discord requires a server. SMS costs money per message. Telegram gives you a production-ready channel in minutes with no gating whatsoever.

The polling model is the other big advantage. OpenClaw's Telegram integration uses long polling by default — the gateway reaches out to Telegram's servers and asks for new messages. This means your bot works from behind NAT, from a home server, from a cloud VM with no inbound firewall rules. No webhook setup. No SSL certificate required for local testing.

Here's what most guides don't tell you: Telegram also queues messages while your bot is offline. When the gateway restarts, it picks up any messages that arrived during downtime and processes them in order. This makes Telegram particularly forgiving during development when you're restarting the gateway constantly.

Prerequisites Before You Start

You need three things before running the setup commands:

• OpenClaw installed and the gateway running — if you haven't completed basic installation, start with the installation guide first
• A Telegram account — personal account works fine; no business verification needed
• The Telegram mobile or desktop app — you'll use it to talk to BotFather and test your bot

That's it. No API keys to purchase, no domain to register, no business account to create. This is why Telegram is the recommended first channel for new OpenClaw users.

Step-by-Step: Creating and Registering Your Telegram Bot

Step 1: Create Your Bot With BotFather

Open Telegram and search for @BotFather — the official bot creation tool run by Telegram. Send it the command /newbot. BotFather will ask for two things: a display name (anything you like) and a username (must end in "bot", e.g. myagent_bot). After you set both, BotFather sends you a token that looks like this:

7123456789:AAH4s8xKpQ-mT3nR_example_token_here

Copy this token. You'll need it in the next step. Keep it private — anyone with this token controls your bot.

Step 2: Add the Telegram Channel to OpenClaw

With the OpenClaw gateway running, register the Telegram channel using the CLI:

openclaw channels add telegram --token 7123456789:AAH4s8xKpQ-mT3nR_example_token_here

OpenClaw will validate the token against the Telegram API, register the channel, and start polling immediately. The terminal output should confirm the channel ID assigned to this bot.

Step 3: Assign the Channel to an Agent

A registered channel does nothing until it's connected to an agent. Open your agent configuration file and add the channel to the agent's channel list:

# In your agent config (agents/my-agent/config.yaml)
channels:
  - telegram-default

# Or specify a custom channel ID you assigned
channels:
  - my-telegram-bot

Reload the agent configuration:

openclaw agents reload my-agent

Step 4: Set Your Bot's Description and Commands (Optional but Recommended)

Back in BotFather, use /setdescription to add a short description to your bot, and /setcommands to register slash commands that appear in the Telegram command menu. A basic command list that works well with OpenClaw agents:

/start - Start the conversation
/help - Get help
/status - Check agent status
/clear - Clear conversation history

OpenClaw's Telegram channel handles these commands natively. The /clear command wipes the conversation context for that user, which is useful during testing.

Step 5: Keep the Bot Online With a Process Manager

The bot only works while the OpenClaw gateway is running. For anything beyond quick testing, run the gateway under a process manager so it survives reboots and crashes:

# Using systemd (Linux)
sudo systemctl enable openclaw-gateway
sudo systemctl start openclaw-gateway

# Using PM2 (cross-platform)
pm2 start "openclaw gateway start" --name openclaw-gateway
pm2 save
pm2 startup

Testing and Verifying Your Telegram Bot

Open Telegram and search for your bot by username — the one you set in BotFather. Send /start. If everything is configured correctly, the agent responds within a few seconds.

Sound familiar? That's the exact moment most setups break — the bot doesn't respond. Here's how to diagnose it fast:

# Check channel status
openclaw channels status

# View live logs for the Telegram channel
openclaw logs --channel telegram --follow

# Verify the agent has the channel assigned
openclaw agents show my-agent

The most common cause of a non-responding bot is the agent not having the channel ID in its channels list. The second most common cause is a typo in the token — Telegram returns a 401 error which appears clearly in the logs.

Verifying Multi-User Behavior

Have a second Telegram account send a message to your bot simultaneously. Both conversations should receive responses independently — OpenClaw handles concurrent sessions per user ID. If you want to restrict access to specific users, add an allowlist to your agent configuration:

# In your agent config
telegram:
  allowed_user_ids:
    - 123456789
    - 987654321

Any user not on the allowlist receives no response — the message is silently dropped. For private bots, this is the right approach.

Common Mistakes With OpenClaw Telegram Bots

• Not assigning the channel to an agent — registering a channel just creates the connection. The agent must explicitly list the channel ID in its configuration or the bot will never respond.
• Running the gateway in a terminal that gets closed — the gateway stops when the terminal session ends. Use systemd, PM2, or nohup openclaw gateway start & for persistent operation.
• Using the same token in development and production — one token, one active poller. If two instances try to poll with the same token, only one gets messages. Always create separate bots for dev and prod.
• Ignoring the conversation context limits — by default, OpenClaw keeps a sliding window of conversation history per user. For long sessions, older context gets dropped. If your agent needs full history, configure a persistent memory backend.
• Sending bot messages to the wrong Telegram entity — bots can't initiate conversations with users they've never heard from. The user must send the first message. Bots can message groups and channels they've been added to, but direct messages require the user to start first.

Frequently Asked Questions

Do I need a server to run an OpenClaw Telegram bot?

You need a machine running the OpenClaw gateway — a $5 VPS, a home server, or even a local machine with a tunnel. The bot polls Telegram's servers, so no public IP is required for basic setups. For production reliability, a cloud VPS is the right call.

How do I get a Telegram bot token for OpenClaw?

Open Telegram, search for @BotFather, and send /newbot. Follow the prompts to set a name and username. BotFather replies with your bot token — a string in the format 123456:ABC-DEF... Copy this token and use it in the openclaw channels add telegram command.

Can multiple users message the same OpenClaw Telegram bot?

Yes, by default OpenClaw handles concurrent users on a single Telegram channel. Each user gets their own conversation context. You can restrict access to specific Telegram user IDs in your agent config if you want a private bot for a single user or a defined team.

How do I test that my OpenClaw Telegram bot is working?

After running openclaw channels add telegram, send /start to your bot in Telegram. If the bot replies, the channel is live. Run openclaw channels status to see the connection state. Check openclaw logs --channel telegram for any errors if the bot doesn't respond.

What happens if the OpenClaw gateway goes offline mid-conversation?

Telegram queues messages while the gateway is offline. When the gateway restarts and the channel reconnects, it picks up queued messages and processes them in order. The user sees a delayed reply. For critical bots, run the gateway under a process manager like systemd or PM2 to minimize downtime.

Can I run more than one Telegram bot with OpenClaw?

Yes. Create multiple bots in BotFather, each with a unique token. Register each one as a separate channel with a distinct channel ID: openclaw channels add telegram --token TOKEN_A --id bot-a and a second command for bot-b. Each maps to its own agent configuration.