Bug Report: Internal restart via stop && start permanently kills gateway on macOS

Version: OpenClaw 2026.4.22 (00bd2cf) Platform: macOS 26.4.1 (arm64) · node 24.4.1 Severity: Critical — gateway self-destructs and never recovers

Summary

When OpenClaw internally triggers a gateway restart (e.g. after config changes like switching web-search provider), it executes:

openclaw gateway stop && sleep 2 && openclaw gateway start

On macOS with launchd, this sequence fails to bring the gateway back up, leaving the service permanently offline. Because OpenClaw runs inside the gateway, once the gateway dies it can no longer fix itself — this is a self-destruct mechanism.

Root Cause Analysis

1. stop && start is not atomic with launchd

openclaw gateway stop causes the process to exit cleanly. On macOS, launchd with KeepAlive=true does not restart a service that exits with code 0 — it considers it an intentional shutdown. The sleep 2 gap is too short for the old service to fully bootout, so the subsequent start (bootstrap) often silently fails or leaves the service in a "not loaded" state.

2. Contrast with openclaw gateway restart

The CLI restart command uses SIGUSR1 → "full process restart (supervisor restart)", which keeps the launchd service alive:

[gateway] received SIGUSR1; restarting
[gateway] restart mode: full process restart (supervisor restart)

This path works reliably because launchd never sees the process exit.

3. Restart continuation is also broken

Even when a restart succeeds via SIGUSR1, the restart-sentinel logs show:

[restart-sentinel] Gateway restart restart ok (gateway.restart):
  continuation delivery failed: Error: restart continuation route unavailable

This means interrupted sessions/tasks are lost after restart.

Evidence from Logs

Last successful internal restart (SIGUSR1 path)

2026-04-25T22:12:50.189+08:00 [gateway] received SIGUSR1; restarting
2026-04-25T22:12:55.542+08:00 [gateway] restart mode: full process restart (supervisor restart)

The failing stop && start sequence

2026-04-25T23:06:26.342+08:00 [exec] elevated command
  openclaw gateway stop 2>&1 && sleep 2 && openclaw gateway start 2>&1

2026-04-25T23:06:27.683+08:00 [gateway] signal SIGTERM received
2026-04-25T23:06:27.683+08:00 [gateway] received SIGTERM; shutting down
2026-04-25T23:06:27.769+08:00 [feishu] feishu[default]: abort signal received, stopping
2026-04-25T23:06:27.771+08:00 [ws] ws client closed manually

2026-04-25T23:06:31.804+08:00 restart scheduled, gateway will restart momentarily

After this point, no more gateway logs until manual intervention 8+ hours later.

Morning state: "not loaded"

$ openclaw gateway status
Service: LaunchAgent (not loaded)
...
Runtime: unknown (Could not find service "ai.openclaw.gateway" in domain for user gui: 501)
Connectivity probe: failed

Manual openclaw gateway start was required to recover:

Gateway LaunchAgent was installed but not loaded; re-bootstrapped launchd service.

Reproduction Steps

1. Start gateway: openclaw gateway start
2. Trigger any config change that causes an internal restart request (e.g. modify plugins.entries via an elevated exec tool that edits openclaw.json)
3. Observe that OpenClaw schedules restart, but then executes stop && start
4. Check openclaw gateway status — it shows "not loaded"

Expected Behavior

Gateway restart should be reliable and self-healing:

• Internal tools should use openclaw gateway restart (SIGUSR1 / supervisor restart) instead of stop && start
• If a full process restart is unavoidable, the restart command must verify the service is actually running after start, and retry if launchctl bootstrap fails
• The restart sentinel should gracefully handle continuation delivery or at least surface the error to the user

Suggested Fixes

1. Immediate: Change elevated exec restart command from stop && sleep 2 && start to restart (or at least stop && sleep 5 && start && openclaw gateway status with retry loop)
2. Better: Implement a restart API endpoint on the gateway itself so internal tools can request restart via WebSocket (gateway.restart tool) instead of shelling out
3. Defensive: After any start command, poll launchctl list / curl http://127.0.0.1:18789/ for up to 10s; if unreachable, retry start once more before giving up
4. Continuation fix: Investigate why restart continuation route unavailable occurs and ensure in-flight tasks can resume after restart

Workaround Applied by User

Until this is fixed, user has deployed an external launchd watchdog (ai.openclaw.watchdog) that checks every 30s:

• Is ai.openclaw.gateway loaded in launchd with state = running?
• Does http://127.0.0.1:18789/ respond within 3s? If either check fails → openclaw gateway start.

This should not be necessary for a self-hosted gateway.