Summary

OpenClaw's Telegram channel fails to send/receive messages when IPv6 is enabled on the host system, due to the underlying Telegram client library using autoSelectFamily=true which prioritizes IPv6 connections that may be unreachable.

Environment

• OpenClaw Version: 2026.2.15
• Node.js Version: v22.22.0
• OS: Linux 6.17.0-8-generic (x64)
• Platform: Vultr VPS (Ubuntu-based)

Steps to Reproduce

1. Deploy OpenClaw on a system with IPv6 enabled but where Telegram API's IPv6 addresses (2001:67c:4e8:f004::9) are not reachable.
2. Configure Telegram channel with a valid bot token.
3. Start the gateway: openclaw gateway start
4. Attempt to send/receive messages via Telegram.

Expected Behavior

Telegram channel should automatically fall back to IPv4 when IPv6 is unreachable, ensuring reliable message delivery.

Actual Behavior

All Telegram API requests fail with:

telegram deleteMyCommands failed: Network request for 'deleteMyCommands' failed!
telegram setMyCommands failed: Network request for 'setMyCommands' failed!
telegram sendMessage failed: Network request for 'sendMessage' failed!

Root Cause Analysis

1. Node.js 22+ Default Behavior: The Telegram client uses autoSelectFamily=true (visible in logs: telegram: autoSelectFamily=true (default-node22)).
2. IPv6 Priority: This setting causes Node.js to prioritize IPv6 connections, even when they are unreachable.
3. Timeout Issue: Each request attempts IPv6 first, waits for timeout, then falls back to IPv4.

Diagnostic Evidence

Logs

{"subsystem":"telegram/network","message":"telegram: autoSelectFamily=true (default-node22)"}
{"subsystem":"gateway/channels/telegram","message":"telegram sendMessage failed: Network request for 'sendMessage' failed!"}

Network Testing

• curl (IPv4 forced): ✅ Works
• Node.js with {family: 4}: ✅ Works
• OpenClaw Telegram client: ❌ Fails

Workaround

Temporarily disable IPv6 system-wide:

sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1
sudo sysctl -w net.ipv6.conf.default.disable_ipv6=1
openclaw gateway restart

Side effects: This breaks IPv6-dependent services (e.g., Tailscale).

Proposed Solution

Add a configuration option to override autoSelectFamily for the Telegram client:

{
  "channels": {
    "telegram": {
      "networkOptions": {
        "family": 4
      }
    }
  }
}

Impact

• Severity: High (complete channel failure)
• Affected Users: Anyone running OpenClaw in IPv6-enabled environments where Telegram's IPv6 endpoints are not reachable (common on VPS providers).

Additional Context

• Node.js autoSelectFamily behavior: https://nodejs.org/docs/latest-v22.x/api/net.html#socketconnectoptions-connectlistener