名称： claude-code-usage
描述： 检查 Claude Code OAuth 使用限制（会话与周配额）。当用户询问 Claude Code 使用情况、剩余限制、速率限制或剩余使用量时使用。包含自动会话刷新提醒和重置检测监控功能。
元数据：
clawdbot:
emoji: "📊"
os:
- darwin
- linux
requires:
bins:
- curl

Claude Code 使用情况查询

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

快速开始

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

使用方法

# 默认：显示缓存的用量（如果数据新鲜）
./scripts/claude-usage.sh

# 强制从 API 刷新
./scripts/claude-usage.sh --fresh

# JSON 格式输出
./scripts/claude-usage.sh --json

# 自定义缓存 TTL
./scripts/claude-usage.sh --cache-ttl 300

输出格式

文本格式（默认）：

🦞 Claude Code 使用情况

⏱️  会话（5小时）：🟢 ████░░░░░░ 40%
   重置时间：2小时 15分钟后

📅 周度（7天）：🟡 ██████░░░░ 60%
   重置时间：3天 8小时后

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. 使用 OAuth 承载令牌查询 api.anthropic.com/api/oauth/usage
3. 解析 five_hour 和 seven_day 使用率指标
4. 计算距离重置的剩余时间
5. 使用进度条和状态指示器格式化输出
6. 将结果缓存 60 秒（可配置）

缓存

默认缓存：/tmp/claude-usage-cache（60秒 TTL）

覆盖方法：

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

使用示例

开始工作前检查用量：

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

与状态行集成：

usage=$(./scripts/claude-usage.sh | grep "会话" | awk '{print $NF}')
echo "会话用量：$usage"

获取 JSON 用于监控：

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

自动监控

会话刷新提醒（推荐）

在您的 5 小时会话配额刷新时获得精确通知！

快速设置：

./scripts/session-reminder.sh

这将创建一个自调度链的 cron 任务，功能包括：
1. 检查当前会话到期时间
2. 在会话刷新时安排下一次提醒
3. 通知您当前使用统计数据
4. 自动移除自身（新 cron 任务接管）

您将获得：

🔄 Claude Code 会话状态

⏱️  当前使用率：44%
⏰ 下次刷新：2小时 15分钟后

您的 5 小时配额即将重置！🦞

✅ 下次提醒已安排于：1月22日 01:22 AM

工作原理：
- 每个提醒运行 claude-usage.sh 以找到确切的会话重置时间
- 为该精确时刻安排一次性 cron 任务
- 每 5 小时自动重复
- 如果会话时间漂移，可自我修正

优势：
- ✅ 精确到分钟
- ✅ 无需手动调度
- ✅ 适应您的实际使用模式
- ✅ 最少的 API 调用（仅在需要时）

重置检测监控（替代方案）

通过轮询使用情况，在 Claude Code 配额重置时获得自动通知。

快速设置：

# 测试一次
./scripts/monitor-usage.sh

# 设置自动监控（每30分钟运行一次）
./scripts/setup-monitoring.sh

或直接通过 Clawdbot 添加：

# 每30分钟检查一次
clawdbot cron add --cron "*/30 * * * *" \
  --message "cd /Users/ali/clawd/skills/claude-code-usage && ./scripts/monitor-usage.sh" \
  --name "Claude Code 使用情况监控" \
  --session isolated --deliver --channel telegram

您将获得：

🎉 Claude Code 会话已重置！

⏱️  您的 5 小时配额已重置
📊 使用率：2%
⏰ 下次重置：4小时 58分钟后

新鲜用量已可用！🦞

工作原理：
1. 监控使用情况 每30分钟（可配置）
2. 检测重置 当使用率显著下降时（>10% 或 <5%）
3. 发送通知 重置发生时通过 Telegram 发送
4. 跟踪状态 在 /tmp/claude-usage-state.json 中

自定义配置：

# 更改检查间隔
clawdbot cron add --cron "*/15 * * * *" ...  # 每15分钟
clawdbot cron add --cron "0 * * * *" ...      # 每小时

# 自定义状态文件位置
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