Description

OpenClaw gateway crashes repeatedly on macOS when running on WiFi (especially mobile hotspot) networks. The crash is caused by an unhandled assertion error in the @homebridge/ciao mDNS/Bonjour library.

Error

Unhandled promise rejection: AssertionError [ERR_ASSERTION]: Reached illegal state: IPV4 address change from defined to undefined!

Environment

• OS: macOS (Mac Mini M4)
• OpenClaw version: 2026.3.13 (61d171a)
• Network: Mobile WiFi hotspot (not wired ethernet)
• Install method: npm install -g openclaw

Steps to Reproduce

1. Install OpenClaw on macOS
2. Connect via WiFi (especially mobile hotspot with unstable IP)
3. Start gateway with openclaw gateway start
4. Wait for network fluctuation (IP renewal, brief disconnection)
5. Gateway crashes with the above assertion error

Root Cause Analysis

The @homebridge/ciao library (used for mDNS/Bonjour service discovery) throws an unhandled AssertionError when the network interface's IPv4 address changes from a defined value to undefined during a WiFi fluctuation. This is a known pattern with mobile hotspots and unstable WiFi connections.

Additionally observed: repeated gateway hostname conflict resolved messages in logs, indicating Bonjour name conflicts on the local network.

Workaround

Setting NODE_OPTIONS="--unhandled-rejections=warn" in the LaunchAgent plist prevents the crash (error becomes a warning instead), but this is not a proper fix.

Combined with KeepAlive=true in LaunchAgent, the gateway auto-restarts after crash, but there is a brief window where messages are missed.

Expected Behavior

The gateway should gracefully handle network interface changes without crashing. Either:

1. Catch the assertion error from @homebridge/ciao and reconnect
2. Make mDNS/Bonjour optional or disableable for headless server use cases
3. Update to a patched version of @homebridge/ciao that handles this edge case

Logs

[gateway] gateway name conflict resolved
[gateway] gateway hostname conflict resolved
Unhandled promise rejection: AssertionError [ERR_ASSERTION]: Reached illegal state: IPV4 address change from defined to undefined!

Crash pattern observed at: 13:14, 14:19, 16:47 on same day, all during WiFi fluctuations.