Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix Telegram/QQBot plugins fail to connect on servers without global IPv6 (undici IPv6-first issue) [2 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#75539•Fetched 2026-05-02 05:33:25
View on GitHub
Comments
2
Participants
3
Timeline
8
Reactions
2
Author
nakedsleepwalkernakedsleepwalker
Participants
clawsweeper[bot]clawsweeper[bot]nakedsleepwalkernakedsleepwalkerredpiggy-cyberredpiggy-cyber
Timeline (top)
mentioned ×3subscribed ×3commented ×2

After upgrading to OpenClaw v2026.4.29, both Telegram and QQBot plugins fail to connect on cloud servers that lack global IPv6 reachability. The underlying issue is that undici (the HTTP client bundled with plugin-runtime-deps, v8.1.0) defaults to a happy-eyeballs IPv6-first connection strategy, which blocks the event loop on servers where IPv6 resolves but cannot connect.

Root Cause

The plugin-runtime-deps bundles [email protected]. Node.js default DNS resolution order returns both IPv4 and IPv6 addresses. undici tries IPv6 first in its happy-eyeballs implementation. On servers where IPv6 resolves but has no global route, each outgoing request to api.telegram.org waits for IPv6 connection timeout before falling back to IPv4. These sequential delays stack up and block the event loop, causing the gateway readiness probe to timeout.

Fix Action

Fix / Workaround

Workarounds

Workaround 1 - Force IPv4-first DNS resolution: Set NODE_OPTIONS=--dns-result-order=ipv4first in the gateway service environment.

Workaround 2 - Downgrade to v2026.4.27:

npm install -g [email protected] --force

Code Example

# /etc/systemd/system/openclaw-gateway.service.d/override.conf
[Service]
Environment="NODE_OPTIONS=--dns-result-order=ipv4first"

---

npm install -g openclaw@2026.4.27 --force
RAW_BUFFERClick to expand / collapse

Description

After upgrading to OpenClaw v2026.4.29, both Telegram and QQBot plugins fail to connect on cloud servers that lack global IPv6 reachability. The underlying issue is that undici (the HTTP client bundled with plugin-runtime-deps, v8.1.0) defaults to a happy-eyeballs IPv6-first connection strategy, which blocks the event loop on servers where IPv6 resolves but cannot connect.

Environment

  • OpenClaw Version: v2026.4.29 (upgrade from v2026.4.27)
  • OS: Tencent Cloud Linux (OpenCloudOS 9, kernel 6.6)
  • Node.js: v22.22.0
  • Server has no global IPv6 reachability, but api.telegram.org resolves both A and AAAA records

Symptoms

  1. Connectivity probe fails - gateway status shows Connectivity probe: failed
  2. Event loop blocked - logs show eventLoopDelayP99Ms=31356.6 (31 seconds)
  3. Telegram fetch timeout - fetch timeout reached; aborting operation (getMe, elapsedMs: 18167)
  4. QQBot native approvals timeout - connect ETIMEDOUT 127.0.0.1:XXXXX, gateway event loop readiness timeout
  5. Both Telegram and QQBot channels become unresponsive

Root Cause

The plugin-runtime-deps bundles [email protected]. Node.js default DNS resolution order returns both IPv4 and IPv6 addresses. undici tries IPv6 first in its happy-eyeballs implementation. On servers where IPv6 resolves but has no global route, each outgoing request to api.telegram.org waits for IPv6 connection timeout before falling back to IPv4. These sequential delays stack up and block the event loop, causing the gateway readiness probe to timeout.

Workarounds

Workaround 1 - Force IPv4-first DNS resolution: Set NODE_OPTIONS=--dns-result-order=ipv4first in the gateway service environment.

Systemd override example:

# /etc/systemd/system/openclaw-gateway.service.d/override.conf
[Service]
Environment="NODE_OPTIONS=--dns-result-order=ipv4first"

Workaround 2 - Downgrade to v2026.4.27:

npm install -g [email protected] --force

Expected Behavior

The HTTP client should either:

  1. Respect the system routing and Node.js dns order setting, or
  2. Fail fast on IPv6 and fall back to IPv4 without a multi-second timeout that blocks the event loop

Additional Context

  • v2026.4.27 worked without issues because its HTTP client (likely using Node.js built-in fetch) handled IPv6 fallback properly and respected --dns-result-order=ipv4first
  • The plugin-runtime-deps staging mechanism installs undici under ~/.openclaw/plugin-runtime-deps/, bypassing Node.js built-in fetch
  • This affects any server without global IPv6, which is common for cloud VPS providers

extent analysis

TL;DR

Set NODE_OPTIONS=--dns-result-order=ipv4first in the gateway service environment to force IPv4-first DNS resolution and resolve the connectivity issue.

Guidance

  • Verify that the issue is caused by the happy-eyeballs IPv6-first connection strategy by checking the DNS resolution order and the presence of both A and AAAA records for api.telegram.org.
  • Apply Workaround 1 by setting NODE_OPTIONS=--dns-result-order=ipv4first in the gateway service environment, as shown in the provided systemd override example.
  • Consider downgrading to v2026.4.27 as a temporary workaround, but be aware that this may introduce other compatibility issues.
  • Test the workaround by checking the gateway status and event loop delay after applying the change.

Example

# Set NODE_OPTIONS environment variable
export NODE_OPTIONS=--dns-result-order=ipv4first

# Alternatively, use the systemd override example:
# /etc/systemd/system/openclaw-gateway.service.d/override.conf
[Service]
Environment="NODE_OPTIONS=--dns-result-order=ipv4first"

Notes

The provided workarounds assume that the issue is caused by the happy-eyeballs implementation in [email protected]. If the issue persists after applying the workarounds, further investigation may be necessary to determine the root cause.

Recommendation

Apply Workaround 1 by setting NODE_OPTIONS=--dns-result-order=ipv4first to resolve the connectivity issue without downgrading the OpenClaw version. This workaround is a more targeted solution that addresses the specific issue caused by the happy-eyeballs implementation.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#SSR setup#ISR setup#authentication setup#request error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING