An automated reporting tool that appends accurate, reproducible token and cost statistics to AI agent messages using local log aggregation.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install token-stats-reporter
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-reporter 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 Reporter?
The Token Stats Reporter is a professional-grade utility designed to enhance the transparency of AI interactions within the Openclaw Skills ecosystem. It solves the problem of opaque API costs by generating a standardized footer for every outgoing message, detailing input/output tokens, cache performance, and real-time billing metrics. By utilizing a local aggregation algorithm, it ensures that cost tracking is both reproducible and resilient to session interruptions.
This skill is essential for developers and teams who need to adhere to strict channel policies or simply want to keep a close eye on their expenditure. It operates by analyzing session logs, applying deduplication logic, and maintaining a persistent state to track monthly usage across different models. By integrating this into your workflow, you gain a reliable source of truth for all AI-related consumption metrics.
Token Stats Reporter Use Cases
- Enforcing transparent billing by appending token costs to every user-facing message.
- Generating monthly consumption reports to track budget usage across specific AI models.
- Auditing agent performance and cache efficiency in long, multi-step development tasks.
- Providing real-time feedback to users regarding the resource consumption of their queries.
How Token Stats Reporter Works
- The skill triggers a bundled Python script immediately before the agent delivers a final response.
- The script parses local session log files in the JSONL format, filtering for valid assistant responses containing usage metadata.
- A deduplication engine checks message IDs to ensure that no tokens are double-counted during the aggregation phase.
- Current session data is merged with a persistent state file to calculate both the immediate transaction cost and the cumulative monthly total.
- The tool generates a formatted token line that includes specific metrics such as cache hits, billable tokens, and the active model name.
- A mandatory validation gate inspects the output to prevent manual overrides or incorrect data from being sent to the user.
Token Stats Reporter Setup
To deploy this utility within your Openclaw Skills environment, ensure the scripts have the necessary permissions to read session logs and write to the local memory directory.
# Grant execution permissions to the reporter script
chmod +x /home/admin/.openclaw/workspace/skills/token-stats-reporter/scripts/token-show.py
# The skill requires access to the following directory for state management
mkdir -p /home/admin/.openclaw/workspace/skills/token-stats-reporter/memory/
Once permissions are set, the agent should be configured to run the script and append the output line as the final step of its response generation workflow.
Token Stats Reporter Data Schema & Taxonomy
The skill maintains data integrity through a structured approach to log parsing and state persistence:
| Component | Source / Path | Description |
|---|---|---|
| Session Logs | ~/.openclaw/agents/main/sessions/*.jsonl |
Raw data source for all message and usage metadata. |
| State File | memory/token-agg-state.json |
Stores per-file offsets and aggregated monthly totals to optimize performance. |
| Message Filter | type=message && role=assistant |
Logic used to isolate billable responses from system prompts or user inputs. |
| Timezone | Asia/Shanghai |
The default timezone used for bucketizing monthly usage and costs. |
Token Stats Reporter Advanced Features
- Incremental Replay Logic: Uses per-file offset tracking to scan only new logs, ensuring high performance even with large session histories.
- Fail-Closed Send Gate: A safety mechanism that blocks message delivery if the token statistics script fails or returns invalid data, preventing manual data entry errors.
- Snapshot Synchronization: Automatically detects file truncation or resets, falling back to a full scan to maintain data accuracy.
- Model Attribution: Specifically identifies the model used for each transaction, ensuring cost statistics are attributed to the correct API endpoint.
SKILL.md
Loading
Related Openclaw Skills
Daily Lottery Statistics & Trend Analysis
A professional data processing skill designed to aggregate historical lottery results and generate multi-dimensional statistical trend reports.
Doc Generator
An automated documentation engine that extracts API metadata and technical specifications directly from source code to generate structured documents.
PR Review Skill
An automated workflow for GitHub Pull Requests that performs deep security, performance, and quality analysis using the GitHub CLI.
Image to Video Generator Free
A powerful AI skill that breathes life into static images by transforming them into high-quality animated video sequences for free.
Llama Pet
Llama Pet is a virtual pet system that allows AI agents to adopt and care for over 73 species of digital creatures with real-time needs and evolution paths.
Gemini Pet
A model-agnostic virtual pet system for AI agents featuring 73+ species, real-time stat tracking, and permanent death mechanics.
Featured*
