On this page
🏆 Why Telegram?
| Advantage | Details |
|---|---|
| No public IP needed | Uses long-polling — works behind NAT, firewalls, on local machines. No port forwarding required. |
| 2-minute setup | BotFather gives you a token instantly. No app review, no business verification, no OAuth dance. |
| Rich media | Voice notes, images, files, stickers, location sharing, video — all supported natively. |
| Survives reboots | Token-based auth means you never need to re-scan QR codes (unlike WhatsApp). |
| Group support | Add your bot to groups with mention-based activation and per-group policies. |
| Cross-platform | Works on iOS, Android, desktop, and web — same bot everywhere. |
✅ Community consensus: Telegram is the channel most OpenClaw users start with and many never leave. It's stable, fast, and feature-rich with the lowest setup friction of any channel.
🤖 Create a bot with BotFather
- Open Telegram and search for @BotFather (verify the blue checkmark)
- Send
/newbot - Choose a display name (e.g., “My OpenClaw”)
- Choose a username ending in
bot(e.g.,my_openclaw_bot) - Copy the token (looks like
123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
⚠️ Treat this token like a password. Anyone with it has full control of your bot. Never commit it to version control or share it publicly. If compromised, regenerate via BotFather's
/revoke command.⚙️ Configure OpenClaw
Option A: During onboarding
Select “Telegram (Bot API)” when the wizard asks for a channel. Paste your token when prompted.
Option B: Manual config
// ~/.openclaw/openclaw.json
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123456789:ABCdefGHI...",
"dmPolicy": "pairing"
}
}
}
Option C: Environment variable
export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHI..."
Then restart the gateway: openclaw gateway restart
💡 Note: Telegram does not use
openclaw channels login telegram. Just configure the token and start the gateway — it connects automatically via long-polling.🔐 Pairing & allowlists
With dmPolicy: "pairing" (default), unknown users get a pairing code when they message your bot:
# Approve a pairing request
openclaw pairing approve telegram <code>
# List approved users
openclaw pairing list
# Revoke access
openclaw pairing revoke telegram <user-id>
Find your Telegram user ID
- DM your bot → check
openclaw logs --follow→ look forfrom.id - Or message @userinfobot on Telegram
Switch to allowlist (skip pairing)
{
"channels": {
"telegram": {
"dmPolicy": "allowlist",
"allowFrom": ["123456789"]
}
}
}
⚠️ Never use
dmPolicy: "open" unless you want anyone on Telegram to use your agent (and burn your API credits). See Security Guide.👥 Group chats
Add your bot to a Telegram group, then configure access:
{
"channels": {
"telegram": {
"groups": {
"*": {
"requireMention": true
},
"-1001234567890": {
"requireMention": false,
"activation": "always"
}
}
}
}
}
The * wildcard applies to all groups. Override specific groups by their numeric ID.
💡 Privacy Mode: Telegram bots default to Privacy Mode — they only see messages that @mention them or start with
/. If your bot must see all group messages, disable Privacy Mode via BotFather: /setprivacy → OFF. OpenClaw expects full message access by default.✨ Telegram-specific features
| Feature | Status | Notes |
|---|---|---|
| Text messages | ✅ Full | Markdown formatting, code blocks |
| Voice notes | ✅ Full | Send and receive — great for hands-free use |
| Images / photos | ✅ Full | Send and receive with captions |
| Files / documents | ✅ Full | PDFs, spreadsheets, code files |
| Stickers | ✅ Cached | Described once via vision, cached in sticker-cache.json |
| Video notes | ✅ Full | Circular video messages (no captions, text sent separately) |
| Location sharing | ✅ Full | Share and receive locations |
| Inline buttons | ✅ Full | Agent can send interactive button responses |
| Reply threading | ✅ Full | Maintains context in reply chains |
| Slash commands | ✅ Full | /status, /model, /reset, etc. |
📋 Streaming & forum topics
v2026.3.2+: New Telegram setups default to live streaming (channels.telegram.streaming: "partial"). You see responses word-by-word in DMs and private chats without extra config.
Telegram forum-style private chats (Topics mode) also enable draft streaming — you see the agent's response appearing word by word instead of waiting for the full reply. This requires Bot API 9.3+ and a forum-enabled group.
For cron job delivery to forum topics, use the topic ID format:
--to "-100GROUPID:topic:TOPICID"
🎨 BotFather customization
Optional but recommended — makes your bot look professional:
/setuserpic — Upload a profile picture
/setdescription — "AI assistant powered by OpenClaw"
/setabouttext — Shown in the bot's profile
/setcommands — Register slash commands for autocomplete:
status - Show session status
model - Switch AI model
reset - Reset conversation
help - Show available commands
🔧 Troubleshooting
| Problem | Fix |
|---|---|
| Bot doesn't respond | Check token is correct. Run openclaw logs --follow and send a message — look for errors. |
| 401 Unauthorized in logs | Token is wrong or revoked. Regenerate via BotFather /revoke and update config. |
| “plugin not found” error | Telegram is a built-in channel, not a plugin. Put config under channels.telegram, NOT plugins.entries.telegram. |
| Bot ignores group messages | Disable Privacy Mode: BotFather → /setprivacy → OFF. Or ensure messages @mention the bot. |
| Connection issues in Docker | Set env var OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=true (required for image v2026.2.17+). |
| Old Moltbot/Clawdbot conflict | Kill old processes: ps aux | grep -E '(moltbot|clawdbot).*gateway'. Only one gateway should run. |
| Pairing code expired | Codes expire after 1 hour. Generate a new one by messaging the bot again. |