A professional analytics tool for Openclaw that scans session data to provide detailed breakdowns of token usage, cache efficiency, and costs.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install token-stats
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install token-stats using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Token Stats?
Token Stats is a dedicated utility within the Openclaw Skills ecosystem designed to provide transparency into LLM consumption. It solves the common problem of inaccurate reporting by bypassing snapshots and performing a deep scan of raw session JSONL files, ensuring every API call is accounted for.
This skill is essential for developers and power users who need to monitor their expenses, evaluate the effectiveness of prompt caching, or identify which sessions are most resource-intensive. It uses a corrected calculation formula to handle edge cases where providers return negative input values, providing a ground truth for your Openclaw usage.
Token Stats Use Cases
- Monitoring daily or total token consumption and associated API costs.
- Evaluating cache hit rates to optimize prompt efficiency.
- Identifying the most expensive or token-heavy chat sessions for cleanup.
- Exporting usage data to JSON format for integration with external dashboards.
- Auditing historical usage including deleted or backed-up session files.
How Token Stats Works
- The skill identifies the local Openclaw storage directory, specifically targeting the JSONL session logs.
- It iterates through every assistant entry within the log files to extract the usage object.
- A corrected mathematical formula is applied to rectify provider-specific reporting quirks (like double-deduction of cached tokens).
- Data is aggregated based on user-defined flags such as daily breakdowns or session rankings.
- The final report is rendered to the CLI or exported as a structured JSON file.
Token Stats Setup
To start using this feature within your Openclaw Skills environment, ensure you have Python 3 installed. You can run the script directly using the following commands:
# Basic summary of all tokens
python3 {baseDir}/scripts/token_stats.py
# Get a detailed daily breakdown with session rankings
python3 {baseDir}/scripts/token_stats.py --daily --sessions
# Analyze a specific date range
python3 {baseDir}/scripts/token_stats.py --since 2026-03-01 --until 2026-03-16
Token Stats Data Schema & Taxonomy
Token Stats organizes data by extracting metrics from the entry.message.usage path within session files. It maps the following fields:
| Metric | Description | Logic |
|---|---|---|
| fresh_input | New tokens sent to API | max(input, 0) |
| prompt | Total prompt context | cacheRead + fresh_input |
| output | Generated tokens | raw output value |
| cacheRead | Tokens served from cache | raw cacheRead value |
| total | Comprehensive usage | prompt + output |
Files are scanned from ~/.openclaw/agents/<agent>/sessions/*.jsonl.
Token Stats Advanced Features
- Historical Auditing: Use the
--include-deletedflag to scan.deletedand.bakfiles for a complete lifecycle view. - Machine-Readable Export: Generate outputs in JSON format using
--format jsonfor custom data pipelines. - Performance Ranking: Isolate the 'Top X' heaviest sessions using the
--topflag to manage context window limits. - Compaction Resilience: Unlike standard session snapshots, this skill remains accurate even after Openclaw performs context compaction.
SKILL.md
Loading
Related Openclaw Skills
Page Field Analyzer
An automated browser-use skill that navigates to URLs to identify, count, and categorize every form element and UI component on a page.
Git Commit Helper (gi-git-commit-helper)
An AI-powered skill that analyzes git diffs to generate professional, standardized commit messages following the Conventional Commits specification.
Idea to Startup: Disciplined Entrepreneurship Guide
A rigorous, 24-step roadmap based on MIT methodology to guide entrepreneurs from initial concept to a scalable, validated startup.
Word Chinese Automation
An automated Chinese document proofreading tool for Word that identifies punctuation errors, grammatical issues, and typos with high precision.
Social Security & Housing Fund Assistant (China)
A comprehensive utility for querying social security records, housing fund balances, and calculating payroll deductions across major Chinese cities.
Pension
Pension is a privacy-focused command-line tool for logging financial entries, analyzing spending trends, and generating local reports.
Featured*
