Why does OpenClaw wait exactly 32 seconds before failing?

This is the standard TCP connection timeout. Node.js attempts to connect via IPv6 first; if the provider's server ignores IPv6 packets instead of rejecting them, the process hangs until the timeout.

Will disabling IPv6 affect my other apps?

Our recommended fixes are scoped only to the OpenClaw process using environment variables, so your system-wide settings remain untouched.

Fix: LLM Request Timed Out (IPv6)

Deep Dive: The IPv6 "Black Hole"

Many AI providers (notably Z.AI and some OpenRouter endpoints) have DNS records for both IPv4 and IPv6. Node.js defaults to an algorithm called "Happy Eyeballs," which often prioritizes IPv6. If your network has a "broken" IPv6 route (common in corporate VPNs or specific ISPs), the request enters a black hole and hangs for ~32s before falling back to IPv4.

If curl works instantly but OpenClaw takes 30+ seconds to reply (or fails with fetch failed), you are likely a victim of the IPv6 preference bug.

Next Step

Fix now, then reduce repeat incidents

If this issue keeps coming back, validate your setup in Doctor first, then harden your config.

Open Doctor Harden Config

Need proactive alerts? Join Monitor early access.

Diagnosis: Confirm the Culprit

Run this command to see if your network can actually complete a handshake over IPv6:

IPv6 Connectivity Test

curl -6 -v https://api.openai.com/v1/models

If this command hangs or says "Connection timed out," you must force OpenClaw to use IPv4.

Fix 1: Force IPv4 via Environment Variable (Best)

You can tell the Node.js runtime to always prefer IPv4 for the OpenClaw process. This is the cleanest fix as it doesn't require system-wide changes.

Linux / macOS Fix

export NODE_OPTIONS='--dns-result-order=ipv4first'\nopenclaw gateway restart

Windows (PowerShell) Fix

$env:NODE_OPTIONS='--dns-result-order=ipv4first'\nopenclaw gateway restart

Fix 2: Docker Configuration

If running in Docker, add the environment variable to your docker-compose.yml to ensure the container doesn't waste time on IPv6 handshakes.

services:
  openclaw:
    environment:
      - NODE_OPTIONS=--dns-result-order=ipv4first

Fix 3: Disable IPv6 System-wide (Last Resort)

If you are on a dedicated server or Mac Mini used only for AI, disabling IPv6 at the OS level will solve all connectivity issues permanently.

macOS Disable IPv6

networksetup -setv6off Wi-Fi  # or 'Ethernet'

Success Metrics

After applying Fix 1, OpenClaw should start responding in under 2 seconds. You can verify the latency improvement in the Gateway logs.

Did this guide solve your problem?