OpenClaw helper

Keep your OpenClaw service alive. Automatically.

中文文档

Get Started

npm install -g openclaw-helper
openclaw-helper watch -d

That's it. Doctor monitors your OpenClaw gateway in the background, restarts it when it goes down, and tells you what happened. Zero configuration needed -- it reads everything from your existing OpenClaw setup.

Core Commands

openclaw-helper watch            # Start monitoring (foreground)
openclaw-helper watch -d         # Start monitoring (background)
openclaw-helper unwatch          # Stop monitoring

openclaw-helper status           # Quick health check

These four commands cover 90% of daily use.

Gateway Management

openclaw-helper gateway start    # Start the OpenClaw gateway
openclaw-helper gateway stop     # Stop the gateway
openclaw-helper gateway restart  # Restart the gateway

Diagnostics & Logs

openclaw-helper doctor           # Full diagnostics (binary, gateway, channels)
openclaw-helper logs             # View gateway logs
openclaw-helper logs --error     # View error logs only
openclaw-helper logs --doctor    # View Doctor's own event logs
openclaw-helper dashboard        # Web management UI (http://localhost:9090)

Install

# npm (recommended)
npm install -g openclaw-helper

# or run without installing
npx openclaw-helper status

Requires Node >= 22 (same as OpenClaw).

How It Works

Doctor auto-detects your OpenClaw installation:

• Reads ~/.openclaw/openclaw.json for gateway port, channels, agents
• Finds the launchd service from ~/Library/LaunchAgents/
• Checks health via openclaw health --json (real gateway RPC, not HTTP)
• Restarts via launchctl kickstart when needed

You don't configure OpenClaw details. Doctor figures them out.

All Commands

Configuration

Config is stored at ~/.openclaw-doctor/config.json. Created automatically on first run. Only Doctor's own preferences -- no OpenClaw settings needed.

{
  "checkInterval": 30,
  "failThreshold": 3,
  "dashboardPort": 9090,
  "maxRestartsPerHour": 5,
  "openclawProfile": "default",
  "notify": {
    "webhook": {
      "enabled": false,
      "url": "",
      "bodyTemplate": "{\"msgtype\":\"text\",\"text\":{\"content\":\"{{message}}\"}}"
    },
    "system": {
      "enabled": true
    }
  }
}

Notifications

Doctor notifies you across the full lifecycle:

Channels: Webhook (DingTalk, Feishu, Slack, etc.) + macOS system notifications.

Skills Integration

Doctor runs as a standalone daemon, callable by OpenClaw or other tools:

openclaw-helper status --json    # Machine-readable output
openclaw-helper watch -d         # Idempotent -- safe to call repeatedly

If the caller crashes, Doctor keeps running.

Architecture

                          +-----------------+
                          |  Notification   |
                          |  (Webhook/OS)   |
                          +--------^--------+
                                   |
+-------------+    CLI    +--------+--------+    RPC      +-----------+
|  OpenClaw   | --------> |                 | ---------> |  OpenClaw |
|  / Scripts  |           | openclaw-doctor |            |  Gateway  |
|  / Skills   | <-------- |  (daemon)       | <--------- | :18789    |
+-------------+  stdout   +--------+--------+  health    +-----------+
                                   |
                          +--------v--------+
                          | ~/.openclaw/logs |
                          | (read & analyze) |
                          +-----------------+

Development

git clone https://github.com/openclaw/openclaw-doctor.git
cd openclaw-doctor
npm install

npm run dev -- status          # Quick test
npm run dev -- watch           # Foreground monitoring
npm run dev -- watch -d        # Background daemon
npm run dev -- unwatch         # Stop daemon

npm run build                  # Build for distribution

Roadmap

• Health check via openclaw health --json + auto-restart with throttling
• Auto-detect OpenClaw config (gateway port, channels, agents, launchd)
• Background daemon mode (watch -d / unwatch)
• Gateway management (gateway start/stop/restart)
• Read and display OpenClaw gateway logs
• Web status dashboard
• --json output for status
• Notification system (Webhook + macOS)
• logs --tail (real-time follow)
• config command (get/set)
• Multiple service monitoring
• Linux systemd support

License

MIT

Publishing

This repo publishes two npm packages from the same codebase:

• openclaw-helper — the main package (package.json)
• openclaw-helper — alias package (package.openclaw-helper.json)

Both packages share the same version number and dist output.

Release a new version

# 1. Bump version (patch / minor / major)
npm version patch

# 2. Build + publish both packages
npm run release

npm run release calls scripts/publish.sh, which:

1. Builds once (npm run build)
2. Publishes openclaw-helper with the default package.json
3. Temporarily swaps in package.openclaw-helper.json, publishes openclaw-helper, then restores

To update the openclaw-helper package metadata (description, keywords, bin name, etc.), edit package.openclaw-helper.json. Keep version in sync — it's automatically picked up from whichever package.json is active during publish.