claude-usage

Claude Usage Calculator 是一款专为 Claude Max 订阅用户设计的本地用量分析工具。该 Skill 通过解析 OpenClaw 代理生成的本地会话数据，反向实现了 Anthropic 官方未公开的积分计算体系，帮助用户精准掌握订阅资源消耗情况。

核心用法方面，用户首次使用需配置每周重置时间和订阅档位（Pro/5×/20×），后续即可通过命令行快速获取用量报告。工具支持多维度查询：weekly 概览展示总积分消耗与预算占比、5小时滑动窗口速率限制预警、会话排名及模型分布；单会话模式可深入分析特定对话的 Token 构成与模型占比；JSON 输出模式便于与其他工具集成。所有数据均从 ~/.openclaw/agents/main/sessions/ 本地读取，无需网络连接。

显著优点包括：一是计算精确性，基于社区逆向研究的积分公式（区分 Opus/Sonnet/Haiku 不同输入输出费率，且 Cache 读取免费），准确反映官方计费逻辑；二是本地隐私保护，纯 Python 标准库实现，零外部依赖，所有敏感会话数据仅在本地处理；三是灵活的阈值监控，特别针对 Claude Max 特有的 5 小时速率限制窗口提供可视化进度条，避免服务中断；四是配置持久化，一次设置后自动保存用户偏好。

潜在局限性在于：首先，数据源依赖 OpenClaw 代理，未使用官方 API 或未使用 OpenClaw 的用户无法获取数据；其次，积分公式基于社区逆向工程，若 Anthropic 调整计费策略可能存在计算偏差；再者，界面为命令行交互，对非技术用户不够友好；最后，时区处理依赖系统命令，在部分容器环境可能需要额外配置。

适合群体主要包括：高频使用 Claude Max 的开发者与研究员，需要监控多会话预算分配；运营团队管理共享账号，需追踪成员使用情况；以及关注成本优化的 AI 重度用户，希望基于 5 小时窗口调整使用策略。

使用风险主要涉及：一是 T3 来源（GitHub 个人账号），虽代码已审计但仍建议审查后使用；二是读取本地敏感会话历史，虽无上传行为但需确保运行环境安全；三是配置保存机制使用 --save 显式确认，避免误操作；四是作为非官方工具，存在因 Claude 计费规则变更导致数据失准的可能性。

功能概述

claude-usage 是一款针对 Claude Max 订阅用户的本地用量统计工具，通过解析 OpenClaw 生成的会话 JSONL 文件，帮助用户精准掌握订阅消耗情况。该工具完全基于 Python 标准库开发，无需任何第三方依赖，所有数据处理均在本地完成，确保隐私安全。

核心用法

用户首次使用时需提供周重置时间（如 "Mon 2:00 PM"）和订阅计划（Pro/$20、5×/$100、20×/$200），后续可直接调用。主要功能包括：

• 周度概览：总积分消耗 vs 周预算（带进度条可视化）、5小时滑动窗口限流预警、会话按消耗排序、模型分布统计
• 单会话详情：积分消耗及占比、Token 明细（输入/输出/缓存）、各模型细分数据
• 灵活输出：支持 --top N 限制会话数、--json JSON 格式输出、时区和计划覆盖

显著优点

1. 数据来源权威：基于 she-llac.com 逆向工程的 Claude 积分体系，覆盖 Haiku/Sonnet/Opus 三档费率模型
2. 隐私优先设计：零网络请求，仅读取 ~/.openclaw/ 本地目录，配置信息最小化存储
3. 供应链安全：纯 Python 标准库（json、pathlib、zoneinfo 等），无第三方包引入风险
4. 开源透明：MIT 协议，维护者 lemodigital 为 GitHub 组织账号，代码可审计

潜在局限

• 依赖 OpenClaw：需配合 OpenClaw 工具生成会话数据，独立使用价值有限
• 手动配置依赖：首次使用需用户主动提供重置时间和计划信息
• 平台限制：仅支持 Python 3.9+ 环境，Windows 用户可能需额外处理时区配置
• 非官方工具：积分计算公式为社区逆向结果，可能与 Anthropic 官方计费存在细微偏差

适合人群

• Claude Max（5×/20×）重度用户，需要监控高额度订阅消耗
• 多项目/多会话并行的开发者，需识别高消耗会话优化成本
• 对隐私敏感、拒绝云端分析工具的用户
• OpenClaw 生态现有用户

常规风险

| 风险项 | 等级 | 说明 |

|--------|------|------|

| 子进程调用 | 极低 | 仅用于 `date +%z` 时区获取，参数硬编码无注入风险 |

| 路径遍历 | 低 | 建议对 `--sessions-dir` 等路径参数增加验证 |

| 配置文件权限 | 低 | 当前未设置 0o600 权限，多用户环境可能暴露配置 |

| JSONL 解析异常 | 极低 | 损坏会话文件会被跳过，建议增加错误日志 |

安全评估结论

该工具获得 S 级安全认证，静态/动态分析均通过，无网络外泄风险，是订阅管理类工具中安全实践较为优秀的开源方案。