OpenClaw Token Usage
Use the bundled script to aggregate token usage recorded in local OpenClaw transcript files under ~/.openclaw/agents/*/sessions/.
Quick start
Run:
CODEBLOCK0
Default output includes:
- - total usage
- daily × agent breakdown
- agent totals
- model totals
Optional additions:
- -
--top-sessions 10 for Top N session ranking - INLINECODE2 for CSV exports
- INLINECODE3 for structured output including session totals
- INLINECODE4 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.
- 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:
CODEBLOCK1
Only GitHub Copilot provider:
CODEBLOCK2
Specific agents:
CODEBLOCK3
Top sessions ranking:
CODEBLOCK4
JSON export:
CODEBLOCK5
CSV exports:
CODEBLOCK6
Markdown report:
CODEBLOCK7
Output notes
The script reports these metrics when present in transcripts:
- - INLINECODE12
- INLINECODE13
- INLINECODE14
- INLINECODE15
- INLINECODE16
- INLINECODE17
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.
OpenClaw Token 用量
使用内置脚本汇总本地 OpenClaw 转录文件中记录的 Token 用量，这些文件位于 ~/.openclaw/agents/*/sessions/ 目录下。
快速开始
运行：
bash
python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/reportopenclawtoken_usage.py \
--from 2026-03-14 \
--to 2026-03-16 \
--tz UTC+8
默认输出包括：
可选附加项：
- - --top-sessions 10 用于 Top N 会话排名
- --csv-dir ~/.openclaw/workspace/output/token-usage-csv 用于 CSV 导出
- --format json 用于包含会话总计的结构化输出
- --format markdown 用于可直接分享的报告
工作流程
- 1. 确认时间范围。
- 接受用户的自然语言范围，但在运行脚本前将其转换为明确的时间戳。
- 默认时区应与用户预期一致；除非用户另有要求，否则使用 UTC+8。
- 2. 确定范围。
- 默认包含所有智能体。
- 当用户指定特定智能体时，使用 --agents 缩小范围。
- 当用户只想查看某些模型时，使用 --providers 或 --models 缩小范围。
- 3. 确定输出格式。
- 默认输出人类可读的摘要。
- 当其他工具/脚本需要消费结果时，使用 JSON 格式。
- 当用户需要电子表格/报告友好型输出时，使用 CSV 格式。
- 当用户需要用于文档、消息或状态更新的报告时，使用 Markdown 格式。
- 当用户需要排名或热点分析时，使用 --top-sessions。
- 4. 运行脚本。
- 用通俗语言报告结果。
- 说明时区假设。
- 提及计数基于转录文件，并已对 .reset / .deleted 转录副本进行去重。
- 说明本地转录用量不包括 OpenClaw 之外的 IDE 端 GitHub Copilot 用量。
推荐命令
所有智能体，人类可读摘要：
bash
python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/reportopenclawtoken_usage.py \
--from 2026-03-14 \
--to 2026-03-16 \
--tz UTC+8
仅 GitHub Copilot 提供商：
bash
python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/reportopenclawtoken_usage.py \
--from 2026-03-14 \
--to 2026-03-16 \
--tz UTC+8 \
--providers github-copilot
特定智能体：
bash
python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/reportopenclawtoken_usage.py \
--from 2026-03-14 \
--to 2026-03-16 \
--tz UTC+8 \
--agents main,xiaocheng,xiaowen
Top 会话排名：
bash
python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/reportopenclawtoken_usage.py \
--from 2026-03-14 \
--to 2026-03-16 \
--tz UTC+8 \
--top-sessions 10
JSON 导出：
bash
python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/reportopenclawtoken_usage.py \
--from 2026-03-14 \
--to 2026-03-16 \
--tz UTC+8 \
--format json \
--output ~/.openclaw/workspace/output/token-usage.json
CSV 导出：
bash
python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/reportopenclawtoken_usage.py \
--from 2026-03-14 \
--to 2026-03-16 \
--tz UTC+8 \
--csv-dir ~/.openclaw/workspace/output/token-usage-csv
Markdown 报告：
bash
python3 ~/.openclaw/workspace/skills/openclaw-token-usage/scripts/reportopenclawtoken_usage.py \
--from 2026-03-14 \
--to 2026-03-16 \
--tz UTC+8 \
--format markdown \
--output ~/.openclaw/workspace/output/token-usage-report.md
输出说明
脚本报告以下指标（当转录文件中存在时）：
- - input
- output
- cacheRead
- cacheWrite
- totalTokens
- messages
会话说明：
- - 会话总计根据转录文件和 sessions.json 索引（如果可用）推断得出。
- 如果无法将转录文件映射回会话键，脚本将回退为 file:<文件名>。
Markdown 报告说明：
- - 包括范围、摘要、按日表格、按智能体表格、按模型表格、Top 会话以及自动生成的发现。
- 适合在文档中分享或稍作编辑后粘贴到聊天中。
重要提示：
- - 某些转录条目可能显示模型/提供商，但记录的 Token 用量仍为零。
- 此技能衡量的是本地 OpenClaw 转录中可见的用量。它不包括 OpenClaw 之外的 IDE 端 GitHub Copilot 用量。
- 如果用户专门询问 OpenClaw 内部的 GitHub Copilot 用量，建议使用 --providers github-copilot。
