openclaw - 💡(How to fix) Fix Gateway update/restart races launchd KeepAlive respawn, causing port conflict [2 comments, 2 participants]

Summary

During openclaw update (and gateway restarts triggered by updates), the new gateway process is sometimes already running (respawned by launchd) before the update script's own restart logic executes. This causes the restart attempt to fail with a port conflict on 18789.

Observed behavior

The update completes but the UI hangs briefly before recovering. The gateway log shows the following sequence:

1. Old process is stopped via launchctl
2. launchd immediately respawns the process (within ~1 second, per ThrottleInterval: 1 in the plist)
3. The update script then attempts its own restart, finds port 18789 already occupied
4. Log message: Gateway already running locally. Stop it (openclaw gateway stop) or use a different port.
5. Eventually resolves because launchd's KeepAlive keeps the valid new process running

Root cause

The plist has KeepAlive: true and ThrottleInterval: 1. When the update process calls launchctl stop, launchd respawns the process within 1 second. The update script's subsequent restart races against this respawn and loses the port.

Expected behavior

The update/restart process should either:

• Temporarily unload the launchd job (launchctl unload) during the update cycle, then reload after (launchctl load)
• Or wait for the port to be free before attempting to bind (port-clear check with timeout)
• Or detect that the new version is already running on the correct port and skip the restart

Environment

• macOS (Darwin 25.4.0, arm64)
• OpenClaw version: 2026.5.6 (also observed on prior version)
• Service type: LaunchAgent
• Port: 18789

Reproducibility

Reproducible on every openclaw update run. Self-heals each time but causes a visible hang during the update.