1. 项目概述与核心价值如果你和我一样在日常工作中重度依赖像 OpenClaw 这样的 AI 代理框架来处理各种自动化任务那么一个绕不开的“甜蜜的烦恼”就是成本监控。我们享受着 AI 带来的效率提升但每次看到账单时心里总会咯噔一下这个月又花了多少是哪几个模型消耗了大部分 Token缓存机制到底帮我省了多少钱这些问题如果每次都去翻原始日志或者等月底的账单不仅效率低下而且很难形成直观的洞察。openclaw-token-stats这个项目就是为解决这个痛点而生的。它不是一个庞大的监控平台而是一套轻量、离线、脚本化的工具集专门用来解析你本地 OpenClaw 生成的会话日志*.jsonl文件并从中提炼出你最关心的 Token 使用量和成本数据。它的核心价值在于“快速洞察”和“离线安全”。你不需要部署任何服务不需要将你的使用数据上传到任何第三方就在你自己的机器上运行一个脚本就能立刻得到一份清晰的用量报告。这个工具特别适合几类人一是日常使用 OpenClaw 进行开发或自动化任务的工程师需要定期核算成本二是团队负责人或项目管理者需要监控多个代理的资源消耗情况及时发现异常比如某个模型突然“暴走”三是任何希望对自己的 AI 使用情况有更精细掌控但又不想引入复杂基础设施的用户。它填补了原始日志的杂乱无章与完整商业监控方案之间的空白提供了一个“刚刚好”的解决方案。2. 核心设计思路与哲学在深入代码之前理解这个项目的设计哲学至关重要这决定了它的使用边界和能带给你的价值上限。它的设计可以用三个关键词概括保守、稳定、实用。保守体现在数据来源上。它严格遵循“所见即所得”的原则。脚本只读取日志中已经存在的字段如input,output,cacheRead,cacheWrite,totalTokens以及当且仅当提供商如 OpenAI, Anthropic 等在响应中返回了成本字段如usage.cost.input时才会进行成本汇总。它不会根据公开的价格表去估算缺失的成本也不会去猜测或补全日志中没有的信息。这样做的好处是绝对可靠报告的数字就是你日志中记录的数字避免了因价格波动或估算误差带来的误导。缺点也很明显如果某个运行环境没有返回成本数据那么报告中的成本部分就会是零或缺失。这要求使用者对自己的 OpenClaw 配置和模型提供商的回传数据有清晰的了解。稳定体现在分析视角上。项目文档中明确提到了“Accounting philosophy”即优先呈现整体账本total usage然后是顶级模型消耗接着是缓存情况最后才是成本。这是一个非常务实的决策。在复杂的多轮对话和后台任务交织的日志中试图完美重构每一段对话的上下文和角色归属比如分清哪句话是用户提问哪句是系统指令哪句是后台工具调用是极其困难且容易出错的。与其在一个不完美的细节重构上花费精力不如先抓住最稳定、最不会出错的宏观信号总量。先知道“总共花了多少”再通过按模型、按会话文件钻取去定位“钱花在哪了”。这种从整体到局部、从稳定到波动的分析路径在实践中被证明是最有效的排错和洞察方法。实用则贯穿了工具的每一个功能。它没有华丽的图表界面输出就是结构化的文本Markdown报告或机器可读的 JSON。它的目标不是做一个“看板”而是提供“快答案”。当你感觉今天 API 调用有点慢或者收到成本预警时你能在 30 秒内运行一个命令得到“过去 24 小时gpt-4 消耗了 80% 的 Token其中一次session-2024-05-27-14-30.jsonl的会话异常高”这样的结论。这种速度是任何需要登录、加载的 Web 仪表盘无法比拟的。它就是为了命令行效率而生。3. 环境准备与项目部署开始使用openclaw-token-stats前你需要确保满足几个基本条件。整个过程非常简单几乎不需要额外的依赖安装。3.1 前置条件检查首先你的工作环境中必须已经安装并运行过 OpenClaw因为工具依赖其产生的日志文件。请通过以下命令确认# 检查 OpenClaw 的基本命令行工具是否可用假设是 claw 命令 claw --version # 或者检查默认的日志目录是否存在 ls -la ~/.openclaw/如果上述目录不存在或命令未找到你需要先完成 OpenClaw 的安装和基础配置。这通常包括设置 API 密钥如OPENAI_API_KEY并运行至少一次代理交互以生成初始的会话日志。其次你需要 Python 3.7 或更高版本。工具脚本只使用了 Python 标准库中的json,argparse,datetime,pathlib,collections等模块无需安装任何第三方包这极大地减少了环境冲突的可能性。python3 --version3.2 获取项目代码由于项目托管在 GitHub你有两种主要方式获取代码方式一直接克隆仓库推荐这是最完整的方式可以方便地更新和查看示例。git clone https://github.com/TideKnight/openclaw-token-stats.git cd openclaw-token-stats方式二下载核心脚本如果你只需要核心功能可以仅下载scripts/目录下的两个 Python 文件。mkdir -p ~/tools/openclaw-stats cd ~/tools/openclaw-stats curl -O https://raw.githubusercontent.com/TideKnight/openclaw-token-stats/main/scripts/openclaw_token_stats.py curl -O https://raw.githubusercontent.com/TideKnight/openclaw-token-stats/main/scripts/openclaw_token_report.py我强烈推荐第一种方式因为references/目录下的字段说明和 Cron 任务提示模板非常有用examples/里的报告样本也能让你对输出格式有直观预期。3.3 理解日志结构与路径工具的核心是读取日志因此你必须知道日志在哪。OpenClaw 默认的日志存储路径模式是~/.openclaw/agents/agent_name/sessions/。在这个目录下你会找到一系列以.jsonl结尾的文件可能还有.jsonl.gz压缩格式每个文件对应一次代理会话。一个典型的日志行JSON Lines 格式看起来像这样{timestamp: 2024-05-27T10:15:30Z, model: gpt-4, provider: openai, usage: {input: 150, output: 320, cacheRead: 100, cacheWrite: 50, totalTokens: 470, cost: {input: 0.00045, output: 0.00096, total: 0.00141}}}关键字段解读更详细的在references/fields.mdmodel: 使用的模型标识符。provider: 模型提供商。usage: 用量对象。input/output: 本次调用的输入/输出 Token 数。cacheRead/cacheWrite: 从缓存读取/写入缓存的 Token 数。这是评估缓存效益的关键。totalTokens: 总计 Token通常是 inputoutput可能已扣除 cacheRead。cost:可选字段。如果提供商返回则包含按维度细分的成本。注意不是所有运行环境或模型调用都会返回cost字段。这取决于 OpenClaw 的运行时配置和上游 API 的响应。如果你的报告里成本始终为 0首先需要检查原始日志中是否有usage.cost数据。4. 核心脚本使用详解与实操openclaw-token-stats提供了两个核心脚本用于聚合统计的openclaw_token_stats.py和用于生成周期报告的openclaw_token_report.py。我们分别深入探讨。4.1 基础聚合统计openclaw_token_stats.py这个脚本是你的“瑞士军刀”用于即席查询和钻取分析。它的参数设计非常直观。基本调用查看最近一天“main”代理的总消耗python3 scripts/openclaw_token_stats.py --agent main --days 1执行后你会看到一个简洁的表格输出汇总了最近一天所有会话的总 Token 和总成本如果成本数据存在。按维度深入分析--by参数是核心它让你可以按不同维度切分数据--by model:最常用的维度。快速找出哪个模型是“耗能大户”。python3 scripts/openclaw_token_stats.py --agent main --days 7 --by model--by provider: 如果你使用了多个提供商如 OpenAI、Anthropic、本地模型这个视图可以帮你看清成本分布。--by session:调试神器。当发现某天总消耗异常高时用这个命令可以列出所有会话文件及其消耗迅速定位到那个“问题会话”。python3 scripts/openclaw_token_stats.py --agent main --days 2 --by session输出格式选择默认是易读的纯文本表格。但如果你想把数据导入到其他工具如 Grafana、自定义脚本进行进一步处理或绘图可以使用--json参数输出 JSON 格式。python3 scripts/openclaw_token_stats.py --agent main --days 30 --by model --json monthly_usage.json生成的 JSON 结构清晰包含了按维度分组的详细数据和汇总总计非常适合程序化处理。实操心得关于时间范围--days参数是基于当前时间向前推算的。例如--days 1是统计从昨天此时到今天此时的数据。需要注意的是它依据的是日志文件的时间戳而不是文件名。如果你的日志轮转或归档策略比较特殊可能需要先用--by session检查一下脚本实际读取了哪些文件确保时间范围符合你的预期。4.2 生成周期报告openclaw_token_report.py这个脚本用于生成格式优美的 Markdown 周期报告适合每日站会、每周复盘或月度成本审计。生成报告命令非常简单通过--period指定周期# 生成日报 python3 scripts/openclaw_token_report.py --agent main --period daily # 生成周报 python3 scripts/openclaw_token_report.py --agent main --period weekly # 生成月报 python3 scripts/openclaw_token_report.py --agent main --period monthly报告默认会输出到终端。你可以轻松地重定向到文件甚至直接作为邮件内容发送。python3 scripts/openclaw_token_report.py --agent main --period weekly weekly_report_$(date %Y-%m-%d).md报告内容解析一份典型的日报会包含以下部分详见examples/概览该周期内的总会话数、总 Token 消耗、总成本。模型消耗排名列出消耗 Token 最多的前 N 个模型并显示其占比。这是发现趋势的核心。提供商消耗分布从供应商角度查看成本分布。缓存效率分析展示cacheRead占总input的比例。这个指标至关重要它直接衡量了你的缓存配置节省了多少 Token 和成本。比例越高说明缓存命中率越好。高消耗会话列出该周期内 Token 消耗最高的几个会话文件方便进一步追溯。总结与观察基于数据给出一些文本总结比如“本周主要消耗集中在 GPT-4”“缓存节省了约 30% 的输入 Token”。集成到工作流报告脚本是自动化工作流的理想组件。你可以结合 CronLinux/macOS或 Task SchedulerWindows来定期运行。项目在references/cron-prompt-*.txt中甚至贴心地提供了设置 Cron 任务的提示词模板。例如设置一个每天上午 9 点生成昨日日报的 Cron 任务# 编辑当前用户的 crontab crontab -e # 添加一行假设脚本在 /home/user/tools/openclaw-token-stats/ 下 0 9 * * * cd /home/user/tools/openclaw-token-stats /usr/bin/python3 scripts/openclaw_token_report.py --agent main --period daily /home/user/logs/openclaw_daily_$(date \%Y\%m\%d).log 215. 作为 OpenClaw Skill 集成使用除了作为独立脚本这个项目还可以无缝集成到 OpenClaw 的 Skill 系统中让你的另一个“管理型”代理具备查询用量和生成报告的能力。这为内部运维和自动化提供了更优雅的方式。Skill 部署方法在 OpenClaw 的技能目录通常由配置决定例如~/.openclaw/skills/或项目内的skills/文件夹下创建一个新目录比如token-stats/。将整个openclaw-token-stats项目中的SKILL.md,scripts/,references/三个关键部分复制到这个新目录中。README.md和LICENSE不是 Skill 运行所必需的。确保你的 OpenClaw 代理配置加载了这个技能目录。Skill 交互示例部署成功后你的代理就拥有了新的能力。你可以通过自然语言指令来驱动它“检查一下主代理过去三天的 Token 使用情况。”“生成一份上周的用量周报并总结一下趋势。”“找出昨天消耗 Token 最多的那个会话文件。”代理会根据SKILL.md中的定义在后台调用相应的 Python 脚本并将结果以友好的格式返回给你。这种方式特别适合非技术背景的团队成员查询成本或者构建更复杂的自动化工作流例如当每日成本超过阈值时自动生成报告并发送警报。注意事项以 Skill 方式运行时脚本的执行环境Python 路径、当前工作目录是由 OpenClaw 运行时决定的。你需要确保该环境同样可以访问到存放日志的~/.openclaw目录并且具有读取权限。有时可能需要配置绝对路径。6. 常见问题排查与实战技巧在实际使用中你可能会遇到一些典型问题。这里我结合自己的踩坑经验总结了一份排查清单。问题一运行脚本后没有输出或者输出“No session files found”。检查点 1代理名称是否正确--agent参数必须与你的 OpenClaw 配置中定义的代理名完全一致。默认通常是main但如果你创建了其他代理如coder,researcher就需要指定对应的名字。可以列出~/.openclaw/agents/下的目录来确认。检查点 2日志路径是否存在直接去文件系统查看~/.openclaw/agents/your_agent/sessions/目录下是否有.jsonl文件。如果没有说明你的 OpenClaw 可能没有开启会话日志记录或者日志被保存到了其他位置。你需要检查 OpenClaw 的配置文件。检查点 3时间范围是否合适如果指定了--days 1但最近 24 小时内确实没有产生任何新会话自然没有输出。可以尝试增大--days参数或者使用--by session查看所有能找到的文件。问题二成本cost字段全部显示为 0。原因分析这是最常见的问题根本原因是原始日志中没有usage.cost数据。排查步骤打开一个最近的.jsonl日志文件查看其中一行完整的 JSON 记录。搜索cost字段。如果确实没有说明调用模型时使用的运行时runtime或适配器adapter没有请求或未能接收到成本信息。你需要查阅你所用的 OpenClaw 模型提供商配置确认是否启用了成本计算和回传功能。例如一些社区维护的提供商适配器可能尚未实现该功能。一个快速的验证方法是在 OpenClaw 的交互中直接询问代理“刚才那次调用的成本是多少”有些配置下代理会从上下文中提取并回答。问题三缓存节省的计算看起来不对或者 cacheRead 数值异常。理解缓存机制cacheRead表示本次请求的输入 Token 中有多少是从缓存中直接读取的因此不需要向模型提供商付费。cacheWrite是本次请求的结果被写入缓存的 Token 数可能用于未来读取。一个健康的缓存系统cacheRead应该随着时间推移在总input中占可观的比例。排查建议单独分析一个长时间运行的、重复任务较多的代理日志。使用--by model并观察特定模型的cacheRead/input比率。如果比率始终很低比如5%可能需要检查你的 OpenClaw 缓存配置如缓存类型、大小、过期策略是否合理或者你的任务模式本身缓存命中率就低。问题四生成的报告文件太大或者 Cron 任务执行失败。日志文件管理OpenClaw 默认可能会一直累积日志文件。长时间运行后sessions/目录下可能有成千上万个文件。虽然脚本处理效率不错但遍历大量文件确实会变慢。建议建立日志归档机制例如每周将旧的日志文件压缩后移动到其他目录。可以在 Cron 任务中先运行日志清理脚本再运行报告生成脚本。Cron 环境问题Cron 任务执行时的环境变量如PATH,HOME与你的登录 Shell 不同。这可能导致python3命令找不到或者~/.openclaw路径解析错误。最佳实践是在 Cron 命令中使用绝对路径并明确设置关键环境变量。# 在 crontab 中一个更健壮的写法示例 0 9 * * * . /home/user/.profile; cd /abs/path/to/openclaw-token-stats /usr/local/bin/python3 scripts/openclaw_token_report.py --agent main --period daily /abs/path/to/logs/report.log 21实战技巧定制化与扩展过滤特定模型脚本目前没有内置的模型过滤器但你可以通过组合命令行工具快速实现。例如先用--json输出再用jq过滤只查看gpt-4的数据python3 scripts/openclaw_token_stats.py --agent main --days 7 --json | jq .models[] | select(.name | contains(gpt-4))长期趋势分析虽然脚本本身不存储历史聚合数据但你可以通过定期运行报告脚本并将 JSON 输出保存到时间序列数据库如 InfluxDB或简单的文件系统中然后使用其他工具如 Python Pandas, Grafana来绘制长期趋势图。项目的 JSON 输出格式为此类集成设计得很好。多代理汇总如果你运行了多个 OpenClaw 代理例如main,assistant,debug需要为每个代理单独运行脚本。要获得全局视图可以写一个简单的包装脚本循环调用openclaw_token_stats.py并合并--json输出结果。这个工具的精髓在于其简单和专注。它不试图解决所有问题而是把“离线、快速、准确地从日志中获取用量洞察”这件事做到了极致。把它作为你 AI 运维工具箱中的一个基础组件结合你自己的脚本和自动化流程就能构建出贴合自身需求的、强大的成本监控与优化体系。