Critical Bug: Telegram File Messages Can Crash Your Entire OpenClaw Gateway

A critical bug report (#28435) has surfaced in the OpenClaw repository that every Telegram user needs to know about. If your agent receives certain file or document messages via Telegram, your entire Gateway process can crash—taking down all your connected channels, not just Telegram.

The Problem: Two Bugs, One Catastrophic Outcome

The issue actually encompasses two distinct but related bugs:

Bug 1: Oversized Files Cause Gateway Process Exit

When a Telegram user sends a file that exceeds size limits, OpenClaw throws an error. The problem? This error bubbles up through the call stack and gets caught by a handler that calls process.exit(). Instead of gracefully rejecting the file and sending the user an error message, the entire Gateway crashes.

Bug 2: pdfjs-dist Loading Failure Kills the Polling Runner

The second bug involves the Telegram polling runner. When processing certain documents, if pdfjs-dist fails to load (a non-network error), the error handling logic doesn't recognize it as retryable. The polling runner exits permanently instead of attempting a restart.

Why This Is P0 Priority

Community contributor @mylukin provided an excellent architecture analysis in the issue comments. The severity here cannot be overstated:

• Production Gateway crashes affect ALL channels, not just Telegram
• A single bad file from any Telegram user can take down your entire agent infrastructure
• The polling runner doesn't automatically recover, requiring manual intervention

The Root Causes

For Bug 1, the root cause is throwing a plain Error that gets caught by error handlers designed for fatal errors, triggering process.exit(). The fix requires catching oversized file errors at the Telegram message handler layer and returning a user-friendly error message instead of crashing.

For Bug 2, the polling runner only retries on network errors. Non-network errors like pdfjs loading failures cause the runner to exit permanently. The fix requires expanding error handling to trigger runner restarts for non-fatal errors rather than permanent exits.

Workarounds Until the Fix Ships

1. Disable file processing: If your use case doesn't require file uploads, consider disabling them at the Telegram bot level via BotFather settings
2. Process monitoring: Use pm2, systemd, or similar to auto-restart your Gateway if it crashes
3. Separate Telegram: Run Telegram on a separate Gateway instance so crashes don't affect other channels

Follow the Issue

Track progress on GitHub Issue #28435. The community has already identified the fix approach—now it's a matter of implementation and testing.

If you've experienced mysterious Gateway crashes when users send files via Telegram, this is likely your culprit. Add a thumbs up to the issue to help prioritize the fix.