About 30% of OpenClaw Telegram issues come down to a bad token. Another 30% are pairing or privacy mode problems. The remaining 40% split across webhook conflicts, removed bots, and post-upgrade regressions. This guide covers the exact diagnostic steps to run every time a bot goes silent.
Quick Triage: Find Your Problem in 60 Seconds
Before reading the full guide, run the diagnostic ladder. Open a terminal on your server and execute these commands in order:
openclaw status --all
openclaw gateway status
openclaw channels status --probe
openclaw logs --follow --json | tail -50
Read the output and jump to the right section:
openclaw statussays the process is not running? Your OpenClaw instance crashed. See our general troubleshooting guide.channels statusshows Telegram asdisconnectedorerror? Start at Invalid or Revoked Bot Token.channels statusshows Telegram asconnectedbut messages never arrive? Go to Bot Not Started or Pairing Not Completed.- Logs show
409 Conflicterrors? Jump to Webhook and Polling Conflict. - Bot works in DMs but not in groups? Read Privacy Mode Blocking Group Messages.
- Everything looks green but a specific group stopped working? Check Bot Removed from Group.
- Bot broke after an update? See Post-Upgrade Regressions.
Invalid or Revoked Bot Token
Symptoms: Channel status shows disconnected or unauthorized. Logs contain HTTP 401 errors from api.telegram.org.
This is the single most common cause. A token can break for three reasons: you copied it with trailing whitespace, BotFather revoked it when you regenerated it, or someone else on your team rotated it without telling you.
Diagnosis:
openclaw logs --follow --json | jq 'select(.error_type == "auth")'
If you see 401 Unauthorized in the output, the token is invalid.
Verify your token is valid directly with Telegram:
curl -s "https://api.telegram.org/bot<YOUR_TOKEN>/getMe" | jq .
A valid token returns your bot’s username and ID. An invalid one returns {"ok":false,"error_code":401}.
Fix:
- Open Telegram and message @BotFather.
- Send
/mybots, select your bot, then tap “API Token” to get the current token. - Update your OpenClaw configuration:
openclaw config set channels.telegram.botToken "<new-token>"
openclaw restart
Or edit ~/.openclaw/config/config.json directly. Make sure the token has no leading or trailing spaces. A trailing newline character is a surprisingly common cause of token validation failures.
Common mistake: Telegram is a built-in channel in OpenClaw, not a plugin. If your config places the token under plugins.entries.telegram instead of channels.telegram, the bot will silently fail. Move the configuration to the correct location.
Bot Not Started or Pairing Not Completed
Symptoms: Channel status shows connected and the bot appears online in Telegram, but sending it a message produces no response. No errors in the logs, or logs show drop dm (pairing required).
OpenClaw requires that users “pair” with your Telegram bot before it responds to them. If someone messages the bot without completing the pairing flow, messages get dropped silently.
Diagnosis:
openclaw pairing pending
This lists all pending pairing requests. If you see entries here, those users are waiting for approval.
Fix:
Approve pending pairings:
openclaw pairing approve telegram <user-id>
For group chats, the group ID is negative. Supergroups use the -100 prefix format (e.g., -1001234567890):
openclaw pairing approve telegram -1001234567890
DM policy options: If you want to skip manual approval, change the DM policy:
pairing(default): users must pair first, you approve manuallyallowlist: only pre-authorized user IDs can interactopen: anyone can message the bot (no approval needed)
openclaw config set channels.telegram.dmPolicy "open"
openclaw restart
Use open only for bots that are meant to be public. For internal team bots, allowlist with numeric user IDs is more secure.
Important: Use numeric user IDs in your allowFrom config, not @username handles. Telegram username resolution can fail. Get a user’s numeric ID by having them message @userinfobot on Telegram, or inspect your OpenClaw logs where the sender ID appears on every incoming message.
Webhook and Polling Conflict
Symptoms: Logs show 409 Conflict: terminated by other getUpdates request. Bot responds intermittently, sometimes answering, sometimes silent.
Telegram bots can receive messages in two ways: polling (the bot asks Telegram for updates) or webhooks (Telegram pushes updates to your server). These two modes cannot coexist. If a webhook is set from a previous deployment and OpenClaw tries to poll, you get a conflict.
This also happens when two OpenClaw instances (or two gateway processes) try to use the same bot token simultaneously. A common scenario is a forgotten default gateway running alongside a production profile. Both compete for the same bot token, and whichever process polls first gets the message while the other gets a 409 error.
Diagnosis:
Check if a webhook is currently set:
curl -s "https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo" | jq .
If the url field is not empty, a webhook is active and will conflict with OpenClaw’s polling.
Fix:
Delete the webhook so OpenClaw can poll cleanly:
curl -s "https://api.telegram.org/bot<YOUR_TOKEN>/deleteWebhook" | jq .
Then restart OpenClaw:
openclaw restart
If the issue is duplicate gateway processes, find and stop the extra one:
ps aux | grep "openclaw gateway"
Kill any extra gateway processes and ensure only one instance uses each bot token. This is a hard rule: one bot token, one gateway process. There are no exceptions.
Privacy Mode Blocking Group Messages
Symptoms: Bot works perfectly in DMs but ignores all group messages. No errors in logs. The bot shows as a member of the group.
Telegram bots have “privacy mode” enabled by default. When privacy mode is on, bots in groups only receive messages that directly mention them (via @botname) or are replies to the bot’s own messages. Regular group messages are invisible to the bot.
Diagnosis:
Check your bot’s privacy mode setting in BotFather:
- Message @BotFather
- Send
/mybotsand select your bot - Go to “Bot Settings” then “Group Privacy”
- It will show either “Privacy mode is enabled” or “Privacy mode is disabled”
Fix:
You have two options:
Option A: Disable privacy mode (bot sees all group messages)
In BotFather, go to Bot Settings and Group Privacy then tap “Turn off.” After disabling, remove and re-add the bot to the group. The privacy mode change only takes effect for groups the bot joins after the setting change.
Option B: Keep privacy mode on and require mentions
Configure OpenClaw to only respond when mentioned:
openclaw config set channels.telegram.mentionRequired true
openclaw restart
This is the better choice for busy groups where you do not want the bot responding to every message.
The re-add step trips people up. A frequent mistake is disabling privacy mode and then wondering why it did not take effect in existing groups. The bot must leave and rejoin the group for Telegram to update its permissions.
Bot Removed from Group
Symptoms: Bot was working in a group, then stopped. No error messages in logs. The bot still works in DMs with individual users.
This one is easy to miss. If someone removes the bot from a group (intentionally or accidentally), messages from that group simply stop arriving. OpenClaw does not log a “bot was removed” event because Telegram stops sending updates for that group entirely.
Diagnosis:
Check whether the bot is still a member of the group. The fastest way:
- Open the group in Telegram
- Tap the group name to see the member list
- Search for your bot’s username
If the bot is not in the member list, it was removed.
You can also verify programmatically:
curl -s "https://api.telegram.org/bot<YOUR_TOKEN>/getChatMember?chat_id=<GROUP_ID>&user_id=<BOT_USER_ID>" | jq .
If the response says "status": "left" or "status": "kicked", the bot is no longer in the group.
Fix:
Add the bot back to the group. In Telegram, open the group, tap “Add Members,” and search for your bot’s username. After adding, you may need to re-approve the pairing:
openclaw pairing approve telegram <group-id>
To prevent accidental removal, make the bot a group administrator. Admin bots cannot be removed by regular members.
Post-Upgrade Regressions
Symptoms: Telegram bot was working, you upgraded OpenClaw, and now it does not respond. DMs, groups, or both may be affected depending on the version.
OpenClaw moves fast and sometimes introduces regressions that affect Telegram. Here are the known issues by version:
2026.2.24 through 2026.2.26: Group messages stopped being received while DMs continued working. This was a regression in the gateway’s group message handler. Fixed in 2026.2.27.
2026.3.2: Multi-account Telegram bots broke. If you run more than one Telegram bot on the same OpenClaw instance, secondary accounts stopped processing messages. Workaround: run each bot on a separate OpenClaw profile until the fix ships.
Moltbot to OpenClaw migration (2026-01-30): The rename from Moltbot/Clawdbot to OpenClaw left some users with duplicate gateway processes. The old Moltbot gateway continued running and intercepted Telegram messages before the new OpenClaw gateway could process them.
Diagnosis:
Check your version:
openclaw --version
Check for duplicate processes from old installations:
ps aux | grep -E "(moltbot|clawdbot|openclaw)" | grep gateway
Fix:
If you are on an affected version, either upgrade to a patched release or apply the version-specific workaround listed above. For the Moltbot migration issue, stop and disable the old process:
sudo systemctl stop moltbot-gateway
sudo systemctl disable moltbot-gateway
openclaw restart
Verify Your Fix Worked
After applying any fix, do not assume it worked. Run these tests in order:
Test 1: Channel status
openclaw channels status --probe
Telegram should show connected with probe: ok.
Test 2: Send a DM
Open your bot in Telegram and send a test message. Check the logs for delivery:
openclaw logs --follow --json | jq 'select(.channel == "telegram" and .direction == "incoming")'
You should see the incoming message appear in the log output within a few seconds.
Test 3: Send a group message
If your bot is in groups, send a message in the group (mentioning the bot if privacy mode is on). Verify it appears in the logs the same way.
Test 4: Confirm response
The bot should respond to your test messages. If the message arrives in logs but no response is sent, the issue is not Telegram-specific. Check your model configuration and API costs to make sure your LLM provider is responding.
Frequently Asked Questions
Why does my OpenClaw bot work in DMs but not in groups?
Privacy mode is the most likely cause. Telegram enables it by default, which means your bot only sees messages that mention it directly. Disable privacy mode in BotFather, then remove and re-add the bot to affected groups. The re-add step is required because Telegram caches the permission setting from when the bot originally joined.
How do I fix a 401 Unauthorized error on my Telegram bot?
Your bot token is invalid or revoked. Get a fresh token from BotFather by sending /mybots, selecting your bot, and tapping “API Token.” Update the token in your OpenClaw config with openclaw config set channels.telegram.botToken "<token>" and restart. Verify the token works by calling https://api.telegram.org/bot<TOKEN>/getMe.
Can I run the same Telegram bot token on two OpenClaw instances?
No. Telegram only allows one consumer per bot token when using polling mode. Running two instances causes 409 Conflict errors and intermittent message delivery. Use a separate bot for each OpenClaw instance.
Why did my Telegram bot stop working after upgrading OpenClaw?
Check the Post-Upgrade Regressions section. Known issues include group messages breaking in 2026.2.24-2026.2.26 and multi-account bots breaking in 2026.3.2. Run openclaw --version and compare against the known issues. If you migrated from Moltbot, check for duplicate gateway processes.
How do I check if my Telegram bot token is valid?
Run curl -s "https://api.telegram.org/bot<YOUR_TOKEN>/getMe" | jq . from your terminal. A valid token returns your bot’s username, ID, and capabilities. An invalid one returns error code 401.
How do I approve a Telegram pairing request in OpenClaw?
Run openclaw pairing pending to see waiting requests, then openclaw pairing approve telegram <user-or-group-id> to approve. For groups, use the negative numeric group ID. If you want to skip manual approval, set the DM policy to open or allowlist.
Does OpenClaw support Telegram group chats?
Yes. OpenClaw supports DMs, groups, and supergroups. For groups, you need to either disable privacy mode (so the bot sees all messages) or configure mention-required mode. Group chats require separate pairing approval from DMs.
Why does my bot show online in Telegram but not respond?
The bot’s “online” indicator comes from the Telegram API connection, not from OpenClaw’s ability to process messages. If the connection is established but pairing is not approved, messages arrive at the gateway and get silently dropped. Check openclaw pairing pending and review the logs for dropped messages.
Key Takeaways
- Run the five-command diagnostic ladder before anything else:
openclaw status,gateway status,channels status --probe,doctor, andlogs --follow - Invalid tokens cause 30% of Telegram bot issues. Always verify with the Telegram
getMeAPI endpoint before diving deeper. - Privacy mode is the top reason bots work in DMs but fail in groups. Disabling it requires re-adding the bot to existing groups.
- One bot token per gateway process. No exceptions. Duplicate processes cause 409 conflicts.
- After every fix, verify with the four-step test: channel status, DM test, group test, response confirmation.
SFAI Labs
