SKILL.md

---
name: token-usage
description: "Track, aggregate, and report OpenClaw token usage and costs across sessions."
homepage: https://github.com/space-cadet/openclaw-token-usage
license: MIT
---

# 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