ARTICLE · 1379736
Claude Code 源码-认证 / OAuth / 额度护栏
Claude Code 源码解析系列
第 9 讲:认证 / OAuth / 额度护栏
基于 Claude Code 源码快照 · 2026-11-19
💡 本讲一句话:前几讲讲"请求怎么发、响应怎么收",这一讲讲更底层的问题——你是谁、你还有多少额度。登录走 OAuth 授权码 + PKCE,手动/自动双通道竞速;token 刷新靠一把跨进程文件锁防并发踩踏;而 Pro/Max 的 5 小时和 7 天额度护栏,全部藏在每个 API 响应的 anthropic-ratelimit-unified-* 头里,客户端用"时间相对阈值"提前预警你烧得太快。
一、PKCE:公共客户端没有 secret,怎么证明"是我发起的授权"
Claude Code 是一个跑在用户机器上的 CLI——OAuth 术语里这叫公共客户端(public client):没有服务器可以保管 client secret,任何打进二进制的"密钥"都能被反编译出来。所以它用 PKCE(RFC 7636)替代 secret:先随机生成一个 verifier,把它的 SHA256 作为 challenge 放进授权 URL;换 token 时再把原始 verifier 交出去。攻击者就算截获了授权码,没有 verifier 也算不出 challenge 的逆运算,换不了 token。
三个生成函数全部在 services/oauth/crypto.ts(全文仅 23 行):
📄 src/services/oauth/crypto.ts (第 3-23 行)
function base64URLEncode(buffer: Buffer): string { // PKCE 要求 URL-safe Base64 且无 padding // 链式起点:Buffer → Base64 字符串 .toString('base64') // 先做标准 Base64 编码 .replace(/\+/g, '-') // + → -,变成 URL 安全字符(RFC 7636) .replace(/\//g, '_') // / → _,同上 .replace(/=/g, '') // 去掉 = padding,URL query 里不能带}export function generateCodeVerifier(): string { // verifier:随机 32 字节,只留在客户端手里 return base64URLEncode(randomBytes(32)) // randomBytes 是 CSPRNG,保证不可预测}export function generateCodeChallenge(verifier: string): string { // challenge = SHA256(verifier),放进授权 URL const hash = createHash('sha256') // S256 方法(RFC 7636 推荐) hash.update(verifier) // 喂入原始 verifier return base64URLEncode(hash.digest()) // 输出 URL-safe Base64}export function generateState(): string { // state:一次性随机数,防 CSRF return base64URLEncode(randomBytes(32)) // 回调时必须原样带回,否则拒绝为什么这样设计:注意 state 和 verifier 都是 32 字节 CSPRNG——一个防"别人把授权码塞给你"(CSRF),一个防"别人拿你的授权码换 token"(code injection)。两者职责正交,缺一不可。而 challenge 用 SHA256 单向哈希而不是直接传 verifier,是因为授权 URL 会出现在浏览器地址栏、历史记录甚至 Referer 头里——challenge 泄露了也没关系,逆运算算不出 verifier。
有了 PKCE 三件套,OAuthService.startOAuthFlow()(services/oauth/index.ts)开始编排整个登录。它最特别的地方是同时准备两条通道:自动通道(浏览器授权后重定向回 localhost)和手动通道(用户自己复制粘贴 code)——因为 CLI 经常跑在没有浏览器的 SSH/容器环境里:
📄 src/services/oauth/index.ts (第 50-86 行)
this.authCodeListener = new AuthCodeListener() // 创建 localhost 回调服务器实例this.port = await this.authCodeListener.start() // listen(0) → OS 分配空闲端口,避免写死端口冲突const codeChallenge = crypto.generateCodeChallenge(this.codeVerifier) // PKCE:SHA256(verifier),放进 URLconst state = crypto.generateState() // CSRF 防护随机数const manualFlowUrl = client.buildAuthUrl({ ...opts, isManual: true }) // 手动通道:重定向到固定网页,用户复制 codeconst automaticFlowUrl = client.buildAuthUrl({ ...opts, isManual: false })// 自动通道:重定向回 localhost:{port}/callbackconst authorizationCode = await this.waitForAuthorizationCode( // 等两条通道中任意一条的结果(先到先赢) state, // 回调必须带回这个 state,否则拒绝 async () => { // onReady:服务器就绪后才开始引导用户 if (options?.skipBrowserOpen) { // SDK 控制协议模式(claude_authenticate) await authURLHandler(manualFlowUrl, automaticFlowUrl) // 两个 URL 都交给调用方,由它决定在哪打开 } else { await authURLHandler(manualFlowUrl) // 先展示手动选项:无浏览器环境的兜底路径 await openBrowser(automaticFlowUrl) // 再尝试自动流程:有浏览器就一键完成 } },)为什么这样设计:"双通道竞速"是 CLI 登录的经典难题的解法——你无法预知用户环境有没有浏览器,与其先探测再分流(探测本身不可靠),不如两条路都铺好,谁先到算谁的。手动通道的 code 通过 handleManualAuthCodeInput() 直接 resolve 同一个 Promise,并顺手关掉 localhost 服务器;自动通道则由回调服务器捕获。另外注意 skipBrowserOpen:SDK 场景下"打开浏览器"这件事归 SDK 宿主所有(它可能跑在远程机器上),CLI 只负责产出 URL——职责边界划得很干净。
下表汇总授权 URL 上的全部参数,后面几节逐个展开:
二、localhost 回调服务器:先扣住响应,等换完 token 再放行浏览器
AuthCodeListener(services/oauth/auth-code-listener.ts,211 行)不是 OAuth 服务器——源码注释特意强调"it's just a redirect capture mechanism"。它只做三件事:监听、校验、扣住响应。核心在 handleRedirect() + validateAndRespond()(第 134-175 行):
📄 src/services/oauth/auth-code-listener.ts (第 134-175 行)
private handleRedirect(req: IncomingMessage, res: ServerResponse): void { // 浏览器重定向落在这里 // 解析回调 URL,取出 code/state , // 相对路径(/callback?code=...) `http://${req.headers.host || 'localhost'}`, // 相对路径补全成完整 URL(host 兜底 localhost) ) if (parsedUrl.pathname !== this.callbackPath) { // 只认 /callback,其他路径一律 404 res.writeHead(404) // 不泄露"这个端口在干什么" res.end() // 结束响应,防止浏览器挂起 return // 提前退出:code/state 缺失时不再处理 } const authCode = parsedUrl.searchParams.get('code') ?? undefined // 从 query 取授权码 const state = parsedUrl.searchParams.get('state') ?? undefined // 从 query 取 state 随机数 this.validateAndRespond(authCode, state, res) // 校验通过才 resolve Promise} // 校验并响应(纯函数,不碰网络) // 授权码(可能缺失) // 防 CSRF 的随机串 // 响应对象(用于写回结果)): void { if (!authCode) { // 没有 code → fail loud,直接拒绝 res.writeHead(400) // 浏览器看到 400,用户知道出错了 res.end('Authorization code not found') // 400 响应体:缺授权码 this.reject(new Error('No authorization code received')) // CLI 侧同步收到错误 return // 提前退出:code/state 缺失时不再处理 } if (state !== this.expectedState) { // state 不匹配 = CSRF 攻击或过期回调,拒绝 res.writeHead(400) // 注意:这里不回显 expectedState(防枚举) res.end('Invalid state parameter') // state 不匹配 → 拒绝(CSRF 防护) this.reject(new Error('Invalid state parameter')) return // 提前退出:code/state 缺失时不再处理 } this.pendingResponse = res // 关键设计:扣住响应对象,先不回复浏览器! this.resolve(authCode) // 只 resolve Promise,让主流程去换 token为什么这样设计:this.pendingResponse = res 这一行是整个类最精妙的地方。HTTP 响应一旦 end() 就收不回来,但"换 token"是异步的、可能失败的——如果校验完 code 就立刻给浏览器回 302 成功页,结果换 token 失败了,用户看到"登录成功"却拿不到凭证,体验极差。所以它把 ServerResponse 对象扣在手里:主流程换 token 成功后调 handleSuccessRedirect(scopes)(按 scope 决定跳 claude.ai 还是 console 的成功页),失败则调 handleErrorRedirect(),finally 里 close() 时若还有未回复的响应也会兜底发一个重定向——保证浏览器永远不会挂在一个无响应的连接上。
🔍 细节:start() 用 listen(port ?? 0)——端口传 0 让 OS 分配空闲端口,然后从 server.address().port 读回真实值。这避免了"先查端口是否占用再监听"的 TOCTOU 竞态:服务器一直开着直到被使用(源码注释原话:"This avoids race conditions by keeping the server open until it's used")。
三、换 token:redirect_uri 必须和授权时一字不差
拿到 code 后,exchangeCodeForTokens()(services/oauth/client.ts 第 107-144 行)向 token endpoint 发起 POST。RFC 6749 要求这里的 redirect_uri 必须与授权请求中声明的完全一致——服务端用它验证"这个 code 确实是发给你的回调地址的":
📄 src/services/oauth/client.ts (第 107-143 行)
const requestBody: Record<string, string | number> = { // token endpoint 请求体(RFC 6749 §4.1.3) grant_type: 'authorization_code', // 授权码模式 code: authorizationCode, // 一次性授权码(用过即失效) redirect_uri: useManualRedirect // 必须与 authorize 时声明的一致,服务端会校验 ? getOauthConfig().MANUAL_REDIRECT_URL // 手动通道:固定网页 URL : `http://localhost:${port}/callback`, // 自动通道:本进程监听的那个端口 client_id: getOauthConfig().CLIENT_ID, // 公共客户端 ID(没有 secret——PKCE 替代了它) code_verifier: codeVerifier, // 交出原始 verifier,服务端验证 SHA256(verifier)==challenge state, // 回传 state,服务端二次核对}if (expiresIn !== undefined) { // SDK 场景可指定 token 有效期 requestBody.expires_in = expiresIn // 普通 CLI 登录不传,用服务端默认值}getOauthConfig().TOKEN_URL, requestBody, { // 发起 token 交换(10s 超时) headers: { 'Content-Type': 'application/json' }, // JSON body(而非表单编码) timeout: 15000, // 15s 超时:登录流程不能无限挂起})if (response.status !== 200) { // 非 200 → 抛人类可读的错误 throw new Error( // 非 2xx:把服务端错误信息带进异常,上层统一处理 response.status === 401 // 401 = code 无效/已用/被抢 ? 'Authentication failed: Invalid authorization code' // 给用户明确提示,而不是裸状态码 : `Token exchange failed (${response.status}): ${response.statusText}`, // 其他状态原样透传 )}为什么这样设计:三个值得注意的点。其一,useManualRedirect 的判定来自 hasPendingResponse()——即"回调服务器是否真的收到了浏览器重定向":收到了说明走的是自动通道,redirect_uri 必须填 localhost;没收到说明 code 是用户手贴的,必须填 MANUAL_REDIRECT_URL。填错任何一个,服务端都会拒绝(redirect_uri mismatch)。其二,timeout: 15000——登录是交互流程,挂死比报错更糟。其三,401 单独映射成"Invalid authorization code":这是最常见的失败原因(用户在两个终端同时登录、code 被抢先消费),值得一个专门的提示。
四、token 刷新:三层防线防"多进程并发踩踏"
access token 是短命的(分钟级),refresh token 长命。麻烦在于:Claude Code 的 token 存在 OS keychain + 全局配置里,同一台机器上可能同时跑着多个进程——交互式 REPL、-p headless 调用、SDK 宿主……它们共享同一份凭证。如果每个进程都独立判断"过期了→刷新",就会并发打爆 token endpoint,甚至互相作废对方的 refresh token(很多 OAuth 服务端对 refresh token 做一次性轮换)。Claude Code 的解法是三层防线,全部在 utils/auth.ts。
第一层:过期判定带 5 分钟安全边际(services/oauth/client.ts 第 344-353 行):
📄 src/services/oauth/client.ts (第 344-353 行)
export function isOAuthTokenExpired(expiresAt: number | null): boolean { // 判断是否需要刷新 // null = 静态 token(API key),永不过期 return false // expiresAt=null = 长生命周期 token,永不过期 } const bufferTime = 5 * 60 * 1000 // 5 分钟安全边际:别等到最后一秒才刷 const now = Date.now() // 当前时间(毫秒) const expiresWithBuffer = now + bufferTime // "现在+5min"已经越过过期点 → 视为已过期 return expiresWithBuffer >= expiresAt // 这样在途请求不会打到一半收到 401为什么这样设计:如果严格按 expiresAt 判断,会出现"判定未过期→发请求→服务端已认为过期→401"的竞态窗口。提前 5 分钟刷新把窗口关死;代价是 token 实际还能用 5 分钟时就换新的——对 refresh grant 来说这是零成本操作。
第二层:进程内去重(utils/auth.ts 第 1427-1445 行)——同一个进程里多个调用方共享同一次刷新:
📄 src/utils/auth.ts (第 1427-1445 行)
// 对外入口:带进程内去重 retryCount = 0, // 重试计数(ELOCKED 退避用) force = false, // true = 服务端已明确说 token 坏了,跳过本地过期判断): Promise<boolean> { // Deduplicate concurrent non-retry, non-force calls // 进程内去重:并发调用共享同一次刷新 if (retryCount === 0 && !force) { // 只有"普通首次检查"参与去重 if (pendingRefreshCheck) { // 已有刷新在飞 → 直接返回那个 Promise return pendingRefreshCheck // 不重复发请求,所有调用方等同一个结果 } (retryCount, force) // 委托给实现函数(便于单测 mock) pendingRefreshCheck = promise.finally(() => { // 无论成功失败都清理标记 pendingRefreshCheck = null // 下次调用可以发起新一轮刷新 }) return pendingRefreshCheck // 已有刷新在飞:共享同一个 Promise } return checkAndRefreshOAuthTokenIfNeededImpl(retryCount, force) // retry/force 路径绕过去重(它们有独立语义)为什么这样设计:一个 REPL 会话里,QueryEngine、工具调用、状态栏刷新可能同时触发"检查 token"——没有去重就是 N 个进程内并发刷新。用一个模块级 pendingRefreshCheck Promise 把并发折叠成一次网络请求。finally 清理标记保证失败后下次还能重试,不会永久卡死。
第三层:跨进程文件锁 + 双重检查(utils/auth.ts 第 1484-1544 行)——这是最精彩的部分:
📄 src/utils/auth.ts (第 1484-1516 行)
// Tokens are still expired, try to acquire lock and refresh // 跨进程互斥从这里开始const claudeDir = getClaudeConfigHomeDir() // ~/.claude 目录作为共享锁的位置await mkdir(claudeDir, { recursive: true }) // 确保目录存在(lockfile 需要父目录)let release // 存释放锁的函数,finally 里用try { logEvent('tengu_oauth_token_refresh_lock_acquiring', {}) // 埋点:进入临界区前 release = await lockfile.lock(claudeDir) // 文件锁:全机器同一时刻只有一个进程能刷新 logEvent('tengu_oauth_token_refresh_lock_acquired', {}) // 埋点:拿到锁} catch (err) { // 任何异常都走统一错误路径(含 ELOCKED 退避重试) if ((err as { code?: string }).code === 'ELOCKED') { // 别人持锁 → 不打架,退避重试 if (retryCount < MAX_RETRIES) { // 最多 5 次(MAX_RETRIES=5) logEvent('tengu_oauth_token_refresh_lock_retry', { // 埋点:记录第几次重试 retryCount: retryCount + 1, // 便于线上分析锁竞争频率 }) await sleep(1000 + Math.random() * 1000) // 1~2s 随机退避:防惊群(thundering herd) return checkAndRefreshOAuthTokenIfNeededImpl(retryCount + 1, force) // 递归重试 } logEvent('tengu_oauth_token_refresh_lock_retry_limit_reached', { // 5 次都拿不到锁 maxRetries: MAX_RETRIES, // 埋点:异常竞争,值得告警 }) return false // 放弃刷新(调用方会引导重新登录) } logError(err) // 非 ELOCKED 的锁错误:记录后放弃📄 src/utils/auth.ts (第 1517-1544 行)
try { // 整个刷新包在 try 里,finally 保证释放锁 // Check one more time after acquiring lock // 拿到锁后再查一次(double-check) getClaudeAIOAuthTokens.cache?.clear?.() // 先清内存缓存——里面可能还是旧 token clearKeychainCache() // 再清 keychain 缓存(token 本体存在 OS keychain) const lockedTokens = await getClaudeAIOAuthTokensAsync() // 从磁盘/keychain 重读最新凭证 if ( !lockedTokens?.refreshToken || // 没有 refresh token → 无米之炊 !isOAuthTokenExpired(lockedTokens.expiresAt) // 或已经不过期了(别人刚刷完) ) { logEvent('tengu_oauth_token_refresh_race_resolved', {}) // 埋点:竞态被他人解决,本次免刷 return false // 直接返回——省掉一次无谓的 refresh grant } logEvent('tengu_oauth_token_refresh_starting', {}) // 埋点:真正开始刷新 lockedTokens.refreshToken, { // 真正发起刷新(传入旧 refresh token) scopes: shouldUseClaudeAIAuth(lockedTokens.scopes) // Claude.ai 订阅者传 undefined ? undefined // → 服务端套默认全量 scope(允许 scope 扩展) : lockedTokens.scopes, // 非订阅者保持原 scope 不变 }) // 例如新增 user:file_upload 无需重新登录 saveOAuthTokensIfNeeded(refreshedTokens) // 新 token 写回 keychain/配置 getClaudeAIOAuthTokens.cache?.clear?.() // 刷新后清缓存,让后续调用拿到新值 clearKeychainCache() // 同上(keychain 层) return true // 刷新成功为什么这样设计:这是教科书级的"锁 + double-check"模式,但有两个工程细节值得放大。其一,ELOCKED 重试带随机抖动(sleep(1000 + Math.random() * 1000)):如果 N 个进程同时发现 token 过期、同时醒来抢锁,固定间隔会让它们下一轮再次撞车;随机化把唤醒时刻打散。其二,拿到锁后必须重读——因为"排队等锁"的这段时间里,持锁进程可能已经刷新完毕并写回了新 token;不 double-check 就会发起一次多余的 refresh grant,而某些 OAuth 服务端对 refresh token 做一次性轮换,多刷一次等于把别人的新 token 作废。源码甚至为这两种竞态结果埋了专门的点(race_resolved / race_recovered),说明线上真的发生过这类问题。
五、一次刷新省下的"700 万请求/天"
refreshOAuthToken()(services/oauth/client.ts)里藏着一个成本优化,注释直接写了数字——"we cut ~7M req/day fleet-wide"。刷新 token 后通常还要拉一次 /api/oauth/profile 拿订阅类型和限流档位;但绝大多数例行刷新时这些数据本地早就有了:
📄 src/services/oauth/client.ts (第 195-211 行)
const config = getGlobalConfig() // 全局配置:billingType/创建时间存在这里const existing = getClaudeAIOAuthTokens() // 安全存储(keychain):subscriptionType/rateLimitTier 在这里const haveProfileAlready = // 两个来源都齐全才允许跳过网络请求: config.oauthAccount?.billingType !== undefined && // 配置里有计费类型 config.oauthAccount?.accountCreatedAt !== undefined && // 配置里有账户创建时间 config.oauthAccount?.subscriptionCreatedAt !== undefined && // 配置里有订阅开始时间 existing?.subscriptionType != null && // keychain 里有订阅档位(pro/max/enterprise/team) existing?.rateLimitTier != null // keychain 里有限流档位const profileInfo = haveProfileAlready // 数据齐全 → 跳过 /api/oauth/profile 往返 ? null // (源码注释:例行刷新都满足此条件,全 fleet 每天省约 700 万请求) : await fetchProfileInfo(accessToken) // 不齐全 → 补一次网络调用拿全为什么这样设计:这段注释里还埋着一个微妙的 bug 防御,值得逐句读。它说:判断"已有 profile"时必须同时检查 keychain(secure storage),不能只看 config——因为 CLAUDE_CODE_OAUTH_REFRESH_TOKEN 重登录路径会在本函数返回后执行 performLogout(),把 keychain 清空。如果这里只查 config 就跳过 fetch、返回 subscriptionType: null,下游会写入 null ?? (已被清空的) ?? null = null——付费用户的订阅类型被永久丢失,且之后每次刷新都看到"config 字段齐全"继续跳过,再也修不回来。正确做法是透传已有值(profileInfo?.subscriptionType ?? existing?.subscriptionType ?? null),让重登录路径写入 cached ?? wiped ?? null = cached。一个 if 条件背后是对整条数据流的推演——这就是"深度源码分析"的价值。
六、额度护栏:每个响应头里都藏着你的余额
Pro/Max 订阅的限流是"5 小时窗口 + 7 天窗口"双额度。Claude Code 不单独调 API 查余额——服务端在每个 API 响应里附带一组 anthropic-ratelimit-unified-* 头(unified limiter 的裁决),客户端解析后驱动 UI。核心逻辑全在 services/claudeAiLimits.ts(515 行)。
先看"提前预警"的配置表——它回答的问题是:"你烧额度的速度超过了窗口允许的速度"该怎么提醒(第 53-70 行):
📄 src/services/claudeAiLimits.ts (第 53-70 行)
const EARLY_WARNING_CONFIGS: EarlyWarningConfig[] = [ // 预警配置,按优先级排列(先查后查) { rateLimitType: 'five_hour', // 5 小时会话窗口 claimAbbrev: '5h', // 头缩写:anthropic-ratelimit-unified-5h-* windowSeconds: 5 * 60 * 60, // 窗口长度 = 5 小时(秒) thresholds: [{ utilization: 0.9, timePct: 0.72 }], // 窗口前 72% 时间就用了 ≥90% → 预警 }, { rateLimitType: 'seven_day', // 7 天周窗口 claimAbbrev: '7d', // 头缩写:anthropic-ratelimit-unified-7d-* windowSeconds: 7 * 24 * 60 * 60, // 窗口长度 = 7 天(秒) thresholds: [ // 三档阈值:越早烧完,预警越激进 { utilization: 0.75, timePct: 0.6 }, // 前 60% 时间用了 ≥75% → 预警 { utilization: 0.5, timePct: 0.35 }, // 前 35% 时间用了 ≥50% → 预警 { utilization: 0.25, timePct: 0.15 }, // 前 15% 时间用了 ≥25% → 预警(烧得太猛) ], },]为什么这样设计:"utilization × timePct"双维度判断比单纯看用量比例聪明得多。只看 utilization,一个用户周一用掉 75%、剩下六天随便用——完全健康;但周五才用到 25%,说明他这周的消费节奏注定撞墙。timeProgress = (now - windowStart) / windowSeconds(第 98-103 行)把"时间走到哪了"量化出来,两个条件同时满足才预警:用量高 + 时间早= 不可持续。7 天窗口的三档阈值形成梯度:越接近窗口起点触发,说明烧得越快。
除了被动解析响应头,客户端还会主动探测一次——checkQuotaStatus()(第 220-249 行)用一个极便宜的请求换回全部额度头:
📄 src/services/claudeAiLimits.ts (第 199-248 行)
async function makeTestQuery() { // 构造一个极便宜的探测请求 const model = getSmallFastModel() // 用最小最快的模型(Haiku 级),成本可忽略 const anthropic = await getAnthropicClient({ // 创建客户端(探测专用配置) maxRetries: 0, // 配额检查不重试:失败不值得放大负载 model, source: 'quota_check', // 标记来源,遥测里能和真实查询区分开 }) return anthropic.beta.messages // beta 命名空间(thinking 等特性) .create({ // 发起 messages.create 请求 model, max_tokens: 1, // 只要 1 个 token:要的是响应头,不是内容 messages: [{ role: 'user', content: 'quota' }], // 最小 prompt,占位即可 metadata: getAPIMetadata(), // 标准 API 元数据(会话/用户标识) }) .asResponse() // asResponse():拿原始 HTTP 响应,才能读额度头export async function checkQuotaStatus(): Promise<void> { // 主动配额探测入口(启动时调用) if (isEssentialTrafficOnly()) { // 隐私模式:非必要流量全禁 → 直接跳过 return // 尊重用户"只发必要请求"的设定 } if (!shouldProcessRateLimits(isClaudeAISubscriber())) { // 只有真订阅者(或 mock 测试)才需要查额度 return // API key 用户走另一套限流,不处理 } if (getIsNonInteractiveSession()) { // -p headless 模式:真实查询马上就要发出去 return // 它的响应头自然会更新额度 → 省掉这次探测调用 } try { // 探测可能失败:429/5xx 也要从错误里捞额度头 const raw = await makeTestQuery() // 发出探测请求(1 token) extractQuotaStatusFromHeaders(raw.headers) // 从成功响应的头里解析额度状态 } catch (error) { if (error instanceof APIError) { // 被拒了?429/5xx 的错误响应同样带额度头 extractQuotaStatusFromError(error) // → 从错误对象里提取(见下节) } }为什么这样设计:max_tokens: 1 + .asResponse() 是"用最小代价买信息"的典范——额度状态全在响应头里,正文一个 token 都不需要。而 catch 分支体现了另一个原则:被拒绝本身就是最强的额度信号(extractQuotaStatusFromError 对 429 强制置 status='rejected'),所以探测失败也不浪费。三个前置守卫(隐私模式 / 非订阅者 / headless)则说明这个"主动探测"被刻意压到最低频——能省就省,和第五节的 700 万请求优化是同一个成本哲学。
真正解析额度的核心函数 computeNewLimitsFromHeaders()(第 376-436 行)把一组头翻译成 UI 可消费的状态:
📄 src/services/claudeAiLimits.ts (第 376-424 行)
// 从响应头计算新额度状态(纯函数) headers: globalThis.Headers, // 每个 API 响应都携带这组额度头): ClaudeAILimits { const status = // unified limiter 对本次请求的裁决 (headers.get('anthropic-ratelimit-unified-status') as QuotaStatus) || 'allowed' // allowed / allowed_warning / rejected const resetsAtHeader = headers.get('anthropic-ratelimit-unified-reset') // 窗口重置时间(unix 秒) const resetsAt = resetsAtHeader ? Number(resetsAtHeader) : undefined // UI 用它显示"X 小时后重置" const unifiedRateLimitFallbackAvailable = // 是否有备用模型可用(Opus 额度将尽时提示降级) headers.get('anthropic-ratelimit-unified-fallback') === 'available' // 只影响提示,不改变实际使用的模型 const rateLimitType = headers.get( // 这条限制属于哪个窗口 'anthropic-ratelimit-unified-representative-claim', // five_hour / seven_day / overage... ) as RateLimitType | null // 映射到展示名:session limit / weekly limit const overageStatus = headers.get( // extra usage(超额)通道状态 'anthropic-ratelimit-unified-overage-status', // allowed/rejected——主额度烧完能否"加钱续命" ) as QuotaStatus | null // 类型断言:头里的 JSON 就是 QuotaStatus const overageDisabledReason = headers.get( // overage 被禁的原因(12 种具体原因 + unknown) 'anthropic-ratelimit-unified-overage-disabled-reason', // out_of_credits / org_level_disabled / ... ) as OverageDisabledReason | null // UI 据此告诉用户"为什么不能超额" const isUsingOverage = // "主额度被拒 + overage 放行" = 正在烧额外用量 status === 'rejected' && // 两个条件缺一不可 allowed_warning') // 超额通道放行(含预警态) let finalStatus: QuotaStatus = status // 默认采用服务端裁决 if (status === 'allowed' || status === 'allowed_warning') { // 还没被拒 → 检查是否需要提前预警 const earlyWarning = getEarlyWarningFromHeaders( // 两级判断:surpassed-threshold 头优先,时间相对阈值兜底 headers, // (上一节的 EARLY_WARNING_CONFIGS 在这里生效) unifiedRateLimitFallbackAvailable, // 把"有无备用模型"一并传给预警状态 ) if (earlyWarning) { return earlyWarning // 命中预警 → 升级为 allowed_warning(UI 显示黄色提示) } }为什么这样设计:注意 isUsingOverage 的判定——"主额度 rejected + overage allowed"这个组合状态是客户端自己推导出来的,服务端并不直接发一个"你在用超额"的头。这说明额度系统的设计哲学:服务端只发原子事实(各通道的 status),语义组合交给客户端——同一组头可以支撑不同产品形态的 UI 逻辑。另外 overageDisabledReason 有 12 种具体取值(org/seat/member/group/service 五个层级 × disabled/zero_credit_limit 两类原因,外加 not_provisioned、no_limits_configured),并且会被 cacheExtraUsageDisabledReason() 持久化到全局配置——跨会话保留"为什么不能超额"的答案,用户下次问起时不用重新推理。
下表汇总本讲涉及的全部额度响应头:
七、token 估算:countTokens API 不可用时的兜底
上下文压缩(第 12 讲的主题)和工具结果截断都需要知道"这段内容有多少 token"。首选是调 messages.countTokens API,但 Bedrock/Vertex 上该接口时有时无——所以 services/tokenEstimation.ts(495 行)准备了一条纯本地估算路径,核心公式朴素到令人发笑:
📄 src/services/tokenEstimation.ts (第 203-242 行)
export function roughTokenCountEstimation( // 离线估算:零网络请求 content: string, // 待估算的文本内容 bytesPerToken: number = 4, // 默认假设:约 4 字符/token(英文经验值)): number { // 返回估算的 token 数 return Math.round(content.length / bytesPerToken) // 长度 ÷ 比例 ≈ token 数,四舍五入取整}export function bytesPerTokenForFileType(fileExtension: string): number { // 按文件类型修正比例 switch (fileExtension) { // 按文件类型选 bytes/token 系数 case 'json': // 密集 JSON 全是单字符 token({ } : , ") case 'jsonl': // → 真实比例接近 2,而不是默认的 4 case 'jsonc': // fallthrough:和 json/jsonl 一样 return 2 // 若仍按 4 算,token 数会被低估一半 default: // 非 JSON 类:4 字符/token return 4 // 其他类型用通用经验值 }}export function roughTokenCountEstimationForFileType( // 文件类型感知版入口(工具结果截断用它) content: string, // 内容 fileExtension: string, // 扩展名:json/jsonl/jsonc 走精确比例): number { // 返回估算的 token 数 return roughTokenCountEstimation( // 复用同一公式,只换比例参数 content, bytesPerTokenForFileType(fileExtension), // JSON → 2,其余 → 4 )}为什么这样设计:源码注释点明了风险方向:"an underestimate can let an oversized tool result slip into the conversation"——估算偏低会让超大的工具结果溜进上下文,直接撑爆窗口。所以 JSON 单独给 2(密集标点使真实 bytes/token 接近 2),宁可高估不可低估。这条兜底路径的调用方还包括 countTokensViaHaikuFallback():当 countTokens API 不可用时,退而用 Haiku 模型"数 token"——Vertex global region 没有 Haiku、Bedrock 的 Haiku 3.5 不支持 thinking block,这两种情况再降级到 Sonnet。一条估算链上叠了三层 fallback,每一层都有明确的适用边界。
八、全链路数据流:登录 → 刷新 → 额度护栏
登录路径(OAuth 授权码 + PKCE)
① 起监听:AuthCodeListener.start(port=0)
OS 分配空闲端口,服务器保持打开直到被使用(防 TOCTOU)。
▼
② 建 URL:PKCE challenge + state,双通道
🔹 自动:redirect_uri=localhost:{port}/callback🔹 手动:MANUAL_REDIRECT_URL(无浏览器兜底)
▼
③ 浏览器授权:claude.ai / console 登录页
用户完成登录;headless 环境走手动通道复制 code。
▼
④ 回调捕获:/callback?code&state → 校验 state
state 不匹配即 400;通过则扣住响应、resolve Promise。
▼
⑤ 换 token:POST token_url + code_verifier
🔹 成功 → 302 跳成功页,token 入 keychain🔹 profile 本地齐全则跳过 /api/oauth/profile(省 7M req/day)
额度路径(每个 API 响应都走一遍)
① 服务端附头:anthropic-ratelimit-unified-*
unified limiter 裁决随每个响应下发,无需专门查询。
▼
② 解析:extractQuotaStatusFromHeaders
computeNewLimitsFromHeaders → status/resetsAt/overage 状态。
▼
③ 预警判断:两级策略
🔹 首选:surpassed-threshold 头(服务端标记)🔹 兜底:时间相对阈值(5h/7d EARLY_WARNING_CONFIGS)
▼
④ 通知:emitStatusChange → UI + 埋点
🔹 statusListeners 驱动限流提示/倒计时🔹 429 错误路径:extractQuotaStatusFromError 强制 rejected
九、本讲小结:三道护栏,一个成本哲学
把本讲的三条防线放在一起看——它们分别守护"身份""节奏""余额"三个维度:
三道护栏总览
🛡️ 身份线:OAuth token 生命周期
触发:expiresAt - now ≤ 5min(isOAuthTokenExpired)数据源:OS keychain + 全局配置动作:进程内 Promise 去重 → 跨进程文件锁 → double-check → refresh grant(允许 scope 扩展,免重新登录)
🛡️ 节奏线:额度提前预警
触发:utilization ≥ 阈值 且 timeProgress ≤ 比例(或服务端 surpassed-threshold 头)数据源:每个响应的 -utilization / -reset 头动作:allowed_warning UI + fallback 模型提示,给用户改节奏的机会
🛡️ 余额线:硬限流裁决
触发:status=rejected(响应头或 429 错误)数据源:unified-status / overage-* 头动作:显示重置倒计时;overage 放行则继续烧额外用量并标记 isUsingOverage
本讲小结:Claude Code 的认证与额度系统有一条贯穿始终的成本哲学——能本地判断就不发网络请求,能复用响应头就不调专门 API:token 刷新前 double-check 省掉无谓的 refresh grant,profile 拉取靠"双来源齐全"跳过(全 fleet 每天省约 700 万请求),配额探测用 max_tokens:1 的最小请求换全部额度头。而安全侧则是层层设防:PKCE 替代 secret、state 防 CSRF、redirect_uri 精确匹配、跨进程文件锁 + double-check 防并发刷新踩踏——每一层都对应一种真实攻击或竞态场景,没有一行是"以防万一"的装饰代码。
📚 系列导航
← 第 8 讲:SSE 流式解析与重试退避
→ 第 10 讲:消息模型与会话流
关注公众号「AI技术推荐官」获取更多源码解析内容
📌 每天 30 条,挑出真能用的 AI 东西
UnitAI 每天从 GitHub / Hacker News / Hugging Face 抓一遍 AI 热榜,还收录了 50+ 个上过榜的项目,能按分类、星级、上榜天数筛。免费看,不用注册。

长按识别二维码打开 · 或点左下角「阅读原文」





