- name
- usage-report
- description
- Generate cost and token usage reports from OpenClaw session logs. Use when asked about API costs, token usage, billing, spending, how much something cost, or daily/session usage summaries. Works by reading per-turn usage data from session JSONL files.
- author
- DirectorVector
- homepage
- https://github.com/DirectorVector
- metadata
Usage Report
Generate cost and token usage reports from OpenClaw session JSONL logs.
Quick usage
# Full text report (all sessions)
{baseDir}/scripts/usage-report.sh
# JSON output
{baseDir}/scripts/usage-report.sh json
# Filter to today only
{baseDir}/scripts/usage-report.sh text today
# Filter to specific date
{baseDir}/scripts/usage-report.sh text 2026-04-07
# JSON for a specific date
{baseDir}/scripts/usage-report.sh json todayOutput fields
- Turns: number of assistant responses (API calls)
- Cost: sum of per-turn costs (input + output + cache read + cache write)
- Output tokens: tokens generated by the model
- Cache read/write: prompt caching token counts
Notes
- Reads from
~/.openclaw/agents/main/sessions/*.jsonlby default - Override with
OPENCLAW_SESSIONS_DIRenv var - Costs are calculated by OpenClaw at request time using provider pricing
- Skips
.lockand.resetbackup files - When presenting to user, round total cost to 2 decimal places