openclaw - 💡(How to fix) Fix gateway restart mode=reload can leave the LaunchAgent deregistered (bootout→bootstrap race, no fallback)

Summary

On macOS, when the gateway restarts in mode=reload, the launchd handoff can fail with Bootstrap failed: 5: Input/output error and leave the LaunchAgent deregistered with no auto-recovery — even with KeepAlive=true. The gateway stays down until a manual launchctl bootstrap.

Environment

• OpenClaw 2026.5.18
• macOS, LaunchAgent under gui/<uid>
• Node 22

Root cause

The reload handoff script (generated in src/daemon/launchd-restart-handoff.ts, mode === "reload") runs:

launchctl enable "$service_target"
launchctl bootout "$service_target" >/dev/null 2>&1 || true
if launchctl bootstrap "$domain" "$plist_path"; then
  status=0
else
  status=$?
fi

launchctl bootout returns 0 immediately, but launchd processes the unload asynchronously. The immediately-following bootstrap can hit the service while it is still registered / in transition and fail with 5: Input/output error (EIO).

Two compounding problems:

1. No fallback. Unlike the kickstart and start-on-demand templates (which retry with launchctl kickstart -k on failure), the reload template has no fallback path.
2. No auto-recovery. Because the bootout succeeded, launchd treats the service as cleanly deregistered (not crashed), so KeepAlive=true does not restart it.

Net effect: the gateway is left with no registered label and never comes back on its own.

Observed log (gateway-restart.log)

openclaw restart attempt source=launchd-handoff mode=reload target=gui/<uid>/<label> waitPid=...
Bootstrap failed: 5: Input/output error
openclaw restart failed source=launchd-handoff mode=reload status=5

Trigger

mode=reload is selected when rewriteLaunchAgentPlistForRestart detects drift between the on-disk plist and the regenerated one. A stale OPENCLAW_SERVICE_VERSION in the generated env file after an upgrade is enough to change the service description (plist Comment), which flips the restart into the fragile reload path on every config change that requires a channel reload. So once the env file goes stale post-upgrade, the next channel-config reload reliably knocks the gateway offline.

Suggested fix

Make mode=reload resilient — any one of:

1. Replace bootout + bootstrap with launchctl kickstart -k "$service_target" (restarts in place, no unload required), or
2. Poll launchctl print "$service_target" until it fails (confirming the unload actually completed) before calling bootstrap, or
3. Give reload the same kickstart -k fallback the other templates already have.

Manual recovery (workaround)

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<label>.plist