Token Usage Optimizer

核心用法

Token Usage Optimizer 是一款专为 Claude Code 付费用户设计的轻量级配额监控工具。用户需先通过 OAuth 流程获取 access token 和 refresh token，运行 setup.sh 完成初始化配置。核心功能通过 check-usage.sh 脚本实现，调用 Anthropic OAuth API (api.anthropic.com/api/oauth/usage) 获取当前 5 小时会话利用率（five_hour.utilization）和 7 天周利用率（seven_day.utilization），结合 resets_at 时间戳计算燃尽速率（burn rate）。

脚本采用 10 分钟本地缓存策略（/tmp/claude-usage.cache），避免频繁 API 调用。输出支持机器可读格式（SESSION/WEEKLY/BURN_RATE 环境变量）和人类可读报告（report.sh），包含进度条式可视化。集成建议通过 HEARTBEAT.md 的晚间检查任务实现自动化监控。

显著优点

1. 订阅 ROI 导向：明确针对 Pro ($20)、Max 100 ($100)、Max 200 ($200) 三档定价设计，帮助用户识别"配额浪费"或"超额消耗"场景
2. 零依赖轻量实现：仅依赖系统内置工具（curl/date/grep/cut/printf），拒绝 jq 等外部依赖，符合 POSIX 兼容性
3. 智能防骚扰机制：SESSION>50% 和 WEEKLY>80% 触发一次性警报，通过 /tmp/claude-usage-alert-state 状态文件避免重复通知
4. 计划自动感知：虽三档周/日预算比例相同（~14%/~2%），但架构预留扩展空间
5. 隐私本地化：令牌存储于 .tokens 文件（gitignored），API 密钥不落第三方服务器

潜在缺点与局限性

1. OAuth 令牌获取门槛：用户需手动从 Claude Code 应用提取 sk-ant-oat01-* 和 sk-ant-ort01-* 令牌，流程对非技术用户存在摩擦
2. 缓存延迟风险：10 分钟 TTL 在高频使用场景下可能显示滞后数据，导致燃尽速率判断偏差
3. 计划识别盲区：当前版本三档计划预算比例硬编码相同，未实际区分 $20/$100/$200 的配额绝对值差异
4. 单点故障依赖：API 端点变更或 OAuth 策略调整将直接致工具失效（2025-04-20 beta 标签提示不稳定期）
5. 无历史趋势分析：仅提供当前快照，缺乏跨周/跨月的使用模式洞察

适合人群

• Claude Code 重度付费用户：日活依赖 AI 编码辅助，需精确配额管理避免中断
• 成本敏感型开发者：$20-200/月投入需量化回报，厌恶配额浪费
• 自动化工作流构建者：希望通过 cron/systemd 实现无人值守监控
• 极简工具偏好者：拒绝 Electron GUI，追求 shell-native 解决方案

常规风险

1. 令牌泄露风险：sk-ant-* 令牌具备账户级权限，.tokens 文件若被误提交至公共仓库将导致未授权访问
2. API 速率限制：虽本地缓存缓解，但缓存失效时的并发调用可能触发 Anthropic 限流
3. 时区/时间解析错误：resets_at ISO 8601 时间戳解析依赖系统 date 实现，跨平台（macOS BSD date vs GNU date）存在兼容性隐患
4. 缓存状态残留：/tmp 目录异常清理或权限变更可能导致陈旧数据误判
5. 订阅条款变更：Claude Code 的配额结构（5h/7d 窗口）属商业策略，未来调整将破坏燃尽计算逻辑

核心用法

Token Usage Optimizer 是一款专为 Claude Code 付费订阅用户设计的轻量级用量监控工具。用户通过 ./scripts/setup.sh 配置 OAuth Access Token 和 Refresh Token 后，即可使用 ./scripts/check-usage.sh 获取实时用量数据，或通过 ./scripts/report.sh 生成人性化日报。工具自动识别 Pro（$20）、Max 100（$100）、Max 200（$200）三档订阅计划，计算每日燃烧速率（burn rate），并在 SESSION 超过 50% 或 WEEKLY 超过 80% 时触发一次性智能告警，避免频繁打扰。

显著优点

极致轻量：纯 Bash 脚本实现，零外部依赖（无需 jq、Python 等），仅需系统自带的 curl、date、grep 即可运行，适合各类 Unix-like 环境。智能缓存：默认 10 分钟 TTL 缓存机制，最大限度减少对 Anthropic API 的调用频率，平衡实时性与效率。计划感知：自动适配三档订阅层级，无需手动配置，降低使用门槛。防骚扰设计：告警采用状态文件跟踪（/tmp/claude-usage-alert-state），确保同一阈值仅触发一次，重置前不会重复提醒。燃烧速率可视化：UNDER（使用不足）、OK（ optimal ）、OVER（即将超限）三色状态，直观指导用户调整使用策略。

潜在缺点与局限性

Token 安全风险：OAuth 凭证以明文形式存储于本地 .tokens 文件，虽已设置 600 权限，但缺乏系统级密钥管理（如 macOS Keychain、Linux Secret Service）集成，多用户环境或系统被入侵时存在泄露风险。无自动刷新：当前版本未实现 Access Token 过期后的自动刷新，用户需手动重新配置或使用 Refresh Token 更新。API 单点依赖：功能完全依赖 Anthropic OAuth Usage API，若官方接口变更或网络故障，工具将失效。平台限制：仅支持 darwin 与 linux 系统，Windows 用户需借助 WSL 使用。配置迁移困难：Token 存储路径固定，跨设备迁移需手动复制文件，无备份导出功能。

适合的目标群体

Claude Code 付费订阅者：特别是 Max 100/200 高单价用户，对配额敏感、希望最大化订阅 ROI 的人群。多会话重度用户：需要频繁监控 5 小时会话配额，避免突发中断的开发者。用量焦虑型用户：希望获得结构化日报、告别手动猜测剩余配额的使用者。技术极简主义者：偏好无依赖、可审计源码、运行极快的 Shell 工具，而非臃肿的 GUI 应用。DevOps/自动化集成者：希望将用量检查纳入定时任务（cron）或 CI/CD 流程，实现自动化监控的团队。

使用风险

性能与稳定性：纯 Shell 实现虽轻量，但字符串解析依赖 grep/cut，若 Anthropic API 响应格式微调，可能导致解析失败。建议用户关注 ClawHub 更新渠道。凭证泄露后果：OAuth Token 泄露后，攻击者可获取用户的 Claude Code 用量信息，虽无法直接消费 Token（需结合会话密钥），但仍构成隐私风险。强烈建议用户定期检查 .tokens 文件权限，避免同步至 Git 或云盘。网络隐私：工具向 api.anthropic.com 发送包含认证信息的 HTTPS 请求，虽加密传输，但企业代理或 DPI 环境可能记录请求元数据。缓存数据陈旧：10 分钟缓存窗口内，实际用量可能已大幅变化，极端场景下（如突发高强度使用）可能出现缓存数据与真实配额偏差。生命周期依赖：Anthropic OAuth API 为 Beta 功能（anthropic-beta: oauth-2025-04-20），官方可能调整接口或弃用，导致工具失效。