Documentation
Everything you need to get ClawDoctor running and monitoring your OpenClaw setup.
Installation
ClawDoctor is distributed as an npm package. Requires Node.js 18 or newer.
npm install -g clawdoctor
After installing, verify it works:
clawdoctor --version
ClawDoctor stores its config and event database in ~/.clawdoctor/.
Quick Start
Run the interactive setup wizard to configure OpenClaw detection and Telegram alerts:
clawdoctor init
The wizard will:
- Detect your OpenClaw installation path
- Configure Telegram alerts (optional)
- Let you choose which watchers to enable
- Ask whether to enable auto-fix (gateway restart)
Once configured, start the monitoring daemon:
clawdoctor start
Check current health status at any time:
clawdoctor status
View recent events:
clawdoctor log clawdoctor log -n 100 -w GatewayWatcher clawdoctor log -s error
Stop the daemon:
clawdoctor stop
Install as a systemd service
To run ClawDoctor automatically on login:
clawdoctor install-service systemctl --user daemon-reload systemctl --user enable clawdoctor systemctl --user start clawdoctor
What Each Watcher Monitors
GatewayWatcher (every 30s)
Checks whether your OpenClaw gateway process is running. Uses three fallback methods in order: openclaw gateway status, systemctl, and pgrep. If the gateway is down and auto-fix is enabled, it attempts a restart and alerts you on Telegram.
CronWatcher (every 60s)
Reads ~/.openclaw/cron/jobs.json and checks each cron job for consecutive errors (3 or more triggers an alert), failed delivery, and overdue runs (30+ minutes past scheduled time).
SessionWatcher (every 60s)
Scans agent session files under ~/.openclaw/agents/*/sessions/*.jsonl. Detects sessions with errors, aborted sessions, and stuck sessions that have been running for over an hour.
AuthWatcher (every 60s)
Searches system journals and log files for auth failure patterns: 401/403 responses, expired tokens, and auth-related error strings. Catches problems before they cascade across your agents.
CostWatcher (every 5 min)
Reads session cost data from OpenClaw session files. Calculates a rolling baseline from the last 20 historical sessions. Flags any session that spends 3x more than your baseline, catching runaway spend before it gets expensive.
Activating a License
After purchasing a Diagnose or Heal plan, you will receive a license key. Activate it with:
clawdoctor activate <your-license-key>
This validates the key against the ClawDoctor API and stores it in ~/.clawdoctor/license.json. On success, it shows your plan name and the features it unlocks.
Using an environment variable
You can set the license key via environment variable. When CLAWDOCTOR_KEY is set, it takes precedence over ~/.clawdoctor/license.json:
export CLAWDOCTOR_KEY=your-license-key clawdoctor start
If neither the environment variable nor ~/.clawdoctor/license.json is present, ClawDoctor runs on the free plan.
Check your current plan
clawdoctor plan
This shows your current tier (free/diagnose/heal), active features, and key status.
Plan limits
| Feature | Watch (Free) | Diagnose ($9) | Heal ($19) |
|---|---|---|---|
| Max monitors | 5 | 20 | Unlimited |
| All watchers | No | Yes | Yes |
| Auto-fix | No | No | Yes |
Non-Interactive Setup
For automated environments and CI/CD pipelines, use flags to skip prompts:
clawdoctor init \ --openclaw-path /home/user/.openclaw \ --telegram-token 123456:ABCdef \ --telegram-chat -1001234567890 \ --auto-fix \ --no-prompt
All flags are optional. If you omit a flag, its default value is used. The --no-prompt flag suppresses all interactive questions and accepts defaults for anything not specified.
Available flags
| Flag | Description | Default |
|---|---|---|
| --openclaw-path | Path to OpenClaw data directory | ~/.openclaw |
| --telegram-token | Telegram bot token | (none) |
| --telegram-chat | Telegram chat ID | (none) |
| --auto-fix | Enable gateway auto-restart | false |
| --no-prompt | Skip all interactive prompts | false |
Troubleshooting
Config not found error
If you see Config not found, run clawdoctor init first to create the config file.
Gateway watcher always shows down
Make sure openclaw is in your PATH. Run which openclaw to check. If you installed OpenClaw in a non-standard location, update openclawPath in ~/.clawdoctor/config.json.
Telegram alerts not arriving
Verify your bot token and chat ID by running clawdoctor status. The Telegram field will show enabled or disabled. Re-run clawdoctor init to reconfigure. Make sure your bot has been started (send /start to it first).
Daemon exits immediately
Check for port conflicts or permission issues with:
clawdoctor start 2>&1 | head -20
Also check if a stale PID file exists:
cat ~/.clawdoctor/clawdoctor.pid rm ~/.clawdoctor/clawdoctor.pid # if daemon is not running
License key not recognized
Make sure you are connected to the internet and clawdoctor.dev is reachable. Run:
clawdoctor activate <key> 2>&1
If the error persists, contact support via GitHub issues.
Config file location
All ClawDoctor files live in ~/.clawdoctor/:
~/.clawdoctor/ config.json # Main config events.db # SQLite event history clawdoctor.pid # Daemon PID (when running) license.json # License key (after activation)