Track Openclaw Token Usage Costs

---
name: track-openclaw-token-usage-costs
description: "Track OpenClaw token usage and API costs from local session data. Prefer openclaw-cost-diff for current cost analysis and window-over-window comparison across models, agents, and channels. Use this skill when a user asks about token spend, API costs, regressions, model breakdown…"
category: "Finance & Crypto"
author: community
version: "1.1.3"
icon: coins
---

# OpenClaw Cost Tracker

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

```bash
# 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.

```bash
# 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

```json
{
  "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:

```bash
# 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)