Claude Usage Tracker如何读取你的用量数据？claude.ai私有API与limits[]新格式完全剖析

Claude Usage Tracker如何读取你的用量数据？claude.ai私有API与limits[]新格式完全剖析

【免费下载链接】Claude-Usage-TrackerNative macOS menu bar app for tracking Claude AI usage limits in real-time. Built with Swift/SwiftUI.项目地址: https://gitcode.com/gh_mirrors/cl/Claude-Usage-Tracker

Claude Usage Tracker 是一款原生 macOS 菜单栏用量监控工具，它能实时读取你的 Claude AI 使用额度（5 小时窗口、每周上限、各模型用量）。这篇文章带你完整剖析它读取用量数据的 3 条凭证通道，以及新版limits[]响应格式的设计原理，帮你彻底搞懂 Claude 用量追踪背后的数据链路。

一、凭证三级校验：应用如何拿到"钥匙"？

一切从凭证开始。Claude Usage Tracker 每次刷新前，都会按优先级挑选最佳鉴权方式（源码见 ClaudeAPIService.swift）：

💡 注意：Console API 会话只用于计费数据，不会作为用量凭证的降级选项——这一细节在 KeychainService.swift 的密钥存取逻辑中有所体现。

会话密钥在保存前会经过 SessionKeyValidator.swift 校验，防止无效密钥入库。

二、主通道：claude.ai 私有 API 的用量端点

拥有有效会话密钥时，应用会向claude.ai/api（基础地址定义在 Constants.swift）发起三组并行请求：

1. /organizations/{orgId}/usage— 核心用量数据（5 小时窗口、每周窗口、各模型用量）
2. /organizations/{orgId}/overage_spend_limit— 超额消费限额
3. /organizations/{orgId}/overage_credit_grant— 超额积分余额

请求携带sessionKeyCookie 时有一个关键细节：应用会同时附带登录窗口捕获的 Cloudflare 防护 Cookie（cf_clearance、__cf_bm等）。只带裸会话密钥的请求经常被风控拦截，返回"Just a moment..."挑战页。源码在 sessionCookieHeader 中处理了这一点，并专门区分"风控拦截"与"凭证过期"两种错误，避免误判。

三、备用通道：从限流响应头"免费"读取用量

当只有 CLI OAuth 凭证时，应用会向 Messages API 发送一次最小化请求（最便宜模型、1 个 token），从响应头中解析用量：

• anthropic-ratelimit-unified-5h-utilization— 5 小时窗口使用率
• anthropic-ratelimit-unified-7d-utilization— 每周窗口使用率
• 对应的-reset头提供重置时间戳

巧妙的地方在于：429 限流响应同样携带这些响应头（见 parseUsageFromRateLimitHeaders），恰好在你最需要数据时（已达上限）也能正常读取。

四、limits[] 新格式完全剖析

发生了什么变化？

旧版 API 通过seven_day_opus、seven_day_sonnet等独立字段上报各模型用量，新版 API 将这些遗留字段置空，改为统一的limits[]数组（解析逻辑见 parseUsageResponse）。

limits[] 数据结构

数组中每个条目形如：

{ "kind": "weekly_scoped", "percent": 73, "resets_at": "2026-09-29T12:59:00Z", "scope": { "model": { "id": null, "display_name": "Fable" } } }

应用的三条匹配规则

1. 只认kind == "weekly_scoped"的条目，其余跳过；
2. 模型识别：优先匹配稳定的id，display_name仅作兜底（因为它可能随改名变化）。Fable 额外兼容别名mythos，Design 兼容omelette；
3. 覆盖原则：limits[]是"唯一事实来源"——只要某模型在数组中出现，就覆盖遗留字段给出的值。

解析器还对percent/utilization做了鲁棒处理，无论服务端返回整数、浮点数还是带%的字符串都能正确归一化（见 parseUtilization）。

五、从 JSON 到菜单栏：完整数据流

凭证校验 → 拉取 /usage → parseUsageResponse 解析 limits[] → 构建 ClaudeUsage 模型 → 菜单栏图标 + 弹出层展示

• 数据模型：所有字段（会话/周度百分比、重置时间、各模型用量、超额消费）统一封装在 ClaudeUsage.swift 中；
• 定时刷新：UsageRefreshCoordinator.swift 按用户配置的间隔定时调度上述流程，实现"实时"监控；
• 类型定义：响应结构、超额消费等类型的 Codable 定义在 ClaudeAPIService+Types.swift；
• CLI 凭证同步：OAuth Token 的提取与过期判断由 ClaudeCodeSyncService.swift 负责。

六、核心文件速查

总结：Claude Usage Tracker 用"三级凭证降级 + 双数据通道 + limits[] 覆盖式解析"三层设计，保证了无论你用浏览器登录、Claude Code 还是钥匙串凭证，都能稳定拿到最新的用量数据——这正是菜单栏上每个百分比背后的完整故事。

【免费下载链接】Claude-Usage-TrackerNative macOS menu bar app for tracking Claude AI usage limits in real-time. Built with Swift/SwiftUI.项目地址: https://gitcode.com/gh_mirrors/cl/Claude-Usage-Tracker