agent-token-usage

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

Why this skill 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 with many turns, real consumption can be 100×+ larger than what sessions_list shows. This skill reads the authoritative trajectory.jsonl files where each LLM call writes a usage object, and sums them per agent.

Quick start

# default = today, Asia/Shanghai local date
python ~/.openclaw/workspace/skills/agent-token-usage/scripts/agent_token_usage.py

# specific date
python ~/.openclaw/workspace/skills/agent-token-usage/scripts/agent_token_usage.py --date 2026-05-20

# also show equivalent billable token (cacheRead × 0.1 + cacheWrite × 1.25 + input + output)
python ~/.openclaw/workspace/skills/agent-token-usage/scripts/agent_token_usage.py --date 2026-05-20 --billable

# JSON for downstream tools
python ~/.openclaw/workspace/skills/agent-token-usage/scripts/agent_token_usage.py --date 2026-05-20 --format json

What the columns mean

用 total 看「谁在烧 LLM 算力」，用 ~bill 看「谁更费钱」。 两者结论可能完全不同 —— 高 cacheRead 的 agent 看似巨大其实便宜，低 cacheWrite 但全 input 的 agent 看似小其实贵。

How it works

1. Walk ~/.openclaw/agents/\x3Cagent>/sessions/*.trajectory.jsonl
2. For each line, check ts startswith target date (ISO YYYY-MM-DD)
3. DFS-search the data field for a usage dict with token counters
4. Sum per agent; also track session count and models used

Trajectory files use schema openclaw-trajectory v1. The usage object lives inside model-response events emitted by the runtime.

Common follow-ups

• "按等效成本排名" → --billable
• "昨天的" → --date YYYY-MM-DD
• "导出给我" → --format json > /tmp/usage.json
• "为什么 sessions_list 的数字差这么多" → 解释：sessions_list.totalTokens 是 context size，不是 cumulative spend。本 skill 直接累加每次 LLM 调用的 usage。

Caveats

• Only counts events that have a usage object — non-LLM tool calls (exec, read, write) are excluded by design
• The 0.1× / 1.25× cache multipliers are Anthropic ballpark numbers; for OpenAI / other providers adjust mentally
• Does NOT compute USD cost — use the model-usage skill (CodexBar cost log) when the user asks for $ amounts
• --date is matched against ISO timestamps in trajectory (which are UTC); for very late-night events this can shift by a day relative to local time. For Asia/Shanghai users this matters between 00:00-08:00 local