Session Token Ledger
Analyze local OpenClaw session-token usage from a generated ledger stored under this skill.
What lives here
- -
scripts/rebuild_sqlite.py — rebuild the local ledger from OpenClaw session transcripts - INLINECODE1 — generate markdown reports for all sessions or one session
- INLINECODE2 — schema, views, and design notes
- INLINECODE3 — canned SQLite queries for common audits
- INLINECODE4 — optional OpenClaw hook setup for automatic rebuilds
- INLINECODE5 — populated after rebuild with suspicious or bad transcript lines
- INLINECODE6 — populated after rebuild; SQLite ledger
- INLINECODE7 — populated after rebuild; machine-readable session index
- INLINECODE8 — populated after rebuild; quick aggregate summary
- INLINECODE9 — populated after rebuild; one markdown file per completed session
Default workflow
- 1. Rebuild the ledger with
python3 scripts/rebuild_sqlite.py if data looks stale. - Start with
assets/index.json for session list and top-level totals. - If the user wants trends or rankings, inspect
assets/session_tokens.db. - If the user wants a narrative for one session, read the matching
assets/YYYY-MM-DD_N.md file. - If the user wants root-cause analysis, inspect these views first:
-
largest_sessions
-
usage_efficiency
-
bloated_sessions
-
top_context_hogs
-
daily_efficiency
- 6. If something looks wrong, read
references/ANOMALIES.md.
Read these references only when needed
- - Read
references/overview.md when you need schema or view meaning. - Read
references/queries.sql when you need canned SQL. - Read
references/hook-setup.md when you want automatic rebuilds after /new, /reset, /stop, or gateway startup.
Quick path
Generate reports:
CODEBLOCK0
Use read-only SQLite queries when available:
CODEBLOCK1
For one session:
CODEBLOCK2
If sqlite3 CLI is unavailable, use the bundled Python scripts instead.
Reporting rules
- - Lead with the plain-English conclusion.
- Separate total tokens, input tokens, output tokens, and cache read.
- Call out whether waste came from long context, too many topic switches, long outputs, or repeated tool/doc loading.
- For subscription-style billing, emphasize token totals and efficiency, not fake precision on dollar cost.
- When giving recommendations, prefer a short ranked list over a long essay.
Boundaries
- - Treat this ledger as local analysis data, not ground truth for provider billing.
- Do not modify the database unless the user explicitly asks to rebuild or update the ledger.
- Rebuilds skip the currently active live
.jsonl session when a matching .lock file exists, so the ledger defaults to completed sessions only. - Prefer querying the DB over manually re-deriving totals from raw session logs unless the ledger appears stale or broken.
会话令牌分类账
分析本地OpenClaw会话令牌使用情况，数据来源于此技能下生成的分类账。
目录结构
- - scripts/rebuildsqlite.py — 从OpenClaw会话记录重建本地分类账
- scripts/report.py — 为所有会话或单个会话生成Markdown报告
- references/overview.md — 架构、视图和设计说明
- references/queries.sql — 用于常见审计的预置SQLite查询
- references/hook-setup.md — 可选的OpenClaw钩子设置，用于自动重建
- references/ANOMALIES.md — 重建后填充可疑或错误的会话记录行
- assets/sessiontokens.db — 重建后填充；SQLite分类账
- assets/index.json — 重建后填充；机器可读的会话索引
- assets/TOTALTOKENS.txt — 重建后填充；快速汇总统计
- assets/YYYY-MM-DDN.md — 重建后填充；每个已完成会话对应一个Markdown文件
默认工作流程
- 1. 如果数据看起来过时，使用python3 scripts/rebuildsqlite.py重建分类账。
- 从assets/index.json开始查看会话列表和顶层总计。
- 如果用户需要趋势或排名，检查assets/sessiontokens.db。
- 如果用户需要某个会话的详细说明，读取对应的assets/YYYY-MM-DD_N.md文件。
- 如果用户需要根本原因分析，首先检查以下视图：
- largest_sessions
- usage_efficiency
- bloated_sessions
- top
contexthogs
- daily_efficiency
- 6. 如果发现异常，读取references/ANOMALIES.md。
仅在需要时阅读以下参考资料
- - 需要了解架构或视图含义时，阅读references/overview.md。
- 需要预置SQL时，阅读references/queries.sql。
- 希望在/new、/reset、/stop或网关启动后自动重建时，阅读references/hook-setup.md。
快速路径
生成报告：
bash
python3 scripts/report.py
python3 scripts/report.py --session SESSION_ID
python3 scripts/report.py --save
python3 scripts/report.py --session SESSION_ID --save
使用只读SQLite查询（可用时）：
bash
sqlite3 -readonly assets/sessiontokens.db SELECT * FROM overallsummary;
sqlite3 -readonly assets/sessiontokens.db SELECT * FROM largestsessions LIMIT 10;
sqlite3 -readonly assets/sessiontokens.db SELECT * FROM bloatedsessions LIMIT 10;
sqlite3 -readonly assets/sessiontokens.db SELECT * FROM topcontext_hogs LIMIT 10;
sqlite3 -readonly assets/sessiontokens.db SELECT * FROM dailyefficiency ORDER BY date DESC;
针对单个会话：
bash
sqlite3 -readonly assets/sessiontokens.db SELECT * FROM usageefficiency WHERE sessionid=SESSIONID;
如果sqlite3命令行工具不可用，请改用附带的Python脚本。
报告规则
- - 以通俗易懂的结论开头。
- 分别列出总令牌数、输入令牌数、输出令牌数和缓存读取数。
- 明确指出浪费来源：长上下文、过多主题切换、长输出或重复的工具/文档加载。
- 对于订阅制计费，强调令牌总数和效率，而非虚假的美元成本精度。
- 提供建议时，优先使用简短排序列表而非长篇论述。
边界说明
- - 将此分类账视为本地分析数据，而非提供商计费的绝对依据。
- 除非用户明确要求重建或更新分类账，否则不要修改数据库。
- 重建时会跳过当前活动的实时.jsonl会话（当存在匹配的.lock文件时），因此分类账默认仅包含已完成会话。
- 优先查询数据库而非手动从原始会话日志重新推导总数，除非分类账看起来过时或损坏。
