Gateway Health Monitor

Diagnose and fix OpenClaw gateway stability issues on macOS. Covers the most common failure modes that cause extended downtime.

Quick Diagnosis

Run the diagnostic script:

CODEBLOCK0

This checks: process state, launchd classification, restart count, plist config, power management, and plugin resolve loops.

Common Failure Modes

1. Plugin Restart Loop (most common)

Symptoms: Gateway restarts every 5-7 minutes. Log shows restartReason=config.patch with plugins.installs.*.resolvedAt.

Cause: Plugins re-resolve on every boot → write new timestamps to openclaw.json → config watcher detects "change" → triggers deferred restart → SIGTERM → repeat.

Fix: Set gateway.reload.mode to "hot":

CODEBLOCK1

In hot mode, safe changes hot-apply instantly. Critical changes (like plugin timestamps) only log a warning — no auto-restart. This breaks the loop.

Verify: grep "reload" ~/.openclaw/logs/gateway.log | tail -5 should show config change applied (dynamic reads) instead of restart.

2. macOS Throttling ("inefficient" classification)

Symptoms: Gateway goes down and stays down for 30-60+ minutes. launchctl print shows immediate reason = inefficient.

Cause: After many restarts (10+/day), macOS marks the job as low-priority and delays restarts via App Nap / Power Nap logic.

Fix: Add these keys to the launchd plist (~/Library/LaunchAgents/ai.openclaw.gateway.plist):

CODEBLOCK2

Then reload:

CODEBLOCK3

Note: openclaw gateway start overwrites the plist. Use the patcher script (below) to auto-reapply.

3. Hung Shutdown

Symptoms: Gateway receives SIGTERM but doesn't exit. launchd can't restart because old PID still alive.

Fix: Set ExitTimeOut in the plist:

CODEBLOCK4

After 10 seconds, launchd sends SIGKILL.

4. Power Nap Interference

Symptoms: Gateway goes down during Mac sleep/wake cycles.

Check: INLINECODE14

Fix: INLINECODE15

Plist Auto-Patcher

Since openclaw gateway start overwrites the plist, use scripts/patch-plist.sh as a launchd WatchPaths agent:

CODEBLOCK5

This creates a launchd agent that watches the gateway plist and re-adds ExitTimeOut, ProcessType, and LowPriorityBackgroundIO within seconds of any overwrite.

Monitoring

One-liner health check

CODEBLOCK6

Returns exit code 0 if healthy, 1 if issues detected. Suitable for cron or heartbeat integration.

Continuous monitoring (cron integration)

Add to your OpenClaw cron:

CODEBLOCK7

Recommended Configuration

For maximum stability on macOS:

CODEBLOCK8

Plus plist keys: ExitTimeOut=10, ProcessType=Interactive, LowPriorityBackgroundIO=false, ThrottleInterval=1, KeepAlive=true.

Troubleshooting Reference