Claude Code 使用情况

检查您的 Claude Code OAuth API 使用限制，包括会话（5小时）和每周（7天）时间窗口。

快速开始

cd {baseDir}
./scripts/claude-usage.sh

使用

# 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):

{
  "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：使用钥匙串访问 Claude Code 凭据
• Linux：使用secret-tool用于凭证存储
• 凭证：必须已认证Claude Code CLI

工作原理

1. 从系统密钥链中获取OAuth令牌
2. 查询api.anthropic.com/api/oauth/usage使用OAuth承载令牌
3. 解析五小时和七天使用率指标
4. 计算距离重置的剩余时间
5. 使用进度条和状态指示器格式化输出
6. 缓存结果60秒（可配置）

缓存

默认缓存：/tmp/claude-usage-cache（60秒生存时间）

覆盖：

CACHE_FILE=/tmp/my-cache CACHE_TTL=300 ./scripts/claude-usage.sh

示例

开始工作前检查使用情况：

./scripts/claude-usage.sh --fresh

与状态栏集成：

usage=$(./scripts/claude-usage.sh | grep "Session" | awk '{print $NF}')
echo "Session: $usage"

获取监控用JSON：

./scripts/claude-usage.sh --json | jq '.session.utilization'

自动化监控

会话刷新提醒（推荐）

在您5小时会话额度刷新的确切时刻获得通知！

快速设置：

./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配额重置时获取自动通知。

快速设置：

# Test once
./scripts/monitor-usage.sh

# Setup automated monitoring (runs every 30 minutes)
./scripts/setup-monitoring.sh

或直接通过Clawdbot添加：

# 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 文件中

自定义：

# 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

选择哪种监控方法？

推荐：使用会话提醒以获取精确、实时的通知。

故障排除

未找到凭据：

• 请确保已安装并认证Claude Code CLI
• 运行claude一次以触发 OAuth 流程

API 请求失败：

• 检查网络连接
• 验证 OAuth 令牌是否未过期
• 尝试--fresh以强制发起新请求

Linux 用户：安装libsecret用于凭证存储：

# Debian/Ubuntu
sudo apt install libsecret-tools

# Fedora/RHEL
sudo dnf install libsecret