OpenClaw Telegram Setup: The Complete Guide (2026)
Connect Telegram to OpenClaw in 5 steps. BotFather, tokens, config, pairing, troubleshooting - everything in one page. Or skip it all with BetterClaw.
Telegram is the most popular channel for OpenClaw agents. Its free Bot API, instant push notifications, markdown support, voice messages, and cross-device availability make it the natural interface for a 24/7 AI assistant.
Setting it up on OpenClaw takes 15–30 minutes if everything goes right. When it doesn’t - wrong token format, pairing code confusion, allowFrom misconfigurations, plugin-vs-channel errors - it can eat hours.
This guide covers the full OpenClaw Telegram setup step by step. We also cover the most common errors, because most tutorials skip them.
Setting up a different channel? WhatsApp setup guide. New to OpenClaw? Read how OpenClaw works first.
What You Need
A working OpenClaw installation
Node.js, npm, and a machine running 24/7. Run npm install -g openclaw@latest and complete the onboarding wizard.
A Telegram account
You need a phone number. Download Telegram on your phone, desktop, or use the web client.
Your Telegram numeric user ID
This is not your @username. We’ll show you how to find it in Step 2.
Terminal / CLI access
The entire setup happens through the command line and JSON config files.
Create a Telegram Bot Through @BotFather
Open Telegram and search for @BotFather. Make sure it’s the official verified account with the blue checkmark.
- Send
/newbotto start the creation process. - Enter a display name for your bot - “My AI Assistant,” your name, anything descriptive.
- Enter a username. Must be unique across Telegram and end in “bot” - e.g.,
myname_openclaw_bot. - BotFather generates a bot token like
123456789:ABCdefGHIjklMNOpqrsTUVwxyz. Copy this immediately. Keep it secret.
Optional but recommended
/setdescription → select your bot → enter a description
/setuserpic → select your bot → upload a profile photo
/setcommands → select your bot → paste: help - Show available commands
This whole process takes about 2 minutes.
Get Your Numeric Telegram User ID
This is where most people make their first mistake.
OpenClaw’s allowFrom requires your numeric user ID, not your @username. Using your @username will silently fail - your bot will ignore your messages without any error.
Easiest
@userinfobot
Send /start. It replies with your numeric ID instantly.
Alternative
@RawDataBot
Send any message. Look for the id field under from.
From logs
OpenClaw logs
Message your bot, run openclaw logs --follow. ID appears in from.id.
Write this number down. You’ll need it in the next step.
Add Your Bot Token and User ID to OpenClaw
Open your config file, typically at ~/.openclaw/openclaw.json or ~/.openclaw/config.json5.
Add or update the Telegram channel configuration:
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"dmPolicy": "pairing",
"allowFrom": [YOUR_NUMERIC_USER_ID],
"groups": {
"*": {
"requireMention": true
}
}
}
}
}Replace botToken with the token from BotFather. Replace YOUR_NUMERIC_USER_ID with the number from Step 2.
Alternatively, set the token as an environment variable:
export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"Critical: channel, not plugin
Telegram is a built-in channel, not a plugin. Configure it under channels.telegram, not under plugins.entries.telegram. Putting it under plugins causes the dreaded “plugin not found: telegram” error.
Restart the Gateway
The gateway doesn’t hot-reload channel config changes. You must restart it.
openclaw gateway restartopenclaw channels statusYou should see: Telegram default: enabled, configured, running, mode:polling
If you migrated from Clawdbot or Moltbot, check for stale processes: ps aux | grep -E '(moltbot|clawdbot|openclaw).*gateway' - stop any old instances before restarting.
Send Your First Message and Pair
- Open Telegram. Find your bot by searching for the username you created in Step 1.
- Click “Start” to initiate the conversation.
- Send a message - “hello” works fine.
- With
dmPolicy: "pairing", you’ll get a response like:
OpenClaw: access not configured. Your Telegram user id: 5077021035. Pairing code: Z2EDQKMKApprove the pairing in your terminal:
openclaw pairing approve telegram Z2EDQKMKPairing codes expire after 1 hour. Send another message to get a new one if needed.
Now send another message. If it responds with an AI-generated reply, your OpenClaw Telegram setup is complete.
Your agent is live on Telegram.
The 7 Errors Everyone Hits (and How to Fix Them)
“You are not authorized to use this command”
Cause: Your allowFrom list doesn’t include your numeric user ID, or you’re using your @username instead of the numeric ID.
Fix: Get your numeric ID from @userinfobot and update allowFrom in your config. Restart the gateway.
“plugin not found: telegram”
Cause: You put the Telegram config under plugins.entries.telegram instead of channels.telegram.
Fix: Telegram is a built-in channel, not a plugin. Move the configuration to channels.telegram and restart.
HTTP 401 authentication error
Cause: Your bot token is wrong, expired, or has extra whitespace.
Fix: Go to BotFather, run /mybots, select your bot, regenerate the API token. Update your config (no extra spaces). Restart.
Bot doesn’t respond at all (no error, just silence)
Cause: Gateway not running, Telegram channel not enabled, or message stuck in pipeline.
Fix: Check openclaw gateway status, then openclaw channels status. Watch openclaw logs --follow and send a test message to see where it gets stuck.
Bot works in DM but not in groups
Cause: Groups require @mention by default, or Telegram privacy mode is blocking messages.
Fix: Either @mention the bot in group messages, or set requireMention: false. Check Telegram’s privacy mode allows full visibility.
Pairing code not appearing
Cause: dmPolicy isn’t set to “pairing” or you didn’t click “Start” in Telegram first.
Fix: Check dmPolicy in your config. Click “Start” in the Telegram chat before sending a message.
Bot stopped working after update/migration
Cause: Old Clawdbot or Moltbot gateway processes still running.
Fix: Stop all old processes: ps aux | grep -E '(moltbot|clawdbot|openclaw).*gateway'. Copy data to ~/.openclaw/ and restart.
Groups, Streaming, Multi-Bot, and Voice
Group Setup
Add your bot to a group, then configure groupPolicy: "allowlist" with specific group IDs, or use "*" as a wildcard. Group auth is separate from DM pairing.
Draft Streaming
Set streamMode: "partial" for draft bubbles in DMs. For groups, use blockStreaming: true which sends messages in chunks.
Multi-Bot
Run multiple bots from one instance using channels.telegram.accounts with unique names and tokens. Set defaultAccount for the primary bot.
Voice Messages
Send a voice note, and the agent processes it. Enable Talk Mode for hands-free interaction. No additional config needed - works if your AI provider supports audio.
Your Telegram Bot Is a Direct Line to Your Agent
Once connected, anyone who knows your bot’s username can try to interact with it. Without allowFrom, they get access to your agent - and potentially your email, files, calendar, and every tool your agent has permissions to use.
Always set allowFrom with your numeric user ID. Never leave it empty in production.
If your bot token leaks, regenerate it immediately in BotFather with /revoke. Update config and restart.
Don’t paste tokens in public repos, screenshots, or unencrypted messages.
OpenClaw has no built-in action approval. Your Telegram bot can trigger any action the agent has permissions for - including sending emails and deleting files. Learn more about OpenClaw security risks.
Connect Telegram in 1 Click. No BotFather. No Config Files.
That was a lot of steps. BotFather, tokens, JSON config files, numeric user IDs, pairing codes, gateway restarts, allowFrom lists, group policies, troubleshooting seven different error types.
Self-Hosted OpenClaw
15–30 minutes if it works. Hours if it doesn’t.
BetterClaw
Under 60 seconds. Every time.
No bot token management. No config files. No pairing codes. No gateway restarts. Security is built in - action approval workflows, encrypted credential storage, and an instant kill switch from your phone.
You still get everything that makes Telegram great for AI agents: push notifications, voice messages, group support, file sharing, cross-device access. You just don’t spend 30 minutes configuring it.
Already running self-hosted OpenClaw? See the migration guide or compare BetterClaw vs OpenClaw.
$19/month per agent · 1-click Telegram connect · No config files
OpenClaw Telegram Setup - Commands at a Glance
| Create bot | @BotFather → /newbot → copy token |
| Find your ID | @userinfobot → /start → copy numeric ID |
| Config location | ~/.openclaw/openclaw.json |
| Key config | channels.telegram.enabled: true + botToken + allowFrom |
| Restart | openclaw gateway restart |
| Check status | openclaw channels status |
| Approve pairing | openclaw pairing approve telegram [CODE] |
| Watch logs | openclaw logs --follow |
| Regenerate token | @BotFather → /mybots → API Token → Revoke |
OpenClaw Telegram Setup: Common Questions
Does the Telegram bot cost anything?
The Telegram Bot API is completely free. You pay nothing to Telegram. Your costs are OpenClaw infrastructure (hardware/VPS) and AI model API usage. With BetterClaw, it’s $19/month per agent with Telegram included.
Can I use one bot across DMs and groups?
Yes. Configure both DM and group policies in your channels.telegram config. DMs and groups have separate authorization - users approved in DMs aren’t automatically approved in groups.
Does OpenClaw work with Telegram channels (broadcast)?
Telegram channels are different from groups. OpenClaw’s primary Telegram integration is for bot DMs and groups, not broadcast channels.
Can my agent send me proactive messages?
Yes. Once paired, your agent can initiate messages to you on Telegram - reminders, alerts, task completions, scheduled reports. This works through OpenClaw’s heartbeat system.
What about Telegram voice notes?
Supported. Send a voice note to your bot, and OpenClaw processes it if your AI provider supports audio. You can enable Talk Mode for fully hands-free interaction.
Done Reading? Deploy in 60 Seconds Instead.
BetterClaw connects Telegram, Slack, Discord, WhatsApp, and 11 more channels with one click. No BotFather. No config files. No pairing codes.
$19/month per agent · 15+ channels · 1-click connect