Token Stats Reporter

Generate and append accurate token/cost statistics in replies with a reproducible local algorithm (snapshot+incremental log aggregation + dedupe). Use when u...

Security Scan

The skill's requests and behavior align with its stated purpose: it reads local session logs and maintains local state to compute token/cost stats; nothing in the code exfiltrates data or requests unrelated credentials.

Purpose & Capability

The skill's description (generate token/cost stats) matches its actions: it reads local session jsonl files and aggregates usage, and writes local state/counter files. Minor mismatch: SKILL.md tells the agent to run a hardcoded path (/home/admin/.openclaw/...), while the bundled script contains portable path-detection logic; this could cause the documented invocation to fail on systems where that exact path doesn't exist.

Instruction Scope

Instructions are narrow and specific: run the bundled Python script immediately before sending replies, append one exact token line, and fail-closed if the script fails. The script only reads local session logs (~/.openclaw/agents/main/sessions) and updates workspace/memory state. This is within scope for token reporting, but noteworthy because the skill will block sending messages if the script fails (operational impact) and it reads full conversation logs (sensitive data) — however it does not network-out or request extra credentials.

Install Mechanism

No install spec; skill is instruction-only with a bundled Python script. There are no network downloads or external package installs, and the script is present in the skill bundle. Low install risk.

Credentials

The skill requests no environment variables or credentials, which is appropriate. It does require read access to session log files (conversation transcripts) and write access to its own workspace/memory files — this access is necessary for its purpose but involves exposure of conversation contents, so consider privacy implications.

Persistence & Privilege

The skill does not request always:true and does not modify other skills. It writes state and counter files under its own workspace/memory directory (token-agg-state.json, token-counter.json), which is expected for aggregation state.

Assessment

This skill appears to do what it claims: it reads local conversation logs to compute token and cost stats and writes local state files. Before installing, verify (1) you are comfortable that the script will read your ~/.openclaw/agents/main/sessions logs (these contain user/assistant messages), (2) the hardcoded run path in SKILL.md matches your install location or update the invocation to the actual script path, (3) you are okay with the skill's fail-closed behavior (it can block sending messages if the script fails), and (4) you review the bundled script (it is local and contains no network calls). Consider testing in a non-production instance first and backing up session/state files.

Use this skill to produce a single, consistent token line at the end of every user-facing message.

Workflow

1. Run the bundled reporter script:
   • python3 /home/admin/.openclaw/workspace/skills/token-stats-reporter/scripts/token-show.py
2. Append exactly one returned line to the end of the reply.
3. Do not modify numbers manually.

Output format (exact)

📊 Token: <in> in / <out> out | cacheRead: <cache> | 本次总消耗: <single_total> | 本次计费token: <single_billable> | 本月: <count> 次 | 月累计总消耗: <monthly_total> | 本次费用: <single_cost> | 本月费用: <monthly_cost> | 模型: <model>

Algorithm guarantees (must preserve)

• Data source: ~/.openclaw/agents/main/sessions/*.jsonl*
• Valid rows only:
  • type=message
  • message.role=assistant
  • has text content
  • has usage
• Deduplication: by message.id (fallback composite key only if id missing)
• Monthly bucket: by message timestamp in local timezone (Asia/Shanghai)
• Aggregation strategy: snapshot + incremental replay
  • Persisted state file: memory/token-agg-state.json
  • Per-file offset tracking for incremental scans
  • Truncation/reset-safe fallback (offset reset when file shrinks)
• Cost source: usage.cost.total
• Model source: latest valid message message.model

Reliability rules

• Run token collection immediately before final delivery.
• In long, multi-step tasks, refresh once again right before sending.
• Keep exactly one token line per outgoing message.
• If script fails, fallback to session_status and explicitly label as fallback.

v1.2.0 Send Gate (fail-closed)

Use this mandatory gate to avoid hand-written token lines:

1. Build token line first (must run script):
   • python3 /home/admin/.openclaw/workspace/skills/token-stats-reporter/scripts/token-show.py
2. Validate token line before sending:
   • must contain 📊 Token:
   • must contain 模型:
   • model must NOT be delivery-mirror
3. Append token line to message body, then send.
4. If step 1 or 2 fails: block sending (do not handwrite numbers).
5. Allowed fallback text only when blocked:
   • 📊 Token: 统计暂不可用（脚本失败，已拦截手填）

Portability rule (for other assistants)

When installing on another assistant instance, use this skill's bundled script path as the source of truth. Do not depend on external ad-hoc scripts with unknown local modifications.