OpenClaw Doctor (macOS)

macOS Gateway 24/7 watchdog with 4-layer health checks and auto-repair. Monitors: L1 process alive, L2 HTTP port, L3 WebSocket communication (1006 detection)...

Security Scan

The skill's files and runtime instructions match its stated purpose as a macOS watchdog for an OpenClaw Gateway; there are a few minor inconsistencies and missing artifacts that the user should verify before installing.

Purpose & Capability

The name/description align with the included script: it checks process, HTTP, WebSocket errors, prevents sleep, and attempts restarts. The script calls an 'openclaw' CLI and uses launchctl/launch agents, which is reasonable for a Gateway watchdog. Minor mismatch: registry metadata in the skill header said no required binaries, but the SKILL.md metadata and the script expect commands like curl, pgrep, launchctl, caffeinate and the openclaw CLI — the openclaw binary is not declared in the registry 'Required binaries' list.

Instruction Scope

SKILL.md instructions stay within watchdog/setup duties (copy script, set env vars, install LaunchAgent). The script reads local logs (/tmp/openclaw/openclaw-YYYY-MM-DD.log) and writes logs to ~/.openclaw/logs — these are expected for debugging but worth reviewing. It also invokes 'openclaw doctor --repair' and 'openclaw gateway start' which can perform non-trivial repair actions; users should confirm what those commands do on their system before enabling automated repairs. SKILL.md references a 'references/ai.openclaw.doctor.plist' to edit, but that file is not present in the bundle.

Install Mechanism

This is an instruction-only skill with no install spec or remote downloads. The only persistent change it instructs is adding a LaunchAgent and copying the provided script to ~/.openclaw — low install-surface and no external code fetches in the package.

Credentials

No credentials or external network endpoints are requested. The script probes only a local gateway URL (default http://127.0.0.1:18789) and manipulates local services and files. Environment variables offered for customization are optional and limited to service names/URL.

Persistence & Privilege

The skill asks the user to install a LaunchAgent (normal for a watchdog) which grants persistent background execution. 'always: false' and autonomous invocation of the skill by the agent are default. This persistence is proportional for a 24/7 watchdog but means the script will run periodically and may restart services — verify you want that behavior.

Assessment

Before installing: (1) Inspect the provided scripts yourself (they are included) and confirm you trust the 'openclaw' CLI that the script invokes — the script will call openclaw doctor/gateway start which can restart services. (2) The SKILL.md mentions a references/ai.openclaw.doctor.plist but that file is not present in the package — do not copy or run an unknown plist; request the missing plist or create a LaunchAgent yourself following the documented fields. (3) Confirm service names (OPENCLAW_DOCTOR_SERVICE_NAME and OPENCLAW_DOCTOR_NODE_SERVICE) match your system's launchd labels; mismatches could cause failed restarts. (4) Note the script reads local logs (/tmp/openclaw/...) and writes to ~/.openclaw/logs; ensure those paths are acceptable and do not contain sensitive information you don't want aggregated. (5) If you enable the LaunchAgent, expect periodic automatic restarts and caffeinate (prevents sleep) — if you prefer manual control, run the script manually for testing first. If you want higher assurance, request the missing plist and explicit declaration of required binaries (including the openclaw CLI) from the skill author before installation.

OpenClaw Doctor — macOS Gateway 看门狗 v2

24/7 health watchdog for OpenClaw Gateway on macOS. Detects and auto-repairs four layers of failure.

Why

OpenClaw Gateway is the message bridge — if it dies, the AI assistant goes silent. Common failure modes on macOS:

Layer	Failure	Symptom
L1	Process crash	Complete silence
L2	HTTP port stuck	Complete silence
L3	WebSocket 1006 disconnect	Process alive, HTTP OK, but messages don't arrive (sneakiest!)
L4	Mac sleep/hibernate	All connections die after lid close or idle timeout

Architecture

LaunchAgent (every 5 min)
  → L1: pgrep + launchctl (process alive?)
  → L2: curl HTTP probe (port responding?)
  → L3: Log scan for WS 1006 errors (communication healthy?)
  → L4: caffeinate keepalive (prevent sleep)
  → Auto-repair with minimum intervention principle

Repair Strategy (escalating)

Failure	Action	Rationale
Process down	openclaw doctor --repair → restart Gateway	Process crashed
HTTP unreachable	Restart Gateway	Port stuck
WS frequent disconnect	Restart Node first → then full restart	WS layer issue, Node restart usually sufficient
Post-sleep recovery	Gateway + Node dual restart	All connections need rebuild

Setup

1. Copy the script

cp scripts/doctor.sh ~/.openclaw/doctor.sh
chmod +x ~/.openclaw/doctor.sh

2. Configure (optional)

Environment variables for customization:

# In ~/.bashrc or ~/.zshrc (if non-default)
export OPENCLAW_DOCTOR_GATEWAY_URL="http://127.0.0.1:18789"  # default
export OPENCLAW_DOCTOR_SERVICE_NAME="ai.openclaw.gateway"     # default
export OPENCLAW_DOCTOR_NODE_SERVICE="ai.openclaw.node"        # default

3. Install LaunchAgent

Edit references/ai.openclaw.doctor.plist — replace REPLACE_WITH_HOME with your actual home directory path (e.g. /Users/yourname).

# Copy and customize the plist
cp references/ai.openclaw.doctor.plist ~/Library/LaunchAgents/ai.openclaw.doctor.plist
sed -i '' "s|REPLACE_WITH_HOME|$HOME|g" ~/Library/LaunchAgents/ai.openclaw.doctor.plist

# Load the service
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.doctor.plist

4. Verify

# Manual test run
bash ~/.openclaw/doctor.sh

# Check logs
tail -10 ~/.openclaw/logs/doctor.log

# Confirm caffeinate is running
pgrep -la caffeinate

# Confirm LaunchAgent is loaded
launchctl list | grep doctor

Logs

Location: ~/.openclaw/logs/doctor.log

Prefix	Meaning
HEARTBEAT	Periodic health confirmation (hourly)
ALERT	Anomaly detected
DIAGNOSIS	Fault classification
ACTION	Repair in progress
RESOLVED	Fault repaired
CRITICAL	All repair attempts failed
INFO	General info (e.g. caffeinate started)

Auto-rotates at 5MB (keeps last 1000 lines).

Troubleshooting

Process alive + HTTP OK but messages don't arrive? → WS disconnect. Check: grep "1006" /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | tail -10

Disconnects every night? → Mac sleep. Verify caffeinate: pgrep -la caffeinate

Doctor itself not running? → Check LaunchAgent: launchctl list | grep doctor. Reload if missing.

Temporarily disable:

launchctl bootout gui/$(id -u)/ai.openclaw.doctor

Files

• scripts/doctor.sh — Main watchdog script
• references/ai.openclaw.doctor.plist — LaunchAgent template

Version History

Version	Date	Changes
v1	2026-03-07	Initial: process check + HTTP probe + Gateway restart
v2	2026-03-23	WS health check + Mac sleep prevention + layered repair + Node restart