Claude Code 用量监控：用官方 rate_limits 做一行 5 小时 / 7 天额度状态栏（含脚本，已测）
Claude Code 会把 rate_limits 传给状态栏脚本：5 小时和 7 天两个窗口的已用百分比和重置时间。我们写了一个短 bash 脚本，用 6 组模拟输入测了，还在本地会话数据上跑了 ccusage 20.0.48，对比两种看法各自能看到什么。
buffer关于作者约 6 分钟阅读
先说结论：Claude Code 会在每次刷新状态栏时，把一段 JSON 通过标准输入传给你的脚本，其中的 rate_limits 字段就是官方给的额度数据：5 小时窗口和 7 天窗口各自的已用百分比，以及重置时间。写一个大约 30 行的脚本就能把它显示成一行 5h 24% (1h23m) | 7d 41% (2d7h)。我们 2026 年 11 月 10 日把脚本用 6 组模拟输入测了一遍，又在本地会话数据上跑了社区工具 ccusage 20.0.48，对比两种看法各自能看到什么。限制要先说清：我们没有订阅账号登录，没在真实账号上看到过 rate_limits 的真实值，脚本是按官方文档的 JSON 结构用模拟数据测的。
官方文档里 rate_limits 是什么
下面这些都来自官方 状态栏文档（我们 11-10 抓取）：
| 字段 | 含义 |
|---|---|
rate_limits.five_hour.used_percentage / rate_limits.seven_day.used_percentage | 5 小时、7 天窗口已用的百分比，0 到 100 |
rate_limits.five_hour.resets_at / rate_limits.seven_day.resets_at | 对应窗口重置的时间，Unix 时间戳（秒） |
rate_limits.spend_limit.* | 只在连接带花费上限的 Claude apps 网关时才有，本文脚本不处理 |
使用前要知道的几件事（都是文档原话的意思）：
rate_limits只对 claude.ai 的 Pro、Max、Ultra 订阅用户出现（或连的是设了花费上限的网关）。用 API key 的看不到。- 即使是订阅用户，也要等会话里第一次 API 响应之后才有，每个窗口还可能单独缺失。所以脚本里要处理「没有」的情况。
- 一个窗口的
resets_at过了，Claude Code 就把这个窗口丢掉；窗口到点时脚本也会被重新触发。 - 状态栏脚本在本地运行，不消耗 API token。脚本必须退出码为 0 且有输出，否则状态栏会变空白。
- 状态栏会在这些时候刷新：新的助手消息、
/compact结束、权限模式改变、vim 模式切换、command改变；也可以加refreshInterval（秒，最小 1）定时刷新。
脚本（已测）
依赖 jq。保存成 ~/.claude/statusline.sh：
#!/bin/bash
# 5 小时 / 7 天额度状态栏（读取官方 rate_limits 字段）
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
now=$(date +%s)
left() { # 参数：resets_at（epoch 秒）→ 输出「还剩 1h23m」
local s=$(( $1 - now ))
[ "$s" -le 0 ] && return
if [ "$s" -ge 86400 ]; then printf '%dd%dh' $((s/86400)) $(((s%86400)/3600))
else printf '%dh%02dm' $((s/3600)) $(((s%3600)/60)); fi
}
color() { # 参数：百分比 → ANSI 颜色
local p=${1%.*}
if [ "$p" -ge 90 ]; then printf '\033[31m'
elif [ "$p" -ge 70 ]; then printf '\033[33m'
else printf '\033[32m'; fi
}
RESET='\033[0m'
OUT=""
for w in five_hour seven_day; do
pct=$(echo "$input" | jq -r ".rate_limits.$w.used_percentage // empty")
rs=$(echo "$input" | jq -r ".rate_limits.$w.resets_at // empty")
[ -z "$pct" ] && continue
[ "$w" = five_hour ] && label=5h || label=7d
seg="$(color "$pct")${label} $(printf '%.0f' "$pct")%${RESET}"
[ -n "$rs" ] && l=$(left "$rs") && [ -n "$l" ] && seg="$seg ($l)"
OUT="${OUT:+$OUT | }$seg"
done
if [ -n "$OUT" ]; then echo -e "[$MODEL] $OUT"; else echo "[$MODEL]"; fi然后 chmod +x ~/.claude/statusline.sh，在 ~/.claude/settings.json 里加：
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh"
}
}改完 Claude Code 会自动重新加载设置，状态栏就出现了。想让倒计时在空闲时也走，可以再加 "refreshInterval": 60（每 60 秒重跑一次）。另外官方文档提醒：没接受工作区信任弹窗之前状态栏是空白的；Windows 上路径要用正斜杠，或改用 PowerShell 版本，细节见文档的 Windows 一节。
脚本的颜色阈值：低于 70% 绿色，70% 到 89% 黄色，90% 以上红色（和官方多行示例用的阈值一致）。百分比用 printf '%.0f' 四舍五入，所以 23.5 会显示成 24%。
我们测了什么
用官方文档里的 JSON 结构手工造 6 组输入，通过管道喂给脚本（resets_at 用当前时间加一个偏移量）。输出（去掉颜色码后）：
5h 23.5%、7d 41.2% → [Opus] 5h 24% (1h23m) | 7d 41% (2d7h)
5h 93%、7d 72% → [Opus] 5h 93% (0h10m) | 7d 72% (1d1h)
没有 rate_limits → [Opus]
只有 seven_day 8% → [Sonnet] 7d 8% (3d11h)
5h 的 resets_at 已过期 → [Opus] 5h 50%
只有 spend_limit（网关） → [Opus]颜色码另外用 cat -v 看过：93% 是红色，72% 是黄色，其余绿色。没测的：真实订阅账号下 rate_limits 的实际数值、Claude Code 实际调用脚本时的渲染效果（我们只是把 JSON 管道喂给脚本，没有在交互界面里挂上状态栏）。
和 /usage、ccusage 有什么不同
| 办法 | 数据从哪来 | 能看到什么 |
|---|---|---|
| 状态栏 + rate_limits（本文） | Claude Code 传给脚本的 JSON，官方字段 | 5 小时、7 天窗口的已用百分比和重置时间 |
/usage 命令 | 官方命令；官方错误文档写它能看计划的各个窗口和重置时间 | 同样是计划窗口，但要手动打开 |
| ccusage（社区工具） | 本地会话文件，npm 描述是 “Analyze coding (agent) CLI token usage and costs from local data” | token 数和估算费用，按日、周、月、会话汇总 |
| ccstatusline（社区工具） | 官方状态栏文档在 Tips 里点了名，npm 描述是 “A customizable status line formatter for Claude Code CLI” | 现成的状态栏格式化，我们没测 |
ccusage 我们实测了：npx ccusage@latest --version 输出 ccusage 20.0.48，在一个只有模拟会话的测试目录上，daily 子命令列出了按日期汇总的输入、输出、缓存 token 和 Cost (USD) 几列，blocks 子命令按「会话块」列出了一个进行中的块，写着已过去多久、还剩多久，并给出按当前速度的预测。它读的是本地 ~/.claude 下的会话文件，所以它显示的是你本机记录的 token 和估算费用，不是服务器上你的 5 小时、7 天窗口占了百分之多少，blocks 里的「剩余时间」是它根据本地记录推算的，我们没有拿真实账号对比，不知道和官方重置时间差多少。官方文档对费用也有说明：cost.total_cost_usd 是客户端按标价估算的，可能和实际账单不同。
所以分工是：想看「离限额还有多远」，用官方 rate_limits；想看「我这周花了多少 token」，用 ccusage 一类的本地统计。两个数字不要混着算。额度到底怎么算、Pro 和 Max 差多少，见 Claude 额度怎么算。
常见问题
状态栏不显示 5h、7d 怎么办？
先想：你是订阅用户吗？用 API key 时 rate_limits 根本不会出现。其次是会话里还没有第一次 API 响应。再对照官方文档的排查：脚本有没有执行权限、有没有往 stdout 输出、claude --debug 里有没有脚本的报错。
状态栏会消耗额度吗？
官方文档写明状态栏在本地运行，不消耗 API token。
想看更多字段
官方文档列了完整字段，比如上下文窗口占用 context_window.used_percentage、费用 cost.total_cost_usd、当前模型和 git 分支。改脚本里的 jq 就行。