You followed the guide. You created the bot, got the token, pasted it in. Everything looked right. Then your agent stopped responding and you have no idea why.
This is extremely common. Not because OpenClaw is broken — it's because Telegram integration has specific failure modes that nobody explains clearly upfront. Each one is fixable. Each one is also easy to miss.
Here are the five most common ways OpenClaw's Telegram setup breaks, how to diagnose each, and what to do.
Failure 1: The Bot Token Is Wrong (More Common Than You'd Think)
What it looks like: Your agent starts, shows no errors, but never responds to Telegram messages. Or you get "unauthorized" errors in your logs.
What's happening: The bot token is wrong. This sounds basic, but it's remarkably easy to get wrong:
- BotFather sends tokens with a colon (
1234567890:ABCdef...) — the entire string is the token, including the number before the colon - Tokens get truncated if you copy them from a notification preview instead of the message itself
- If you created multiple bots, you might have the wrong bot's token
- Tokens can be revoked — if you ran
/tokenor/mybotsagain in BotFather and regenerated it, the old one is invalid
How to diagnose: Test your token directly. Open a browser and go to:
https://api.telegram.org/bot<YOUR_TOKEN>/getMe
Replace <YOUR_TOKEN> with your actual token. If it returns JSON with your bot's name, the token is valid. If it returns an error, the token is wrong or revoked.
Fix: Get a fresh token from BotFather (/mybots → select your bot → API Token → Revoke current token). Update your OpenClaw config with the new token, then restart.
Failure 2: Your Server Can't Reach Telegram's API
What it looks like: Agent starts, token is valid, but messages never arrive. No errors, just silence.
What's happening: Some VPS providers block outbound connections to Telegram's servers by default. Your agent is running, but it can't phone home to check for new messages.
How to diagnose: From your server:
curl -s https://api.telegram.org/bot<YOUR_TOKEN>/getMe
If this hangs or times out rather than returning JSON, your server can't reach Telegram's API.
Check your provider's firewall rules and any outbound filtering. Hetzner doesn't block Telegram by default, but other providers do. Some corporate networks also block it.
Fix: Check your server's outbound firewall rules. If you set up UFW with ufw default deny outgoing, you've blocked too much:
ufw default allow outgoing
ufw enable
If your provider filters at the network level, contact their support or switch providers.
Failure 3: The Agent Silently Dies
What it looks like: Your agent worked for a few days, then stopped responding. It was fine last time you checked. You have no idea when it stopped.
What's happening: OpenClaw crashes. Not catastrophically — just quietly exits and doesn't restart. This is the single most common complaint in the OpenClaw community.
Common causes:
- Memory leak in a skill — the process runs out of RAM and is killed
- Uncaught exception in a skill handler
- Framework update that introduced a regression
- Server ran out of disk space (logs filled the drive)
How to diagnose: Check if the daemon is running:
openclaw gateway status
Check the logs for the last thing that happened before it died:
openclaw logs --follow
Check system memory and disk:
free -h
df -h
Fix: If it's a one-time crash, openclaw gateway run and monitor. If it crashes repeatedly, look for the error pattern in the logs. Skill-related crashes usually name the skill. Remove or update that skill.
To prevent silent deaths from going unnoticed: set up UptimeRobot (free) to ping your agent's webhook endpoint every 5 minutes. You'll get an email when it goes down.
Failure 4: Pairing Code Confusion
What it looks like: During setup, you're asked for a "pairing code" or "phone code." You're not sure what it's asking for or where to get it.
What's happening: Some OpenClaw configurations use Telegram's user API (as a user account) rather than the Bot API. User API requires logging in with a phone number and a verification code that Telegram sends via SMS or another app.
This is a different flow from bot token setup, and the two are often conflated in older tutorials.
How to diagnose: If you're being asked for a phone number or pairing code, you're setting up user API mode. If you created a bot via BotFather and have a token, you're in bot mode. They're different.
Fix: Decide which you want:
- Bot mode (simpler): Use BotFather to create a bot, use the token in your config, set
telegram_mode: botin your OpenClaw configuration - User mode (more capable, more complex): You'll log in with your own Telegram account. Your agent messages appear to come from you, not a bot. Requires phone verification.
Most first-time setups should use bot mode. It's simpler and sufficient for 90% of use cases.
Failure 5: Long-Poll Conflicts and Webhook Confusion
What it looks like: The agent was working, then you tried to change something, and now you're getting "webhook conflict" errors. Or messages get delivered to the old version of your bot.
What's happening: Telegram delivers messages to bots in two ways — long polling (bot asks Telegram "any new messages?") and webhooks (Telegram pushes messages to your server). If you've ever set a webhook and then try to use long polling, or vice versa, you get conflicts.
How to diagnose: Check if a webhook is currently set:
https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo
If url is non-empty, a webhook is set. If you want to use long polling (the default for most OpenClaw setups), you need to clear it.
Fix: To delete the webhook and switch to long polling:
https://api.telegram.org/bot<YOUR_TOKEN>/deleteWebhook
Then restart OpenClaw. It will default to long polling.
If you want webhooks (needed for some integrations), make sure your webhook URL is correct and your server is accessible on the configured port.
When DIY Troubleshooting Stops Making Sense
Each failure above is diagnosable and fixable. But there's a pattern worth naming: every fix opens a door to the next thing that can go wrong.
Fix the token → discover the server can't reach Telegram → fix the outbound firewall → realize you blocked too much → fix that → agent crashes → need to set up monitoring → monitoring reveals another skill is leaking memory → need to remove and reinstall the skill.
This is normal for self-hosted software. It's not a reason to give up. But it is worth being honest about: this is ongoing maintenance, not a one-time setup.
The reason Volos exists is specifically this: every one of these failure modes gets handled before your agent goes live, and when something breaks after that, you tell Volos — not a forum — and it gets fixed.
If you want to run your own agent and you're willing to do the maintenance, the above is everything you need. If you've read this far and thought "I don't want to deal with any of this," that's a valid and reasonable conclusion.
