Site icon Efficient Coder

OpenClaw Telegram China Debugging: Fix Network Connection Errors with Proxy Configuration

高效码农

Fixing OpenClaw Telegram Connection Errors: A Complete Debugging Guide for China-Based Deployments

Tags: OpenClaw, Telegram Bot, Network Debugging, SOCKS5 Proxy, China Deployment, Node.js

TL;DR

If OpenClaw keeps throwing Network request for 'deleteWebhook' failed errors, the culprit is almost always a misconfigured or offline proxy. Run nc -zv 127.0.0.1 <port> to find your active proxy port, then update OpenClaw’s Telegram proxy setting to match. Skip to the solution if you’re in a hurry.

The Problem

After setting up OpenClaw with a Telegram Bot channel, the gateway logs filled up with repeated errors:

[telegram] webhook cleanup failed: Network request for 'deleteWebhook' failed!
[telegram] retrying in 30s.
[telegram] autoSelectFamily=false (config)
[telegram] dnsResultOrder=ipv4first (config)

The bot was completely unresponsive. OpenClaw kept retrying every 30 seconds with no success.

Debugging Step by Step

Step 1 — Verify System Network Access to Telegram

The first instinct was to check whether the machine could reach Telegram at all:

curl -v https://api.telegram.org

Result: 302 Found. The system network was fine.

Step 2 — Validate the Bot Token

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

Result:

{"ok":true,"result":{"id":...,"is_bot":true,...}}

The token was valid. Not the issue.

Step 3 — Check Node.js Network Layer

Since curl worked, the next step was to verify that Node.js itself could reach the Telegram API — they don’t always behave the same way:

node -e "fetch('https://api.telegram.org').then(r => console.log('OK', r.status)).catch(e => console.log('FAIL', e.message))"

Result: OK 200. Node.js networking was fine too.

Step 4 — Run the OpenClaw Diagnostic Tool

openclaw doctor --fix

Two issues surfaced:

  1. Stale Gateway service entrypoint — After an update, the LaunchAgent still pointed to the old entry.js instead of index.js.
  2. Telegram status: failed (unknown) - fetch failed

Step 5 — Inspect the Telegram Channel Configuration

openclaw config get channels.telegram

This revealed the real culprit:

"proxy": "socks5://127.0.0.1:7891"

OpenClaw was configured to route all Telegram traffic through a local SOCKS5 proxy on port 7891.

Step 6 — Check Whether the Proxy Port Was Actually Running

nc -zv 127.0.0.1 7891

Result: Connection refused

The port wasn’t listening. The proxy wasn’t running.

Root Cause Analysis

The machine was deployed in mainland China, where Telegram is blocked. A proxy is required for any outbound connection to Telegram’s API servers.

The OpenClaw config had been set up for Clash (which exposes a local SOCKS5 proxy on port 7891 by default). However, the VPN software actually in use was LetsVPN — a full-tunnel VPN that routes traffic at the system level and does not expose any local proxy port.

This mismatch meant:

  • curl worked fine (it used the system-level VPN tunnel)
  • Node.js standalone worked fine (same reason)
  • OpenClaw failed because it was explicitly told to connect through 127.0.0.1:7891, which didn’t exist

The Fix

Find the Active Proxy Port

Scan common local proxy ports to find what’s actually listening:

for port in 1080 1087 1086 7890 7891 8080 8118 10808 10809; do
  nc -zv 127.0.0.1 $port 2>&1 | grep -v refused
done

In this case, port 7890 responded with succeeded.

Update OpenClaw’s Proxy Configuration

openclaw config set channels.telegram.proxy "socks5://127.0.0.1:7890"

Restart the Gateway

openclaw gateway

Telegram connected immediately. No more errors.

Summary Table

Check Tool Result
System network curl ✅ Accessible
Bot Token curl /getMe ✅ Valid
Node.js networking node fetch ✅ Working
Proxy port 7891 nc -zv ❌ Not listening
Proxy port 7890 nc -zv ✅ Active

Key Takeaways

1. curl working does not mean your Node.js app will work.
When an application uses an explicit proxy config, it bypasses the system VPN tunnel entirely. Always test at the application layer.

2. Match your proxy software to OpenClaw’s config.
OpenClaw’s Telegram proxy setting expects a local SOCKS5 or HTTP proxy endpoint. Full-tunnel VPN clients like LetsVPN, ExpressVPN, or NordVPN don’t provide this — they operate at the OS network layer.

3. Clash-compatible clients are the most reliable choice for China-based deployments.
Tools like ClashX, Clash Verge, or Mihomo Party expose a local SOCKS5 port (default: 7891) and an HTTP proxy port (default: 7890), which is exactly what OpenClaw expects.

4. Use nc -zv to quickly audit local proxy ports.
It’s faster and more reliable than guessing. One liner, instant answer.

Quick Reference: Common Local Proxy Ports by Software

Software HTTP Port SOCKS5 Port
ClashX / Clash Verge 7890 7891
Surge 6152 6153
V2rayU 1087 1086
Shadowsocks 1087 1080
Proxifier varies varies

Frequently Asked Questions

Q: Do I need a proxy if I’m running OpenClaw outside China?
No. If Telegram is accessible from your network directly, remove the proxy config entirely:

openclaw config unset channels.telegram.proxy

Q: Can I use an HTTP proxy instead of SOCKS5?
Yes. OpenClaw supports both:

openclaw config set channels.telegram.proxy "http://127.0.0.1:7890"

Q: Why does openclaw status show Telegram as OK even when it’s failing?
The status command checks token validity, not live connectivity. A token can be valid while the proxy connection is broken. Use openclaw logs --follow for real-time diagnostics.

Q: What if none of the ports respond?
Your proxy software isn’t running, or it’s bound to a different address. Start your proxy client first, then re-run the port scan.

If this guide helped you, consider sharing it with others running self-hosted AI agents in restricted network environments.

Exit mobile version