Token Usage

Track, aggregate, and report OpenClaw token usage and costs across sessions.

Token Usage Tracker

Parse OpenClaw session JSONL files to extract token usage, aggregate by date/model/session, and generate cost reports.

When to Use

• User asks "how many tokens did I use today/this week"
• User wants to know session costs or model breakdown
• Budget monitoring and anomaly detection
• Before/after optimization comparisons

Workflow

1. Locate sessions — Find .jsonl files in ~/.openclaw/agents/*/sessions/
2. Parse usage — Extract input, output, cacheRead, cacheWrite, totalTokens from each assistant message
3. Aggregate — Group by date, model, session ID
4. Report — Output summaries, trends, cost estimates

Commands

Parse and aggregate current sessions

bash

python3 ~/.openclaw/skills/token-usage/scripts/parse.py --today

Weekly report with cost estimates

bash

python3 ~/.openclaw/skills/token-usage/scripts/parse.py --week --costs

All-time summary by model

bash

python3 ~/.openclaw/skills/token-usage/scripts/parse.py --all --by-model

Export to JSON for external dashboards

bash

python3 ~/.openclaw/skills/token-usage/scripts/parse.py --week --json > /tmp/token-report.json

Data Format

Sessions are stored as JSONL with lines like:

json

{"type":"message","message":{"role":"assistant",...},"usage":{"input":1000,"output":500,"totalTokens":1500},...}

Cost Estimation

Uses model pricing from scripts/pricing.json (user-editable). Default prices:

• Kimi k2.7: $0.50/1M input, $2.00/1M output
• Claude Sonnet 4: $3.00/1M input, $15.00/1M output
• GPT-4o: $2.50/1M input, $10.00/1M output

Costs are approximate. Cache read/write pricing applied when available.

Important: What "Total" Means

The script reports input + output tokens as the usage metric. This is the actual new token consumption per turn.

The totalTokens field in session files includes cacheRead (cached context window), which gets re-counted at every turn. Summing totalTokens across messages would massively overcount — a 10K context used for 100 turns would appear as 1M tokens. The script avoids this by only summing input and output.

Output Locations

• Daily summaries: ~/.openclaw/skills/token-usage/logs/YYYY-MM-DD.md
• Weekly reports: ~/.openclaw/skills/token-usage/logs/week-YYYY-Www.md
• Raw JSON exports: user-specified or /tmp/token-usage-*.json

Limitations

• Only parses assistant messages with usage fields (OpenClaw 2026.5+ format)
• Historical sessions before JSONL format not supported
• Costs are estimates; actual billing may differ