PR #69701: fix(gateway): skip IPv6 ::1 loopback binding on Windows to prevent HTTP hang

• Repository: openclaw/openclaw
• Author: SARAMALI15792
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/69701

Description (problem / solution / changelog)

Summary

• Problem: Gateway HTTP server hangs on Windows — all HTTP requests (including health checks) time out and never receive a response.
• Why it matters: Windows users cannot run the gateway at all; any request hits ESTABLISHED TCP state but the Node.js request event never fires.
• What changed: resolveGatewayListenHosts now returns only ["127.0.0.1"] on Windows (skips ::1). Two unit tests added to lock in this behaviour.
• What did NOT change: Non-Windows platforms retain existing dual-binding logic unchanged.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #69674
• Related #
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: resolveGatewayListenHosts returns ["127.0.0.1", "::1"] when IPv6 is bindable. On Windows, Node.js (via libuv uv_tcp_bind6) binds ::1 without UV_TCP_IPV6ONLY, creating a dual-stack socket that also accepts IPv4-mapped ::ffff:127.0.0.1. Simultaneously binding 127.0.0.1 on the same port causes Windows TCP routing to become non-deterministic: connections reach ESTABLISHED state at the TCP layer but the Node.js request event never fires.
• Missing detection / guardrail: No platform guard existed in resolveGatewayListenHosts; IPv6 bindability was checked without accounting for Windows dual-stack socket semantics.
• Contributing context (if known): This is a libuv/Windows behaviour difference — Linux handles the same dual-bind cleanly; Windows does not.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/net.test.ts
• Scenario the test should lock in: On process.platform === "win32", resolveGatewayListenHosts must return only ["127.0.0.1"] and must never call canBindToHost with ::1.
• Why this is the smallest reliable guardrail: The hang is deterministic given the dual-bind; a unit test on the host-resolution function catches any regression without needing a live server.
• Existing test that already covers this (if any): None — gap in coverage.
• If no new test is added, why not: N/A — 2 new tests added.

User-visible / Behavior Changes

On Windows, the gateway binds only 127.0.0.1 instead of both 127.0.0.1 and ::1. All existing IPv4 localhost traffic is unaffected. Users who explicitly need ::1 on Windows are unaffected in practice because the hang made ::1 unusable anyway.

Diagram (if applicable)

Before (Windows):
[request] -> [::1 dual-stack socket + 127.0.0.1 socket] -> TCP ESTABLISHED -> request event never fires -> hang

After (Windows):
[request] -> [127.0.0.1 socket only] -> TCP ESTABLISHED -> request event fires -> response

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Windows 11 Pro 10.0.26200
• Runtime/container: Node.js, native process
• Model/provider: N/A
• Integration/channel (if any): Gateway HTTP server
• Relevant config (redacted): Default gateway config, localhost binding

Steps

1. Start gateway on Windows with default config
2. Send any HTTP request to gateway (e.g. health check)
3. Observe request hangs indefinitely — no response, no error

Expected

• Gateway responds normally to all HTTP requests

Actual

• All HTTP requests hang; gateway appears up (port bound) but never responds

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

pnpm test -- src/gateway/net.test.ts — 114/114 pass including 2 new Windows-specific tests asserting ::1 is skipped.

Human Verification (required)

• Verified scenarios: Windows platform guard returns ["127.0.0.1"] only; non-Windows path unchanged; both new unit tests pass; full gateway test suite passes.
• Edge cases checked: IPv6-only environments (not affected — Windows guard is platform-conditional); non-Windows platforms (unchanged behaviour verified).
• What you did not verify: Live Windows hardware end-to-end (unit tests mock process.platform).

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: Users on Windows who rely on ::1 binding for some custom routing
  • Mitigation: The hang makes ::1 non-functional on Windows already — no real regression. If Windows IPv6-only support is needed in future, a dedicated UV_TCP_IPV6ONLY flag approach should be implemented separately.

Changed files

• src/gateway/net.test.ts (modified, +21/-0)
• src/gateway/net.ts (modified, +6/-0)