夜雨聆风学习资料网

ARTICLE · 1379736

Claude Code 源码-认证 / OAuth / 额度护栏

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 上的全部参数,后面几节逐个展开:

参数
值 / 来源
作用
code_challenge
SHA256(code_verifier),S256
换 token 时验证"发起者身份",替代 client secret
state
32 字节 CSPRNG 随机数
CSRF 防护:回调必须原样带回,否则 400 拒绝
redirect_uri(自动)
http://localhost:{port}/callback
端口由 OS 分配(listen(0)),避免与其他应用冲突
redirect_uri(手动)
MANUAL_REDIRECT_URL 固定页
无浏览器环境兜底:网页展示 code,用户复制回 CLI
scope
ALL_OAUTH_SCOPES;inferenceOnly 时仅推理 scope
inference-only 场景签发长生命周期 token(SDK/CI)
expires_in
可选,调用方传入
SDK 控制协议可指定 token 有效期

二、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() 持久化到全局配置——跨会话保留"为什么不能超额"的答案,用户下次问起时不用重新推理。

下表汇总本讲涉及的全部额度响应头:

响应头(anthropic-ratelimit-unified- 前缀省略)
含义
客户端行为
status
allowed / allowed_warning / rejected
总裁决;rejected → 显示限流 UI + 重置倒计时
reset
窗口重置时间(unix 秒)
"X 小时后重置"倒计时;持久模式可睡到重置时刻
fallback
available / 缺省
Opus 额度将尽时提示可降级,不自动切换模型
representative-claim
five_hour / seven_day / overage…
映射展示名(session limit / weekly limit)
5h-utilization / 7d-utilization
0–1 用量比例(每窗口一份)
预警判断原料;getRawUtilization() 暴露给 statusline 脚本
{claim}-surpassed-threshold
服务端标记"已越过预警阈值"
header-based 预警(首选路径,优先于本地计算)
overage-status / overage-reset
超额通道状态与重置时间
主额度烧完时判断能否继续(isUsingOverage)
overage-disabled-reason
12 种原因 + unknown
解释"为何不能超额";缓存到配置跨会话保留

七、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+ 个上过榜的项目,能按分类、星级、上榜天数筛。免费看,不用注册。

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

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料