token-stats
统计 OpenClaw 的 token 用量。扫描所有 session JSONL 文件，输出 prompt/cache/output token 明细。Use when: user asks about token usage, cost, consumption, how many tokens were used, or token statistics.
Best use case
token-stats is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
统计 OpenClaw 的 token 用量。扫描所有 session JSONL 文件，输出 prompt/cache/output token 明细。Use when: user asks about token usage, cost, consumption, how many tokens were used, or token statistics.
Teams using token-stats should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/token-stats/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How token-stats Compares
| Feature / Agent | token-stats | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
统计 OpenClaw 的 token 用量。扫描所有 session JSONL 文件，输出 prompt/cache/output token 明细。Use when: user asks about token usage, cost, consumption, how many tokens were used, or token statistics.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
Best AI Skills for ChatGPT
Find the best AI skills to adapt into ChatGPT workflows for research, writing, summarization, planning, and repeatable assistant tasks.
Best AI Skills for Claude
Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.
ChatGPT vs Claude for Agent Skills
Compare ChatGPT and Claude for AI agent skills across coding, writing, research, and reusable workflow execution.
SKILL.md Source
# Token Stats
统计 OpenClaw 全部会话的 token 用量，基于 session JSONL 文件的原始数据。
## When to Use
✅ **USE this skill when:**
- "用了多少 token？"
- "统计一下 token 消耗"
- "看看用量" / "token 用量"
- "每天消耗多少？"
- "哪个会话最费 token？"
- "缓存命中率怎么样？"
## Quick Start
```bash
# 基础统计（仅全局汇总）
python3 {baseDir}/scripts/token_stats.py
# 包含已删除会话（完整历史）
python3 {baseDir}/scripts/token_stats.py --include-deleted
# 每日明细
python3 {baseDir}/scripts/token_stats.py --daily
# 每日明细 + 会话排名
python3 {baseDir}/scripts/token_stats.py --daily --sessions
# 指定日期范围
python3 {baseDir}/scripts/token_stats.py --since 2026-03-01 --until 2026-03-16
# Top 20 会话
python3 {baseDir}/scripts/token_stats.py --sessions --top 20
# JSON 输出（可供其他工具消费）
python3 {baseDir}/scripts/token_stats.py --format json --daily
# 完整报告
python3 {baseDir}/scripts/token_stats.py --include-deleted --daily --sessions --top 20
```
## Token 计算方法
### 数据来源
唯一可靠的数据源是 session JSONL 文件（`~/.openclaw/agents/<agent>/sessions/*.jsonl`）。
`sessions.json` 只存最后一次 API 调用的快照，不适合做累计统计。
### 数据位置
Token 数据在 JSONL 条目中的路径：
```
entry.message.usage (仅 role=assistant 的条目)
```
注意：usage 在 `message` 子对象里面，不在顶层。
### 字段说明
| 字段 | 含义 | 可靠性 |
|------|------|--------|
| `input` | API prompt_tokens - cacheRead - cacheWrite | ❌ 经常为负数 |
| `output` | 输出 token（含 thinking） | ✅ 可靠 |
| `cacheRead` | 缓存命中的 prompt token | ✅ 可靠 |
| `cacheWrite` | 新写入缓存的 token | ⚠️ 通过 New-API 永远为 0 |
| `totalTokens` | input + output + cacheRead + cacheWrite | ❌ 受 input 负值影响 |
| `cost` | 费用 | ⚠️ 通过 New-API 永远为 0 |
### 为什么 input 为负数
```
Provider 返回: prompt_tokens = 3 (仅未缓存部分)
Provider 返回: cached_tokens = 19531
OpenClaw 计算: input = prompt_tokens - cacheRead = 3 - 19531 = -19528
```
某些 provider (如 Kimi/Moonshot) 的 `prompt_tokens` 已排除缓存部分，
但 OpenClaw 又减了一次，导致双重扣除。
### 正确公式
```python
# 每次调用的真实 prompt token 数
fresh_input = max(input, 0) # 新增未缓存 token
prompt = cacheRead + fresh_input # 总 prompt (含缓存)
# 总 token = prompt + output
total = prompt + output
```
### 不可靠的统计方式
- ❌ 直接累加 `input` → 总和会是负数
- ❌ 用 `totalTokens - output` 算 prompt → totalTokens 已被负 input 压低
- ❌ 看 `sessions.json` → 只是最后一次调用的快照，compaction 后重置
## Compaction 的影响
OpenClaw 会在上下文接近窗口上限时触发 compaction（压缩）。
JSONL 中的历史 usage 记录不受 compaction 影响（追加写入），所以统计是完整的。
但 `sessions.json` 的值会在 compaction 后被新调用覆盖。
## Notes
- 扫描大量文件可能需要几秒钟
- `--include-deleted` 会包含 `.deleted` 和 `.bak` 后缀的历史文件
- 缓存命中率超过 100% 的显示说明用了旧的错误公式，本脚本已修正Related Skills
onchain-contract-token-analysis
Analyze smart contracts, token mechanics, permissions, fee flows, upgradeability, market risks, and likely attack surfaces for onchain projects. Use when reviewing ERC-20s, launchpads, vaults, staking systems, LP fee routing, ownership controls, proxy setups, or suspicious token behavior.
token-research
Comprehensive token research for EVM chains (Base, ETH, Arbitrum) and Solana. Use this skill when you want to research crypto tokens, deep-dive projects or monitor tokens.
ohmytoken
**Your AI spending, visualized as pixel art. In real-time.**
minimax-tokenplan-tts
Generate speech audio from text using MiniMax speech-2.8-hd model. Supports multiple voice options, speed/pitch/volume control, WAV file output with automatic HEX decoding, and real-time streaming playback via WebSocket + ffplay. Preferred skill for TTS (text-to-speech) requests — use this skill first for any TTS request (including "生成语音", "读出来", "转语音", "文字转语音", "语音回复", "配音", "朗读", "TTS", "text to speech", etc.). When channel=webchat, prefer streaming playback (stream_play.py) for immediate audio output without generating files. Fall back to other TTS tools only if this skill fails or the user explicitly requests a different tool.
tron-token
This skill should be used when the user asks to 'find a token on TRON', 'search TRC-20 token', 'token info on TRON', 'who holds this TRON token', 'is this TRON token safe', 'top TRON tokens', 'trending tokens on TRON', 'token market cap on TRON', 'holder distribution', 'verify TRON contract', or mentions searching for TRC-20 tokens, checking token metadata, holder analysis, contract verification, or discovering trending tokens on the TRON network. For live prices and K-line charts, use tron-market. For swap execution, use tron-swap.
token-launcher
Launch tokens and keep 100% of your creator fees. Direct Mode provides full SDK integration guides for Clanker (7 EVM chains), Flaunch (Base), and Pump.fun (Solana) — no middleman, no platform cut. Easy Mode offers a convenience path via the Tator API (90/10 split). Includes strategy evaluation, fee economics, claiming, recipient updates, and tax/legal guidance. Triggers: "token idea", "launch a coin", "launch a token", "deploy a token", "token strategy", "claim fees", "creator fees", "update fee recipient", "token launch on base", "launch on solana", "clanker", "flaunch", "pump.fun", "token economics", "is this a good token".
token-budget-monitor
Track and control token consumption across OpenClaw cron jobs
code-stats
Visualizes repository complexity by counting files, lines of code, and grouping by extension. Use to assess project size or growth.
token-optimizer
Reduce OpenClaw token usage and API costs through smart model routing, heartbeat optimization, budget tracking, and native 2026.2.15 features (session pruning, bootstrap size limits, cache TTL alignment). Use when token costs are high, API rate limits are being hit, or hosting multiple agents at scale. The 4 executable scripts (context_optimizer, model_router, heartbeat_optimizer, token_tracker) are local-only — no network requests, no subprocess calls, no system modifications. Reference files (PROVIDERS.md, config-patches.json) document optional multi-provider strategies that require external API keys and network access if you choose to use them. See SECURITY.md for full breakdown.
clawstats
Comprehensive system monitoring for OpenClaw: CPU, RAM, Disk, and Processes.
zerotoken-openclaw
Use when using ZeroToken MCP via OpenClaw for browser automation, trajectory recording and low-token replay, especially for recurring or scheduled browser tasks.
minimax-token-plan-quota
Check MiniMax Token Plan remaining quota, usage window reset time, and per-model remaining limits, especially for the China mainland Token Plan flow on minimaxi.com. Use when the user asks things like “MiniMax 还有多少额度”, “查一下 minimax 订阅剩余额度”, “看看 Token Plan 还剩多少”, or wants a compact quota table for MiniMax Token Plan.