Environment

• OpenClaw version: 2026.4.9
• OS: macOS (darwin 25.5.0)
• Install method: Homebrew (/opt/homebrew)
• Service manager: launchd (ai.openclaw.gateway LaunchAgent)

Bug Description

After macOS wakes from sleep (or on boot), the gateway process starts but never opens port 18789. The process appears alive (ps shows it running), but the HTTP server is never started and the port never listens.

Key observation: the gateway log only contains 2 entries — the startup banner and credential sync — then stops. The normal startup sequence ([gateway] starting HTTP server..., [canvas] host mounted at http://127.0.0.1:18789/) never appears.

Root Cause Analysis

The launchd plist uses RunAtLoad=true and KeepAlive=true. On wake/boot, launchd starts the gateway immediately, before the network stack is ready (Wi-Fi reassociation → DHCP → DNS all take time).

The gateway's startup sequence includes a remote authentication/validation HTTP call. When this call is made during the post-wake network window:

1. The TCP connection enters SYN_SENT state
2. The request hangs indefinitely — no timeout is set at the application layer
3. The process does not crash, so launchd's KeepAlive never triggers a restart
4. Result: the gateway is permanently stuck in the initialization phase

# Process is alive but port never opens:
$ lsof -i :18789
(no output)

$ ps aux | grep openclaw
peterson  3008  openclaw   ← alive, 0% CPU, just waiting

Expected Behaviour

The gateway should either:

• Fail fast with a non-zero exit code if the startup network request times out (allowing launchd's KeepAlive to restart it with exponential backoff until connectivity is established), or
• Retry the authentication call internally with a timeout+backoff loop before proceeding

Suggested Fix (for openclaw team)

Apply a timeout (5–10 seconds) to any network calls made during gateway initialization. On timeout or connection failure, log the error and exit(1). launchd will then restart the process automatically, and by the next attempt the network is typically ready.

// Example — apply to the auth/validation fetch at startup
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 8000);
try {
  await fetch(AUTH_URL, { signal: controller.signal });
} catch (err) {
  console.error('[gateway] startup network check failed:', err.message);
  process.exit(1);  // let launchd KeepAlive restart us
} finally {
  clearTimeout(timer);
}

Workaround (user-side)

Created a wrapper script (~/.local/bin/openclaw-gateway-start) that polls for connectivity before exec-ing the gateway, and pointed the launchd plist's ProgramArguments at it. This prevents the hang but is a band-aid — the real fix belongs in the application.

Additional Notes

• Reviewed by both Claude (Sonnet 4.6) and Gemini (gemini-3.1-pro-preview) independently; both arrived at the same root cause conclusion.
• NetworkState=true in the plist is not a sufficient fix — on modern macOS it only checks that a network interface is active, not that IP/DNS/internet are actually reachable.