企业官网建设流程全解析

CodexBar Claude 用量数据源全解析：OAuth API、Web Cookie、CLI PTY 与本地成本扫描

【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar

CodexBar 是一个无需登录即可展示 OpenAI Codex 与 Claude Code 用量统计的菜单栏应用。本文以仓库 docs/claude.md 为核心，系统讲解 CodexBar 为 Claude 提供的四类用量数据路径（OAuth API、Web API/浏览器 Cookie、CLI PTY、本地成本日志扫描）及组织级 Admin API，完整覆盖各数据源的配置入口、凭证形态、端点、解析映射与故障处理行为，并结合 Sources/CodexBarCore/Providers/Claude 下的源码实现，说明自动选源、Keychain 提示策略、claude-swap 多账户切换与成本去重等底层机制。读完本文，你可以准确理解 Claude 用量在 CodexBar 中"从凭证到菜单栏"的完整链路，并能针对性地配置、排障与扩展。

Claude 支持三条用量数据路径（OAuth、Web、CLI）加一条本地成本扫描路径。主 provider 流水线使用运行时相关的自动选择，但代码库中在重构完成前仍存在多个活跃的 Claude.auto决策点；精确的当前状态一致性契约见 docs/refactor/claude-current-baseline.md。

当配置了 Anthropic Admin API 密钥时，Claude 还可以在同一个内联仪表盘模式（与 OpenAI API provider 相同）中展示组织级的花费/消息数/Token 数。

数据源与选择顺序

默认选择（Debug 菜单未启用）

• 如果配置了 Admin API 密钥，则使用 Admin API 策略获取 Claude API 的花费/用量。
• App 运行时主流水线：OAuth API → CLI PTY → Web API。
• CLI 运行时主流水线：Web API → CLI PTY。
• 显式选择模式（OAuth/Web/CLI）会绕过自动回退。
• 一个更底层的直接 Claude fetcher 仍包含独立的.auto顺序。该不一致性记录在 docs/refactor/claude-current-baseline.md。

选择用量来源：

• 偏好设置 → Providers → Claude → Usage source（Auto / OAuth / Web / CLI）。

Admin API 密钥配置：

• 偏好设置 → Providers → Claude → Admin API key，存储在~/.codexbar/config.json。
• CLI/环境变量：printf '%s' "$ANTHROPIC_ADMIN_KEY" | codexbar config set-api-key --provider claude --stdin。
• Token 账户也可以持有sk-ant-admin...前缀的密钥；它们会路由到 Admin API，而不是 cookie/OAuth 用量。
• 环境变量回退：ANTHROPIC_ADMIN_KEY。

从源码看，主 provider 流水线的策略解析在 ClaudeProviderDescriptor.swift 中完成：先处理"显式选中 Token 账户"（Admin API / OAuth / Web 账户分别返回单一策略，且不回退到环境级凭证），随后处理claudeOwnerCLIRecoveryOnly恢复场景，再检查sourceMode == .api或自动模式下的 Admin API 密钥，最后交给ClaudeSourcePlanner规划可执行步骤。ClaudeProviderDescriptor.resolveStrategies中对缺失或格式错误的选中账户凭证直接返回空策略数组，注释明确"被选中的账户是权威边界，绝不能回退到环境 CLI、浏览器会话或全局 API 密钥并打上该账户的标签"。

关键行为矩阵

运行时与来源模式的完整矩阵（引自 docs/refactor/claude-current-baseline.md，由ClaudeProviderDescriptor通过ProviderFetchPlan/ProviderFetchPipeline拥有）：

规划器实现位于 ClaudeSourcePlanner.swift：.auto在 app 运行时产出oauth/cli/web三步，在 CLI 运行时产出web/cli两步；显式.oauth在 app 运行时额外带一个explicitOAuthOwnerCLIFallback（仅当 OAuth 凭证由 Claude CLI 所有且需要委托刷新时）。isPlausiblyAvailable决定步骤是否进入executionSteps：OAuth 依赖hasOAuthCredentials，Web 依赖hasWebSession，CLI 依赖hasCLI。

其他活跃的.auto决策点

基线文档明确记录了两个不一致的决策点：

后者实现在 ClaudeUsageFetcher.swift 的StepExecutor.executeAuto：按计划步骤逐个执行，失败且非取消时记录日志并continue到下一步。ClaudeUsageTests.swift已直接刻画了可达的ClaudeUsageFetcher(.auto)分支（OAuth/Web/CLI 均可用时选 OAuth；OAuth 不可用时 Web 优先于 CLI）；成功选中 CLI 及 CLI 失败回退 OAuth 的分支因缺少稳定的测试接缝，仍以代码审查加周边回归覆盖为准。

Debug 选择（Debug 菜单启用）

• Debug 面板可以强制 OAuth / Web / CLI。
• Web 附加项是内部专用的（不会在 Providers 面板暴露）。

Admin API（组织级用量）

• 密钥前缀：sk-ant-admin...。
• 端点：
  • /v1/organizations/cost_report
  • /v1/organizations/usage_report/messages
• 输出：
  • 今日/7 天/30 天花费与消息/Token 汇总。
  • 当存在日粒度桶时，展示内联的 30 天仪表盘图表。
  • 身份登录方式：Admin API。

实现位于 ClaudeAdminAPIUsageFetcher.swift：两个端点 URL 在源码中显式定义（https://api.anthropic.com/v1/organizations/cost_report与https://api.anthropic.com/v1/organizations/usage_report/messages）。请求携带anthropic-version: 2023-06-01、x-api-key头、20 秒超时；cost 请求按description分组、messages 请求按model分组，均以bucket_width=1d、limit=31拉取最多 31 个日桶。花费金额按 Anthropic 最低美元单位字符串解析并除以 100 转为美元（usdFromAnthropicLowestUnitAmount）。Token 计数区分uncachedInputTokens、cacheCreation、cacheReadInputTokens、outputTokens四类并累加总 Token。

Keychain 提示策略（Claude OAuth）

• 偏好设置 → Providers → Claude → Keychain prompt policy。
• 选项：
  • Never prompt：绝不尝试交互式 Claude OAuth Keychain 提示。
  • Only on user action（默认）：交互式提示仅保留给用户发起的修复流程。
  • Always allow prompts：允许在用户流程和后台流程中都进行交互式提示。
• 该设置只影响 Claude OAuth Keychain 提示行为，不会切换你的 Claude 用量来源。
• 如果偏好设置 → Advanced → Disable Keychain access 已启用，该策略仍然可见但处于非激活状态，直到重新启用 Keychain 访问。

从 ClaudeUsageFetcher.swift 的ClaudeOAuthKeychainPromptPolicy.canPromptNow可见三档语义：never恒为 false；onlyOnUserAction仅在interaction == .userInitiated时允许；always恒为 true。shouldRespectKeychainPromptCooldown在非用户发起场景下尊重冷却，避免轰炸系统对话框；用户动作（打开菜单 / 刷新 / 设置）可绕过冷却——currentClaudeOAuthInteractivePromptPolicy在用户发起交互时会调用ClaudeOAuthKeychainAccessGate.clearDenied()清除先前记录的拒绝状态。

基线文档补充的提示/冷却行为（后续重构必须保留的契约）：

• 默认 Claude keychain 提示模式为onlyOnUserAction。
• 提示策略仅在 Claude OAuth 读取策略为securityFramework时适用。
• 用户发起的交互会在重试可用性或修复前清除先前的 Claude keychain 冷却拒绝。
• 启动引导提示仅在同时满足以下条件时允许：运行时为 app、交互为后台、刷新阶段为 startup、提示模式为onlyOnUserAction、且不存在缓存的 Claude 凭证。
• 当提示策略为onlyOnUserAction且调用方未显式允许后台委托刷新时，后台委托刷新被阻止。
• 提示模式never阻止委托刷新尝试。
• 过期凭证的所有者行为：.claudeCLI走委托刷新路径，.codexbar走直接刷新路径，.environment不自动刷新。

委托刷新被抑制时，后台刷新会以ClaudeUsageError.oauthFailed抛出可读错误，提示用户点击 CodexBar 菜单中的 Refresh 重试。

OAuth API（首选来源）

凭证来源（按优先级）：

• CodexBar OAuth 缓存（可用时）。
• 文件回退：~/.claude/.credentials.json。
• Claude CLI Keychain 引导/修复回退：Claude Code-credentials。

对于默认 CLI profile，过期的缓存凭证可以在文件回退后采用已变更的全新 CLI Keychain Token。既有的直接读取同意、提示策略、冷却和非交互读取检查仍然生效。自定义 profile 不会从未加作用域的全局条目恢复，且此同步永远不会重写 CLI 凭证。

在 Claude Code 2.1.x 上，Claude Code-credentials可能只包含 MCP 服务器 OAuth 状态（mcpOAuth）而没有claudeAiOauth。CodexBar 将其视为 OAuth 配置错误：不运行后台委托的claude /status刷新，而是给出重新授权指引。此时可改用 Web 或 CLI 用量来源，或恢复有效的 Claude OAuth Keychain 条目（参见 issue #1844）。

关键约束：

• 需要user:profile作用域（只有user:inference的 CLI Token 无法调用 usage）。
• 端点：
  • GET https://api.anthropic.com/api/oauth/usage
  • GET https://api.anthropic.com/api/oauth/profile→ 账户身份用于校验可选的 Web 增强数据是否属于同一 Claude 账户。
• 请求头：
  • Authorization: Bearer <access_token>
  • anthropic-beta: oauth-2025-04-20
• 窗口映射：
  • five_hour→ 会话窗口。
  • seven_day→ 周窗口；当five_hour缺失或无利用率时，也作为主回退。
  • seven_day_sonnet/seven_day_opus→ 模型专属周窗口。
  • limits[].weekly_scoped→ 模型专属周窗口；通用的All models作用域保留在主周行。
  • 菜单将作用域标题本地化为"模型名 + 周时长"；规范化快照与 CLI 标题保持不变。
  • seven_day_routines/seven_day_cowork→ Daily Routines 额外窗口。
  • Claude Design/Omelette 键被忽略，因为 Claude Design 与主 Claude 用量共享同一限制。
  • extra_usage→ Extra usage 花费（月度花费/限制）。
• 偏好设置 → Providers → Claude → Show Daily Routines usage 只在菜单和 provider 预览中隐藏 Daily Routines 行。全局的可选积分与额外用量设置是它的总开关；Claude 专属设置不改变抓取、历史、通知、组件、模型作用域周限制、hooks 或 CLI 输出。
• 偏好设置 → Providers → Claude → Show model-specific weekly usage in widgets 控制桌面组件中的模型作用域周配额行。默认关闭；开启后显示每个带claude-weekly-scoped-标识的已知 Claude 窗口（例如 Fable）。再次关闭也会丢弃先前快照持久化的作用域行。它不改变抓取、菜单、历史、通知、hooks 或 CLI 输出。

刷新同一已识别账户的凭证会保留配额阈值告警历史：剩余配额恢复到阈值以上时告警重新武装，并在之后再次向下穿越阈值时触发。未知账户所有权会退役无主告警状态，而不是在可能不同的账户之间共享。

成功的 OAuth 登录会启用 Claude 并保留所选用量来源。默认 Auto 来源下，OAuth 在可读时保持优先，OAuth 凭证不可用时 CLI/Web 回退仍可用。

Claude Code 会定期轮换其Claude Code-credentialsKeychain 条目，并可能替换授予 CodexBar 的 ACL 读取权限。Auto 会把这种情况视为 OAuth 来源失败，复用最近的成功的 CLI 结果或继续走向 CLI/Web，而不会把现有凭证误报为缺失。手动 Refresh 可以重新授予 Keychain 访问；选择 CLI 或 Web 可以避免外部 Keychain 依赖。

当所有实时 Auto 来源都失败时，CodexBar 会保留history/claude.json中最后一次捕获的会话/周百分比作为过期数据显示，并展示其捕获时间而不是清空配额条。恢复的历史和 CLI 抓取的百分比都显示"Limited usage detail"：该警告描述的是保真度降低，而非历史捕获的来源。这不改变登录或刷新恢复动作。

计划推断：优先使用subscriptionType；rate_limit_tier回退为 Max/Pro/Team/Enterprise。当 Max 的rate_limit_tier携带用量倍数（default_claude_max_5x/default_claude_max_20x）时，标签中显示为 "Max 5x" / "Max 20x"。

OAuth 作用域校验在 ClaudeUsageFetcher.swift 的validateRequiredOAuthScope中强制：凭证scopes不含user:profile时抛错并提示claude setup-token重新生成凭证或切换 Web/CLI 来源。403 响应体包含user:profile时也走同一提示路径。成功请求后，历史记录按凭证的单向所有者标识符（oauthHistoryOwnerIdentifier）作用域隔离；代码刻意"不要在一次成功请求后拿获胜凭证去和 Claude Code 的外部 Keychain 条目比较"（keychainMatch在 owner 为.claudeCLI时标记为.unavailable）。

Web API（Cookie 抓取）

• 偏好设置 → Providers → Claude → Cookie source（Automatic 或 Manual）。
• Manual 模式接受 claude.ai 请求中的Cookie:头。
• 多账户手动 Token：向~/.codexbar/config.json（tokenAccounts）添加条目，并将 Claude cookies 设为 Manual。菜单可以堆叠显示所有账户或显示切换条（偏好设置 → Advanced → Display）。
• Claude Token 账户接受sessionKeycookie 或 OAuth 访问 Token（sk-ant-oat...）。OAuth Token 账户路由到 OAuth 路径并禁用 cookie 模式；session-key 或 cookie 头账户保持手动 cookie 模式。精确的边缘路由规则记录在 docs/refactor/claude-current-baseline.md。

Token 账户路由基线（来自 TokenAccountSupport.swift 的字符串启发式与两个边缘所有者）：

• 接受的输入形态：sk-ant-oat...原始 OAuth Token、Bearer sk-ant-oat...输入、原始 session key、完整 cookie 头。
• OAuth Token 形态的输入不会被当作 cookie。
• Cookie/头形态的输入是任何已包含Cookie:或=的值。
• App 侧：OAuth Token 账户保持用量来源设置不变、禁用 cookie 模式（.off）、清空手动 cookie 头，依赖环境 Token 注入；session-key/cookie 头账户保持来源设置、强制手动 cookie 模式，并把原始 session key 规范化为sessionKey=<value>。
• CLI 侧：OAuth Token 账户把有效来源模式从auto改为oauth、禁用 cookie 模式、省略手动 cookie 头并注入CODEXBAR_CLAUDE_OAUTH_TOKEN；session-key/cookie 头账户保持 cookie/manual 模式。

Cookie 来源顺序（macOS）：

1. Safari：~/Library/Cookies/Cookies.binarycookies
2. Chrome/Chromium 系：~/Library/Application Support/Google/Chrome/*/Cookies
3. Firefox：~/Library/Application Support/Firefox/Profiles/*/cookies.sqlite

• 域名：claude.ai。
• 必需的 cookie 名：sessionKey（值前缀sk-ant-...）。
• 缓存 cookie：Keychain 缓存com.steipete.codexbar.cache（账户cookie.claude，含来源与时间戳）。在重新从浏览器导入前会先复用。
• API 调用（全部带Cookie: sessionKey=<value>）：
  • GET https://claude.ai/api/organizations→ org UUID。
  • GET https://claude.ai/api/organizations/{orgId}/usage→ session/weekly/opus。
  • GET https://claude.ai/api/organizations/{orgId}/overage_spend_limit→ Extra usage 花费/限制。
  • GET https://claude.ai/api/organizations/{orgId}/prepaid/credits→ 剩余 Usage credits 余额。
  • GET https://claude.ai/api/account→ email + 计划提示。
• 输出：
  • Session + weekly + 模型专属百分比。
  • usage API 返回时的 Daily Routines 额外窗口。
  • Extra usage 花费/限制（若启用）。
  • 剩余 Usage credits 余额（若启用）。
  • 账户 email + 推断计划。

claude.ai 上的 Cloudflare 挑战是网络路径限制，而不是过期 cookie 信号。CodexBar 会保留缓存的 cookie 和先前的配额快照、识别该挑战并链接到设置。在该网络下可选择 OAuth 获取实时配额窗口（Web 专属的 Usage credits 余额不可用），或换一个网络。显式 Web 模式是终端的，绝不以 OAuth 凭证作为回退读取。

实现细节见 ClaudeWebAPIFetcher.swift：基 URL 为https://claude.ai/api，浏览器 cookie 导入通过BrowserCookieClient，且 Web 抓取仅在 macOS 上受支持（isSupportedOnCurrentPlatform在非 macOS 返回 false）。所有浏览器抓取通过ClaudeWebBrowserFetchGateactor 串行化，防止并发抓取互相干扰；FetchError.cloudflareChallenge的错误文案明确说明"重新认证也无济于事"，并指引切换 OAuth 或更换网络。Web 抓取整体受ClaudeWebFetchStrategy的截止时间预算约束（ClaudeWebFetchDeadlineState记录 deadline，BoundedTaskJoin在预算内完成可用性探测与抓取，超时抛timedOut）。

Web 增强（siloing 与 web-enrichment 基线）

当主来源是 OAuth 或 CLI 时，Claude Web 增强仅限 extra usage 附加数据（基线文档 docs/refactor/claude-current-baseline.md）：

• Web 附加数据可以补充可选费率窗口，并可在providerCost缺失时填充它。
• 匹配的 prepaid 余额可以增强既有providerCost，而不会替换其花费/限制值。
• OAuth 增强调用GET /api/oauth/profile；只有当 email 或组织 UUID 与主 Claude 账户匹配时才合并 Web 数据。
• Web 附加数据不得替换主来源的accountEmail、accountOrganization或loginMethod。
• 快照身份保持 provider 作用域于 Claude。

该行为由 ClaudeUsageFetcher.swift 的applyWebExtrasIfNeeded实现。

claude-swap 多账户（opt-in）

多账户设计文档见 docs/claude-multi-account-and-status-items.md。下面完整归纳 docs/claude.md 中的行为契约。

设置：偏好设置 → Providers → Claude → "Read accounts from claude-swap"，然后把路径指向cswap可执行文件（例如~/.local/bin/cswap）。版本探测在启动探测失败或被取消后会重试；被替换的刷新不能覆盖更新的结果；禁用适配器或更改其可执行文件会清除先前检测到的版本。

行为：每次 Claude 刷新时，CodexBar 独立于环境 Claude 抓取运行cswap --list --json（无 shell、固定参数、有界运行时间与输出），要求schemaVersion == 1，只解析插槽号、激活状态、用量状态、email（仅显示）、仅显示的organizationName（始终存在、可为空）、非空时可选的alias（仅显示）、5 小时/7 天窗口，以及usage.scoped中可选的模型作用域周窗口。身份保持为claude-swap:<slot>；组织名与别名绝不作身份使用。当两个及以上插槽共享同一 email 时，卡片追加· organizationName或· Account N；用户选择的 cswap 别名替换该标签。唯一 email 保持仅显示 email。

展示：当 claude-swap 报告多个账户时，其账户替换环境/Token 账户的 Claude 卡片。应用遵循Menu → Multi-account layout：

• Segmented：显示账户按钮 + 一个活动账户卡片；挂起或失败的切换显示被请求账户的详情，而活动标记保持来源所有。过期或不可用账户仍可检查而不激活；选择活动账户会返回其卡片。适配器报告无活动账户时，菜单会明确说明而不是选中第一行。三个账户以上按钮换行为两行。Hide Personal Info 使用稳定的Account N插槽标签。
• Stacked：每账户一张卡片（活动账户在前，随后按数字插槽）。四个及以上账户时切换到紧凑布局（AccountMenuLayoutPlanner）：活动账户保留完整卡片，非活动账户折叠为单行（按剩余余量排序，最受限的在前，剩余低于 50%/10% 显示红/琥珀色，最健康的可激活账户带星标），健康行收进"N more accounts ready"摘要行。点击紧凑行会在当前菜单会话中展开该账户的完整卡片；摘要行揭示隐藏行。codexbar cards保持完整的逐账户输出。同一紧凑布局适用于所有堆叠多账户列表（任何 provider 的 Token 账户、扁平的 Codex 账户列表；工作区分组 Codex 列表保持分节堆叠布局）。
• 单账户也想用该展示时：启用"Show account card when only one account is available"，或在已解析配置文件（通常~/.config/codexbar/config.json；旧安装可能用~/.codexbar/config.json）的 Claude provider 上设置claudeSwapShowSingleAccount: true。该选项默认关闭；零账户仍用环境展示；账户身份是claude-swap:<slot>，绝不是显示 email。

终端范围：这种自动优先级仅限 cards，且在所有受支持的 CLI 平台上生效。显式指定 Claude provider 或--source auto仍适用；--account、--account-index、--all-accounts和显式非 auto 来源标志会绕过适配器。codexbar usage与 serve/usage//cost保持不变，而codexbar dashboard与GET /dashboard/v1/snapshot会在 Claude provider 行内为每个 swap 账户嵌套一个条目——默认完整身份，设置--identity redacted时对 email 本地部分打码。

隔离：CodexBar 绝不为此功能读取 claude-swap 或 Claude Code 的凭证存储；子进程自行处理其凭证访问。App 内，适配器失败会把最后成功的账户作为过期数据保留，在 provider 设置中显示错误，绝不影响环境 Claude 用量卡片。终端 cards 中，列表失败保留当前环境输出，追加一条独立的Claude (claude-swap)页脚条目，并以非零码退出。

哨兵状态：token_expired、api_key、keychain_unavailable、no_credentials及未知未来值在完整与简版 cards 中渲染为逐账户注释而非用量条。当unavailable表示 claude-swap 因窗口达 100% 而推迟轮询时，CodexBar 保留该插槽最后预计的用量条并指明已耗尽的窗口（5 小时会话、7 天周窗口和/或 Fable 等作用域模型）及重置时间——而不是显示"Usage fetch failed"。首次刷新已unavailable且无保留窗口时，仍注明轮询被推迟。活动行标记为[active]；任何 claude-swap 行都不推断计划徽章。

切换：带可用来源凭证的非活动账户显示"Switch Account…"。点击它恰好运行cswap --switch-to <slot> --json，验证带版本的结果与请求的插槽，然后同时刷新环境 Claude 用量和每个 claude-swap 账户卡片。切换是串行化的；不会自动切换。当 claude-swap 拥有账户展示时，独立的环境 OAuth 动作显示为"Sign in with Claude Code…"，不会添加或切换 claude-swap 账户。

过期、缺失、未知或 Keychain 不可访问的凭证保持不可操作。失败的切换仍在该账户上可见，且不会丢弃其最后一次成功用量。正在运行的 Claude Code 进程最长可能需要 claude-swap 的 Keychain 缓存间隔才能观察到新账户。

多个 claude-swap 账户——以及显式启用的单账户——优先于 Claude Token 账户展示（堆叠卡片与分段切换器）。

打包的合成验证截图（假的cswap可执行文件，无真实账户或凭证）：

模型作用域周窗口验证（合成数据，无真实账户或凭证）：

之前	之后

CLI PTY（回退来源）

• 在 PTY 会话中运行claude（ClaudeCLISession）。
• 默认行为：每次探测后退出；Debug → "Keep CLI sessions alive" 可让它在两次探测之间保持运行。
• 探测工作目录：~/Library/Application Support/CodexBar/ClaudeProbe，带有本地 Claude 设置，可在无头探测期间禁用 deep-link URL handler 注册。
• 瞬时探测退出后，CodexBar 会删除该专用ClaudeProbe项目目录下的 Claude Code.jsonl会话工件，以免后台/usage轮询污染用户的 Claude 项目历史。
• 命令流程：
  1. 以--allowed-tools ""（无工具）启动 CLI。
  2. 自动应答首次运行提示（信任文件、工作区、遥测）。
  3. 发送/usage，等待渲染面板；必要时发送 Enter 重试。
  4. 可选发送/status提取身份字段。
• 解析（ClaudeStatusProbe）：
  • 去除 ANSI，定位 "Current session" + "Current week" 头部。
  • 提取这些头部附近的剩余/已用百分比与重置文本。
  • 无法解析重置日期时，菜单保留其描述并只规范一次前导Reset/Resets标签，包括作用域周限制。
  • 存在时解析Account:与Org:行。
  • 成功的 CLI 配额读取即使缺少可选身份字段也会保留菜单的 Switch Account 动作。恢复的历史与失败的刷新不计为成功登录。
  • 直接暴露 CLI 错误（如 token 过期）。
  • 某些 Education 与组织托管的订阅只返回订阅通知，没有数字化的会话或周配额字段。CodexBar 将这些限制报告为不可用，保留本地花费/Token 历史可见，绝不由花费或 Token 总量推导配额百分比。

实现细节：ClaudeStatusProbe.fetch先解析claude二进制路径（支持CLAUDE_CLI_PATH环境覆盖），在共享 PTY 会话中按顺序执行/usage与/status捕获；/usage输出看起来像启动输出时重试一次。解析器使用TextParsing.stripANSICodes清理文本，裁剪到最后一个 Settings/Usage 面板，按标签子串定位百分比与重置时间，并在布局漂移时以顺序百分比抓取兜底；缺少 "Current session" 标签时抛parseFailed。ClaudeCLIRateLimitGate在检测到限流后阻塞后续 CLI 探测，并在成功读取后recordSuccess。CLI 抓取超时体系：auto 首次 12 秒、显式首次 24 秒、重试 60 秒（cliAutoProbeTimeout/cliProbeTimeout/cliRetryProbeTimeout）；PTY 失败且错误可恢复（超时、"still loading usage" 等）时，先尝试一次"直接 CLI"路径（时间预算为 PTY 超时的三分之一、6–8 秒），失败信息含 "subscription" 时以直接结果替换 PTY 错误。

成本用量（本地日志扫描）

来源根目录：

• 原生 Claude 日志：
  • $CLAUDE_CONFIG_DIR选择一个字面目录，并使用<root>/projects；路径中的逗号是其一部分。
  • 回退根目录：
    • ~/.config/claude/projects
    • ~/.claude/projects（Claude Code 与当前 Claude Desktop Code/Cowork CLI 会话）
    • 其他嵌入式 Claude Desktop 项目存储（若存在）：
      • ~/Library/Application Support/Claude/local-agent-mode-sessions/**/.claude/projects
      • ~/Library/Application Support/Claude/claude-code-sessions/**/.claude/projects
  • 当前 Claude Desktop 在claude-code-sessions下的元数据通过cliSessionId指向共享的 CLI 会话 JSONL；仅元数据的目录不作为用量来源。
• 受支持的 pi 兼容会话：
  • ~/.pi/agent/sessions/**/*.jsonl
  • ~/.omp/agent/sessions/**/*.jsonl

文件：原生项目根目录与发现的 Claude Desktop 项目根目录下的**/*.jsonl，以及受支持的 pi 兼容会话文件。

解析：

• 原生 Claude 日志解析type: "assistant"且带message.usage的行。
• 使用分模型 Token 计数（input、cache read/create、output）。
• 按message.id + requestId对流式分块去重（每个分块的 usage 是累积的）。
• pi 与 OMP 会话把anthropic助手的 usage 归属到 Claude，并按助手轮次时间戳分桶，因此单个 pi 兼容会话可以贡献给多个模型/天。
• 同一会话内匹配的助手条目 ID 跨根目录只计数一次；不同轮次则保留。

缓存：

• 原生 provider 缓存：~/Library/Caches/CodexBar/cost-usage/claude-v6.json
• 报表备忘录：~/Library/Caches/CodexBar/cost-usage/claude-v6.report-memo.json跨启动存储来源时间戳与日报表。仅在转录清单、缓存/定价工件、请求窗口与报表语义版本仍匹配时复用。
• Claude/Vertex 缓存工件独立于共享的 Codex 解析器指纹保留源文件身份。替换转录会重建其行，而不是把旧前缀合并进新后缀；真正的追加仍使用已保存的解析偏移。没有身份的旧条目在复用前会被重建一次（包括正常刷新防抖期间）。
• pi 兼容会话缓存：~/Library/Caches/CodexBar/cost-usage/pi-sessions-v8.json

CLAUDE_CONFIG_DIR的"字面目录"语义在 ClaudeConfigPaths.swift 中实现：configRoot把该环境变量的值当作一个字面路径（相对路径基于探测工作目录解析），只在未设置时回退到~/.claude；credentialsURL另外支持CLAUDE_SECURESTORAGE_CONFIG_DIR。主成本扫描入口是 CostUsageFetcher.swift，pi/OMP 扫描由 PiSessionCostScanner.swift 与 PiSessionCostCache.swift 承担。

关键文件索引

• OAuth：Sources/CodexBarCore/Providers/Claude/ClaudeOAuth（凭证模型、Keychain 访问门、委托刷新协调器、用量抓取与限流门）
• 来源规划与策略：ClaudeProviderDescriptor.swift、ClaudeSourcePlanner.swift、ClaudeUsageFetcher.swift
• Web API：ClaudeWebAPIFetcher.swift、ClaudeWebExtraRateWindowParser.swift
• CLI PTY：ClaudeStatusProbe.swift、ClaudeCLISession.swift
• Admin API：ClaudeAdminAPIUsageFetcher.swift、ClaudeAdminAPISettingsReader.swift
• claude-swap：Sources/CodexBarCore/Providers/Claude/ClaudeSwap
• 凭证路由与 Token 账户：ClaudeCredentialRouting.swift、TokenAccountSupport.swift
• 成本用量：CostUsageFetcher.swift、PiSessionCostScanner.swift、PiSessionCostCache.swift、Sources/CodexBarCore/Vendored/CostUsage
• 当前状态基线：docs/refactor/claude-current-baseline.md

【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar