Token Waste Auditor
Audit QClaw/OpenClaw token consumption and pinpoint waste. Outputs an anonymized report with concrete optimization estimates.
Quick Start
# Full audit (daily + session deep scan)
python scripts/auditor.py --days 30
# Lite audit (daily summary only, no session scan)
python scripts/auditor.py --days 30 --lite
# JSON output for CI
python scripts/auditor.py --days 7 --json
Data Sources
| Source | What | Cost |
|---|---|---|
openclaw gateway usage-cost --json |
Daily input/output/cache totals | 0 (built-in) |
Session .jsonl files |
Per-message + tool-call audit | 0 (local) |
Skill SKILL.md files |
Prompt size measurement | 0 (local) |
Waste Dimensions
| Code | Waste Type | Detection |
|---|---|---|
| W01 | Low Cache Efficiency | cacheRead / total < 90% — context changes too often |
| W02 | Context Overstuffing | input / output > 20:1 — too much context for too little output |
| W03 | Skill Prompt Bloat | SKILL.md > 20KB — diminishing returns on instruction length |
| W04 | Skill Prompt Redundancy | Duplicate blocks found across multiple SKILL.md files |
| W05 | Session Bloat | Single session > 100K tokens without recent compaction |
| W06 | Aborted Runs | Assistant messages truncated mid-generation |
Output Structure
══════════════════════════════════════════════
Token Waste Audit Report
Period: 2026-05-01 ~ 2026-05-21 (21 days)
══════════════════════════════════════════════
[1/6] Cache Efficiency
read: 347.5M (96.6%)
input: 10.9M (3.0%)
waste: 1.2M (0.3%) ← cache-miss overhead
Status: ✅ healthy
[2/6] Context Overstuffing
avg input:output ratio = 7.9:1
worst day: 2026-05-12 → 16.1:1
Status: ✅ within bounds (< 20:1)
[3/6] Skill Prompt Bloat (top 3)
1. skill-07 48KB ⚠️ suggests split
2. skill-03 42KB ⚠️ suggests split
3. skill-12 31KB — acceptable
Est. waste: ~800K tokens/load × loads/week
[4/6] Skill Prompt Redundancy
7 duplicate blocks found across 4 skill files
Est. savings: ~140K tokens/week if deduplicated
[5/6] Session Bloat (top 3)
1. session-01 14.2MB ⛰️ ⛰️ active 24d, 2 compactions
2. session-02 2.5MB ⛰️ active 1d, 7 compactions
3. session-03 2.0MB active 1d, 8 compactions
Suggests: archive long-lived sessions
[6/6] Aborted Runs
Count: 2 aborted assistant responses
Est. waste: ~45K tokens (negligible)
Status: ✅ healthy
══════════════════════════════════════════════
Summary
══════════════════════════════════════════════
Total tokens (period): 359.8M
Est. waste: 11.5M (~3.2%)
Est. savings potential: 4-8M/month
══════════════════════════════════════════════
Constraints
- Anonymity: All skill/agent/session names are hashed or replaced with generic labels. No path, name, or methodology from the user's setup ever appears in output.
- Privacy: The report contains only token metrics and waste estimates. No conversation content is extracted or reproduced.
- Safety: Read-only. Never modifies session files, skill files, or system config.
