Summary

On macOS with OpenClaw 2026.5.12, the generated LaunchAgent uses KeepAlive=true. If a foreground/manual gateway already owns the configured port, starting the LaunchAgent causes the service process to detect the existing healthy gateway, exit cleanly with code 0, and then launchd restarts it again. This can create repeated gateway startup/shutdown churn even though there is no config or runtime crash.

This looks like the macOS equivalent of the supervisor restart-cascade behavior discussed in #80696, and the local workaround matches the proposed direction in #73849.

Environment

• OpenClaw: 2026.5.12 (f066dd2)
• macOS: arm64, macOS 26.x
• Node: 22.22.0
• Install/runtime: npm global install, macOS LaunchAgent
• Gateway port: 18789

What happened

1. A foreground/manual gateway was running with:

   openclaw gateway run
   

2. The LaunchAgent was installed with:

   KeepAlive = true
   RunAtLoad = true

3. Running openclaw gateway start loaded the LaunchAgent.

4. The LaunchAgent process started, noticed the existing gateway on 18789, and exited cleanly. Logs showed repeated entries like:

   [gateway] starting HTTP server...
   [health-monitor] started
   [shutdown] started: gateway startup failed
   [shutdown] completed cleanly
   [gateway] already running under launchd; existing gateway is healthy, leaving it in control
   

5. Because KeepAlive=true restarts after any exit, including successful exit, launchd kept starting another gateway process roughly every throttle interval.

This produced a loop of launchd-owned gateway attempts while the foreground gateway continued to own the port.

Clean local test

I patched the local LaunchAgent plist from:

KeepAlive = true

to:

KeepAlive = {
  SuccessfulExit = false
}

Then I reran openclaw gateway start while the foreground gateway still owned 18789.

Observed result after 30 seconds:

state = not running
runs = 1
last exit code = 0
semaphores = {
  successful exit => 0
}

The foreground gateway remained healthy, and the LaunchAgent did not keep restarting.

Expected behavior

If the gateway process exits cleanly because it detected an already-running healthy gateway, launchd should not keep restarting it forever.

Actual behavior

With KeepAlive=true, launchd restarts after clean exit code 0, creating avoidable churn and making recovery/handoff/debugging much harder.

Suggested fix

Generate the macOS LaunchAgent with:

KeepAlive = {
  SuccessfulExit = false
}

instead of KeepAlive=true, as proposed in #73849.

Related issues/PRs:

• fix(daemon): use KeepAlive SuccessfulExit=false to prevent launchd crash-loop #73849
• systemd unit: RestartSec=5 vs warmup time defeats gateway-lock exit-78 protection #80696
• [v29] CLI commands trigger gateway restart — "wait 5s and retry" takes over running gateway port #75398
• macOS: retry stale launchd bootstrap #81728