Claw Usage Rollup

Daily OpenClaw model and token usage reports from local session logs, with both a CLI and a tidy local dashboard.

What this is for

This is for normal OpenClaw users who want a simple answer to questions like:

• what used GPT today?
• did Ollama Cloud get used?
• were local models active?
• did my setup drift away from local-first?

It is meant to be lightweight and practical. It is not a fancy analytics platform.

Two ways to use it

1. Dashboard mode, recommended for most people

Run:

bash scripts/run_dashboard.sh

Then open the local page shown by the server.

Dashboard mode gives you:

• headline totals
• drift warnings
• top models
• provider breakdown
• by-model table
• refresh from the page

2. CLI mode, useful for automation and terminal use

Single day:

python3 scripts/usage_rollup.py --date 2026-04-16 --openclaw-home ~/.openclaw --csv

Today helper:

bash scripts/usage_today.sh

Date range:

python3 scripts/usage_rollup.py --start-date 2026-04-14 --end-date 2026-04-16 --openclaw-home ~/.openclaw --csv

What it does

Claw Usage Rollup scans local OpenClaw session and cron artifacts and builds usage summaries by:

• model
• provider
• agent
• date or date range

It writes:

• JSON reports
• Markdown summaries
• CSV exports
• policy and drift summaries that help spot GPT-heavy or cloud-heavy days

What it does not do

This is a local artifact rollup, not billing truth.

Important limits:

• event counts are not guaranteed to equal unique model calls
• token totals depend on what providers write into local artifacts
• some providers or local models may show activity with zero usable token totals
• cost is intentionally not estimated in v1

Inputs scanned

By default it scans:

• ~/.openclaw/agents/*/sessions/*.jsonl*
• ~/.openclaw/cron/runs/*.jsonl*

It ignores lock and temp files.

Privacy note

By default the script redacts absolute paths in its report output. Use --show-paths only for local debugging.

Outputs

Examples:

• reports/model-usage/daily-2026-04-16.json
• reports/model-usage/daily-2026-04-16.md
• reports/model-usage/daily-2026-04-16-by-model.csv
• reports/model-usage/daily-2026-04-16-by-agent.csv
• reports/model-usage/range-2026-04-14_to_2026-04-16.md

Interpretation guide

Best fields to trust first:

• nonzero_token_requests
• recorded_total_tokens
• top token usage summary
• policy summary and policy warnings

Treat these more carefully:

• activity_events
• token_bearing_requests
• any model with lots of zero_token_records
• policy warnings, which are guidance rather than hard billing truth

Docs

• docs/README-dashboard.md
• docs/README-cli.md
• SUPPORT.md

Example output

See fixtures/sample-report-daily.json for a small example report shape.

Optional support

Claw Usage Rollup is free to use and will remain free to use.

There is no paywall, no locked feature tier, and no pressure to pay. If it saves someone time and they want to help with future improvements, they can optionally support it here:

• https://buymeacoffee.com/vinceandholly

Support is never required.

License

MIT