← Back to Skills Marketplace
OpenClaw Doctor (macOS)
by
Dr-xiaoming
· GitHub ↗
· v1.0.0
· MIT-0
202
Downloads
0
Stars
0
Active Installs
1
Versions
Install in OpenClaw
/install openclaw-doctor-macos
Description
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)...
README (SKILL.md)
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 scriptreferences/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 |
Usage Guidance
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.
Capability Analysis
Type: OpenClaw Skill
Name: openclaw-doctor-macos
Version: 1.0.0
The skill provides a legitimate watchdog utility for maintaining the OpenClaw Gateway on macOS. The shell script (scripts/doctor.sh) implements multi-layered health checks using standard system tools like pgrep, curl, and launchctl, and uses caffeinate to prevent system sleep. No evidence of data exfiltration, malicious command execution, or obfuscation was found; the persistence mechanism via LaunchAgent is explicitly documented and aligned with the stated purpose of a 24/7 background monitor.
Capability Assessment
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.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install openclaw-doctor-macos - After installation, invoke the skill by name or use
/openclaw-doctor-macos - Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.0
Initial release: macOS Gateway 24/7 watchdog with L1-L4 health checks, WS 1006 detection, caffeinate sleep prevention, layered auto-repair
Metadata
Frequently Asked Questions
What is 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)... It is an AI Agent Skill for Claude Code / OpenClaw, with 202 downloads so far.
How do I install OpenClaw Doctor (macOS)?
Run "/install openclaw-doctor-macos" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is OpenClaw Doctor (macOS) free?
Yes, OpenClaw Doctor (macOS) is completely free, licensed under MIT-0. You can download, install and use it at no cost.
Which platforms does OpenClaw Doctor (macOS) support?
OpenClaw Doctor (macOS) is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created OpenClaw Doctor (macOS)?
It is built and maintained by Dr-xiaoming (@dr-xiaoming); the current version is v1.0.0.
More Skills