Session Token Ledger 是一个专为分析本地 OpenClaw 会话令牌使用情况的工具，通过生成并维护一个 SQLite 数据库来记录和汇总所有会话的令牌消耗数据。该工具将每个会话的详细令牌使用情况（包括输入、输出、缓存读取等）结构化存储，并提供丰富的查询视图和自动化报告功能，帮助用户全面了解自己的令牌使用模式。其核心优势在于将原本分散在日志中的信息转化为可快速检索、可视化和分析的持久化数据，特别适合需要进行深度审计或优化令牌效率的场景。
该工具默认仅处理已完成的会话，避免干扰正在进行的实时交互。它通过 Python 脚本自动重建数据库索引，并生成对应日期的 Markdown 格式会话摘要文件，使得用户既能获得机器可读的数据快照，也能阅读人类友好的叙事性总结。同时，它内置了对异常使用模式的检测机制，会在重建过程中标记可疑或低效的日志条目，为后续分析提供线索。整个系统设计强调只读操作，确保原始数据不被意外修改，除非用户主动触发重建流程。
对于希望监控自身 AI 交互成本、识别浪费行为或提升上下文管理效率的用户而言，Session Token Ledger 提供了一个可靠且非侵入式的本地分析解决方案。无论是进行月度财务复盘、排查特定会话的高开销原因，还是追踪长期趋势，该工具都能显著降低手动解析原始日志的工作负担，让数据驱动决策变得更加便捷。
核心功能特点
- 自动生成结构化的 SQLite 数据库，完整记录每个会话的令牌消耗明细
- 提供多种预定义 SQL 视图（如 largest_sessions、bloated_sessions），快速定位高开销或低效会话
- 支持一键生成 Markdown 格式的会话摘要报告，便于阅读与归档
- 内置异常检测机制，自动标记可疑或格式错误的日志条目供人工核查
- 可通过命令行脚本灵活生成全局统计或单个会话的详细分析结果
- 设计为只读模式运行，保护原始数据完整性，仅在用户请求时重建数据库
适用场景
当用户需要对自己的 OpenClaw 会话进行全面的令牌使用审计时，Session Token Ledger 是最直接的选择。例如，在订阅制计费模式下，用户可能希望精确掌握每月令牌总消耗量，区分输入、输出及缓存读取的比例，从而预估实际成本。该工具提供的 overall_summary 视图和 TOTAL_TOKENS.txt 文件能快速给出这些关键指标，避免从零开始计算。
对于发现某次会话异常耗费的场景，比如输出过长或上下文切换频繁导致费用激增，用户可以通过 largest_sessions 或 bloated_sessions 视图快速筛选出问题会话，再结合对应的 Markdown 摘要文件查看详细对话内容，定位具体原因。此外，top_context_hogs 视图有助于识别哪些工具或文档加载造成了不必要的令牌浪费，指导后续优化策略。
在日常使用中，若用户希望持续追踪自己的令牌使用效率趋势，daily_efficiency 视图提供了按日期排序的效率评分，帮助判断是否存在逐渐变差的使用习惯。而对于开发者或高级用户，references/queries.sql 中收录的常用查询语句可作为模板，用于定制更复杂的分析需求，而无需深入理解底层 schema。总之，任何涉及令牌成本意识、使用效率评估或历史数据分析的需求，都可以借助 Session Token Ledger 高效完成。