openrouter-usage

Track your OpenRouter spending directly from your OpenClaw agent. Shows credit balance, per-model cost/token breakdown, and spending projections.

Trigger

Use when the user asks about OpenRouter credits, costs, spending, balance, usage, billing, or the /usage command.

Commands

Full report (recommended — combines everything)

openrouter-usage report              # credits + today's usage + projection
openrouter-usage report --week       # credits + last 7 days
openrouter-usage report --month      # credits + last 30 days

Credit balance only

openrouter-usage credits

Per-model breakdown only

openrouter-usage sessions --today
openrouter-usage sessions --week
openrouter-usage sessions --month
openrouter-usage sessions --date 2026-02-25
openrouter-usage sessions --from 2026-02-01 --to 2026-02-15

Filtering and output

openrouter-usage report --agent main          # specific agent only
openrouter-usage report --format json         # JSON output
openrouter-usage sessions --today --utc       # use UTC instead of local timezone

Notes

• API key auto-discovered from OpenClaw auth store or OPENROUTER_API_KEY env var.
• Session parsing is fully local — reads ~/.openclaw/agents/*/sessions/*.jsonl.
• Date filters use local timezone by default. Pass --utc to override.
• Zero dependencies beyond Python 3 stdlib.