openclaw - 💡(How to fix) Fix SIGTERM loop after physical network migration — mDNS crash presents with no visible error in logs (2026.5.27, macOS arm64)

Environment

• macOS, Apple Silicon (arm64)
• OpenClaw 2026.5.27 (27ae826)
• Node.js 24.16.0
• Gateway managed as LaunchAgent (ai.openclaw.gateway)
• Channels: Slack, WhatsApp, Telegram, BlueBubbles

Trigger

Machine physically relocated to a new network in a different country. Gateway had been running stably for weeks before the move. Symptoms began on first startup after the network change, coinciding with a binary update from the previous day (2026.5.27).

Symptoms

Gateway entered a persistent SIGTERM restart loop. The key pattern in the log:

[whatsapp] Listening for WhatsApp inbound messages...  ← T+0
[gateway] signal SIGTERM received                      ← T+0.3s to T+1.2s
[gateway] received SIGTERM; shutting down
[shutdown] completed cleanly in ~165ms
[gateway] loading configuration…                       ← launchd restarts

SIGTERM fired 0.3–1.2 seconds after WhatsApp completed its startup sequence on every single cycle. WhatsApp is the last channel to connect and its socket bind appears to be the event that triggers the mDNS interface probe.

Critically: no unhandled rejection or mDNS error appeared anywhere in the logs. The SIGTERM was the only visible symptom, making diagnosis very difficult and causing several hours of misdiagnosis chasing stale processes, plist corruption, and custom LaunchAgent interactions.

Misleading diagnostic signals

Because gateway-restart.log showed source=launchd-handoff entries and a prior gateway.startup_failed stability bundle existed, the initial hypothesis was a stale process from the binary update handoff. Running OPENCLAW_GATEWAY_RESTART_TRACE=1 openclaw gateway start found and killed stale processes and the gateway briefly survived — but only because the kill temporarily disrupted the restart cycle, not because the root cause was resolved.

Other dead ends investigated before identifying the mDNS cause:

• Custom whatsapp-watcher LaunchAgent — no kill/signal code, confirmed innocent
• Update pending flag file — did not exist
• Dashboard server — no gateway management code
• launchd plist configuration — plist was valid

The stale-process pattern and the network-change/mDNS pattern produce identical observable symptoms (clean SIGTERM loop with no error in logs). This is the core of the diagnostic difficulty.

Secondary problems introduced during diagnosis:

• openclaw gateway stop ran launchctl bootout internally, leaving the bootstrap domain in a broken state (Could not find service "ai.openclaw.gateway" in domain for user gui: 505)
• Manual launchctl unload calls on the whatsapp-watcher plist resulted in Input/output error requiring sudo launchctl bootout to clear
• Recovery required openclaw gateway install followed by openclaw gateway start to re-register the LaunchAgent

Resolution

Adding the following to ~/.openclaw/.env stopped the crash loop immediately:

OPENCLAW_DISABLE_BONJOUR=1

Gateway has been stable since.

Suggested improvements

1. Log the SIGTERM source. When the gateway receives a SIGTERM originating from an internal mDNS/ciao assertion failure, the log should identify the source (e.g. [gateway] SIGTERM from internal mDNS handler: ciao assertion failed) rather than presenting as an externally-sourced signal. The current output is indistinguishable from a legitimate operator restart or a stale process kill.

2. Include mDNS state in diagnostics export. openclaw gateway diagnostics export should include the Bonjour/mDNS enabled state and last mDNS event in the health snapshot so support can identify this class of issue without requesting raw logs.

3. Do not let stale stability bundles obscure live problems. The gateway.startup_failed stability bundle from a prior event (two weeks earlier) appeared in the diagnostics export and drew attention away from the current failure. The export should distinguish between historical bundles and current-session events.

4. Consider auto-disabling mDNS on network change. If @homebridge/ciao cannot gracefully handle network interface changes, the gateway should catch the assertion error and either restart the mDNS subsystem silently or disable it with a warning, rather than propagating a SIGTERM to itself.

Related issues

#3821 (closed), #72561, #72075, #73074, #10887