介绍
# Claude Code Usage
检查您的 Claude Code OAuth API 使用限制，包括会话（5 小时）和每周（7 天）窗口。
## 快速开始
```bash cd {baseDir} ./scripts/claude-usage.sh ```
## 使用方法
```bash # Default: show cached usage (if fresh) ./scripts/claude-usage.sh
# Force refresh from API ./scripts/claude-usage.sh --fresh
# JSON output ./scripts/claude-usage.sh --json
# Custom cache TTL ./scripts/claude-usage.sh --cache-ttl 300 ```
## 输出
**文本格式**（默认）： ``` 🦞 Claude Code Usage
⏱️ Session (5h): 🟢 ████░░░░░░ 40% Resets in: 2h 15m
📅 Weekly (7d): 🟡 ██████░░░░ 60% Resets in: 3d 8h ```
**JSON 格式**（`--json`）： ```json { "session": { "utilization": 40, "resets_in": "2h 15m", "resets_at": "2026-01-19T22:15:00Z" }, "weekly": { "utilization": 60, "resets_in": "3d 8h", "resets_at": "2026-01-22T04:00:00Z" }, "cached_at": "2026-01-19T20:00:00Z" } ```
## 功能
- 📊 **会话限制**（5 小时窗口）- 短期速率限制 - 📅 **每周限制**（7 天窗口）- 长期速率限制 - ⚡ **智能缓存** - 60 秒缓存以避免 API 滥用 - 🎨 **精美输出** - 进度条、表情符号、颜色编码状态 - 🔄 **强制刷新** - `--fresh` 标志以绕过缓存 - 📤 **JSON 输出** - 机器可读格式 - 🔔 **自动监控** - 配额重置时获取通知
## 状态指示器
- 🟢 **绿色** - 使用量 0-50%（健康） - 🟡 **黄色** - 使用量 51-80%（中等） - 🔴 **红色** - 使用量 81-100%（高/严重）
## 系统要求
- **macOS**：使用 Keychain 访问 Claude Code 凭证 - **Linux**：使用 `secret-tool` 进行凭证存储 - **凭证**：必须已通过 Claude Code CLI 身份验证
## 工作原理
1. 从系统钥匙串检索 OAuth 令牌 2. 使用 OAuth bearer 令牌查询 `api.anthropic.com/api/oauth/usage` 3. 解析 `five_hour` 和 `seven_day` 使用率指标 4. 计算距离重置的剩余时间 5. 使用进度条和状态指示器格式化输出 6. 缓存结果 60 秒（可配置）
## 缓存
默认缓存：`/tmp/claude-usage-cache`（60 秒 TTL）
覆盖： ```bash CACHE_FILE=/tmp/my-cache CACHE_TTL=300 ./scripts/claude-usage.sh ```
## 示例
**开始工作前检查使用量：** ```bash ./scripts/claude-usage.sh --fresh ```
**集成到状态栏：** ```bash usage=$(./scripts/claude-usage.sh | grep "Session" | awk '{print $NF}') echo "Session: $usage" ```
**获取 JSON 用于监控：** ```bash ./scripts/claude-usage.sh --json | jq '.session.utilization' ```
## 自动监控
### 会话刷新提醒（推荐）
在您的 5 小时会话配额刷新时立即获取通知！
**快速设置：** ```bash ./scripts/session-reminder.sh ```
这将创建一个**自调度链**的 cron 作业，用于： 1. 检查您当前的会话到期时间 2. 在您的会话刷新时安排下一个提醒 3. 通知您当前的使用情况统计 4. 自动移除自身（新的 cron 接管）
**您将获得：** ``` 🔄 Claude Code Session Status
⏱️ Current usage: 44% ⏰ Next refresh: 2h 15m
Your 5-hour quota will reset soon! 🦞
✅ Next reminder scheduled for: Jan 22 at 01:22 AM ```
**工作原理：** - 每个提醒运行 `claude-usage.sh` 以查找确切的会话重置时间 - 为该确切时刻安排一次性 cron - 每 5 小时自动重复 - 如果会话时间发生偏移，会自动修正
**优势：** - ✅ 精确到分钟 - ✅ 无需手动调度 - ✅ 适应您的实际使用模式 - ✅ 最少的 API 调用（仅在需要时）
### 重置检测监控（替代方案）
通过轮询使用情况，在 Claude Code 配额重置时获取自动通知。
**快速设置：** ```bash # Test once ./scripts/monitor-usage.sh
# Setup automated monitoring (runs every 30 minutes) ./scripts/setup-monitoring.sh ```
或通过 Clawdbot 直接添加： ```bash # Check every 30 minutes clawdbot cron add --cron "*/30 * * * *" \ --message "cd /Users/ali/clawd/skills/claude-code-usage && ./scripts/monitor-usage.sh" \ --name "Claude Code Usage Monitor" \ --session isolated --deliver --channel telegram ```
**您将获得：** ``` 🎉 Claude Code Session Reset!
⏱️ Your 5-hour quota has reset 📊 Usage: 2% ⏰ Next reset: 4h 58m
Fresh usage available! 🦞 ```
**工作原理：** 1. **监控使用量**每 30 分钟（可配置） 2. **检测重置**当使用量显著下降（>10% 或 <5%） 3. **发送通知**重置时通过 Telegram 发送 4. **跟踪状态**在 `/tmp/claude-usage-state.json` 中
**自定义：** ```bash # Change check interval clawdbot cron add --cron "*/15 * * * *" ... # Every 15 minutes clawdbot cron add --cron "0 * * * *" ... # Every hour
# Custom state file location STATE_FILE=/path/to/state.json ./scripts/monitor-usage.sh ```
### 选择哪种监控方法？
| 功能 | 会话提醒 | 重置检测 | |---------|-----------------|-----------------| | 精确度 | ✅ 精确到分钟 | 约 30 分钟窗口 | | API 调用 | 最少 | 每次检查 | | 通知时机 | 重置时准时 | 最长 30 分钟延迟 | | 设置 | 单条命令 | 单条命令 | | 维护 | 自调度 | Cron 永久运行 |
**推荐：** 使用**会话提醒**以获得精确、实时的通知。
## 故障排除
**未找到凭证：** - 确保 Claude Code CLI 已安装并完成身份验证 - 运行一次 `claude` 以触发 OAuth 流程
**API 请求失败：** - 检查网络连接 - 验证 OAuth 令牌未过期 - 尝试 `--fresh` 以强制发起新请求
**Linux 用户：** 安装 `libsecret` 用于凭证存储： ```bash # Debian/Ubuntu sudo apt install libsecret-tools
# Fedora/RHEL sudo dnf install libsecret ```