agent-token-usage 📊#

Accurately attribute LLM token consumption across all OpenClaw agents for a given day.

Ships two things in one skill:

1. CLI — scripts/agent_token_usage.py, always works, zero setup
2. UI button — optional apply-ui.sh injects a 📊 button into Control UI's header next to Search; clicking shows today's per-agent table in a modal

Why this exists#

sessions_list returns each session's totalTokens field which is the last context window size, NOT the cumulative consumption across all LLM calls in that session. For long-running sessions, real consumption can be 100×+ larger. This skill reads the canonical session log ( <id>.jsonl, NOT <id>.trajectory.jsonl) and sums every type=="message" / role=="assistant" row's usage object — exactly one entry per real LLM API call. This matches pew / openclaw's own accounting.

Quick start (CLI)#

bash

# default = today, UTC date (matches pew / openclaw accounting)
python ~/.openclaw/workspace/skills/agent-token-usage/scripts/agent_token_usage.py

# local-tz date instead of UTC
python …/agent_token_usage.py --tz local

# specific date
python …/agent_token_usage.py --date 2026-05-20

# equivalent billable (cacheRead × 0.1 + cacheWrite × 1.25 + input + output)
python …/agent_token_usage.py --date 2026-05-20 --billable

# JSON
python …/agent_token_usage.py --format json

Optional: 📊 button in Control UI#

bash

bash ~/.openclaw/workspace/skills/agent-token-usage/apply-ui.sh

Then refresh the Control UI tab. The button appears next to Search; clicking shows the modal.

Uninstall:

bash

bash ~/.openclaw/workspace/skills/agent-token-usage/remove-ui.sh

Per-browser toggle:

js

localStorage.setItem('milly.tokenUsageBtn', 'off')
localStorage.removeItem('milly.tokenUsageBtn')

How the UI part works#

text

launchd (5min)  →  refresh-data.sh  →  <ui>/data/agent-token-usage.json
                                              │ same-origin fetch
                                              ▼
                                    Control UI bundle (patched IIFE)
                                       📊 button → modal table

CSP-friendly ( connect-src 'self') because data is served from the UI's own origin. No extra daemon, no extra port. After openclaw update overwrites dist/control-ui/*, just re-run apply-ui.sh — idempotent.

Column semantics#

FieldMeaningBilling weightinputnew, non-cached prompt tokens1.0×outputmodel-generated tokens1.0× (typically 5× input price)cacheReadprompt tokens served from prompt cache0.1×cacheWriteprompt tokens written to cache1.25×totalsum of all four (real LLM throughput)—~billweighted billable-equivalent tokens—

Use total to see "who's burning the most LLM compute"; use ~bill to see "who's actually most expensive". High-cacheRead agents look huge but are cheap; high-input agents look small but cost more.

How it works#

1. Walk ~/.openclaw/agents/<agent>/sessions/*.jsonl (excluding *.trajectory.jsonl, *.deleted*, *.bak)
2. For each line keep only records with type=="message" and message.role=="assistant"
3. Match timestamp against target date in chosen timezone ( --tz utc default, --tz local available)
4. Sum message.usage.{input,output,cacheRead,cacheWrite} per agent; track sessions and models

Why NOT trajectory.jsonl#

Each LLM call produces several trajectory events ( prompt.submitted, context.compiled, model.completed, trace.artifacts, …) and every one of them embeds the same usage snapshot. A DFS sum over trajectory inflates the real number by ~2.6×. The canonical <id>.jsonl has exactly one type=="message" row per call — 1:1 with the API call, no de-dup needed.

Caveats#

• Only counts LLM calls (events with a usage object) — non-LLM tool calls excluded by design
• Cache multipliers are Anthropic ballpark numbers; adjust for other providers mentally
• Does NOT compute USD cost — use the model-usage skill for $ amounts
• --date matches ISO timestamps in session logs (UTC by default). Use --tz local to bucket by your local day instead
• UI auto-refresh job (launchd) is macOS only; on Linux, run scripts/refresh-data.sh via cron/systemd timer

Files#

FilePurposescripts/agent_token_usage.pyCLI aggregatorscripts/refresh-data.shWrites JSON into every patched Control UI distscripts/token-usage-button.iife.jsUI patch payload (button + modal + same-origin fetch)apply-ui.shInject IIFE, cache-bust, install launchd refresh jobremove-ui.shRestore bundle, remove launchd job, delete data dir