Claude Code CLI 用量监控：实时查看 token 消耗与速率限制的完整指南

你是否用着 Claude Code 订阅，却完全不知道自己这一轮对话消耗了多少 token？只知道"被限流了"，但不知道为什么、还剩多少额度？

Claude Code 订阅不同于 API 调用，不会显示"剩余 token"——因为订阅套餐采用速率限制机制，而非固定的 token 配额。如果你用的是 VS Code 插件版，可以直接看到上下文窗口消耗；但命令行只能通过 /cost 查看当前会话的使用明细：

/cost
  ⎿  You are currently using your subscription to power your Claude Code usage
     breakdown · sonnet: 100% · haiku: 0% · cache hit: 97%

本文手把手教你配置 Claude Code CLI 底部状态栏，实时查看上下文、token 用量、缓存命中率和速率限制——目的只有一个：找到更省 token 的大模型用法。

1. 配置状态栏实时显示用量指标

配置完成后，Claude Code 底部将持续显示：

[Claude Sonnet 4.6  ctx:12%  tok:8.3k+1.2k  cache:74%  5h:22%]

第一步：创建状态栏脚本

在 ~/.claude/ 目录下创建文件 statusline-command.sh，内容如下：

#!/usr/bin/env bash
# Claude Code status line: token usage, model, cache hit rate, rate limits

input=$(cat)

model=$(echo "$input" | jq -r '.model.display_name // "Unknown Model"')
ctx_used=$(echo "$input" | jq -r '.context_window.used_percentage // empty')
total_in=$(echo "$input" | jq -r '.context_window.total_input_tokens // 0')
total_out=$(echo "$input" | jq -r '.context_window.total_output_tokens // 0')
cache_read=$(echo "$input" | jq -r '.context_window.current_usage.cache_read_input_tokens // 0')
cache_create=$(echo "$input" | jq -r '.context_window.current_usage.cache_creation_input_tokens // 0')
cur_input=$(echo "$input" | jq -r '.context_window.current_usage.input_tokens // 0')
five_pct=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
week_pct=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')

fmt_k() {
  local n=$1
  if [ "$n" -ge 1000 ] 2>/dev/null; then
    printf "%.1fk" "$(echo "scale=1; $n / 1000" | bc)"
  else
    echo "$n"
  fi
}

total_tokens=$((total_in + total_out))

cache_rate=""
if [ "$cur_input" -gt 0 ] 2>/dev/null; then
  total_cur=$((cur_input + cache_read + cache_create))
  if [ "$total_cur" -gt 0 ]; then
    cache_rate=$(echo "scale=0; $cache_read * 100 / $total_cur" | bc)
    cache_rate=" cache:${cache_rate}%"
  fi
fi

ctx_info=""
if [ -n "$ctx_used" ]; then
  ctx_info=" ctx:$(printf '%.0f' "$ctx_used")%"
fi

rate_info=""
if [ -n "$five_pct" ]; then
  rate_info=" 5h:$(printf '%.0f' "$five_pct")%"
fi
if [ -n "$week_pct" ]; then
  rate_info="$rate_info 7d:$(printf '%.0f' "$week_pct")%"
fi

tok_info=""
if [ "$total_tokens" -gt 0 ] 2>/dev/null; then
  tok_info=" tok:$(fmt_k $total_in)+$(fmt_k $total_out)"
fi

printf "\033[2m[%s%s%s%s%s]\033[0m" \
  "$model" \
  "$ctx_info" \
  "$tok_info" \
  "$cache_rate" \
  "$rate_info"

💡 脚本依赖 jq 和 bc，Git Bash 环境下通常已内置。

第二步：更新 settings.json

编辑 ~/.claude/settings.json，在现有配置中添加 "statusLine" 块：

{
  "permissions": {
    "allow": ["Read", "Edit"],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(git push --force *)"
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "bash C:/Users/your-username/.claude/statusline-command.sh"
  }
}

第三步：重启 Claude Code

保存文件后重启 Claude Code，状态栏即生效。

📌 状态栏字段速查

| 字段 | 含义 | |---|---| | Claude Sonnet 4.6 | 当前使用的模型名称 | | ctx:12% | 上下文窗口已用百分比 | | tok:8.3k+1.2k | 累计输入 + 输出 token 数 | | cache:74% | 当前轮次的缓存命中率 | | 5h:22% | 5 小时滚动窗口速率限制使用率 | | 7d:XX% | 7 天滚动窗口速率限制使用率（有数据时显示） |

2. "用量状态栏"参数说明

2.1 `ctx:%` — 上下文窗口使用率

上下文窗口是 Claude 在一次对话中持有的"工作记忆"——包括你说的所有内容、Claude 的回复、读取的文件内容、工具输出等。

把它想象成一张有限面积的白板：写满了，Claude 就得擦掉最早的内容才能继续。

Sonnet 4.6 的上下文窗口上限为 200,000 tokens
当上下文将满时，Claude Code 会自动执行 /compact 压缩旧消息
ctx% 越高 = 响应越慢 + 早期对话内容有丢失风险

2.2 `tok:Xk+Yk` — 会话 Token 用量

当前会话累计消耗的 token 数：

X = 输入 token（你的消息 + 喂给 Claude 的文件内容）
Y = 输出 token（Claude 的回复）

⚠️ 在订阅制下，输入和输出 token 都计入速率限制。读一个大文件的代价，远超你想象。

2.3 `cache:%` — 缓存命中率

Claude 会缓存重复内容（系统提示、大型文件等），避免每次对话都重新处理。

可以把缓存理解成复印底稿：第一次处理要花钱，之后引用同一份内容，只收取少量"翻印费"。

缓存命中率高（>70%）= 好 — 节省 token，响应更快
缓存命中率低 = 每次对话大量内容被重新处理
保持长会话、避免频繁 /clear 是维持高缓存命中率的关键

2.4 `5h:%` / `7d:%` — 速率限制使用率

订阅计划强制执行两个滚动时间窗口的用量限制：

| 指标 | 时间窗口 | 重置周期 | |---|---|---| | 5h:% | 5 小时滚动窗口 | 每 5 小时 | | 7d:% | 7 天滚动窗口 | 每 7 天 |

2.5 最容易触发限制的操作（按影响排序）

| 触发原因 | 影响程度 | |---|---| | 读取大文件（对大型代码库使用 Read） | 极高 | | 长时间对话不执行 /compact | 高 | | 缓存命中率低（冷启动、频繁 /clear） | 高 | | 运行 Agent/子 Agent（每个都全新启动） | 中高 | | 让 Claude 重写/重构大型文件 | 中 |

核心规律：输入 token 消耗速率限制的速度，远快于输出 token。 读取一个 1000 行的文件，消耗的 token 可能超过 10 轮普通对话。

2.6 最佳实践：如何避免触发限制

上下文接近 70% 时主动执行 /compact
非必要不使用 /clear（会清空缓存）
读取文件时只读需要的部分（使用 offset / limit 参数）
尽量保持长会话以维持高缓存命中率
避免在同一会话内频繁切换大型文件

3. 深度解析：`5h` 与 `7d` 速率限制机制及长期规避策略

3.1 两个限制窗口的本质

Claude Code 订阅制采用双层滚动窗口限速，而非按自然日重置：

| 窗口 | 长度 | 重置方式 | 用途 | |---|---|---|---| | 5h | 5 小时 | 滚动（从最早一笔消耗起算） | 防止短时间内集中爆发 | | 7d | 7 天 | 滚动（从 7 天前的消耗起算） | 控制长期总用量上限 |

⚠️ 滚动窗口 ≠ 固定时间段重置。 例如：你在 09:00 触发了 5h:100%，不是等到 14:00 整点重置，而是等 09:00 那笔最早的消耗"滑出"窗口后，百分比才会下降。

3.2 两个限制的关系

每次请求同时计入 5h 和 7d 两个窗口
       │
       ├─ 5h 先满 → 被短期限流，等数小时恢复
       │
       └─ 7d 先满 → 被长期限流，需等数天才能完全恢复

5h 满：影响范围小，等几小时即可继续工作，属于可接受的日常节点
7d 满：影响范围大，整周工作节奏被打乱，属于需要主动避免的情况

3.3 哪些行为最容易耗尽 `7d` 配额

| 高危行为 | 原因 | 替代方案 | |---|---|---| | 对整个代码库做全量索引/读取 | 一次操作可消耗相当于数天的正常用量 | 分批次、按需读取；使用 Glob 先筛选目标文件 | | 连续运行大量 Agent 任务 | 每个 Agent 独立启动，上下文冷加载，输入 token 翻倍 | 合并任务到单个会话；复用已有上下文 | | 高频 /clear + 重复提问 | 每次清空后缓存归零，相同问题重复全量计费 | 保持会话连续性；用 /compact 代替 /clear | | 让 Claude 生成超长输出 | 输出 token 同样计入配额，大输出累积快 | 拆分为多轮生成；每轮聚焦一个模块 |

3.4 长期规避策略：养成"低消耗"工作习惯

策略一：分散用量，避免单日峰值

❌ 错误模式：周一集中处理所有大任务 → 7d 在前两天耗尽
✅ 正确模式：每天均匀分配任务 → 7d 始终有余量

策略二：善用缓存，减少重复输入

在会话开头一次性加载核心文件，后续引用走缓存，不重复计费
避免在同一天内多次 /clear 后重新加载相同内容
cache:% 维持在 60% 以上是健康状态的参考线

策略三：监控趋势，提前干预

| 7d:% 当前值 | 建议行动 | |---|---| | 0–50% | 正常使用，无需干预 | | 50–75% | 开始减少大文件操作，优先处理高价值任务 | | 75–90% | 切换到轻量模式：只做问答，不读大文件，不跑 Agent | | 90–100% | 暂停高消耗操作，等待窗口自然滑出 |

策略四：利用 `5h` 节奏规划工作

5h 限制反而可以作为工作节律的自然分隔：

第 1 个 5h 窗口：处理高强度任务（大文件分析、Agent 运行）
              ↓ 5h 窗口重置
第 2 个 5h 窗口：处理轻量任务（问答、小修改、文档撰写）

这样既充分利用每个窗口的配额，又避免 7d 被单一窗口耗尽。

3.5 触发长期限制后的恢复方案

若 7d:% 已达 100%，可采取以下措施：

等待自然滑出：7 天前消耗最多的那一天"滑出"窗口后，配额会批量释放
切换到纯问答模式：不读文件、不运行工具，单纯对话消耗极少
利用 ctx:% 完成任务：上下文内已加载的内容不再重复计费，可继续在当前会话内工作
评估是否升级计划：如果 7d 频繁触顶，说明当前用量已超出订阅计划设计的使用强度

4. 常见问题与故障排查

Q1：状态栏不显示 / 显示 `Unknown Model`

确认 statusline-command.sh 文件存在于 ~/.claude/ 目录，且换行符为 LF（不是 CRLF）
检查 settings.json 中的 "command" 路径是否正确，建议使用正斜杠 /

在 Git Bash 中手动运行脚本测试：

echo '{}' | bash ~/.claude/statusline-command.sh

Unknown Model 通常意味着脚本收到的 JSON 中 model.display_name 字段为空——确认 Claude Code 版本支持状态栏数据输出

Q2：`cache:%` 长期为 0% 或极低

| 可能原因 | 解决方式 | |---|---| | 频繁执行 /clear | 减少 /clear 使用，改用 /compact | | 每次对话都重新加载大文件 | 将常用文件固定在会话开头一次性加载 | | 会话过短，缓存来不及建立 | 保持较长会话，复用同一上下文 |

缓存在同一会话内有效；执行 /clear 或重启 Claude Code 会清空缓存。

Q3：`5h:%` 突然飙升到 100%

常见触发点：

在短时间内用 Read 读取了多个大文件（每个大文件 = 数千 token 输入）
连续运行多个 Agent / 子 Agent（每个 Agent 都重新加载全部上下文）
让 Claude 对大型文件进行全量重写

缓解方案：

触发限制后，等待 5 小时滚动窗口自然重置
下次操作时改用 offset / limit 参数分段读取文件
将 Agent 任务拆分到不同会话，避免集中触发

Q4：`/compact` 和 `/clear` 有何区别？

| 命令 | 作用 | 对缓存的影响 | |---|---|---| | /compact | 压缩旧消息，保留上下文摘要，不清空缓存 | 缓存保留，命中率维持 | | /clear | 完全清空对话历史和上下文 | 缓存清空，下一轮重新建立 |

💡 建议：优先使用 /compact，仅在需要彻底重置时才使用 /clear。

Q5：如何估算一个操作会消耗多少 token？

粗略参考：

| 操作 | 大约消耗 token | |---|---| | 读取 100 行代码文件 | ~500–800 输入 token | | 读取 1000 行代码文件 | ~5,000–8,000 输入 token | | 一轮普通问答（无文件） | ~200–600 token | | 运行一个子 Agent（含上下文） | ~10,000–50,000 输入 token | | 全量重写 500 行文件 | ~3,000 输入 + ~5,000 输出 token |

精确用量可通过状态栏 tok: 字段在操作前后对比得出。