llm-cost-tracker#

Track and report LLM token usage and cost for OpenClaw via OpenRouter.

Quick Start#

bash

python3 scripts/collect_usage.py --init      # first-time: create DB + backfill
python3 scripts/run_tracker.py               # telegram report (default)
python3 scripts/run_tracker.py --output terminal  # full terminal report
python3 scripts/run_tracker.py --output debug     # per-request debug

Core Design#

• Source of truth: usage.cost.total from OpenRouter — never recomputed from token counts
• Data source: OpenClaw session JSONL files (including .reset files from context compaction)
• Deduplication: by openrouter_request_id — safe to re-run backfill anytime
• Time windows: 24h rolling (UTC); 7d/30d/90d/365d calendar days (configurable timezone)

Schema: request_facts#

ColumnSourceopenrouter_request_idresponseId (unique key)created_at_utcentry timestampmodelmodel IDprompt_tokensusage.inputcompletion_tokensusage.outputcached_tokensusage.cacheReadcache_write_tokensusage.cacheWritereasoning_tokensusage.reasoningtotal_tokensusage.totalTokensbilled_costusage.cost.total (canonical)

Configuration#

config/env.json (all fields optional):

json

{
  "SESSIONS_DIR": "",
  "TIMEZONE": "Asia/Hong_Kong",
  "UTC_OFFSET_HOURS": 8
}

• SESSIONS_DIR: override session file location (empty = auto-detect)
• TIMEZONE / UTC_OFFSET_HOURS: for calendar-day window calculations
• API key: auto-detected from ~/.openclaw/agents/main/agent/auth-profiles.json or OPENROUTER_API_KEY env var

Scheduled Reports#

bash

openclaw cron add --name "llm-cost:collect" --message "collect usage data" \
  --cron "5 0 * * *" --tz "Asia/Hong_Kong" --session isolated --no-deliver

openclaw cron add --name "llm-cost:daily" --message "llm cost" \
  --cron "0 9 * * *" --tz "Asia/Hong_Kong" --session isolated