Why Telegram is the easiest OpenClaw channel
Telegram support ships with OpenClaw, so there's no plugin to install.
One bot token from @BotFather. No phone number, QR code or business account.
OpenClaw uses long polling by default, so it works on a laptop or behind a firewall.
Buttons, live-updating replies, voice notes, topics and a Control UI mini app.
You need OpenClaw installed with an AI model connected. New? Start with the install guide.
Create a bot with @BotFather
- Open Telegram and search for @BotFather. Check it has the blue verification tick. You can also use BotFather's web app at
t.me/BotFather?startapp. - Send
/newbot. - Choose a display name, for example "My OpenClaw".
- Choose a username that ends in
bot, for examplemy_openclaw_bot. - Copy the token BotFather sends. It looks like
123456789:AAH….
Anyone with your bot token can control the bot. Never post it publicly. If it leaks, send /revoke to @BotFather to get a new one, then update OpenClaw.
Give OpenClaw the bot token
openclaw channels add --channel telegram --token <bot-token>{
channels: {
telegram: {
enabled: true,
botToken: "123456789:AAH...",
dmPolicy: "pairing",
},
},
}Then run openclaw gateway restart.
export TELEGRAM_BOT_TOKEN="123456789:AAH..."To keep it for the background service, add TELEGRAM_BOT_TOKEN=... to ~/.openclaw/.env.
Check that Telegram is ready
openclaw channels status --probeThis confirms the token works and OpenClaw can reach Telegram.
Message your bot and approve yourself
Open your bot in Telegram (search for its username), tap Start and send a message. Because the default policy is pairing, the bot replies with a pairing code and your Telegram user ID. Note the ID, because you'll need it in step 5.
Example reply. The exact wording may differ.
Your Telegram user id: 482913775
Approve it on the computer running OpenClaw:
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>Send another message. Your assistant now answers.
Lock down who can use the bot
Telegram bots are public. Anyone can find yours by username. Choose a direct-message policy:
dmPolicy | What it does | Use when |
|---|---|---|
| pairing default | Unknown users get a code and wait for your approval | You'll add people over time |
| allowlist | Only user IDs in allowFrom can chat. Everyone else is ignored. | A private, personal bot (most secure) |
| open | Anyone who finds the bot can use it | Public bots with tightly restricted tools only |
| disabled | Blocks all direct messages | Group-only bots |
allowFrom needs your numeric Telegram user ID, such as 482913775. A phone number, @username, group ID or the bot's own ID won't work. The pairing reply in step 4 shows your ID.
Telegram config builder
Enter your numeric user IDs and, optionally, group chat IDs. Copy the result into ~/.openclaw/openclaw.json.
Add your OpenClaw bot to Telegram groups
- Add the bot to the group from the group's member list.
- Find the group chat ID. Supergroups use negative IDs that start with
-100. It appears in OpenClaw's logs when the group sends a message. - Allow the group under
channels.telegram.groupswithgroupPolicy: "allowlist". Use the builder above. - Decide what it can see. By default, Telegram's privacy mode only shows bots messages that mention them or are commands. To let it see all messages, send
/setprivacyto @BotFather and disable it, or make the bot a group admin.
Keep requireMention: true so the bot only replies when someone types its @username, not to every message.
OpenClaw features on Telegram
Tap to approve actions or pick options, with no typing.
Answers stream in by editing the message as it's written.
Send /dashboard to open the Control UI inside Telegram.
Each topic in a forum group gets its own session.
Send voice notes, video notes and photo albums.
Share places and venues. OpenClaw sees your reactions.
Long polling is the default. For high-traffic bots on a public server, OpenClaw also supports webhook mode with webhookUrl and webhookSecret.
Telegram on Docker or a VPS
Telegram is the ideal VPS channel because OpenClaw connects out to Telegram, so you don't need to open any inbound ports. With Docker:
docker compose run --rm openclaw-cli channels add --channel telegram --token "<bot-token>"See the Docker guide and VPS guide.
Fix common Telegram bot problems
Bot doesn't replyRun openclaw channels status --probe, then check openclaw pairing list telegram for a waiting request.
Ignored after switching to allowlistMake sure allowFrom has your numeric user ID, not your @username or phone number.
Conflict: terminated by other getUpdatesTwo programs are using the same bot token. Run only one OpenClaw gateway per bot, or create a second bot.
Silent in groupsCheck the group is in channels.telegram.groups, mention the bot, and review privacy mode with /setprivacy.
Unauthorized / invalid tokenThe token was mistyped or revoked. Get a fresh one from @BotFather and add it again.
Stops when the laptop sleepsReplies need the gateway running. Use an always-on machine or a VPS.
More fixes: troubleshooting guide.
OpenClaw Telegram questions
How do I connect OpenClaw to Telegram?
Create a bot with @BotFather using /newbot, then run openclaw channels add --channel telegram --token followed by your token. Message your bot and approve yourself with openclaw pairing approve telegram and the code it sends.
Is Telegram free to use with OpenClaw?
Yes. Telegram bots are free, and Telegram support is bundled with OpenClaw. You only pay for the AI model you connect.
How do I find my Telegram user ID for OpenClaw?
Message your bot while dmPolicy is pairing. The pairing reply shows "Your Telegram user id". Use that numeric ID in allowFrom, not your username or phone number.
Do I need to open ports for Telegram?
No. OpenClaw uses long polling by default, so it connects out to Telegram and works behind firewalls and on servers with no open ports. Webhook mode is optional.
How do I stop strangers using my OpenClaw bot?
Keep dmPolicy on pairing, or switch to allowlist and put only your numeric user IDs in allowFrom. Avoid the open policy unless the bot's tools are tightly restricted.
Can my OpenClaw bot work in Telegram groups?
Yes. Add it to the group, allow the group's chat ID under channels.telegram.groups and keep requireMention on. To let it see every message, disable privacy mode with /setprivacy or make it an admin.