OpenClaw Token Usage

Inspect token usage from local OpenClaw transcripts across a specified time range. Use when the user asks how many tokens were consumed in OpenClaw, GitHub C...

Security Scan

The skill's code and instructions consistently implement a local-only OpenClaw transcript token-usage reporter and do not ask for unrelated credentials, network access, or unusual system privileges.

Purpose & Capability

The name/description promise (inspect token usage from local OpenClaw transcripts) matches the bundled Python script which reads ~/.openclaw/agents/*/sessions/, parses transcript JSONL, aggregates token metrics, and emits summaries/CSV/JSON/markdown. There are no unrelated binaries, credentials, or config paths requested.

Instruction Scope

SKILL.md tells the agent to run the included script with time range, tz, and optional scope filters; the script implementation confines itself to reading transcript files under the user's OpenClaw directory and producing local outputs. There are no instructions to read unrelated system files, environment variables, or to send data to external endpoints.

Install Mechanism

No install spec is present (instruction-only with a bundled script). No remote downloads or archive extraction are used. Risk is limited to local execution of the provided Python script.

Credentials

The skill requests no environment variables or credentials. It accesses files only under the user's home OpenClaw paths (sessions and sessions.json), which is proportionate to its stated purpose.

Persistence & Privilege

The skill is not always-enabled and uses normal agent invocation. It does not request persistent system-wide privileges or modify other skills' configuration in the reviewed code.

Assessment

This skill appears to do what it says: it reads OpenClaw transcript files from your home directory and summarizes token usage locally. Before running, confirm the transcript path (~/.openclaw/agents/...) is where you keep the data you want analyzed, and that you are comfortable running a third‑party Python script on those files. The script can write JSON/CSV/markdown to paths you supply—verify output paths to avoid overwriting important files. If you need extra assurance, inspect the remainder of the script (the truncated portion) yourself for any network calls or subprocess invocations; if no network calls are present, running it locally is low-risk. Also ensure your Python environment supports zoneinfo or pass a simple tz like UTC/UTC+8 as advised in SKILL.md.

Use the bundled script to aggregate token usage recorded in local OpenClaw transcript files under ~/.openclaw/agents/*/sessions/.

Quick start

Run:

python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/report_openclaw_token_usage.py \
  --from '2026-03-14' \
  --to '2026-03-16' \
  --tz 'UTC+8'

Default output includes:

• total usage
• daily × agent breakdown
• agent totals
• model totals

Optional additions:

• --top-sessions 10 for Top N session ranking
• --csv-dir ~/.openclaw/workspace/output/token-usage-csv for CSV exports
• --format json for structured output including session totals
• --format markdown for a ready-to-share report

Workflow

1. Confirm the time range.
   • Accept natural ranges from the user, but convert them to explicit timestamps before running the script.
   • Default timezone should match the user's expectation; use UTC+8 unless they ask otherwise.
2. Decide the scope.
   • All agents by default.
   • Narrow with --agents when the user asks for specific agents.
   • Narrow with --providers or --models when the user wants only some models.
3. Decide the output shape.
   • Human summary by default.
   • JSON when another tool/script will consume the result.
   • CSV when the user wants spreadsheet/report-friendly output.
   • Markdown when the user wants a report for docs, messages, or status updates.
   • --top-sessions when the user wants ranking or hotspot analysis.
4. Run the script.
5. Report the result in plain language.
   • Call out timezone assumptions.
   • Mention that counts are transcript-based and deduplicated across .reset / .deleted transcript copies.
   • Clarify that local transcript usage does not cover IDE-side GitHub Copilot usage outside OpenClaw.

Recommended commands

All agents, human-readable summary:

python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/report_openclaw_token_usage.py \
  --from '2026-03-14' \
  --to '2026-03-16' \
  --tz 'UTC+8'

Only GitHub Copilot provider:

python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/report_openclaw_token_usage.py \
  --from '2026-03-14' \
  --to '2026-03-16' \
  --tz 'UTC+8' \
  --providers github-copilot

Specific agents:

python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/report_openclaw_token_usage.py \
  --from '2026-03-14' \
  --to '2026-03-16' \
  --tz 'UTC+8' \
  --agents main,xiaocheng,xiaowen

Top sessions ranking:

python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/report_openclaw_token_usage.py \
  --from '2026-03-14' \
  --to '2026-03-16' \
  --tz 'UTC+8' \
  --top-sessions 10

JSON export:

python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/report_openclaw_token_usage.py \
  --from '2026-03-14' \
  --to '2026-03-16' \
  --tz 'UTC+8' \
  --format json \
  --output ~/.openclaw/workspace/output/token-usage.json

CSV exports:

python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/report_openclaw_token_usage.py \
  --from '2026-03-14' \
  --to '2026-03-16' \
  --tz 'UTC+8' \
  --csv-dir ~/.openclaw/workspace/output/token-usage-csv

Markdown report:

python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/report_openclaw_token_usage.py \
  --from '2026-03-14' \
  --to '2026-03-16' \
  --tz 'UTC+8' \
  --format markdown \
  --output ~/.openclaw/workspace/output/token-usage-report.md

Output notes

The script reports these metrics when present in transcripts:

• input
• output
• cacheRead
• cacheWrite
• totalTokens
• messages

Session notes:

• Session totals are inferred from transcript files and sessions.json indexes when available.
• If a transcript file cannot be mapped back to a session key, the script falls back to file:<filename>.

Markdown report notes:

• Includes scope, summary, by-day table, by-agent table, by-model table, Top sessions, and auto-generated findings.
• Suitable for sharing in docs or pasting into chat after light editing.

Important:

• Some transcript entries may show a model/provider but still have zero token usage recorded.
• This skill measures usage visible in local OpenClaw transcripts. It does not cover IDE-side GitHub Copilot usage outside OpenClaw.
• If the user asks specifically for GitHub Copilot usage inside OpenClaw, prefer --providers github-copilot.