clawprobe 0.6.9 → 0.7.0

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.ja.md ADDED
@@ -0,0 +1,369 @@
1
+ # clawprobe
2
+
3
+ **OpenClaw エージェントの状態をリアルタイムで把握する。**
4
+
5
+ トークン使用量・API コスト・コンテキスト健全性・スマートアラート —— すべてを一箇所で、OpenClaw のコードを一切変更せずに。
6
+
7
+ [![npm](https://img.shields.io/npm/v/clawprobe)](https://www.npmjs.com/package/clawprobe)
8
+ [![npm downloads](https://img.shields.io/npm/dm/clawprobe)](https://www.npmjs.com/package/clawprobe)
9
+ [![GitHub Stars](https://img.shields.io/github/stars/seekcontext/ClawProbe)](https://github.com/seekcontext/ClawProbe)
10
+ [![License](https://img.shields.io/github/license/seekcontext/ClawProbe)](./LICENSE)
11
+
12
+ [English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.md)
13
+
14
+ [なぜ clawprobe か](#なぜ-clawprobe-か) •
15
+ [クイックスタート](#クイックスタート) •
16
+ [コマンド一覧](#コマンド一覧) •
17
+ [エージェント連携](#エージェント連携) •
18
+ [設定](#設定) •
19
+ [仕組み](#仕組み)
20
+
21
+ ---
22
+
23
+ ## なぜ clawprobe か
24
+
25
+ OpenClaw エージェントはコンテキストウィンドウの中で静かに動いています —— トークンを消費し、会話をサイレント圧縮し、API 予算を使い続けています。しかしその様子は、実行中はまったく見えません。
26
+
27
+ clawprobe はこの問題を解決します。バックグラウンドで OpenClaw のファイルを監視し、エージェントが今何をしているかをリアルタイムで可視化します。
28
+
29
+ | あなたの疑問 | clawprobe の答え |
30
+ |------------|----------------|
31
+ | 「エージェントは今、正常に動いている?」 | `clawprobe status` — 即時スナップショット |
32
+ | 「ずっと見ていたい」 | `clawprobe top` — 自動更新のライブダッシュボード |
33
+ | 「なぜコンテキストがすぐ圧縮されるの?」 | `clawprobe context` + `clawprobe suggest` |
34
+ | 「圧縮後にエージェントが忘れたことは?」 | `clawprobe compacts` |
35
+ | 「これ、いくらかかってるの?」 | `clawprobe cost --week`(主要モデルの価格内蔵) |
36
+ | 「TOOLS.md はちゃんとモデルに届いている?」 | トランケーション検出を内蔵 |
37
+
38
+ **設定不要。副作用ゼロ。100% ローカル動作。**
39
+
40
+ ---
41
+
42
+ ## クイックスタート
43
+
44
+ ```bash
45
+ npm install -g clawprobe
46
+
47
+ clawprobe start # バックグラウンドデーモンを起動(OpenClaw を自動検出)
48
+ clawprobe status # 即時スナップショットを確認
49
+ ```
50
+
51
+ clawprobe は OpenClaw のインストール先を自動検出します。API キー不要、アカウント登録不要、テレメトリなし。
52
+
53
+ ### OpenClaw スキルとしてインストール(1 コマンド)
54
+
55
+ OpenClaw を使用している場合、clawprobe をスキルとしてインストールすることで、エージェントが自分自身を監視できるようになります:
56
+
57
+ ```bash
58
+ clawhub install clawprobe
59
+ ```
60
+
61
+ またはエージェントに直接伝えるだけでもインストールできます:
62
+
63
+ > https://raw.githubusercontent.com/seekcontext/ClawProbe/main/skills/clawprobe/SKILL.md を読み、その手順に従って clawprobe のセルフモニタリングを設定してください。
64
+
65
+ 新しい OpenClaw セッションを開始すると、エージェントは自動的に `clawprobe` コマンドにアクセスできるようになります。スキルの完全な定義は [`skills/clawprobe/SKILL.md`](./skills/clawprobe/SKILL.md) を参照してください。
66
+
67
+ ---
68
+
69
+ ## コマンド一覧
70
+
71
+ ### `clawprobe status` — 即時スナップショット
72
+
73
+ セッション・モデル・コンテキスト使用率・本日のコスト・アクティブなアラートを一目で確認。
74
+
75
+ ```
76
+ $ clawprobe status
77
+
78
+ 📊 Agent Status (active session)
79
+ ──────────────────────────────────────────────────
80
+ Agent: main
81
+ Session: agent:main:workspace:direct:xxx ●
82
+ Model: moonshot/kimi-k2.5
83
+ Active: Today 16:41 Compacts: 2
84
+
85
+ Context: 87.3K / 200.0K tokens ███████░░░ 44%
86
+ Tokens: 72.4K in / 5.2K out
87
+
88
+ Today: $0.12 → clawprobe cost で詳細を確認
89
+
90
+ 🟡 コンテキストウィンドウが 44% に達しています
91
+ → 新しいセッションを開始するか、手動で圧縮することを推奨
92
+ ```
93
+
94
+ ---
95
+
96
+ ### `clawprobe top` — ライブダッシュボード
97
+
98
+ エージェントが長いタスクを実行している間、サイドターミナルで開いておきましょう。2 秒ごとに自動更新 —— コンテキスト進捗バー、コストカウンター、ターンごとのトークン消費をリアルタイムで表示します。
99
+
100
+ ```
101
+ clawprobe top refreshing every 2s (q / Ctrl+C to quit) 03/18/2026 17:42:35
102
+ ────────────────────────────────────────────────────────────────────────────────
103
+ Agent: main ● daemon running
104
+ Session: agent:main:workspace:direct:xxx ● active
105
+ Model: moonshot/kimi-k2.5
106
+ Active: Today 17:42 Compacts: 2
107
+ ────────────────────────────────────────────────────────────────────────────────
108
+ Context ████████░░░░░░░░░░░░░░░░ 44% 87.3K / 200.0K tokens
109
+ Headroom 112.7K tokens remaining (56%)
110
+ ────────────────────────────────────────────────────────────────────────────────
111
+ Session cost $0.52 Input 859.2K tok Output 29.8K tok
112
+ Today total $0.67 Cache read 712.0K tok
113
+ ────────────────────────────────────────────────────────────────────────────────
114
+ Recent turns
115
+ Turn Time ΔInput ΔOutput Cost Note
116
+ 27 17:42 22.0K 908 $0.0094 ← latest
117
+ 26 17:19 990 630 $0.0026
118
+ 25 17:19 20.4K 661 $0.0094
119
+ 24 15:57 564 39 $0.0014
120
+ 23 15:56 18.8K 231 $0.0076 ◆ compact
121
+ ────────────────────────────────────────────────────────────────────────────────
122
+ 🟡 Context window at 44% capacity
123
+ Costs are estimates based on public pricing.
124
+ ```
125
+
126
+ `q` または `Ctrl+C` で終了。ターミナルの表示を壊さずクリーンに終了します。
127
+
128
+ ```bash
129
+ clawprobe top # デフォルト 2 秒更新
130
+ clawprobe top --interval 5 # 5 秒更新
131
+ clawprobe top --agent coder # 特定のエージェントを指定
132
+ ```
133
+
134
+ ---
135
+
136
+ ### `clawprobe cost` — API コスト追跡
137
+
138
+ 30 以上のモデルの価格を内蔵。入力・出力・キャッシュトークンを個別に集計。日・週・月・全期間で表示できます。
139
+
140
+ ```
141
+ $ clawprobe cost --week
142
+
143
+ 💰 Weekly Cost 2026-03-12 – 2026-03-18
144
+ ──────────────────────────────────────────────────
145
+ Total: $0.67
146
+ Daily avg: $0.096
147
+ Month est: $2.87
148
+
149
+ 2026-03-12 ██████████████░░ $0.15
150
+ 2026-03-16 ████████████████ $0.16
151
+ 2026-03-17 █░░░░░░░░░░░░░░░ $0.0088
152
+ 2026-03-18 ███░░░░░░░░░░░░░ $0.03
153
+
154
+ Input: 1.0M tokens $0.65 (97%)
155
+ Output: 47.8K tokens $0.03 (3%)
156
+
157
+ コストは推定値です。正確な金額はプロバイダーの請求画面でご確認ください。
158
+ ```
159
+
160
+ 内蔵済み価格:OpenAI(GPT-4o、o1、o3、o4-mini)、Anthropic(Claude 3/3.5/3.7 Sonnet/Opus/Haiku)、Google(Gemini 2.0/2.5 Flash/Pro)、Moonshot(kimi-k2.5)、DeepSeek(v3、r1)など。未収録モデルは `~/.clawprobe/config.json` でカスタム追加できます。
161
+
162
+ ---
163
+
164
+ ### `clawprobe session` — セッション詳細
165
+
166
+ 任意のセッションを掘り下げる:合計コスト・トークン推移・各ターンの消費量を確認。
167
+
168
+ ```
169
+ $ clawprobe session
170
+
171
+ 💬 Session agent:main:workspace:…
172
+ ──────────────────────────────────────────────────
173
+ Model: moonshot/kimi-k2.5
174
+ Duration: 2h 14m
175
+ Tokens: In 859.2K Out 29.8K Context 87.3K
176
+ Est. cost: $0.52
177
+ Compacts: 2
178
+
179
+ Turn timeline:
180
+ Turn Time ΔInput ΔOutput Cost
181
+ 1 14:02 4.2K 312 $0.003
182
+ 2 14:18 12.7K 891 $0.009 ◆ compact
183
+ 3 14:41 38.1K 2.4K $0.028
184
+
185
+ ```
186
+
187
+ ---
188
+
189
+ ### `clawprobe context` — コンテキストウィンドウ分析
190
+
191
+ 何がコンテキストを圧迫しているかを把握し、問題が起きる前にサイレントなトランケーションを検出します。
192
+
193
+ ```
194
+ $ clawprobe context
195
+
196
+ 🔍 Context Window agent: main
197
+ ──────────────────────────────────────────────────
198
+ Used: 87.3K / 200.0K tokens ███████░░░ 44%
199
+
200
+ Workspace overhead: ~4.2K tokens (7 injected files)
201
+ Conversation est: ~83.1K tokens (messages + system prompt + tools)
202
+
203
+ ⚠ TOOLS.md: 31% truncated — この部分はモデルに届いていません
204
+ openclaw.json の bootstrapMaxChars を増やしてください
205
+
206
+ Remaining: 112.7K tokens (56%)
207
+ ```
208
+
209
+ ---
210
+
211
+ ### `clawprobe compacts` — 圧縮イベント記録
212
+
213
+ すべての圧縮イベントを記録。何が失われたかを確認し、完全に消える前に重要なコンテキストをアーカイブできます。
214
+
215
+ ```
216
+ $ clawprobe compacts
217
+
218
+ 📦 Compact Events last 5
219
+ ──────────────────────────────────────────────────
220
+
221
+ #3 Today 16:22 [agent:main…] 3 messages
222
+
223
+ 👤 "Can you add retry logic to the upload handler?"
224
+ 🤖 "Done — added exponential backoff with 3 retries. The key change is in…"
225
+
226
+ → Archive: clawprobe compacts --save 3
227
+ ```
228
+
229
+ ---
230
+
231
+ ### `clawprobe suggest` — 最適化アドバイス
232
+
233
+ よくある問題を自動検出。本当に注意が必要なときだけ通知します。
234
+
235
+ | ルール | 検出内容 |
236
+ |--------|---------|
237
+ | `tools-truncation` | TOOLS.md が切り捨てられ、モデルがツール定義を参照できない |
238
+ | `high-compact-freq` | コンテキストの充填が速すぎ、30 分未満ごとに圧縮が発生 |
239
+ | `context-headroom` | コンテキストウィンドウの使用率が 90% 超 — 圧縮が間近 |
240
+ | `cost-spike` | 本日の支出が週平均の 2 倍超 |
241
+ | `memory-bloat` | MEMORY.md が大きすぎ、毎ターンでトークンを無駄に消費 |
242
+
243
+ 不要なルールを無効化:`clawprobe suggest --dismiss <rule-id>`
244
+
245
+ ---
246
+
247
+ ## エージェント連携
248
+
249
+ clawprobe は**エージェントから呼び出されること**を想定して設計されています。すべてのコマンドが `--json` 出力をサポートし、エラーも常に構造化 JSON で返ります。パースを壊すカラーテキストは出力しません。
250
+
251
+ ### ワンコールでヘルスチェック
252
+
253
+ ```bash
254
+ clawprobe status --json
255
+ ```
256
+
257
+ ```json
258
+ {
259
+ "agent": "main",
260
+ "daemonRunning": true,
261
+ "sessionKey": "agent:main:workspace:direct:xxx",
262
+ "model": "moonshot/kimi-k2.5",
263
+ "sessionTokens": 87340,
264
+ "windowSize": 200000,
265
+ "utilizationPct": 44,
266
+ "todayUsd": 0.12,
267
+ "suggestions": [
268
+ {
269
+ "severity": "warning",
270
+ "ruleId": "context-headroom",
271
+ "title": "Context window at 44% capacity",
272
+ "detail": "...",
273
+ "action": "Consider starting a fresh session or manually compacting now"
274
+ }
275
+ ]
276
+ }
277
+ ```
278
+
279
+ ### 出力スキーマを確認する
280
+
281
+ ```bash
282
+ clawprobe schema # 全コマンドを一覧表示
283
+ clawprobe schema status # status --json のフィールド仕様
284
+ clawprobe schema cost # cost --json のフィールド仕様
285
+ ```
286
+
287
+ ### プログラムからアドバイスを無効化
288
+
289
+ ```bash
290
+ clawprobe suggest --dismiss context-headroom --json
291
+ # → { "ok": true, "dismissed": "context-headroom" }
292
+ ```
293
+
294
+ ### エラーレスポンスは常にパース可能
295
+
296
+ ```bash
297
+ clawprobe session --json # アクティブなセッションがない場合
298
+ # → { "ok": false, "error": "no_active_session", "message": "..." }
299
+ # exit code 1
300
+ ```
301
+
302
+ ---
303
+
304
+ ## 設定
305
+
306
+ オプション設定ファイル `~/.clawprobe/config.json` —— 初回の `clawprobe start` 実行時に自動生成されます:
307
+
308
+ ```json
309
+ {
310
+ "timezone": "Asia/Tokyo",
311
+ "openclaw": {
312
+ "dir": "~/.openclaw",
313
+ "agent": "main"
314
+ },
315
+ "cost": {
316
+ "customPrices": {
317
+ "my-provider/my-model": { "input": 1.00, "output": 3.00 }
318
+ }
319
+ },
320
+ "alerts": {
321
+ "dailyBudgetUsd": 5.00
322
+ },
323
+ "rules": {
324
+ "disabled": ["memory-bloat"]
325
+ }
326
+ }
327
+ ```
328
+
329
+ ほとんどのユーザーに設定は不要です。clawprobe は既存の OpenClaw 設定からすべてを自動検出します。
330
+
331
+ ---
332
+
333
+ ## 仕組み
334
+
335
+ clawprobe はバックグラウンドで OpenClaw の既存ファイルを読み取ります —— コード変更・プラグイン・フック一切不要。
336
+
337
+ - **設定不要** — `~/.openclaw` の OpenClaw を自動検出
338
+ - **副作用ゼロ** — OpenClaw のファイルには一切触れず、`~/.clawprobe/` のみに書き込む
339
+ - **バックグラウンドデーモン** — `clawprobe start` がファイル変更を監視し、ローカル DB を随時更新
340
+ - **最小フットプリント** — 本番依存パッケージは 4 つのみ、クラウドサービスなし、テレメトリなし
341
+
342
+ ---
343
+
344
+ ## プライバシー
345
+
346
+ - **100% ローカル動作** — データが外部に送信されることはありません
347
+ - **テレメトリなし** — clawprobe は何も収集しません
348
+ - **アカウント不要・API キー不要** — インストールしてすぐ使えます
349
+
350
+ ---
351
+
352
+ ## 動作環境
353
+
354
+ すべてのバージョンの OpenClaw に対応。Node.js ≥ 22 · macOS または Linux(Windows は WSL2 経由)が必要です。
355
+
356
+ ---
357
+
358
+ ## コントリビューション
359
+
360
+ MIT ライセンス。コントリビューション歓迎です。
361
+
362
+ ```bash
363
+ git clone https://github.com/seekcontext/ClawProbe
364
+ cd ClawProbe && npm install && npm run dev
365
+ ```
366
+
367
+ ---
368
+
369
+ [MIT License](./LICENSE)
package/README.md CHANGED
@@ -9,10 +9,11 @@ Token usage. API cost. Context health. Smart alerts. All in one place — withou
9
9
  [![GitHub Stars](https://img.shields.io/github/stars/seekcontext/ClawProbe)](https://github.com/seekcontext/ClawProbe)
10
10
  [![License](https://img.shields.io/github/license/seekcontext/ClawProbe)](./LICENSE)
11
11
 
12
+ [English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.md)
13
+
12
14
  [Why clawprobe](#why-clawprobe) •
13
15
  [Quick Start](#quick-start) •
14
16
  [Commands](#commands) •
15
- [`top` Live Dashboard](#clawprobe-top--live-dashboard) •
16
17
  [Agent Integration](#agent-integration) •
17
18
  [Configuration](#configuration) •
18
19
  [How It Works](#how-it-works)
@@ -27,12 +28,12 @@ clawprobe fixes that. It watches OpenClaw's files in the background and gives yo
27
28
 
28
29
  | Problem | clawprobe |
29
30
  |---------|-----------|
30
- | "Is my agent healthy right now?" | `clawprobe status` — one-glance dashboard |
31
- | "I want to keep watching it live" | `clawprobe top` — htop-style live dashboard |
32
- | "Why is context getting compacted so often?" | `clawprobe context` + `clawprobe suggest` |
31
+ | "Is my agent healthy right now?" | `clawprobe status` — instant snapshot |
32
+ | "I want to keep watching it live" | `clawprobe top` — live dashboard, auto-refreshing |
33
+ | "Why is context compacting so often?" | `clawprobe context` + `clawprobe suggest` |
33
34
  | "What did the agent forget after compaction?" | `clawprobe compacts` |
34
35
  | "What is this costing me?" | `clawprobe cost --week` with per-model pricing |
35
- | "What is my TOOLS.md taking up?" | Truncation detection + token estimates |
36
+ | "Is my TOOLS.md actually reaching the model?" | Truncation detection built-in |
36
37
 
37
38
  **No configuration required. Zero side effects. 100% local.**
38
39
 
@@ -44,44 +45,57 @@ clawprobe fixes that. It watches OpenClaw's files in the background and gives yo
44
45
  npm install -g clawprobe
45
46
 
46
47
  clawprobe start # Launch background daemon (auto-detects OpenClaw)
47
- clawprobe status # Instant dashboard
48
+ clawprobe status # Instant snapshot
49
+ ```
50
+
51
+ clawprobe auto-detects your OpenClaw installation. No API keys, no accounts, no telemetry.
52
+
53
+ ### Install as an OpenClaw skill (one command)
54
+
55
+ If you use OpenClaw, install clawprobe as a skill so your agent can monitor itself:
56
+
57
+ ```bash
58
+ clawhub install clawprobe
48
59
  ```
49
60
 
50
- That's it. clawprobe auto-detects your OpenClaw installation at `~/.openclaw`. No API keys, no accounts, no telemetry.
61
+ Or tell your agent directly:
62
+
63
+ > Read https://raw.githubusercontent.com/seekcontext/ClawProbe/main/skills/clawprobe/SKILL.md and follow the instructions to set up clawprobe self-monitoring.
64
+
65
+ Start a new OpenClaw session and the agent will automatically have access to `clawprobe` commands for self-monitoring. See [`skills/clawprobe/SKILL.md`](./skills/clawprobe/SKILL.md) for the full skill definition.
51
66
 
52
67
  ---
53
68
 
54
69
  ## Commands
55
70
 
56
- ### `clawprobe status` — Dashboard
71
+ ### `clawprobe status` — Instant Snapshot
57
72
 
58
- Everything you need at a glance: session, model, context utilization, today's cost, and active alerts.
73
+ Everything at a glance: session, model, context utilization, today's cost, and active alerts.
59
74
 
60
75
  ```
61
76
  $ clawprobe status
62
77
 
63
78
  📊 Agent Status (active session)
64
79
  ──────────────────────────────────────────────────
65
- Agent: main
66
- Session: agent:main:workspace:direct:xxx ●
67
- Model: moonshot/kimi-k2.5
68
- Provider: moonshot
80
+ Agent: main
81
+ Session: agent:main:workspace:direct:xxx ●
82
+ Model: moonshot/kimi-k2.5
83
+ Active: Today 16:41 Compacts: 2
69
84
 
70
85
  Context: 87.3K / 200.0K tokens ███████░░░ 44%
71
- Input: 72.4K tokens Output: 5.2K tokens
72
- Compacts: 2 Last active: Today 16:41
86
+ Tokens: 72.4K in / 5.2K out
73
87
 
74
- Today: $0.12
88
+ Today: $0.12 → clawprobe cost for full breakdown
75
89
 
76
- Context window at 44% capacity
77
- → Consider starting a fresh session if nearing limit
90
+ 🟡 Context window at 44% capacity
91
+ → Consider starting a fresh session or manually compacting now
78
92
  ```
79
93
 
80
94
  ---
81
95
 
82
96
  ### `clawprobe top` — Live Dashboard
83
97
 
84
- An htop-style auto-refreshing view fixed header, scrollable turn list, pinned alerts footer. Open it in a side terminal while your agent runs a long task.
98
+ Open it in a side terminal while your agent runs a long task. Stays on screen and updates every 2 seconds context bar, cost counters, and a live turn-by-turn feed.
85
99
 
86
100
  ```
87
101
  clawprobe top refreshing every 2s (q / Ctrl+C to quit) 03/18/2026 17:42:35
@@ -92,7 +106,7 @@ clawprobe top refreshing every 2s (q / Ctrl+C to quit) 03/18/2026 17:42:35
92
106
  Active: Today 17:42 Compacts: 2
93
107
  ────────────────────────────────────────────────────────────────────────────────
94
108
  Context ████████░░░░░░░░░░░░░░░░ 44% 87.3K / 200.0K tokens
95
- Headroom 112.7K tokens remaining (91%)
109
+ Headroom 112.7K tokens remaining (56%)
96
110
  ────────────────────────────────────────────────────────────────────────────────
97
111
  Session cost $0.52 Input 859.2K tok Output 29.8K tok
98
112
  Today total $0.67 Cache read 712.0K tok
@@ -104,22 +118,16 @@ clawprobe top refreshing every 2s (q / Ctrl+C to quit) 03/18/2026 17:42:35
104
118
  25 17:19 20.4K 661 $0.0094
105
119
  24 15:57 564 39 $0.0014
106
120
  23 15:56 18.8K 231 $0.0076 ◆ compact
107
- … (fills terminal height)
108
121
  ────────────────────────────────────────────────────────────────────────────────
109
122
  🟡 Context window at 44% capacity
110
- → Consider starting a fresh session or manually compacting now
111
123
  Costs are estimates based on public pricing.
112
124
  ```
113
125
 
114
- - **Fixed header** agent info, context bar, and cost summary always visible
115
- - **Scrollable turns** — fills available terminal height, newest turn on top
116
- - **Pinned footer** — active alerts always visible at the bottom
117
- - **Alternate screen** — exits cleanly, restores your terminal (like `htop`/`vim`)
118
- - `q` or `Ctrl+C` to quit
126
+ `q` or `Ctrl+C` to quit. Exits cleanly without leaving a mess in your terminal.
119
127
 
120
128
  ```bash
121
129
  clawprobe top # default 2s refresh
122
- clawprobe top --interval 5 # custom refresh rate
130
+ clawprobe top --interval 5 # slower refresh
123
131
  clawprobe top --agent coder # target a specific agent
124
132
  ```
125
133
 
@@ -146,17 +154,16 @@ $ clawprobe cost --week
146
154
  Input: 1.0M tokens $0.65 (97%)
147
155
  Output: 47.8K tokens $0.03 (3%)
148
156
 
149
- Costs are estimates based on public pricing.
150
- Verify with your provider's billing dashboard.
157
+ Costs are estimates. Verify with your provider's billing dashboard.
151
158
  ```
152
159
 
153
- Built-in prices for: OpenAI (GPT-4o, o1, o3, o4-mini), Anthropic (Claude 3/3.5/3.7 Sonnet/Opus/Haiku), Google (Gemini 2.0/2.5 Flash/Pro), Moonshot (kimi-k2.5), DeepSeek (v3, r1), xAI (Grok), and more. Override or add any model via `~/.clawprobe/config.json`.
160
+ Built-in prices for: OpenAI (GPT-4o, o1, o3, o4-mini), Anthropic (Claude 3/3.5/3.7 Sonnet/Opus/Haiku), Google (Gemini 2.0/2.5 Flash/Pro), Moonshot (kimi-k2.5), DeepSeek (v3, r1), and more. Add any unlisted model via `~/.clawprobe/config.json`.
154
161
 
155
162
  ---
156
163
 
157
- ### `clawprobe session` — Session Detail
164
+ ### `clawprobe session` — Session Breakdown
158
165
 
159
- Per-session breakdown with a turn-by-turn cost and token timeline.
166
+ Drill into any session: total cost, token timeline, and exactly what each turn consumed.
160
167
 
161
168
  ```
162
169
  $ clawprobe session
@@ -181,7 +188,7 @@ $ clawprobe session
181
188
 
182
189
  ### `clawprobe context` — Context Window Analysis
183
190
 
184
- See what's eating your context window and catch truncation before it silently breaks your agent's tool knowledge.
191
+ Find out what's filling your context window, and catch silent truncation before it causes problems.
185
192
 
186
193
  ```
187
194
  $ clawprobe context
@@ -194,7 +201,7 @@ $ clawprobe context
194
201
  Conversation est: ~83.1K tokens (messages + system prompt + tools)
195
202
 
196
203
  ⚠ TOOLS.md: 31% truncated — model never sees this content
197
- Run: clawprobe context --json or increase bootstrapMaxChars in openclaw.json
204
+ Increase bootstrapMaxChars in openclaw.json to fix this
198
205
 
199
206
  Remaining: 112.7K tokens (56%)
200
207
  ```
@@ -203,7 +210,7 @@ $ clawprobe context
203
210
 
204
211
  ### `clawprobe compacts` — Compaction Events
205
212
 
206
- Every compaction is captured. See what was discarded and archive key context with `--save`.
213
+ Every compaction is captured. See exactly what was discarded and save it before it's gone forever.
207
214
 
208
215
  ```
209
216
  $ clawprobe compacts
@@ -223,25 +230,25 @@ $ clawprobe compacts
223
230
 
224
231
  ### `clawprobe suggest` — Optimization Alerts
225
232
 
226
- Automatic detection of common issues. Fires only when something actually needs your attention.
233
+ Automatic detection of common issues. Only fires when something actually needs your attention.
227
234
 
228
235
  | Rule | What It Detects |
229
236
  |------|----------------|
230
- | `tools-truncation` | TOOLS.md exceeds bootstrap limit — tool descriptions silently cut off |
231
- | `high-compact-freq` | Context fills and compacts too fast (< 30 min intervals) |
232
- | `context-headroom` | Context window > 90% full — compaction imminent |
233
- | `cost-spike` | Today's spend > 2× weekly average |
234
- | `memory-bloat` | MEMORY.md too large — burning tokens every session |
237
+ | `tools-truncation` | TOOLS.md cut off — tool descriptions the model can't see |
238
+ | `high-compact-freq` | Context fills too fast, compacting every < 30 minutes |
239
+ | `context-headroom` | Context window > 90% full — compaction is imminent |
240
+ | `cost-spike` | Today's spend > 2× your weekly average |
241
+ | `memory-bloat` | MEMORY.md too large — wasting tokens on every turn |
235
242
 
236
- Dismiss noisy rules with `--dismiss <rule-id>`.
243
+ Dismiss noisy rules: `clawprobe suggest --dismiss <rule-id>`
237
244
 
238
245
  ---
239
246
 
240
247
  ## Agent Integration
241
248
 
242
- clawprobe is designed to be called **by agents**, not just humans. Every command supports `--json` for clean, parseable output. Errors are always JSON too — never coloured text on stderr.
249
+ clawprobe is designed to be called **by agents**, not just humans. Every command supports `--json` for clean, parseable output. Errors are always structured JSON — never coloured text that breaks parsing.
243
250
 
244
- ### One-shot health check
251
+ ### Health check in one call
245
252
 
246
253
  ```bash
247
254
  clawprobe status --json
@@ -272,22 +279,22 @@ clawprobe status --json
272
279
  ### Discover the output schema
273
280
 
274
281
  ```bash
275
- clawprobe schema # List all commands with descriptions
276
- clawprobe schema status # Full field-by-field spec for status --json
277
- clawprobe schema cost # Field spec for cost --json
282
+ clawprobe schema # list all commands
283
+ clawprobe schema status # full field spec for status --json
284
+ clawprobe schema cost # full field spec for cost --json
278
285
  ```
279
286
 
280
- ### Dismiss a suggestion from a script
287
+ ### Dismiss a suggestion programmatically
281
288
 
282
289
  ```bash
283
290
  clawprobe suggest --dismiss context-headroom --json
284
291
  # → { "ok": true, "dismissed": "context-headroom" }
285
292
  ```
286
293
 
287
- ### Error responses are always parseable
294
+ ### Errors are always parseable
288
295
 
289
296
  ```bash
290
- clawprobe session --json # when no session is active
297
+ clawprobe session --json # no active session
291
298
  # → { "ok": false, "error": "no_active_session", "message": "..." }
292
299
  # exit code 1
293
300
  ```
@@ -296,7 +303,7 @@ clawprobe session --json # when no session is active
296
303
 
297
304
  ## Configuration
298
305
 
299
- Optional config at `~/.clawprobe/config.json` (auto-created on first `clawprobe start`):
306
+ Optional config at `~/.clawprobe/config.json` auto-created on first `clawprobe start`:
300
307
 
301
308
  ```json
302
309
  {
@@ -307,57 +314,30 @@ Optional config at `~/.clawprobe/config.json` (auto-created on first `clawprobe
307
314
  },
308
315
  "cost": {
309
316
  "customPrices": {
310
- "my-custom-model": { "input": 1.00, "output": 3.00 }
317
+ "my-provider/my-model": { "input": 1.00, "output": 3.00 }
311
318
  }
312
319
  },
313
320
  "alerts": {
314
321
  "dailyBudgetUsd": 5.00
315
322
  },
316
323
  "rules": {
317
- "disabled": ["memory-bloat"],
318
- "compactionFreqThresholdMin": 30,
319
- "memoryBloatThresholdChars": 20000
324
+ "disabled": ["memory-bloat"]
320
325
  }
321
326
  }
322
327
  ```
323
328
 
324
- Most users need zero configuration. clawprobe auto-detects everything.
329
+ Most users need zero configuration. clawprobe auto-detects everything from your existing OpenClaw setup.
325
330
 
326
331
  ---
327
332
 
328
333
  ## How It Works
329
334
 
330
- clawprobe reads OpenClaw's existing data files — no patches, no plugins, no hooks.
331
-
332
- ```
333
- ~/.openclaw/ clawprobe
334
- ────────────────────────────────── ─────────────────────────────────
335
- sessions.json → Session metadata, token counts, model
336
- *.jsonl transcripts → Turn-level costs, compact events, usage
337
- workspace/*.md → File size analysis, truncation detection
338
- openclaw.json → Model config, bootstrap limits
339
-
340
-
341
- ~/.clawprobe/probe.db (SQLite, local only)
342
-
343
-
344
- CLI + optimization engine
345
- ```
346
-
347
- **Why it just works:**
335
+ clawprobe reads OpenClaw's existing files in the background — no code changes, no plugins, no hooks required.
348
336
 
349
337
  - **Zero configuration** — auto-detects OpenClaw at `~/.openclaw`
350
- - **Zero side effects** — read-only; only writes to its own `~/.clawprobe/` directory
351
- - **Background daemon** — `clawprobe start` launches a watcher with 300ms debounce
352
- - **4 production dependencies** — chokidar, commander, chalk, cli-table3. No cloud, no telemetry.
353
-
354
- ---
355
-
356
- ## Compatibility
357
-
358
- clawprobe works with any OpenClaw version that writes `sessions.json` and `.jsonl` transcript files to `~/.openclaw/agents/<agent>/sessions/`.
359
-
360
- **Requirements:** Node.js ≥ 22 · macOS or Linux (Windows via WSL2)
338
+ - **Zero side effects** — never touches OpenClaw's files; writes only to `~/.clawprobe/`
339
+ - **Background daemon** — `clawprobe start` watches for changes and keeps the local database current
340
+ - **Minimal footprint** — 4 production dependencies, no cloud services, no telemetry
361
341
 
362
342
  ---
363
343
 
@@ -369,6 +349,12 @@ clawprobe works with any OpenClaw version that writes `sessions.json` and `.json
369
349
 
370
350
  ---
371
351
 
352
+ ## Compatibility
353
+
354
+ Works with any OpenClaw version. Requires Node.js ≥ 22 · macOS or Linux (Windows via WSL2).
355
+
356
+ ---
357
+
372
358
  ## Contributing
373
359
 
374
360
  MIT licensed. Contributions welcome.
@@ -0,0 +1,369 @@
1
+ # clawprobe
2
+
3
+ **实时掌握你的 OpenClaw Agent 状态。**
4
+
5
+ Token 用量、API 成本、上下文健康度、智能告警 —— 一站式呈现,无需改动 OpenClaw 任何代码。
6
+
7
+ [![npm](https://img.shields.io/npm/v/clawprobe)](https://www.npmjs.com/package/clawprobe)
8
+ [![npm downloads](https://img.shields.io/npm/dm/clawprobe)](https://www.npmjs.com/package/clawprobe)
9
+ [![GitHub Stars](https://img.shields.io/github/stars/seekcontext/ClawProbe)](https://github.com/seekcontext/ClawProbe)
10
+ [![License](https://img.shields.io/github/license/seekcontext/ClawProbe)](./LICENSE)
11
+
12
+ [English](./README.md) · [简体中文](./README.zh-CN.md) · [日本語](./README.ja.md)
13
+
14
+ [为什么选择 clawprobe](#为什么选择-clawprobe) •
15
+ [快速开始](#快速开始) •
16
+ [命令说明](#命令说明) •
17
+ [Agent 集成](#agent-集成) •
18
+ [配置](#配置) •
19
+ [工作原理](#工作原理)
20
+
21
+ ---
22
+
23
+ ## 为什么选择 clawprobe
24
+
25
+ 你的 OpenClaw Agent 在上下文窗口里悄悄运行 —— 消耗 Token、静默压缩对话、花掉 API 预算。但这一切发生时,你什么都看不见。
26
+
27
+ clawprobe 解决这个问题。它在后台监听 OpenClaw 的文件,让你实时了解 Agent 正在做什么:
28
+
29
+ | 你的疑问 | clawprobe 的答案 |
30
+ |---------|----------------|
31
+ | "Agent 现在状态正常吗?" | `clawprobe status` — 即时快照 |
32
+ | "我想持续盯着它看" | `clawprobe top` — 实时仪表盘,自动刷新 |
33
+ | "为什么上下文老是被压缩?" | `clawprobe context` + `clawprobe suggest` |
34
+ | "压缩后 Agent 忘了什么?" | `clawprobe compacts` |
35
+ | "这花了我多少钱?" | `clawprobe cost --week`,内置主流模型价格 |
36
+ | "TOOLS.md 有没有完整传给模型?" | 内置截断检测,自动告警 |
37
+
38
+ **零配置。零副作用。100% 本地运行。**
39
+
40
+ ---
41
+
42
+ ## 快速开始
43
+
44
+ ```bash
45
+ npm install -g clawprobe
46
+
47
+ clawprobe start # 启动后台守护进程(自动识别 OpenClaw 安装路径)
48
+ clawprobe status # 查看即时快照
49
+ ```
50
+
51
+ clawprobe 自动识别你的 OpenClaw 安装。无需 API Key、无需注册账号、无遥测数据上报。
52
+
53
+ ### 作为 OpenClaw Skill 安装(一行命令)
54
+
55
+ 如果你使用 OpenClaw,可以将 clawprobe 安装为 Skill,让 Agent 具备自我监控能力:
56
+
57
+ ```bash
58
+ clawhub install clawprobe
59
+ ```
60
+
61
+ 或者直接告诉你的 Agent:
62
+
63
+ > 读取 https://raw.githubusercontent.com/seekcontext/ClawProbe/main/skills/clawprobe/SKILL.md 并按照其中的说明配置 clawprobe 自我监控。
64
+
65
+ 新建 OpenClaw 会话后,Agent 即可直接调用 `clawprobe` 命令进行自我监控。完整 Skill 定义见 [`skills/clawprobe/SKILL.md`](./skills/clawprobe/SKILL.md)。
66
+
67
+ ---
68
+
69
+ ## 命令说明
70
+
71
+ ### `clawprobe status` — 即时快照
72
+
73
+ 一眼看清当前会话、模型、上下文用量、今日花费和活跃告警。
74
+
75
+ ```
76
+ $ clawprobe status
77
+
78
+ 📊 Agent Status (active session)
79
+ ──────────────────────────────────────────────────
80
+ Agent: main
81
+ Session: agent:main:workspace:direct:xxx ●
82
+ Model: moonshot/kimi-k2.5
83
+ Active: Today 16:41 Compacts: 2
84
+
85
+ Context: 87.3K / 200.0K tokens ███████░░░ 44%
86
+ Tokens: 72.4K in / 5.2K out
87
+
88
+ Today: $0.12 → clawprobe cost 查看详情
89
+
90
+ 🟡 上下文窗口已用 44%
91
+ → 建议开启新会话或手动触发压缩
92
+ ```
93
+
94
+ ---
95
+
96
+ ### `clawprobe top` — 实时仪表盘
97
+
98
+ 在侧边终端打开,Agent 跑长任务时持续盯着它。每 2 秒自动刷新 —— 上下文进度条、成本计数器、逐轮 Token 消耗一览无余。
99
+
100
+ ```
101
+ clawprobe top refreshing every 2s (q / Ctrl+C to quit) 03/18/2026 17:42:35
102
+ ────────────────────────────────────────────────────────────────────────────────
103
+ Agent: main ● daemon running
104
+ Session: agent:main:workspace:direct:xxx ● active
105
+ Model: moonshot/kimi-k2.5
106
+ Active: Today 17:42 Compacts: 2
107
+ ────────────────────────────────────────────────────────────────────────────────
108
+ Context ████████░░░░░░░░░░░░░░░░ 44% 87.3K / 200.0K tokens
109
+ Headroom 112.7K tokens remaining (56%)
110
+ ────────────────────────────────────────────────────────────────────────────────
111
+ Session cost $0.52 Input 859.2K tok Output 29.8K tok
112
+ Today total $0.67 Cache read 712.0K tok
113
+ ────────────────────────────────────────────────────────────────────────────────
114
+ Recent turns
115
+ Turn Time ΔInput ΔOutput Cost Note
116
+ 27 17:42 22.0K 908 $0.0094 ← latest
117
+ 26 17:19 990 630 $0.0026
118
+ 25 17:19 20.4K 661 $0.0094
119
+ 24 15:57 564 39 $0.0014
120
+ 23 15:56 18.8K 231 $0.0076 ◆ compact
121
+ ────────────────────────────────────────────────────────────────────────────────
122
+ 🟡 Context window at 44% capacity
123
+ Costs are estimates based on public pricing.
124
+ ```
125
+
126
+ 按 `q` 或 `Ctrl+C` 退出,不会破坏终端原有内容。
127
+
128
+ ```bash
129
+ clawprobe top # 默认 2 秒刷新
130
+ clawprobe top --interval 5 # 5 秒刷新
131
+ clawprobe top --agent coder # 指定 Agent
132
+ ```
133
+
134
+ ---
135
+
136
+ ### `clawprobe cost` — API 成本统计
137
+
138
+ 内置 30+ 模型价格,分别统计输入、输出、缓存 Token 的费用。支持按天、周、月、全部查看。
139
+
140
+ ```
141
+ $ clawprobe cost --week
142
+
143
+ 💰 Weekly Cost 2026-03-12 – 2026-03-18
144
+ ──────────────────────────────────────────────────
145
+ Total: $0.67
146
+ Daily avg: $0.096
147
+ Month est: $2.87
148
+
149
+ 2026-03-12 ██████████████░░ $0.15
150
+ 2026-03-16 ████████████████ $0.16
151
+ 2026-03-17 █░░░░░░░░░░░░░░░ $0.0088
152
+ 2026-03-18 ███░░░░░░░░░░░░░ $0.03
153
+
154
+ Input: 1.0M tokens $0.65 (97%)
155
+ Output: 47.8K tokens $0.03 (3%)
156
+
157
+ 价格为估算值,请以模型厂商账单为准。
158
+ ```
159
+
160
+ 已内置价格:OpenAI(GPT-4o、o1、o3、o4-mini)、Anthropic(Claude 3/3.5/3.7 Sonnet/Opus/Haiku)、Google(Gemini 2.0/2.5 Flash/Pro)、Moonshot(kimi-k2.5)、DeepSeek(v3、r1)等。未收录的模型可通过 `~/.clawprobe/config.json` 自定义添加。
161
+
162
+ ---
163
+
164
+ ### `clawprobe session` — 会话详情
165
+
166
+ 查看任意会话的总成本、Token 时间线,以及每一轮的具体消耗。
167
+
168
+ ```
169
+ $ clawprobe session
170
+
171
+ 💬 Session agent:main:workspace:…
172
+ ──────────────────────────────────────────────────
173
+ Model: moonshot/kimi-k2.5
174
+ Duration: 2h 14m
175
+ Tokens: In 859.2K Out 29.8K Context 87.3K
176
+ Est. cost: $0.52
177
+ Compacts: 2
178
+
179
+ Turn timeline:
180
+ Turn Time ΔInput ΔOutput Cost
181
+ 1 14:02 4.2K 312 $0.003
182
+ 2 14:18 12.7K 891 $0.009 ◆ compact
183
+ 3 14:41 38.1K 2.4K $0.028
184
+
185
+ ```
186
+
187
+ ---
188
+
189
+ ### `clawprobe context` — 上下文窗口分析
190
+
191
+ 看清是什么在占用上下文,在截断问题造成麻烦之前提前发现。
192
+
193
+ ```
194
+ $ clawprobe context
195
+
196
+ 🔍 Context Window agent: main
197
+ ──────────────────────────────────────────────────
198
+ Used: 87.3K / 200.0K tokens ███████░░░ 44%
199
+
200
+ Workspace overhead: ~4.2K tokens (7 injected files)
201
+ Conversation est: ~83.1K tokens (messages + system prompt + tools)
202
+
203
+ ⚠ TOOLS.md: 31% truncated — 模型看不到这部分内容
204
+ 请在 openclaw.json 中提高 bootstrapMaxChars
205
+
206
+ Remaining: 112.7K tokens (56%)
207
+ ```
208
+
209
+ ---
210
+
211
+ ### `clawprobe compacts` — 压缩事件记录
212
+
213
+ 每次上下文压缩都被完整记录。看清被丢弃了什么,并在彻底消失前将关键内容归档。
214
+
215
+ ```
216
+ $ clawprobe compacts
217
+
218
+ 📦 Compact Events last 5
219
+ ──────────────────────────────────────────────────
220
+
221
+ #3 Today 16:22 [agent:main…] 3 messages
222
+
223
+ 👤 "Can you add retry logic to the upload handler?"
224
+ 🤖 "Done — added exponential backoff with 3 retries. The key change is in…"
225
+
226
+ → Archive: clawprobe compacts --save 3
227
+ ```
228
+
229
+ ---
230
+
231
+ ### `clawprobe suggest` — 优化建议
232
+
233
+ 自动检测常见问题,只在真正需要关注时才触发提醒。
234
+
235
+ | 规则 | 检测内容 |
236
+ |------|---------|
237
+ | `tools-truncation` | TOOLS.md 被截断,模型看不到部分工具描述 |
238
+ | `high-compact-freq` | 上下文填充过快,每 < 30 分钟就触发一次压缩 |
239
+ | `context-headroom` | 上下文窗口已用超过 90%,压缩即将发生 |
240
+ | `cost-spike` | 今日花费超过周均 2 倍 |
241
+ | `memory-bloat` | MEMORY.md 过大,每轮都在浪费 Token |
242
+
243
+ 屏蔽不需要的规则:`clawprobe suggest --dismiss <rule-id>`
244
+
245
+ ---
246
+
247
+ ## Agent 集成
248
+
249
+ clawprobe 专为**被 Agent 调用**而设计,而不只是给人用。所有命令都支持 `--json` 输出结构化数据,错误也始终以 JSON 格式返回,不会有破坏解析的彩色文本。
250
+
251
+ ### 单次健康检查
252
+
253
+ ```bash
254
+ clawprobe status --json
255
+ ```
256
+
257
+ ```json
258
+ {
259
+ "agent": "main",
260
+ "daemonRunning": true,
261
+ "sessionKey": "agent:main:workspace:direct:xxx",
262
+ "model": "moonshot/kimi-k2.5",
263
+ "sessionTokens": 87340,
264
+ "windowSize": 200000,
265
+ "utilizationPct": 44,
266
+ "todayUsd": 0.12,
267
+ "suggestions": [
268
+ {
269
+ "severity": "warning",
270
+ "ruleId": "context-headroom",
271
+ "title": "Context window at 44% capacity",
272
+ "detail": "...",
273
+ "action": "Consider starting a fresh session or manually compacting now"
274
+ }
275
+ ]
276
+ }
277
+ ```
278
+
279
+ ### 查询输出结构
280
+
281
+ ```bash
282
+ clawprobe schema # 列出所有命令
283
+ clawprobe schema status # status --json 的完整字段说明
284
+ clawprobe schema cost # cost --json 的完整字段说明
285
+ ```
286
+
287
+ ### 程序化屏蔽建议
288
+
289
+ ```bash
290
+ clawprobe suggest --dismiss context-headroom --json
291
+ # → { "ok": true, "dismissed": "context-headroom" }
292
+ ```
293
+
294
+ ### 错误响应始终可解析
295
+
296
+ ```bash
297
+ clawprobe session --json # 无活跃会话时
298
+ # → { "ok": false, "error": "no_active_session", "message": "..." }
299
+ # exit code 1
300
+ ```
301
+
302
+ ---
303
+
304
+ ## 配置
305
+
306
+ 可选配置文件 `~/.clawprobe/config.json`,首次运行 `clawprobe start` 时自动创建:
307
+
308
+ ```json
309
+ {
310
+ "timezone": "Asia/Shanghai",
311
+ "openclaw": {
312
+ "dir": "~/.openclaw",
313
+ "agent": "main"
314
+ },
315
+ "cost": {
316
+ "customPrices": {
317
+ "my-provider/my-model": { "input": 1.00, "output": 3.00 }
318
+ }
319
+ },
320
+ "alerts": {
321
+ "dailyBudgetUsd": 5.00
322
+ },
323
+ "rules": {
324
+ "disabled": ["memory-bloat"]
325
+ }
326
+ }
327
+ ```
328
+
329
+ 大多数用户无需任何配置,clawprobe 会自动从现有的 OpenClaw 配置中读取所有信息。
330
+
331
+ ---
332
+
333
+ ## 工作原理
334
+
335
+ clawprobe 在后台读取 OpenClaw 的现有文件 —— 无需修改代码、无需插件、无需 Hook。
336
+
337
+ - **零配置** — 自动识别 `~/.openclaw` 下的 OpenClaw 安装
338
+ - **零副作用** — 从不修改 OpenClaw 的文件,只写入 `~/.clawprobe/` 目录
339
+ - **后台守护** — `clawprobe start` 启动文件监听,保持本地数据库实时更新
340
+ - **极简依赖** — 仅 4 个生产依赖,无云服务,无遥测
341
+
342
+ ---
343
+
344
+ ## 隐私
345
+
346
+ - **100% 本地运行** — 数据不会离开你的机器
347
+ - **无遥测** — clawprobe 不收集任何数据
348
+ - **无账号,无 API Key** — 安装即用
349
+
350
+ ---
351
+
352
+ ## 兼容性
353
+
354
+ 支持所有版本的 OpenClaw。需要 Node.js ≥ 22 · macOS 或 Linux(Windows 通过 WSL2)。
355
+
356
+ ---
357
+
358
+ ## 参与贡献
359
+
360
+ MIT 开源协议,欢迎贡献。
361
+
362
+ ```bash
363
+ git clone https://github.com/seekcontext/ClawProbe
364
+ cd ClawProbe && npm install && npm run dev
365
+ ```
366
+
367
+ ---
368
+
369
+ [MIT License](./LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "clawprobe",
3
- "version": "0.6.9",
3
+ "version": "0.7.0",
4
4
  "description": "The missing observability layer for OpenClaw agents",
5
5
  "keywords": [
6
6
  "openclaw",