How to connect OpenClaw to Telegram, step by step

By the serverserv team · 7 min read · Updated 22 October 2026

Telegram is the quickest chat app to connect to OpenClaw, because it uses an official bot token instead of a QR-code login. You create a bot with BotFather, give OpenClaw the token, approve your first message and start chatting. The whole setup takes about 10 minutes. This guide walks through each step, how to use your agent in Telegram groups, how to keep strangers out, and how to fix the errors people hit most.

Before you start

• OpenClaw installed and running, with a model provider set up, such as Anthropic, OpenAI, Google or OpenRouter.
• A computer that stays on. Your bot only answers while the OpenClaw gateway is running. On a laptop it stops when the lid closes, so most people run it on a server. Our OpenClaw VPS requirements guide explains what size you need.
• A Telegram account on your phone or desktop.

Step 1: Create a bot in BotFather

1. In Telegram, search for @BotFather. Check the handle is exactly @BotFather with the blue verified tick, because there are fake copies.
2. Send /newbot.
3. Choose a display name, for example "My Assistant", then a username that ends in bot, for example my_assistant_bot.
4. BotFather replies with a token that looks like 123456789:AAE.... Copy it and keep it private: anyone with the token can control your bot.

You can also create the bot in BotFather's web app at t.me/BotFather?startapp if you prefer buttons to commands.

Step 2: Add the token to OpenClaw

The fastest way is the OpenClaw command line, on the machine where OpenClaw runs:

openclaw channels add --channel telegram --token <your-bot-token>

Or add it to your config file at ~/.openclaw/openclaw.json:

{ channels: { telegram: { enabled: true, botToken: "123456789:AAE...", dmPolicy: "pairing", groups: { "*": { requireMention: true } }, }, }, }

A third option is the TELEGRAM_BOT_TOKEN environment variable, which works for the default account only. If more than one is set, a token file wins over botToken, which wins over the environment variable. Telegram does not use the openclaw channels login command that WhatsApp uses.

Step 3: Check the gateway is running

OpenClaw normally picks up the new config on its own. Check that Telegram is connected:

openclaw channels status --probe

If the gateway is not running, start it with openclaw gateway start to run it as a background service, or openclaw gateway to run it in the current terminal. On a server, use the service so the bot keeps running after you log out.

Step 4: Approve your first message

By default OpenClaw uses pairing for Telegram: nobody can talk to your agent until you approve them. Send any message to your new bot, then on the server run:

openclaw pairing list telegram openclaw pairing approve telegram <CODE>

Pairing codes expire after one hour. Once approved, send your bot another message and your agent replies.

Using OpenClaw in Telegram groups

1. Add your bot to the group.
2. Find the group's chat ID by watching the logs with openclaw logs --follow while someone posts in the group. Group IDs usually start with -100.
3. Allow the group by adding its ID under channels.telegram.groups, or use "*" to allow every group the bot is in.
4. Send /whoami@your_bot_username in the group to confirm your user ID and the group ID.

With requireMention: true, the agent only answers when someone mentions the bot, which stops it replying to every message. If you want it to read every message, turn off privacy mode: in BotFather send /setprivacy, choose your bot and pick Disable, or make the bot a group admin. Then remove the bot from the group and add it back, because Telegram only applies the change when the bot rejoins.

Keeping your bot private

Your agent can read messages, call tools and act for you, so decide carefully who can reach it. The dmPolicy setting controls direct messages:

dmPolicy	What it does
pairing (default)	New people must be approved with a pairing code
allowlist	Only numeric Telegram user IDs listed in allowFrom can message it
open	Anyone can message it; requires "*" in allowFrom. Not recommended for a personal agent
disabled	No direct messages

For groups, groupPolicy defaults to allowlist, so only senders you allow can trigger the agent. You can also limit which tools the agent may use in a particular chat. Keep the server itself updated and use SSH keys, as covered in our guide to securing a Linux VPS.

Troubleshooting

• "getMe returned 401" at startup: the token is wrong or was revoked. Copy it again from BotFather, or generate a new one, and update it in your config.
• The bot ignores group messages: check the group is listed under channels.telegram.groups (or "*" is set), that the bot is still a member, and that you mentioned it if requireMention is on. openclaw logs --follow shows why a message was skipped.
• It only answers when mentioned, but you want every message: turn off privacy mode with /setprivacy, then remove and re-add the bot.
• Commands do nothing: your Telegram account must be approved through pairing or listed in allowFrom, even in open groups.
• "fetch failed" or "Polling stall detected" in the logs: OpenClaw retries these on its own. If they keep coming back, the server's connection to api.telegram.org is unreliable; a server in a proper data centre usually fixes it.

Want WhatsApp or Discord as well? Follow our WhatsApp and Discord setup guides. One agent can answer on all of them.

Questions

Sources

• OpenClaw Docs: Telegram
• OpenClaw Docs: Telegram setup
• OpenClaw Docs: Telegram access control
• OpenClaw Docs: Telegram troubleshooting
• Telegram: Bots introduction