Usage Report

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.

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 today

Output 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/*.jsonl by default
• Override with OPENCLAW_SESSIONS_DIR env var
• Costs are calculated by OpenClaw at request time using provider pricing
• Skips .lock and .reset backup files
• When presenting to user, round total cost to 2 decimal places