Token Usage Optimizer（令牌用量优化器）

版本： 1.0.5

最大化利用您的 Claude Code 订阅服务——实时监控用量，并优化每日消耗速率。

为何使用本工具？

您每月为 Claude Code 支付 $20–$200。但您是否：

• ✅ 充分发挥了其全部潜力？
• ❌ 过早触及用量上限？
• ❌ 在配额重置前仍有大量额度未使用？

本技能持续追踪您的 5 小时会话配额 和 7 天周配额，计算您的 每日消耗速率（burn rate），并明确提示您应加大使用强度，还是主动限流。

功能特性

• 📊 消耗速率追踪 —— 您当前是低于/高于/正符合最优用量节奏？
• ⚡ 智能告警 —— 当 SESSION > 50% 时触发一次性提醒（无信息轰炸）
• 🎯 订阅计划感知 —— 自动识别 Pro（$20）、Max 100（$100）、Max 200（$200）三种方案
• 💾 极致轻量 —— 缓存有效期 10 分钟，API 调用次数极少
• 📅 每日报告 —— 晚间汇总：SESSION、WEEKLY 及 burn rate
• 🔄 令牌健康检查 —— 每小时自动检测 + 若需手动刷新则发出提醒（约每周一次）

快速上手

1. 初始化配置

运行配置向导以设置 OAuth 令牌：

cd {baseDir}
./scripts/setup.sh

您需要提供：

• 访问令牌（Access Token）（sk-ant-oat01-...）
• 刷新令牌（Refresh Token）（sk-ant-ort01-...）

获取方式详见 references/token-extraction.md。

2. 查询用量

./scripts/check-usage.sh

输出示例：

SESSION=22.0
WEEKLY=49.0
BURN_RATE=OK
CACHED_AT=1771583780

3. 人性化可读报告

./scripts/report.sh

输出示例：

📊 Claude Code 日度检查：

⏱️  SESSION (5h): 22%
📅 WEEKLY (7d): 49%

⚪ На темпі — оптимальне використання

消耗速率（Burn Rate）解读

• 🟢 UNDER（偏低） —— 您未充分使用订阅额度。建议加大使用，让每一分钱都物有所值！
• ⚪ OK（正常） —— 使用节奏适中，与您的订阅方案完全匹配。
• 🔴 OVER（偏高） —— 消耗过快，将在下次重置前提前触达限额。

各订阅方案对应的日预算

（7 天窗口期每周重置，因此日均 ~14% ≈ 周度 100%）

与 Heartbeat 集成

将以下内容添加至您的 HEARTBEAT.md：

### 晚间检查（18:00–20:00）
- Claude Code 用量：`/path/to/token-usage-optimizer/scripts/report.sh`

告警阈值

• SESSION > 50% → 🟡 一次性告警（下次重置前不再重复）
• WEEKLY > 80% → 🟡 一次性告警

告警通过状态文件（/tmp/claude-usage-alert-state）实现去重，避免信息刷屏。

缓存机制

默认缓存路径：/tmp/claude-usage.cache，TTL（生存时间）为 10 分钟。

如需覆盖默认设置：

CACHE_FILE=/custom/path CACHE_TTL=300 ./scripts/check-usage.sh

文件说明

• scripts/setup.sh —— 初始令牌配置脚本
• scripts/check-usage.sh —— 核心用量检查器（含缓存与消耗速率计算）
• scripts/report.sh —— 生成人性化可读的每日报告
• references/api-endpoint.md —— Anthropic OAuth API 官方文档
• references/token-extraction.md —— 如何获取 OAuth 令牌
• references/plans.md —— Claude Code 各订阅层级说明

API 接口端点

GET https://api.anthropic.com/api/oauth/usage
Authorization: Bearer 
anthropic-beta: oauth-2025-04-20

响应示例：

{
  "five_hour": {
    "utilization": 22.0,
    "resets_at": "2026-02-20T14:00:00.364238+00:00"
  },
  "seven_day": {
    "utilization": 49.0,
    "resets_at": "2026-02-24T10:00:01.364256+00:00"
  }
}

系统依赖

• curl —— 用于发起 API 请求
• date —— 用于解析时间戳
• grep、cut、printf —— 用于文本解析

不依赖外部工具（如 jq 等）。

隐私说明

令牌存储于 {baseDir}/.tokens（已加入 .gitignore，不会被提交至 Git）。

请勿向任何人共享您的 access/refresh token。

令牌健康检查（推荐启用）

OAuth 令牌有效期约为 1 周，之后需手动刷新。为提升可靠性，建议配置每 30 分钟执行一次健康检查：

# 添加 cron 任务，每 30 分钟检查一次令牌健康状态
openclaw cron add 
  --name "claude-token-refresh" 
  --every 30m 
  --announce 
  --message "运行 {baseDir}/scripts/auto-refresh-cron.sh"

该任务行为如下：

• ✅ 令牌有效 → 静默运行（无任何输出）
• 🔴 令牌已过期 → 触发 一次性告警，并附带手动刷新指引

手动刷新操作（每周约 1 次，耗时约 30 秒）：

claude auth login
# 浏览器自动打开 → 登录 claude.ai → 完成！

登录成功后，新令牌将自动同步至 {baseDir}/.tokens。

故障排查

“No token configured”（未配置令牌）
→ 运行 ./scripts/setup.sh

“Token expired”（令牌过期） / “API request failed”（API 请求失败）
→ OAuth 令牌有效期约 1 周
→ 手动刷新：执行 claude auth login（浏览器打开 → 登录 claude.ai → 完成）
→ 建议配置每小时健康检查，以便在过期前及时收到告警（见上文）

消耗速率显示为空
→ API 响应中缺失 resets_at 字段 —— 可稍等几分钟后重试

自动刷新失败
→ OAuth 刷新接口可能已变更
→ 手动刷新：运行 claude auth login → 复制新令牌 → 执行 ./scripts/setup.sh

更新日志

v1.0.5（2026-02-22）

• 🐛 缺陷修复： 修复 auto-refresh-cron.sh 中的令牌提取逻辑（移除了引号处理）
• ⚡ 性能优化： 将 cron 检查间隔从 1 小时缩短至 30 分钟，提升令牌刷新可靠性
• 📝 优化 OAuth 令牌同步逻辑，增强与 ~/.claude/.credentials.json 的兼容性

v1.0.4（2026-02-21）

• 🔄 将自动刷新机制替换为“健康检查 + 手动刷新”工作流
• 📚 更新文档，补充详细的手动刷新操作说明
• ⏰ 健康检查会在需要手动刷新时发出告警（约每周一次）

v1.0.3（2026-02-20）

• ⏱️ 修复自动刷新时间间隔（由 5 小时修正为每小时）
• 📊 提升消耗速率（burn rate）计算精度

参与贡献

发现 Bug 或有功能建议？
→ 请在 ClawHub 提交 Issue：https://clawhub.ai/friday/token-usage-optimizer

许可证

MIT