Bug: openclaw gateway restart leaves gateway down for extended periods without error

Summary

The openclaw gateway restart command sends SIGTERM to the gateway process but does not verify that the gateway successfully restarts. This can leave the gateway down for extended periods with no error indication or automatic recovery.

Steps to Reproduce

1. Run openclaw gateway restart from an elevated context (e.g., TUI)
2. Observe the command completes successfully
3. Gateway may or may not restart properly

Expected Behavior

The gateway restart command should:

1. Send SIGTERM to gracefully shutdown
2. Wait for the process to terminate
3. Verify the gateway has successfully restarted (poll health endpoint or check for new PID)
4. Report success or failure to the user

Actual Behavior

The command sends SIGTERM and exits immediately without verification. In my case:

• 18:19:10 EDT - Gateway received SIGTERM and shutdown
• 19:36:44 EDT - Gateway finally started (77 minutes later, after manual intervention)

During the 77-minute gap, the gateway was completely down with no automatic recovery.

Environment

• OpenClaw Version: 2026.3.8
• OS: macOS 26.3 (arm64)
• Node: 22.22.0
• Install: Homebrew (/opt/homebrew/lib/node_modules/openclaw)
• Service: LaunchAgent (ai.openclaw.gateway.plist)

LaunchAgent Configuration

<key>KeepAlive</key>
<true/>
<key>ThrottleInterval</key>
<integer>1</integer>

The LaunchAgent is configured to keep the gateway alive, but the restart still failed.

Evidence

gateway.log

2026-03-12T18:19:09.876-04:00 [exec] elevated command openclaw gateway restart
2026-03-12T18:19:10.744-04:00 [gateway] signal SIGTERM received
2026-03-12T18:19:10.745-04:00 [gateway] received SIGTERM; shutting down
2026-03-12T18:19:10.762-04:00 [gmail-watcher] gmail watcher stopped

... 77 minutes of silence ...

2026-03-12T19:36:44.896-04:00 [gateway] [plugins] loaded without install/load-path provenance...
2026-03-12T19:36:44.963-04:00 [gateway] listening on ws://127.0.0.1:18789...

gateway.err.log

No errors logged between 18:19 and 19:36. No crash reports generated.

Possible Causes

1. No verification step: The restart command doesn't poll for successful restart
2. LaunchAgent race condition: Process may have left a lock file or socket in a bad state
3. macOS sleep/nap intervention: System may have delayed the respawn
4. Port binding issue: Previous process may not have fully released the port

Suggested Fix

The restart command should:

async function restart(): Promise<void> {
  const oldPid = getGatewayPid();
  
  // Send graceful shutdown
  process.kill(oldPid, 'SIGTERM');
  
  // Wait for process to terminate
  await waitForProcessExit(oldPid, { timeout: 10000 });
  
  // Wait for new process to spawn (LaunchAgent should respawn)
  // OR manually spawn if not managed
  await waitForGatewayReady({ 
    timeout: 30000,
    pollInterval: 500 
  });
  
  // Verify health endpoint responds
  const health = await fetch('http://127.0.0.1:18789/health');
  if (!health.ok) {
    throw new Error('Gateway restart failed: health check failed');
  }
  
  console.log('Gateway restarted successfully (PID: %s)', getGatewayPid());
}

Impact

• Availability: Gateway can be down for extended periods without notification
• User Experience: No error message - user assumes restart succeeded
• Automation: Cron jobs or scheduled tasks using restart can leave system in broken state
• Heartbeats: Agent heartbeats fail, scheduled tasks don't run

Workaround

After running openclaw gateway restart, manually verify:

openclaw status

If gateway shows as unreachable, run:

openclaw gateway restart
# or
launchctl kickstart gui/$(id -u) ai.openclaw.gateway