Feature Request

Version: 2026.2.6-3

Problem

There is no API or CLI command to retrieve cumulative token usage or estimated cost per session. The existing data sources are misleading or incomplete:

sessions.json token fields are not cumulative

• inputTokens / outputTokens — these track per-message token counts (single digits), not session totals
• totalTokens — this is the context window size (100K+), not cumulative tokens consumed
• None of these can be used to estimate actual API spend

No session-level usage API

• /status and session_status show current context window usage, not historical spend
• /usage tokens and /usage full exist per docs but return session-scoped snapshots, not aggregated billing data
• openclaw status --usage provides a summary but no per-session or per-model breakdown accessible programmatically

What's needed for cost tracking

Building a cost dashboard (or even basic spend monitoring) requires:

1. Cumulative input/output tokens per session (or per turn)
2. Model used per request (to apply correct pricing)
3. Either raw token counts (user applies pricing) or pre-calculated cost estimates

Use Cases

1. Daily cost monitoring — "How much did I spend today across all sessions?"
2. Per-cron-job cost tracking — "Which of my 23 cron jobs costs the most?"
3. Model cost comparison — "How much cheaper would Haiku be for this job vs Opus?"
4. Budget alerts — "Warn me if daily spend exceeds $X"
5. Dashboard integration — Programmatic access for custom UIs

Proposed Solutions

Option A: Per-turn token logging in session history
Each turn in the .jsonl session log includes inputTokens, outputTokens, model, and optionally cost (if provider reports it). A CLI command aggregates:

openclaw usage --session <key> --json
openclaw usage --date 2026-02-08 --json
openclaw usage --model anthropic/claude-opus-4-6 --json

Option B: Usage event stream / webhook
Emit a usage event per model invocation with token counts and model info. Users can aggregate however they want.

Option C: Built-in usage database
SQLite or similar, auto-populated per request. Query via CLI/API.

Related

• Feature Request: Display cost estimates in session_status #9696 — requests cost display in session_status (display layer — this issue is about the underlying data layer that would power it)
• Add granular session-log usage diagnostics (date ranges + JSON export) #3718 (closed) — granular session-log usage diagnostics
• Isolated cron sessions accumulate indefinitely — no built-in pruning #12289 — orphaned cron sessions (cost tracking would help identify expensive orphans)