Telegram Bot Troubleshooting: 5 Common Issues Fixed in OpenClaw 2026.2.17

If you've been running an OpenClaw-powered Telegram bot, you've probably hit some frustrating issues that seemed impossible to debug. The good news: OpenClaw 2026.2.17 (released today) quietly fixes several long-standing Telegram problems. Here's what was wrong and how to verify you're fixed.

1. BOT_COMMAND_INVALID Errors Wiping Your Menu

The Problem: Your Telegram bot's command menu would randomly disappear, or you'd see BOT_COMMAND_INVALID errors in your logs. This happened when you had skill commands containing hyphens (like /my-skill).

What Was Happening: Telegram requires command names to use underscores, not hyphens. OpenClaw was registering commands with their original names, causing Telegram to reject the entire command menu sync.

The Fix: OpenClaw now normalizes command names automatically (my-skill → my_skill) before registering them with Telegram. Previously failed syncs are now logged instead of silently swallowed.

Verify It's Fixed: Check your gateway logs after startup—you should see successful command menu registration without BOT_COMMAND_INVALID errors.

2. Connection Failures on IPv6 Networks

The Problem: Your Telegram bot would fail to connect on certain networks, particularly those with broken or partial IPv6 support. You'd see timeout errors even though other services worked fine.

What Was Happening: Node.js 22+ changed its default DNS resolution behavior, and OpenClaw wasn't explicitly telling it to fall back to IPv4 when IPv6 failed.

The Fix: OpenClaw 2026.2.17 enables autoSelectFamily by default on Node.js 22+, which automatically falls back to IPv4 when IPv6 connections fail.

Verify It's Fixed: If you were experiencing random connection issues on certain networks, try updating and testing—the bot should connect reliably now.

3. 20MB Media Files Crashing Your Bot

The Problem: When someone sent a large video or file (approaching Telegram's 20MB limit for bots), your agent would crash or the message would be dropped entirely.

What Was Happening: OpenClaw would retry the getFile API call indefinitely when it failed due to size limits, eventually timing out and dropping the message.

The Fix: OpenClaw now detects Telegram's 20MB limit error and gracefully falls back to placeholder-only processing. Your agent gets the message context without the oversized attachment, and the user doesn't experience a silent failure.

Verify It's Fixed: Send a large video file to your bot. Instead of silence, you should see the agent respond (acknowledging it couldn't process the large attachment).

4. Stale Polling Offsets After Token Rotation

The Problem: After changing your Telegram bot token (for security rotation or switching bots), your new bot would miss messages or behave erratically.

What Was Happening: OpenClaw stored polling offsets per-account but didn't clear them when the bot token changed. The new bot would try to resume from an invalid offset.

The Fix: OpenClaw now clears stored polling offsets when bot tokens change or accounts are deleted, ensuring fresh starts with new credentials.

Verify It's Fixed: If you rotate tokens, your bot should immediately start receiving messages without needing to manually clear state.

5. Private Chat Topics Breaking DM Sends

The Problem: If you used private-chat topics (Telegram's newer threading feature), replies would fail with 400 Bad Request: message thread not found.

What Was Happening: OpenClaw was incorrectly including message_thread_id for regular DM sends and draft previews, which Telegram rejected.

The Fix: OpenClaw now properly omits message_thread_id for standard DMs while preserving it for actual forum topics (including the special handling for forum general topics with id=1).

Verify It's Fixed: DM conversations should work reliably, and if you use topics in groups, those should thread correctly too.

How to Update

If you're running OpenClaw via npm:

npm update -g openclaw
# or
openclaw update

Then restart your gateway. Check version with openclaw --version—you should see 2026.2.17 or later.

Related Issues

• #10942 - Thread ID DM failures
• #18233 - Polling offset cleanup
• #18272 - IPv6 autoSelectFamily
• #19257 - Command name normalization

Have other Telegram issues? Drop them in the comments or open an issue on GitHub!