openclaw - 💡(How to fix) Fix Restart race condition with LaunchAgent KeepAlive causes shutdown instead of restart

Version

v2026.5.27 (27ae826), running on macOS (arm64) with LaunchAgent (~/Library/LaunchAgents/ai.openclaw.gateway.plist, KeepAlive=true)

Summary

When the gateway tool triggers a restart (e.g. after a config change that requires restart), the restart logic fails because of a port conflict with the LaunchAgent process, causing the gateway to shut down completely instead of restarting.

Reproduction

1. Install gateway as LaunchAgent with KeepAlive=true (standard installer behavior)
2. Trigger a gateway restart (e.g. via gateway tool config.patch that needs restart, or gateway restart)
3. Gateway receives SIGTERM, tries to stop LaunchAgent, but launchd immediately respawns a new process before the old one releases port 18789
4. Restart fails → gateway falls through to a full shutdown

Log Evidence

From /tmp/openclaw/openclaw-2026-05-29.log:

2026-05-29T22:32:29.150-07:00 gateway tool: restart requested
2026-05-29T22:32:29.152-07:00 restart request coalesced (already scheduled)
2026-05-29T22:32:41.252-07:00 signal SIGTERM received
2026-05-29T22:32:41.253-07:00 received SIGTERM; shutting down        ← SHOULD be "restarting"
2026-05-29T22:32:41.266-07:00 shutdown started: gateway stopping
2026-05-29T22:32:41.325-07:00 ERROR: Gateway stop failed: Error: gateway port 18789 is still busy after LaunchAgent stop
                                    Port 18789 is already in use.
                                    - pid 21331 jeremy: /opt/homebrew/opt/node/bin/node … gateway --port 18789
2026-05-29T22:32:41.398-07:00 shutdown completed cleanly in 133ms

The gateway stayed down until launchd re-bootstrapped ~5 hours later:

2026-05-30T04:17:39.912-07:00 Gateway LaunchAgent was installed but not loaded; re-bootstrapped launchd service.

Root Cause Analysis

1. gateway restart sends SIGTERM and tries to stop the LaunchAgent
2. KeepAlive=true in the plist causes launchd to immediately respawn the process
3. The new process binds to port 18789 while the old process is still releasing it
4. The restart fallback logic treats the port conflict as a fatal error → full shutdown with no retry
5. LaunchAgent doesn't auto-restart because it was "stopped" deliberately vs. crashed

Expected Behavior

• Gateway should successfully restart and come back up
• If LaunchAgent interferes with port release, the restart logic should retry or use a different strategy
• Gateway should never end up in a "permanently down" state after a restart request

Workaround

Manually launchctl bootout the LaunchAgent before restart:

launchctl bootout gui/$UID/ai.openclaw.gateway
openclaw gateway start

Related

See also #88046 regarding upgrade-related LaunchAgent issues.