#16845: fix(daemon): gateway auto-restart on SIGTERM + agent restart guidelines
gateway
agents
stale
size: XS
Cluster:
Gateway Restart Improvements
## Summary
This PR fixes an issue where the OpenClaw gateway would remain stopped after receiving SIGTERM, instead of automatically restarting.
### Root Cause
The LaunchAgent's `KeepAlive=true` setting only restarts the service on abnormal termination (crashes). When the gateway receives SIGTERM and exits cleanly (exit code 0), launchd considers it an intentional stop and does not restart it.
Additionally, AI agents were running `launchctl bootout` without a subsequent `load`, leaving the gateway permanently stopped.
### Changes
1. **`src/daemon/launchd-plist.ts`**: Changed `KeepAlive` from `true` to a dict with `SuccessfulExit=false`, ensuring restart on all terminations including SIGTERM.
2. **`src/daemon/service-audit.ts`**: Updated audit logic to recognize the new plist format.
3. **`src/agents/system-prompt.ts`**: Added explicit guidance for agents to use `openclaw gateway restart` instead of direct `launchctl bootout` commands.
4. **`AGENTS.md`**: Added documentation about proper gateway restart procedures.
### Testing
- Verified that the new plist format is correctly generated after `openclaw gateway install`
- Verified that `openclaw gateway restart` uses `kickstart -k` which handles stop+start atomically
- Build passes, lint clean
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Changed LaunchAgent `KeepAlive` configuration from boolean to dict with `SuccessfulExit=false` to enable auto-restart on SIGTERM. Previously, the gateway would exit cleanly (exit code 0) on SIGTERM and launchd wouldn't restart it. The PR also adds documentation and agent guidance to prevent direct `launchctl bootout` usage, which permanently stops the service.
- Modified plist generation in `src/daemon/launchd-plist.ts` to use `<dict><key>SuccessfulExit</key><false/></dict>` instead of `<true/>`
- Updated `src/daemon/service-audit.ts` regex to recognize both old and new formats for backward compatibility
- Added clear warnings in `src/agents/system-prompt.ts` and `AGENTS.md` directing agents to use `openclaw gateway restart` (which uses `kickstart -k`) instead of `bootout`
- The atomic `kickstart -k` command properly handles stop+start without leaving the service stopped
<h3>Confidence Score: 5/5</h3>
- Safe to merge - addresses a clear bug with proper backward compatibility
- The changes correctly fix the auto-restart issue by using launchd's `SuccessfulExit=false` mechanism. The audit logic maintains backward compatibility by detecting both formats. Documentation changes prevent the problematic `bootout` pattern. The implementation aligns with Apple's launchd behavior where `KeepAlive=true` only restarts on abnormal exits.
- No files require special attention
<sub>Last reviewed commit: e042c52</sub>
<!-- greptile_other_comments_section -->
<sub>(4/5) You can add custom instructions or style guidelines for the agent [here](https://app.greptile.com/review/github)!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#20272: fix: LaunchAgent KeepAlive causes restart loop (fixes #20257)
by MisterGuy420 · 2026-02-18
85.1%
#7155: fix(gateway): use kill SIGTERM instead of bootout for stop
by rafaelreis-r · 2026-02-02
84.9%
#11327: fix(launchd): reload plist from disk on restartLaunchAgent
by caiop91 · 2026-02-07
83.6%
#22224: fix(launchd/macos): prevent restart loop by using KeepAlive.Success...
by ashiabbott · 2026-02-20
82.9%
#18236: macOS daemon: bootstrap LaunchAgent on gateway start after stop
by agisilaos · 2026-02-16
81.0%
#22304: Gateway: fix launchd start after stop
by apethree · 2026-02-21
80.3%
#13084: fix(daemon): multi-layer defense against zombie gateway processes
by openperf · 2026-02-10
79.2%
#21591: fix(update): prevent double restart when refreshing service env
by irchelper · 2026-02-20
79.2%
#11147: fix(daemon): stop gateway by port when no daemon service is active
by jasonthewhale · 2026-02-07
78.7%
#19857: fix(launchd): self-heal restart when service is unloaded
by vibecodooor · 2026-02-18
77.9%