核心用法
ai-usage 是面向 Claude Code 与 OpenClaw 用户的用量监控工具，通过单一命令行脚本聚合 Anthropic 官方配额与本地会话日志，输出可视化仪表盘或结构化 JSON。执行 python3 scripts/usage_check.py 即可获取周度利用率、5 小时滚动窗口、模型级消耗及剩余额度倒计时；加 --json 标志可对接 CI/CD 或告警系统。
显著优点
1. 零依赖轻量：仅依赖 Python 3.10+ 标准库，无需 pip 安装。
2. 自动鉴权刷新：检测 OAuth Token 过期后，自动调用 claude --print 续期，无需人工干预。
3. 多源聚合：同时覆盖 Anthropic 官方 API 限额与 OpenClaw 本地会话（支持 Ollama、OpenAI 等任意后端路由）。
4. 模型级细账：区分 Sonnet/Opus 等模型的周度消耗，并换算等效 API 成本。
潜在缺点与局限性
- 环境耦合强：必须预先安装 Claude Code 与 OpenClaw，且需保持 OAuth 登录状态；若 CLI 未在 PATH 或凭证作用域不足，Anthropic 配额模块将静默跳过。
- 非官方接口：Anthropic 端点
api/oauth/usage属于未文档化接口，存在随时变更或限流风险。 - 本地日志依赖：OpenClaw 统计完全基于本地 JSONL 会话文件，若日志轮转或路径自定义，需手动同步
OPENCLAW_SESSIONS_DIR变量。 - 无历史趋势：当前版本仅展示实时/周期快照，缺乏长期趋势数据库与对比分析。
适合人群
- 高频使用 Claude Code 的开发者与团队，需精细化额度预警；
- 运营多模型后端（Ollama + OpenAI + Anthropic）的 AI 应用架构师；
- 希望将用量监控集成至定时任务（cron）或内部 Dashboard 的运维工程师。
常规风险
| 风险项 | 说明与缓释 |
|--------|-----------|
| 凭证泄露 | 脚本读取 `~/.claude/.credentials.json`，需确保文件权限 600，避免容器镜像层泄露。 |
| Token 自动刷新副作用 | `claude --print` 会触发一次无实际交互的网络请求，可能在严格零出站环境被防火墙拦截。 |
| 未公开 API 稳定性 | `oauth/usage` 返回结构变更可能导致解析异常，建议配合 `--json` 输出做 Schema 校验与降级。 |