A dedicated utility to monitor and report API costs and token consumption across your AI agent sessions.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install usage-report
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 usage-report 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 Usage Report?
The Usage Report skill is a specialized diagnostic tool designed to provide granular visibility into LLM spending within the Openclaw ecosystem. By parsing per-turn session logs, it allows developers to track financial metrics and resource consumption in real-time. This skill is essential for users of Openclaw Skills who need to maintain budget control and understand the cost-efficiency of their agentic workflows.
It operates by reading raw data from session JSONL files, aggregating input and output tokens alongside prompt caching statistics. This transparency ensures that every interaction is accounted for, allowing users to optimize their prompts and model selections based on actual usage patterns.
Usage Report Use Cases
- Monitoring daily API expenditure to stay within a specific development budget.
- Analyzing token efficiency and the impact of prompt caching on total costs.
- Generating detailed session summaries for client billing or internal reporting.
- Identifying high-cost interactions within complex agentic workflows to improve ROI.
How Usage Report Works
- The skill identifies the active session directory, utilizing either the default path or the OPENCLAW_SESSIONS_DIR environment variable.
- It scans all valid JSONL log files within the directory, automatically filtering out lock files and backup resets.
- The tool parses each log entry to extract metadata regarding turns, input/output tokens, and cache hits/misses.
- Metrics are aggregated based on the user's requested timeframe, such as a specific date or a 'today' filter.
- Financial totals are calculated using the provider pricing data captured by Openclaw at the time of the request.
- The final report is generated in either a human-readable text format or a machine-parseable JSON structure.
Usage Report Setup
To use this skill, ensure your system has the necessary binary dependencies installed:
sudo apt-get install jq bc
By default, the skill looks for logs in ~/.openclaw/agents/main/sessions/. You can override this by setting an environment variable in your shell configuration:
export OPENCLAW_SESSIONS_DIR="/your/custom/path/sessions"
Usage Report Data Schema & Taxonomy
The skill organizes and reports data based on the following taxonomy derived from session logs:
| Metric | Description |
|---|---|
| Turns | Total number of assistant responses and API calls made during the session. |
| Cost | The sum of input, output, cache read, and cache write costs in USD. |
| Output Tokens | The volume of tokens generated by the language model. |
| Cache Metrics | Specific counts for prompt caching (read and write) to measure efficiency. |
| Filtering | Data can be scoped by 'today', 'all', or a specific 'YYYY-MM-DD' date string. |
Usage Report Advanced Features
- JSON output mode for seamless integration with other Openclaw Skills and automation pipelines.
- Dynamic date filtering for precise historical usage analysis.
- Automated cleanup of log paths by skipping .lock and .reset backup files.
- High-precision cost calculation with rounding logic optimized for user presentation.
SKILL.md
Loading
Related Openclaw Skills
OctenSearch
A high-performance web search skill providing AI agents with real-time, LLM-optimized data in under 80ms.
Custom API Summary
A specialized AI skill that connects agents to external APIs for high-performance text summarization and content extraction.
Perspective Transform Visualizer
A Three.js-powered interactive tool for visualizing 2D-to-3D perspective transformations and matrix parameters in real-time.
X Builder Digest
A technical skill to transform social feed JSON into professional bilingual English and Chinese markdown digests for builders and researchers.
DeepXiv CLI
A specialized command-line interface for progressive discovery, triage, and targeted reading of open-access academic literature.
Agentforce Observability & Session Tracing
A high-performance telemetry analysis skill for extracting and debugging Salesforce Agentforce session traces using the Session Tracing Data Model (STDM).
Featured*
