@clawnitor/plugin 1.0.0 → 1.0.1
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.
- package/README.md +74 -24
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -1,15 +1,20 @@
|
|
|
1
1
|
# @clawnitor/plugin
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@clawnitor/plugin)
|
|
4
|
+
[](LICENSE)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
Agent monitoring, rules enforcement, and kill switch for OpenClaw. Blocks dangerous actions **before** they execute.
|
|
7
|
+
|
|
8
|
+
## Why
|
|
9
|
+
|
|
10
|
+
Prompt-level safety instructions are fragile — they get dropped during context compaction, ignored by the model, or overridden by conflicting instructions. Clawnitor enforces rules at the architecture level via `before_tool_call`. Context compaction can't drop it because it's not in the context.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
6
13
|
|
|
7
14
|
```bash
|
|
8
|
-
|
|
15
|
+
npm install @clawnitor/plugin
|
|
9
16
|
```
|
|
10
17
|
|
|
11
|
-
## Configuration
|
|
12
|
-
|
|
13
18
|
Add to your `openclaw.json`:
|
|
14
19
|
|
|
15
20
|
```json
|
|
@@ -26,35 +31,80 @@ Add to your `openclaw.json`:
|
|
|
26
31
|
}
|
|
27
32
|
```
|
|
28
33
|
|
|
29
|
-
|
|
34
|
+
Get your API key at [clawnitor.io](https://clawnitor.io). Events appear on your dashboard immediately.
|
|
35
|
+
|
|
36
|
+
## What it captures
|
|
37
|
+
|
|
38
|
+
| Event | Hook | Details |
|
|
39
|
+
|-------|------|---------|
|
|
40
|
+
| Tool calls | `before_tool_call` / `after_tool_call` | Name, params, result, duration. **Can block.** |
|
|
41
|
+
| LLM requests | `llm_input` / `llm_output` | Model, tokens, cost |
|
|
42
|
+
| Messages | `message_sending` / `message_sent` / `message_received` | Content (redacted). **Can block sends.** |
|
|
43
|
+
| Lifecycle | `session_start` / `session_end` / `agent_end` | Session tracking |
|
|
44
|
+
| Sub-agents | `subagent_spawning` / `subagent_ended` | Coordination tracking |
|
|
45
|
+
|
|
46
|
+
## Pre-action defense (3 layers)
|
|
47
|
+
|
|
48
|
+
Every tool call and message is checked **before execution**:
|
|
49
|
+
|
|
50
|
+
1. **Kill state** — server-triggered pause via WebSocket. Instant, remote.
|
|
51
|
+
2. **Local failsafe** — spend circuit breaker, rate limiter, tool blocklist. Always active, even offline.
|
|
52
|
+
3. **Cached rules** — your server-side rules fetched every 60s, evaluated locally. Keyword, rate, threshold — all pre-action.
|
|
53
|
+
|
|
54
|
+
If any layer triggers, the action is blocked in-process. Zero network latency.
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
// Agent tries to run: bash("rm -rf /app/data")
|
|
58
|
+
// Clawnitor intercepts via before_tool_call:
|
|
59
|
+
|
|
60
|
+
BLOCKED by Clawnitor
|
|
61
|
+
Rule matched: keyword "rm -rf"
|
|
62
|
+
Action stopped before execution
|
|
63
|
+
Agent paused. Resume from dashboard when ready.
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Configuration
|
|
30
67
|
|
|
31
68
|
| Option | Default | Description |
|
|
32
69
|
|--------|---------|-------------|
|
|
33
|
-
| `apiKey` | required | Your Clawnitor API key |
|
|
70
|
+
| `apiKey` | **required** | Your Clawnitor API key (starts with `clw_live_`) |
|
|
34
71
|
| `backendUrl` | `https://api.clawnitor.io` | Backend URL |
|
|
35
|
-
| `spendLimit` | `100` |
|
|
72
|
+
| `spendLimit` | `100` | Session spend limit in USD before auto-pause |
|
|
36
73
|
| `rateLimit` | `120` | Max tool calls per minute before auto-pause |
|
|
37
|
-
| `toolBlocklist` | `[]` | Tool names to always block |
|
|
74
|
+
| `toolBlocklist` | `[]` | Tool names to always block (case-insensitive) |
|
|
38
75
|
| `redactionPatterns` | `[]` | Additional regex patterns for secret redaction |
|
|
39
76
|
|
|
40
|
-
|
|
77
|
+
### Full example
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"plugins": {
|
|
82
|
+
"entries": {
|
|
83
|
+
"clawnitor": {
|
|
84
|
+
"config": {
|
|
85
|
+
"apiKey": "clw_live_abc123",
|
|
86
|
+
"spendLimit": 50,
|
|
87
|
+
"rateLimit": 60,
|
|
88
|
+
"toolBlocklist": ["execute_bash", "delete_file"],
|
|
89
|
+
"redactionPatterns": ["sk-[a-zA-Z0-9]{32}"]
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
```
|
|
41
96
|
|
|
42
|
-
|
|
43
|
-
- LLM requests (input/output, token usage, cost)
|
|
44
|
-
- Messages (sending, sent, received)
|
|
45
|
-
- Session lifecycle (start, end, agent completion)
|
|
46
|
-
- Sub-agent spawning and completion
|
|
97
|
+
## Privacy
|
|
47
98
|
|
|
48
|
-
|
|
99
|
+
Sensitive data (API keys, passwords, tokens) is automatically redacted before transmission. 25+ built-in patterns plus your custom `redactionPatterns`. Data sharing for aggregate pattern improvement is opt-in and **off by default**.
|
|
49
100
|
|
|
50
|
-
|
|
51
|
-
- **Spend circuit breaker** — auto-pauses at configurable spend limit
|
|
52
|
-
- **Rate limiter** — auto-pauses at configurable tool call rate
|
|
53
|
-
- **Tool blocklist** — prevents specific tools from ever executing
|
|
54
|
-
- **Secret redaction** — strips API keys, passwords, tokens from logged data
|
|
101
|
+
## Links
|
|
55
102
|
|
|
56
|
-
|
|
103
|
+
- [Live demo](https://clawnitor.io/demo) — see it in action, no signup
|
|
104
|
+
- [Documentation](https://clawnitor.io/docs) — full reference
|
|
105
|
+
- [Dashboard](https://app.clawnitor.io) — sign up and monitor
|
|
106
|
+
- [Main repo](https://github.com/davidkny22/clawnitor) — backend + dashboard source
|
|
57
107
|
|
|
58
|
-
|
|
108
|
+
## License
|
|
59
109
|
|
|
60
|
-
|
|
110
|
+
[AGPL-3.0](LICENSE)
|
package/package.json
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clawnitor/plugin",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "OpenClaw plugin for Clawnitor — agent monitoring, alerting, and kill switch",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
7
7
|
"types": "./dist/index.d.ts",
|
|
8
8
|
"openclaw": {
|
|
9
|
-
"extensions": [
|
|
9
|
+
"extensions": [
|
|
10
|
+
"./dist/index.js"
|
|
11
|
+
]
|
|
10
12
|
},
|
|
11
13
|
"files": [
|
|
12
14
|
"dist",
|