OpenClaw Health Guardian

Monitors OpenClaw Gateway on macOS, auto-restarts on failure with 180s cooldown and max 5 restarts/hour to prevent restart loops.

Security Scan

The skill largely does what its README says (monitor and restart a local OpenClaw Gateway), but the shipped scripts contain hard-coded /Users/pg paths and other inconsistencies that make behavior unpredictable and warrant manual review before installing.

Purpose & Capability

Name/description claim a macOS LaunchAgent to monitor and restart the OpenClaw Gateway — the included scripts implement exactly that. However, many paths in the runtime script are hard-coded to /Users/pg rather than using $HOME; the installer attempts to patch one file (the plist) but does not modify the main health-check script. This mismatch (declared purpose vs. literal requested file paths) is disproportionate and risky because the script may operate on a different user's home directory or fail silently.

Instruction Scope

SKILL.md instructs the agent/user to run the install script which will create LaunchAgent files, write into ~/Library/LaunchAgents, and install scripts/log/state under ~/.openclaw — that's expected. But the health-check script itself references many absolute paths (/Users/pg/...) and hard-coded PATH entries including a specific nvm location. The script will run launchctl bootstrap/bootout/loads, run curl against localhost:18789, call openclaw commands and osascript. There are no unexpected external network endpoints, but the hard-coded user paths and PATH entries expand scope beyond the claimed portable, per-user install and may cause writes in /Users/pg or attempt to run binaries from attacker-controllable locations in $HOME/.nvm if present.

Install Mechanism

No network downloads or third-party package installs: install is local and instruction-only (copying shipped script to user's dotfiles and writing a LaunchAgent plist). That's low-risk compared to remote archive downloads. The installer does run launchctl to load the LaunchAgent, which is normal for this purpose.

Credentials

The skill declares no required env vars or credentials, which matches its local-only behavior. However, the script embeds explicit absolute paths (/Users/pg, explicit nvm path) and a PATH export that favors a specific user layout. Those hard-coded values are not justified by the SKILL.md and may cause cross-user file access or run binaries from unexpected locations. No secrets are requested, but the script's reliance on specific user paths is disproportionate and fragile.

Persistence & Privilege

The skill installs a per-user LaunchAgent and will persist in the user's LaunchAgents folder; this is expected for a persistent health daemon. The skill does not request always:true or system-wide privileges, nor does it modify other skills. It does attempt to load/bootstraps a separate ai.openclaw.gateway LaunchAgent (to start the gateway) which is reasonable for recovery but worth auditing because it manipulates other LaunchAgent units.

Scan Findings in Context

[HARDCODED_USER_PATH_/Users/pg] unexpected: The main script contains many literal references to /Users/pg (logs, state, PATH). For a per-user portable installer this is unexpected and can cause writes to another user's home or failure when the current user is not 'pg'. The installer only replaces /Users/pg in the plist but does not patch the health-check script.

[USE_OF_LAUNCHCTL_BOOTSTRAP_BOOTOUT] expected: The script uses launchctl bootstrap/bootout/load/unload to manage LaunchAgents (including attempting to start ai.openclaw.gateway). This is expected for a tool designed to manage macOS services, but it deserves review because it manipulates other launch units.

[OSASCRIPT_TERMINAL_EXEC] expected: The script uses osascript to open Terminal and run interactive commands for user notification and diagnostics. That is within the claimed behavior, but opening a terminal to run commands should be audited because it executes shell commands in an interactive window (could reveal state or run unintended commands if modified).

What to consider before installing

This skill implements a reasonable local health-checker, but DO NOT run the installer blindly. Before installing: 1) Inspect and fix absolute paths in scripts: replace all /Users/pg occurrences with $HOME (or ensure the files use dynamic $HOME), and remove or parameterize the hard-coded NVM path. 2) Audit the openclaw-health-check.sh contents line-by-line (it runs launchctl bootstrap/bootout and will attempt to start gateway services). 3) Run the scripts manually step-by-step (create directories, copy scripts, review plist) rather than piping the install script straight into bash. 4) Confirm the LaunchAgent plist references the correct user path and that you are comfortable it will run as your account. 5) If you have multiple user accounts or are on a shared machine, ensure the hard-coded paths are fixed; otherwise the script may try to access another user's home. If you are unsure, run the health-check script once manually (bash -x ...) to observe behavior and logs before enabling the LaunchAgent.

Auto-monitor and recover OpenClaw Gateway with intelligent rate limiting.

Quick Start

Install health guardian:

bash ~/.openclaw/skills/openclaw-health-guardian/scripts/install.sh

Verify installation:

launchctl list | grep openclaw

When to Use

• Gateway frequently stops responding
• Need automatic recovery without manual intervention
• Running OpenClaw on macOS with LaunchAgent support
• Want cooldown protection against restart loops

Features

Feature	Value	Description
Check Interval	5 minutes	LaunchAgent StartInterval
Cooldown	180 seconds	Minimum between restarts
Rate Limit	5/hour	Max restarts per hour
HTTP Timeout	5 seconds	curl --max-time
Auto Notify	Terminal popup	AppleScript alert on failure

Workflow

1. Install guardian

   bash ~/.openclaw/skills/openclaw-health-guardian/scripts/install.sh
   

2. Verify service running

   launchctl list | grep com.openclaw.healthcheck
   

3. Monitor logs

   tail -f ~/.openclaw/logs/health-check.log
   

4. Test manually (optional)

   bash ~/.openclaw/scripts/openclaw-health-check.sh
   

Commands

Command	Purpose
launchctl list | grep openclaw	Check service status
tail -f ~/.openclaw/logs/health-check.log	View real-time logs
bash ~/.openclaw/scripts/openclaw-health-check.sh	Manual check
launchctl unload ~/Library/LaunchAgents/com.openclaw.healthcheck.plist	Stop service
launchctl load ~/Library/LaunchAgents/com.openclaw.healthcheck.plist	Start service

File Structure

After installation:

~/.openclaw/
├── scripts/
│   └── openclaw-health-check.sh    # Main script
├── state/
│   ├── last_restart                # Timestamp
│   ├── restart_count               # Hourly counter
│   └── hour_marker                 # Hour tracking
└── logs/
    ├── health-check.log            # Main log
    ├── health-check-daemon.log     # Daemon stdout
    └── health-check-daemon-error.log # Daemon stderr

~/Library/LaunchAgents/
└── com.openclaw.healthcheck.plist  # LaunchAgent config

Log Examples

Normal:

[2026-03-16 10:28:47] No issues found. OpenClaw is healthy!

Cooldown triggered:

[2026-03-16 10:30:05] 冷却期内 (120s/180s)，跳过重启操作

Rate limit triggered:

[2026-03-16 10:30:05] 本小时已达重启上限(5次)，跳过

Restart executed:

[2026-03-16 10:30:02] 已记录重启事件 (冷却: 180s, 限流: 5/小时)
[2026-03-16 10:30:05] Gateway restart completed successfully

Uninstall

# Stop and remove service
launchctl unload ~/Library/LaunchAgents/com.openclaw.healthcheck.plist
rm ~/Library/LaunchAgents/com.openclaw.healthcheck.plist

# Remove scripts and logs
rm ~/.openclaw/scripts/openclaw-health-check.sh
rm -rf ~/.openclaw/state/
rm ~/.openclaw/logs/health-check*.log

Requirements

• macOS 10.14+
• OpenClaw installed
• User home directory write permissions

References

• references/technical-details.md - Implementation details
• references/troubleshooting.md - Common issues