Openclaw Cost Tracker

Track OpenClaw token usage and API costs from local session data. Prefer openclaw-cost-diff for current cost analysis and window-over-window comparison acros...

Analyze OpenClaw token usage and API costs from local session data.

Prefer openclaw-cost-diff as the default tool for current analysis because it can compare time windows and break down changes by model, agent, and channel.

Preferred usage

# Compare the last 7 days vs the prior 7 days
/root/.openclaw/venvs/openclaw-cost-diff/bin/openclaw-cost-diff --last 7d --prev 7d

# JSON output for tooling or dashboards
/root/.openclaw/venvs/openclaw-cost-diff/bin/openclaw-cost-diff --data /root/.openclaw/agents --last 7d --prev 7d --json

# Focus on a specific model
/root/.openclaw/venvs/openclaw-cost-diff/bin/openclaw-cost-diff --model openai-codex/gpt-5.4 --last 14d --prev 14d

# Compare agent behavior
/root/.openclaw/venvs/openclaw-cost-diff/bin/openclaw-cost-diff --agent main --prev-agent codex --last 7d --prev 7d

Legacy/local fallback

Use the bundled cost_tracker.py only as a secondary local fallback when openclaw-cost-diff is unavailable or when you want the older single-window daily spend report format.

# All-time cost report
python3 scripts/cost_tracker.py

# Last 7 days
python3 scripts/cost_tracker.py --days 7

# Today only
python3 scripts/cost_tracker.py --days 1

# Since a specific date
python3 scripts/cost_tracker.py --since 2026-02-01

# JSON output for dashboards/integrations
python3 scripts/cost_tracker.py --days 30 --format json

# Custom agents directory
python3 scripts/cost_tracker.py --agents-dir /path/to/agents

What It Reports

Per-model breakdown:

• Total cost, tokens, and request count
• Input/output/cache token split
• Visual percentage bar

Daily spend: Bar chart of cost per day (text) or structured array (JSON).

Grand totals: Combined cost, tokens, and requests across all models.

How It Works

1. Auto-discovers the OpenClaw agents directory (~/.openclaw/agents)
2. Scans all agent session JSONL files (filtered by mtime for speed)
3. Extracts message.usage and message.model from each entry
4. Aggregates by model and by day
5. Outputs formatted report or JSON

JSON Output Schema

{
  "models": [
    {
      "model": "claude-opus-4-6",
      "totalTokens": 220800000,
      "inputTokens": 3200,
      "outputTokens": 390800,
      "cacheReadTokens": 149400000,
      "cacheWriteTokens": 1200000,
      "totalCost": 528.55,
      "requestCount": 2088
    }
  ],
  "daily": [
    { "date": "2026-02-20", "cost": 37.14, "byModel": { "opus-4-6": 35.0, "sonnet-4": 2.14 } }
  ],
  "grandTotal": { "totalCost": 580.11, "totalTokens": 269800000, "totalRequests": 3122 },
  "meta": { "agentsDir": "...", "filesScanned": 65, "entriesParsed": 3122, "range": "7d" }
}

Integration

Feed JSON output into dashboards, alerting, or budgeting tools. The daily array is ready for charting. Set up a cron to track spend over time:

# Daily cost snapshot to file
0 0 * * * python3 /path/to/cost_tracker.py --days 1 --format json >> ~/cost-log.jsonl

Notes

• Prefer openclaw-cost-diff first for comparison and regression work.
• If totals look surprising, sanity-check against direct raw sums from message.usage.cost.total in local JSONL records.
• Keep cost_tracker.py as a fallback, not the default source of truth.

Requirements

• Python 3.8+
• OpenClaw installed with session data in ~/.openclaw/agents/
• No external dependencies (stdlib only)