openclaw-cost-guard – OpenClaw Skill

---

name: openclaw-cost-guard description: Track OpenClaw/Clawdbot token and cost usage from session JSONL logs (prefer real usage.cost when present), generate daily/weekly summaries and top expensive sessions, and run budget checks (exit code on breach). Use to monitor spend, enforce budgets via cron/alerts, and apply a token-saving playbook to reduce output/tool-call cost.

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)

python3 {baseDir}/scripts/extract_cost.py --last-days 7

Today / yesterday

python3 {baseDir}/scripts/extract_cost.py --today
python3 {baseDir}/scripts/extract_cost.py --yesterday

Top expensive sessions

python3 {baseDir}/scripts/extract_cost.py --top-sessions 10

JSON output (for dashboards)

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:

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:

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:

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, bullets > paragraphs
• Ask 1 question max (only if truly blocking)
• Progressive disclosure: offer details only if asked
• Tool calls: batch; avoid repeated status/browser calls
• No log dumps into chat; summarize + point to file path
• Hard limits: max 3 web iterations (search/fetch) per task

Optional phrasing to keep yourself in check:

"Answer in <=6 lines. If more is needed, ask permission."

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

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:

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):

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.