openclaw-cost-guard

# OpenClaw Cost Guard

Use this skill when you need:
- **accurate cost reports** (daily/weekly/lifetime)
- **top expensive sessions**
- **guardrails to reduce token burn** (without changing config unless user asks)

## 1) Data source (important)

Prefer **session JSONL** logs (they contain per-call `usage`, often with **real USD cost**):
- OpenClaw: `~/.openclaw/agents/*/sessions/*.jsonl`
- Legacy/compat: `~/.clawdbot/agents/*/sessions/*.jsonl`

Do **not** estimate from “current context window” style token fields.

## 2) Quick commands

### Daily costs (last 7 days)
```bash
python3 {baseDir}/scripts/extract_cost.py --last-days 7
```

### Today / yesterday
```bash
python3 {baseDir}/scripts/extract_cost.py --today
python3 {baseDir}/scripts/extract_cost.py --yesterday
```

### Top expensive sessions
```bash
python3 {baseDir}/scripts/extract_cost.py --top-sessions 10
```

### JSON output (for dashboards)
```bash
python3 {baseDir}/scripts/extract_cost.py --last-days 30 --json
```

## 3) If cost is missing (fallback estimate)

Some providers may omit `usage.cost`. You can provide per-1M-token prices:

```bash
export PRICE_INPUT=1.75
export PRICE_OUTPUT=14
export PRICE_CACHE_READ=0.175
export PRICE_CACHE_WRITE=0
python3 {baseDir}/scripts/extract_cost.py --last-days 7
```

## 4) Budget alerts

The extractor can run as a **budget check**:

```bash
python3 {baseDir}/scripts/extract_cost.py --today --budget-usd 5
```

- If budget is exceeded, it prints an **ALERT** and exits with code **2** (default).
- For non-failing checks:

```bash
python3 {baseDir}/scripts/extract_cost.py --today --budget-usd 5 --budget-mode warn
```

### Wiring it to a cron alert (recommended)
Run it daily (or hourly) and if exit code is 2, send yourself a Telegram message.
(Implementation depends on your OpenClaw channel setup; do not embed secrets in scripts.)

## 5) Token-saving playbook (teach the AI)

When the user says “use as few tokens as possible”, apply:
- **Default response budget:** 1–6 lines...

# openclaw-cost-guard

Track **real OpenClaw/Clawdbot usage + cost** from session JSONL logs, generate summaries, and support **budget alerts**.

## What it does

- Reads OpenClaw logs: `~/.openclaw/agents/*/sessions/*.jsonl`
- Also reads legacy logs: `~/.clawdbot/agents/*/sessions/*.jsonl`
- Extracts per-call usage from `message.usage` (tokens + cost breakdown when available)
- Summarizes cost by day and can list **top expensive sessions**
- Can act as a **budget check** (exit code 2 on breach) so it can be wired into cron/alerts

## Quick start

```bash
python3 scripts/extract_cost.py --today
python3 scripts/extract_cost.py --last-days 7
python3 scripts/extract_cost.py --today --top-sessions 10
python3 scripts/extract_cost.py --today --top-sessions 10 --json
```

## Budget alerts

Exit code behavior:
- `0` = OK
- `2` = budget exceeded

Examples:

```bash
python3 scripts/extract_cost.py --today --budget-usd 5

# non-failing (always exit 0)
python3 scripts/extract_cost.py --today --budget-usd 5 --budget-mode warn
```

## Fallback cost estimation (optional)

If a provider doesn’t write `usage.cost`, you can estimate using env vars (per **1M tokens**):

```bash
export PRICE_INPUT=1.75
export PRICE_OUTPUT=14
export PRICE_CACHE_READ=0.175
export PRICE_CACHE_WRITE=0

python3 scripts/extract_cost.py --last-days 7
```

## Token-saving playbook

See `SKILL.md` (kept short on purpose). It includes a playbook the agent can follow to keep output/tool usage minimal.