A utility to accurately calculate, aggregate, and display cumulative LLM token usage across all OpenClaw agents, featuring a Python CLI and an optional Control UI analytics button.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install agent-token-usage
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 agent-token-usage 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 agent-token-usage?
The agent-token-usage skill is designed to solve a critical accounting challenge in multi-agent environments: tracking actual cumulative token usage. Unlike standard session listings that only display the last context window size, this utility parses the canonical raw session logs (.jsonl) to sum every single LLM API call. It provides developers and administrators with precise visibility into how much computation each individual agent consumes. Keep your resource usage transparent and optimize your API budgets seamlessly with this and other Openclaw Skills.
It ships with two distinct components: a robust Python command-line interface (CLI) and an optional web integration that patches a statistics button into your Control UI. By calculating real LLM throughput and weighted billable-equivalent tokens, it allows you to easily identify which agent is burning the most compute or driving the highest cost.
agent-token-usage Use Cases
- Tracking real cumulative token consumption over time instead of just the final context window size.
- Identifying high-cost or runaway agents within an OpenClaw multi-agent deployment.
- Generating CSV, JSON, or table-formatted daily token reports for auditing and optimization using Openclaw Skills.
- Visualizing resource usage inside the OpenClaw Control UI with an integrated interactive dashboard button.
- Adjusting agent behavior by differentiating between highly-cached, low-cost interactions and expensive raw input/output calls.
How agent-token-usage Works
- Log Discovery: The skill scans directories matching
~/.openclaw/agents/<agent>/sessions/*.jsonlto locate canonical session transaction logs while systematically ignoring trajectory files. - Filtering & Extraction: It reads each line, filtering exclusively for records where
typeismessageand theroleisassistantto ensure a strict 1:1 match with physical LLM API requests. - Time-Bucket Matching: Individual API call timestamps are evaluated against the target date query, using either UTC or your configured local timezone.
- Aggregation: The script sums up key token metrics including input, output, cacheRead, and cacheWrite, and groups them dynamically per active agent.
- Reporting: The utility formats the aggregated results into a ranked table showing absolute totals and calculated billable estimates, which are then outputted to the CLI or rendered inside the UI modal.
agent-token-usage Setup
To start using this skill directly from your CLI, navigate to your workspace and run the Python script:
# Standard usage (aggregates usage for today based on UTC)
python ~/.openclaw/workspace/skills/agent-token-usage/scripts/agent_token_usage.py
# Group by your local timezone instead of UTC
python ~/.openclaw/workspace/skills/agent-token-usage/scripts/agent_token_usage.py --tz local
# Query token statistics for a specific historical date
python ~/.openclaw/workspace/skills/agent-token-usage/scripts/agent_token_usage.py --date 2026-05-20
To inject the stats visualizer button into your Control UI dashboard, install the UI patch:
bash ~/.openclaw/workspace/skills/agent-token-usage/apply-ui.sh
If you ever need to remove the UI modifications, simply run the cleanup script:
bash ~/.openclaw/workspace/skills/agent-token-usage/remove-ui.sh
agent-token-usage Data Schema & Taxonomy
The agent-token-usage skill processes underlying data from standard log paths and evaluates token tracking fields based on the following metrics schema:
| Token Type | Meaning | Approximate Billing Weight |
|---|---|---|
input |
New, non-cached prompt tokens submitted to the model | 1.0x |
output |
Tokens generated dynamically by the model response | 1.0x (base, typically priced higher) |
cacheRead |
Prompt tokens read from active context cache | ~0.1x (highly discounted) |
cacheWrite |
Prompt tokens written to the context cache window | ~1.25x (slight premium) |
total |
Mathematical sum of all physical throughput | N/A |
~bill |
Weighted estimate of billable-equivalent tokens | Calculated based on standard multipliers |
Output Files and Directories
- CLI Execution Script:
scripts/agent_token_usage.py - Control UI Patch Script:
apply-ui.shandremove-ui.sh - Generated UI Asset Data: Serves from
dist/control-ui/data/agent-token-usage.json(integrated cleanly via same-origin fetch to bypass Content Security Policy restrictions).
agent-token-usage Advanced Features
- Weighted Cost Estimation: Features a
--billableflag that translates physical token counts into equivalent-billable tokens based on provider caching multipliers. - Control UI Injection: Leverages an IIFE script patching mechanism to append interactive modal controls next to the global search bar.
- Automated Data Refreshes: Employs a launchd daemon process on macOS (or systemd/cron alternatives on Linux) to dynamically rebuild usage statistics in the background every 5 minutes.
- Timezone Normalization: Fully supports UTC-to-local timezone shifting (
--tz local) to align resource accounting with the operator's real-world business day. - Exportable Data Formats: Supports output redirection with JSON formatting via CLI (
--format json), which integrates smoothly with external DevOps logging dashboards powered by Openclaw Skills.
SKILL.md
Loading
Related Openclaw Skills
Alibaba Cloud ECS Snapshot-Based Disaster Recovery Backup
An automated Alibaba Cloud ECS disaster recovery and backup automation agent skill for cross-AZ full-instance and disk-level recovery.
alibabacloud-pts-pilot
An execution-free performance testing router that intelligently intercepts user intents and delegates Alibaba Cloud PTS actions to dedicated sub-skills.
PPTX Add Slides
An advanced automation script that inserts new slides into existing PPTX files with 100% style and layout consistency by cloning slide XML elements.
Auth0 Android Major Migration
Automates the upgrade of an Android application's Auth0 SDK from v3 to the next major v4 release by auditing call sites and applying code changes safely.
PrepKit: Informatics Olympiad Lesson Preparation Framework
PrepKit is an advanced instructional framework based on the ADDIE model, specifically tailored for AI agents to design and develop elite training materials for informatics competitions like NOI, CSP, and GESP.
AgentNOMOS Governance Preflight
A read-only governance preflight tool that evaluates proposed AI agent actions for authorization, boundaries, risks, and required evidence before execution.
Featured*
