Usage Report

Generate cost and token usage reports from OpenClaw session logs. Use when asked about API costs, token usage, billing, spending, how much something cost, or...

Security Scan

The skill is internally consistent: it only reads local OpenClaw session JSONL files and aggregates per-turn cost/token fields using jq and bc; it does not request credentials or perform network activity.

Purpose & Capability

Name/description match the implementation: the script reads OpenClaw session JSONL files and aggregates usage/cost fields. Requested binaries (jq, bc) are reasonable and proportional.

Instruction Scope

Instructions and the script operate on ~/.openclaw/agents/main/sessions by default (or OPENCLAW_SESSIONS_DIR if set) and only parse per-turn usage fields; this is expected. Note: these session files can contain sensitive conversation content—review or run the script locally before exporting results. Also the script uses GNU date -d semantics (may need gdate on macOS).

Install Mechanism

No install spec — instruction-only with an included shell script. Nothing is downloaded or written to arbitrary locations during install.

Credentials

No credentials or secrets requested. One optional env var (OPENCLAW_SESSIONS_DIR) is justified for overriding the sessions directory.

Persistence & Privilege

always is false, the skill does not modify other skills or system configuration, and contains no persistent privileged behavior.

Assessment

This script appears to do what it says: aggregate local OpenClaw session usage and cost fields. Before installing or running it, review the script yourself (it will read your session JSONL files which may contain private conversation text). Ensure jq and bc are installed, and on macOS install coreutils (gdate) or adapt the date commands. Because the source is 'unknown' in the registry, prefer running the script locally with a test/open copy of your session files (or inspect it line-by-line) rather than running it as-is on sensitive data. It does not contact external endpoints or request credentials.

Generate cost and token usage reports from OpenClaw session JSONL logs.

Quick usage

# Full text report (all sessions)
{baseDir}/scripts/usage-report.sh

# JSON output
{baseDir}/scripts/usage-report.sh json

# Filter to today only
{baseDir}/scripts/usage-report.sh text today

# Filter to specific date
{baseDir}/scripts/usage-report.sh text 2026-04-07

# JSON for a specific date
{baseDir}/scripts/usage-report.sh json today

Output fields

• Turns: number of assistant responses (API calls)
• Cost: sum of per-turn costs (input + output + cache read + cache write)
• Output tokens: tokens generated by the model
• Cache read/write: prompt caching token counts

Notes

• Reads from ~/.openclaw/agents/main/sessions/*.jsonl by default
• Override with OPENCLAW_SESSIONS_DIR env var
• Costs are calculated by OpenClaw at request time using provider pricing
• Skips .lock and .reset backup files
• When presenting to user, round total cost to 2 decimal places