openclaw - 💡(How to fix) Fix LaunchAgent: ThrottleInterval=1 causes unrecoverable gateway downtime after auto-update [1 participants]

Summary

The LaunchAgent plist template hardcodes ThrottleInterval: 1 and omits ExitTimeOut. Combined with the auto-update path using bootout (which removes the service from launchd entirely), this causes extended unrecoverable downtime when an update lands at the wrong moment.

Environment

• macOS 26.4 (arm64), Mac mini M4
• OpenClaw 2026.4.2 (stable channel)
• LaunchAgent service (ai.openclaw.gateway)
• lossless-claw plugin 0.6.1

What happened

Crash #1 (8h53m downtime):

1. Auto-update to 2026.4.2 triggered at 21:01 PDT on Apr 3
2. npm i openclaw@latest ran in-place while gateway was live
3. lossless-claw plugin failed to register during the mid-update file mismatch window (Unable to resolve plugin runtime module)
4. Update flow called launchctl bootout to restart the gateway
5. bootout removed the service from launchd entirely
6. The follow-up bootstrap never completed (process tree died with the bootout)
7. launchd logs confirm: removing service: ai.openclaw.gateway + job state = removed
8. Gateway stayed dead from 21:02 until manual bootstrap at 05:55 next morning

Crash #2 (same day):

1. Agent ran openclaw gateway restart which internally used bootout + bootstrap
2. bootout at 06:27:48 removed the service again
3. bootstrap at 06:28:24 re-registered it, gateway spawned (PID 65862)
4. Gateway received SIGTERM 5 seconds later at 06:28:29 and exited after 10 seconds
5. launchd respawned (PID 65900) successfully, but the gap caused user-visible downtime

Root causes

1. ThrottleInterval=1 is too aggressive

launchd-BPnToG40.js hardcodes:

<key>ThrottleInterval</key>
<integer>1</integer>

With ThrottleInterval: 1 and KeepAlive: true, if the gateway crashes and respawns repeatedly (e.g. during a plugin load failure), launchd treats it as thrashing and permanently stops restarting the service. The user must manually bootstrap + kickstart to recover.

Suggested fix: Change to <integer>10</integer> (or make it configurable). This gives the process enough time to stabilize on restart without triggering launchd's anti-thrash protection.

2. Missing ExitTimeOut

The plist template does not set ExitTimeOut. macOS defaults to 5 seconds, which is too tight for a gateway with active WebSocket connections. If the gateway doesn't exit within 5s of SIGTERM, launchd sends SIGKILL (confirmed in logs: Service did not exit 5 seconds after SIGTERM. Sending SIGKILL.).

Suggested fix: Add <key>ExitTimeOut</key><integer>20</integer> to the plist template.

3. Auto-update uses bootout (permanent service removal)

The update path runs bootout to stop the gateway before updating. bootout removes the service registration from launchd entirely. If the subsequent bootstrap fails for any reason (process tree killed, npm install error, disk full, etc.), the service stays unregistered and launchd will never restart it.

The detached restart handoff script in update-cli-qSRyEupZ.js already implements the correct pattern:

if ! launchctl kickstart -k ... ; then
  launchctl enable ...
  launchctl bootstrap ...
  launchctl kickstart -k ... || true
fi

But the stop command and some update paths still use bootout directly.

Suggested fix: Use kickstart -k as the primary restart mechanism everywhere. Reserve bootout only for openclaw gateway uninstall.

Impact

Any OpenClaw user running as a LaunchAgent on macOS is vulnerable to this. A single failed auto-update or plugin crash during startup can leave the gateway permanently dead until manual intervention. For headless/unattended deployments (Mac minis, build servers), this means hours of unnoticed downtime.

Workaround

1. Manually patch the plist after install:
   • ThrottleInterval from 1 to 10
   • Add ExitTimeOut: 20
2. Always use openclaw gateway restart (not raw launchctl bootout)
3. Pin or control update timing to avoid mid-flight npm updates