openclaw - 💡(How to fix) Fix Telegram channel can stall gateway when Node fetch to api.telegram.org times out while curl -4 succeeds [1 participants]

Summary

On macOS arm64 with OpenClaw 2026.4.24, enabling the Telegram channel can make the local gateway/RPC health path time out. The bot token is valid and curl -4 can reach Telegram, but Node/undici fetch() to https://api.telegram.org fails with ETIMEDOUT. Once channels.telegram.enabled=false, the gateway becomes responsive again.

This looks related to earlier Telegram/undici transport regressions, but in this case the failure also degrades the gateway enough that openclaw health and openclaw gateway status can time out while Telegram is enabled.

Related issues I found:

• #25676
• #28835
• #33013
• #43178
• #59833

Environment

• OpenClaw: 2026.4.24 (cbcfdf6)
• OS: macOS / Darwin 25.4.0, arm64, Apple Silicon
• Install/runtime: npm global OpenClaw, LaunchAgent gateway
• Gateway bind: loopback, 127.0.0.1:18789
• Node used by LaunchAgent: Homebrew Node v24.15.0
• Also reproduced direct Node fetch() timeout with Homebrew Node v22.22.2
• Bonjour is disabled via OPENCLAW_DISABLE_BONJOUR=1 to avoid the separate mDNS issue described in #63248.

Current stable configuration

{
  "env": {
    "vars": {
      "OPENCLAW_DISABLE_BONJOUR": "1"
    }
  },
  "channels": {
    "telegram": {
      "enabled": false,
      "network": {
        "dnsResultOrder": "ipv4first",
        "autoSelectFamily": false
      }
    }
  }
}

With Telegram disabled, gateway status is healthy:

openclaw gateway status --json --timeout 10000

Observed:

{
  "service": {
    "runtime": {
      "status": "running",
      "state": "active"
    },
    "configAudit": {
      "ok": true,
      "issues": []
    }
  },
  "rpc": {
    "ok": true,
    "capability": "admin_capable"
  }
}

openclaw health --json --timeout 10000 also returns normally, with durationMs around a few milliseconds once the gateway settles.

Reproduction / observations

1. Configure a valid Telegram bot token.
2. Keep Bonjour disabled:

OPENCLAW_DISABLE_BONJOUR=1

1. Confirm the machine can reach Telegram with curl over IPv4:

curl -4 -sS -o /tmp/tg.out -w 'http_code=%{http_code} time_total=%{time_total}\n' https://api.telegram.org

Observed:

http_code=302 time_total=0.87

With the actual bot token, curl -4 https://api.telegram.org/bot<TOKEN>/getMe returns {"ok": true, ...} for the configured bot.

1. Run a minimal Node fetch from the same machine/runtime:

NODE_USE_SYSTEM_CA=1 NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem \
/opt/homebrew/bin/node -e "fetch('https://api.telegram.org').then(r=>console.log(JSON.stringify({status:r.status,url:r.url}))).catch(e=>{console.log(JSON.stringify({name:e.name,message:e.message,cause:e.cause&&{code:e.cause.code,errno:e.cause.errno,syscall:e.cause.syscall,hostname:e.cause.hostname}})); process.exitCode=1})"

Observed:

{"name":"TypeError","message":"fetch failed","cause":{"code":"ETIMEDOUT"}}

The same timeout reproduces with:

NODE_OPTIONS=--dns-result-order=ipv4first

and with Homebrew Node v22.22.2.

1. Enable Telegram:

channels.telegram.enabled=true
channels.telegram.network.dnsResultOrder="ipv4first"
channels.telegram.network.autoSelectFamily=false

1. Restart the gateway.

Observed logs:

[telegram] [default] starting provider
[telegram] menu text exceeded the conservative 5700-character payload budget; shortening descriptions to keep 67 commands visible.
[telegram] fetch fallback: enabling sticky IPv4-only dispatcher (codes=ETIMEDOUT,EHOSTUNREACH)
[telegram] [default] channel stop exceeded 5000ms after abort; continuing shutdown

While Telegram is enabled, openclaw health --json --timeout 10000 and openclaw gateway status --json --timeout 10000 can time out against ws://127.0.0.1:18789. Disabling Telegram and restarting restores RPC/health.

Expected behavior

Telegram network failures should not block or degrade the gateway health/RPC path.

If Telegram cannot reach the Bot API, the gateway should:

• mark the Telegram channel as degraded/unhealthy,
• keep openclaw health and openclaw gateway status responsive,
• avoid full gateway stalls during Telegram startup/shutdown,
• surface a clear channel-level diagnostic.

Actual behavior

When Telegram is enabled and Node/undici cannot connect to api.telegram.org, the channel startup/shutdown path can stall long enough that gateway RPC calls time out. The practical workaround is to disable Telegram entirely.

Suggested fix

Concrete things that would likely help:

1. Add a hard timeout around Telegram provider startup, polling setup, and stop/shutdown.
2. Ensure Telegram transport failures are isolated to channel health and never block gateway RPC/health.
3. Make the existing IPv4 fallback more explicit/diagnosable, and expose the resolved transport mode in channels status --deep.
4. Consider a supported fallback transport for Telegram on macOS/Node/undici edge cases where curl -4 works but fetch() times out.
5. Consider documenting a local Bot API/proxy workaround for this class of failure, while ensuring apiRoot setups still dispatch updates to agent sessions.

I can provide additional logs or test a candidate fix on this macOS setup.