token-usage

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

Token Usage Tracker

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

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 agent sessions and nested Codex rollout sessions
2. Parse usage — Extract OpenClaw message usage or Codex event_msg/token_count per-turn usage
3. Aggregate — Group by date, model, session ID
4. Report — Output summaries, trends, cost estimates

Commands

Parse and aggregate current sessions (OpenClaw + Codex)

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

Report by cron job (daily breakdown per job)

bash

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

Weekly cron report with costs (JSON output)

bash

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

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). The bundled table includes Kimi, OpenAI/GPT, Anthropic/Claude, and OpenRouter models. Unknown models are reported without a cost estimate rather than silently priced as Kimi.

Default examples (USD per 1M tokens):

• 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

• OpenClaw records are parsed from message.usage; Codex rollouts are parsed from payload.info.last_token_usage in token_count events
• input + output is the new-usage metric; Codex cached input is reported separately as cacheRead
• Historical sessions before JSONL format are not supported
• Costs are estimates; actual billing may differ