OpenClaw Cost Guard (Budgets + Token-Saving Playbook)

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.

Security Scan

The skill is internally consistent: it only reads local OpenClaw/Clawdbot session JSONL logs, summarizes cost/token usage, optionally estimates costs from PRICE_* env vars, and provides budget exit codes — nothing in the files requests unrelated credentials, network exfiltration, or elevated persistence.

Purpose & Capability

Name/description (cost guard, budgets, token-saving playbook) align with the provided files. The script reads session JSONL files under ~/.openclaw and ~/.clawdbot, extracts usage/cost, aggregates by day/session, and implements budget checks and JSON/text output — exactly what the skill claims.

Instruction Scope

SKILL.md instructs the agent to read the specified session log paths and run the included Python script with various flags; the instructions do not ask the agent to read unrelated paths, harvest environment secrets, or post data to external endpoints. The doc suggests wiring alerts to a channel (e.g., Telegram) but explicitly warns not to embed secrets and leaves implementation to the user.

Install Mechanism

No install spec and only a single Python script are included. There are no downloads or third-party installs, and the script is plain Python (no hidden binaries or archives). This is low-risk and proportionate for the described functionality.

Credentials

No required env vars or credentials are declared. Optional PRICE_* env vars are reasonable and explicitly documented for cost estimation fallback. The script does not request unrelated secrets or cloud credentials.

Persistence & Privilege

The skill is not always-enabled and makes no changes to agent/system configuration. It runs as a user-level script reading files under the user's home directory and returns nonzero exit codes for budget breaches as documented.

Assessment

This skill appears to do what it says: read OpenClaw/Clawdbot session logs and report costs. Before installing/running: confirm the session log paths (~/.openclaw and ~/.clawdbot) are where you expect logs to live, review file permissions (these logs can contain chat content), and run the included script locally to inspect output. If you wire budget alerts to external services (Telegram, email, etc.), avoid embedding API tokens in the script or cron job; store credentials securely and limit recipients. If you want extra assurance, review the included scripts yourself or run them in a restricted user account.

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."