核心用法
Token Usage Optimizer 是一套轻量级 Shell 脚本工具集，专为 Claude Code 付费用户设计，用于实时追踪订阅配额消耗并优化使用策略。
主要功能模块：
setup.sh— 初始配置，安全存储 OAuth Access/Refresh Tokencheck-usage.sh— 核心检测脚本，计算 SESSION/WEEKLY 用量百分比及燃烧速率（Burn Rate）report.sh— 生成可读性日报，支持多语言输出（含乌克兰语示例）
关键机制：
- 调用 Anthropic OAuth API (
api/oauth/usage) 获取实时用量数据 - 10 分钟本地缓存机制，最小化 API 调用频率
- 自动 Token 刷新（Access Token 约 1 小时过期）
- 状态化告警系统（
/tmp/claude-usage-alert-state），避免 SESSION>50% 或 WEEKLY>80% 时的重复通知
燃烧速率算法：
基于当前时间与配额重置时间的比例，判断用户处于 UNDER（使用不足）、OK（理想节奏）或 OVER（即将超限）三种状态，帮助用户在周期结束前均衡消耗配额。
显著优点
1. 成本意识导向：直接解决"付费用不完"或"提前撞墙"的订阅焦虑，量化 ROI
2. 极简依赖：仅依赖标准 Unix 工具（curl/date/grep），无需 jq 等外部二进制文件
3. 隐私优先设计：Token 本地存储于 .tokens（gitignored），无云端上传
4. 可集成性：提供 Heartbeat 集成示例，支持自动化日报工作流
5. 多档位适配：自动识别 Pro ($20)、Max 100 ($100)、Max 200 ($200) 三档订阅
潜在缺点与局限性
1. Token 生命周期脆弱：Access Token 1 小时过期，若自动刷新失败需人工介入
2. 无持久历史数据：10 分钟缓存 + 无数据库，无法分析长期趋势
3. 单一数据源依赖：完全依赖 Anthropic OAuth API，若端点变更或限流则失效
4. Shell 环境差异：虽标注 Darwin/Linux 兼容，但不同发行版 date 命令行为可能存在解析差异
5. 非官方工具：由第三方社区维护（clawhub.ai），非 Anthropic 官方认可，API 变更风险自担
适合人群
- Claude Code 重度用户：每日依赖 AI 辅助编程，需精细化管理配额
- 多项目切换开发者：跨项目时容易遗忘当前会话消耗进度
- 订阅优化意识强的用户：对 $20-200/月投入敏感，希望榨取每一美元价值
- 自动化工作流爱好者：希望通过 cron/Heartbeat 实现用量监控无人值守
常规风险
| 风险类型 | 具体描述 | 缓解建议 |
|---------|---------|---------|
| **Token 泄露** | OAuth Token 本地明文存储，若设备被入侵可导致账户滥用 | 使用系统密钥管理服务（如 macOS Keychain）替代文件存储 |
| **API 失效** | Anthropic 可能调整 OAuth 端点或限流策略 | 关注官方公告，保留手动回退方案（直接查看 Claude Code 界面） |
| **误报/漏报** | Shell 时间解析或缓存逻辑边界情况导致燃烧速率计算偏差 | 定期与官方界面交叉验证，不依赖单一数据源做关键决策 |
| **自动刷新中断** | cron 任务失败导致 Token 过期，监控中断 | 设置外部健康检查，或缩短人工复查周期 |
---
注：安全认证报告为占位内容，实际部署前建议执行完整代码审计与 Token 安全加固。