clawdoctor 0.4.10 → 0.4.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +79 -26
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,8 +1,10 @@
1
- # clawdoctor
1
+ # ClawDoctor
2
2
 
3
- Self-healing monitor for OpenClaw. Watches your gateway, crons, and agent sessions, sends Telegram alerts, and auto-fixes what it can.
3
+ Self-healing monitor for OpenClaw. Watches your gateway, crons, sessions, auth, and budget — sends Telegram alerts and auto-fixes what it can.
4
4
 
5
- Built by people who run 20+ OpenClaw agents in production and got tired of checking if things were still alive.
5
+ Built for people running OpenClaw in production who got tired of checking if things were still alive.
6
+
7
+ **Homepage:** https://clawdoctor.dev | **Source:** https://github.com/turleydesigns/clawdoctor
6
8
 
7
9
  ## Install
8
10
 
@@ -10,57 +12,69 @@ Built by people who run 20+ OpenClaw agents in production and got tired of check
10
12
  npm install -g clawdoctor
11
13
  ```
12
14
 
15
+ Requires Node 18+, Linux.
16
+
13
17
  ## Quick Start
14
18
 
15
19
  ```bash
16
- # Configure
20
+ # Configure (interactive)
17
21
  clawdoctor init
18
22
 
19
- # Start monitoring
23
+ # Start monitoring daemon
20
24
  clawdoctor start
21
25
  ```
22
26
 
23
27
  ## Commands
24
28
 
25
29
  ```bash
26
- clawdoctor init # Interactive setup
27
- clawdoctor start # Start monitoring daemon
28
- clawdoctor start --dry-run # Run without taking healing actions
29
- clawdoctor stop # Stop daemon
30
- clawdoctor status # Live health check of all monitors
31
- clawdoctor log # Show recent events from local database
32
- clawdoctor log -n 100 # Show 100 events
30
+ clawdoctor init # Interactive setup
31
+ clawdoctor start # Start monitoring daemon
32
+ clawdoctor start --dry-run # Run without taking healing actions
33
+ clawdoctor stop # Stop daemon
34
+ clawdoctor status # Live health check of all monitors
35
+ clawdoctor log # Show recent events
36
+ clawdoctor log -n 100 # Show 100 events
33
37
  clawdoctor log -w GatewayWatcher -s critical # Filter by watcher/severity
34
- clawdoctor install-service # Install as systemd user service
38
+ clawdoctor install-service # Install as systemd user service
39
+ clawdoctor plan # Show current plan and features
40
+ clawdoctor activate <key> # Activate a license key
41
+ clawdoctor snapshots # List healer action snapshots (rollback points)
42
+ clawdoctor audit # Show healer audit trail
35
43
  ```
36
44
 
37
45
  ## What It Monitors
38
46
 
39
47
  | Monitor | What It Watches | Interval |
40
48
  |---------|-----------------|----------|
41
- | **GatewayWatcher** | `openclaw` process running | 30s |
42
- | **CronWatcher** | `~/.openclaw/state/cron-*.json` for missed/failed crons | 60s |
43
- | **SessionWatcher** | `~/.openclaw/agents/*/sessions/*.jsonl` for errors, aborts, stuck sessions | 60s |
44
- | **AuthWatcher** | Gateway logs for 401/403/token expired patterns | 60s |
45
- | **CostWatcher** | Session token costs - flags if >3x rolling average | 5m |
49
+ | **GatewayWatcher** | OpenClaw gateway process running | 30s |
50
+ | **CronWatcher** | Cron jobs for failures and overdue runs | 60s |
51
+ | **SessionWatcher** | Agent sessions for errors, aborts, stuck sessions | 60s |
52
+ | **AuthWatcher** | Auth token expiry (warns at 24h, 4h, 1h) | 60s |
53
+ | **BudgetWatcher** | Daily API spend vs configured limit | 5m |
54
+ | **CostWatcher** | Per-session token costs vs rolling average | 5m |
46
55
 
47
56
  ## What It Fixes
48
57
 
49
- | Healer | Action |
50
- |--------|--------|
51
- | **ProcessHealer** | Restarts gateway via `systemctl restart openclaw-gateway` or `openclaw gateway restart`, then verifies |
52
- | **CronHealer** | Logs the failure and includes the manual rerun command in the alert (Phase 0 - no auto-rerun) |
58
+ | Healer | Trigger | Action |
59
+ |--------|---------|--------|
60
+ | **ProcessHealer** | Gateway down | Restarts via `openclaw gateway restart`, verifies recovery |
61
+ | **CronHealer** | Cron failing repeatedly | Logs failure with manual rerun command |
62
+ | **SessionHealer** | Session stuck >2h | Kills session; alerts first if cost >$10 |
63
+ | **AuthHealer** | Auth failures detected | Attempts `openclaw auth refresh`; alerts if fails |
64
+ | **BudgetHealer** | Daily spend exceeded | Requests approval: kill sessions, increase limit, or ignore |
65
+
66
+ All healing actions are logged with a snapshot for rollback. Risky actions require Telegram approval before executing.
53
67
 
54
68
  ## Alerts
55
69
 
56
- Telegram alerts with rate limiting (max 1 per monitor per 5 minutes):
70
+ Telegram alerts, rate-limited to max 1 per monitor per 5 minutes:
57
71
 
58
72
  ```
59
73
  🔴 ClawDoctor Alert
60
74
  Monitor: GatewayWatcher
61
75
  Event: Gateway process not found
62
76
  Action: openclaw gateway restart
63
- Status: ✅ Back online
77
+ Status: Back online
64
78
  ─────
65
79
  Time: 2026-03-15 03:14 UTC
66
80
  Host: devbox
@@ -78,11 +92,14 @@ Config lives at `~/.clawdoctor/config.json`:
78
92
  "cron": { "enabled": true, "interval": 60 },
79
93
  "session": { "enabled": true, "interval": 60 },
80
94
  "auth": { "enabled": true, "interval": 60 },
95
+ "budget": { "enabled": true, "interval": 300 },
81
96
  "cost": { "enabled": true, "interval": 300 }
82
97
  },
83
98
  "healers": {
84
99
  "processRestart": { "enabled": true },
85
- "cronRetry": { "enabled": false }
100
+ "cronRetry": { "enabled": false },
101
+ "sessionKill": { "enabled": true },
102
+ "authRefresh": { "enabled": true }
86
103
  },
87
104
  "alerts": {
88
105
  "telegram": {
@@ -96,7 +113,7 @@ Config lives at `~/.clawdoctor/config.json`:
96
113
  }
97
114
  ```
98
115
 
99
- Events are stored in `~/.clawdoctor/events.db` (SQLite) and retained for 7 days by default.
116
+ Events stored in `~/.clawdoctor/events.db` (SQLite, 7-day retention by default).
100
117
 
101
118
  ## Systemd
102
119
 
@@ -107,6 +124,42 @@ systemctl --user enable clawdoctor
107
124
  systemctl --user start clawdoctor
108
125
  ```
109
126
 
127
+ ## Non-Interactive Setup
128
+
129
+ ```bash
130
+ clawdoctor init \
131
+ --openclaw-path ~/.openclaw \
132
+ --telegram-token TOKEN \
133
+ --telegram-chat CHATID \
134
+ --auto-fix \
135
+ --no-prompt
136
+ ```
137
+
138
+ ## Plans
139
+
140
+ | Feature | Free | Diagnose ($9/mo) | Heal ($19/mo) |
141
+ |---------|------|-----------------|--------------|
142
+ | Monitors | 5 | Up to 20 | Unlimited |
143
+ | Event history | 7 days | 30 days | 90 days |
144
+ | Alerts | Local only | Telegram, Slack, Discord | Everything in Diagnose |
145
+ | Smart alerts with root cause | - | Yes | Yes |
146
+ | Known-issue pattern matching | - | Yes | Yes |
147
+ | Auto-fix (restart, retry) | - | - | Yes |
148
+ | Approval flow for risky fixes | - | - | Yes |
149
+ | Full audit trail and rollback | - | - | Yes |
150
+
151
+ Get a license key at https://clawdoctor.dev, then:
152
+
153
+ ```bash
154
+ clawdoctor activate <your-key>
155
+ ```
156
+
157
+ Or set via env:
158
+
159
+ ```bash
160
+ export CLAWDOCTOR_KEY=your-key
161
+ ```
162
+
110
163
  ## License
111
164
 
112
165
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "clawdoctor",
3
- "version": "0.4.10",
3
+ "version": "0.4.11",
4
4
  "description": "Self-healing doctor for OpenClaw. Watches gateway, crons, and sessions, sends Telegram alerts, and auto-fixes what it can.",
5
5
  "main": "dist/index.js",
6
6
  "bin": {