CodexBar 集成 Chutes 提供商：API Key 认证、订阅用量与配额窗口解析指南-创锋一号

CodexBar 集成 Chutes 提供商：API Key 认证、订阅用量与配额窗口解析指南

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

本指南完整讲解 CodexBar 如何通过手工配置的 API Key 读取 Chutes 的订阅与配额用量：从密钥的三种配置方式、底层三路 API 请求链，到"滚动四小时窗口 + 月度订阅用量"的主次仪表盘逻辑，再到 CLI 查看与常见故障排查。读完你将掌握在 CodexBar 中启用 Chutes 用量统计的完整流程，并能读懂其源码级数据解析与降级策略。

Chutes 服务背景与使用前提

Chutes 是一个以独立矿工节点提供去中心化推理后端的服务商。在接入 CodexBar 之前需要注意几点事实：

其服务条款受尼维斯（圣基茨和尼维斯）法律管辖，去中心化后端由独立矿工运行；
其定价面（pricing surface）历史上多次变动，应视为非长期稳定，在依赖某个套餐或费率之前，应先到 Chutes 官网核对当前定价；
因此，CodexBar 对 Chutes 的处理方式是"只读取用量快照、不做费率假设"：提供商的ProviderTokenCostConfig明确设置supportsTokenCost: false，费用历史不可用时会提示 "Chutes cost history is not available from CodexBar."（见 ChutesProviderDescriptor.swift）。

认证：三种配置 API Key 的方式

Chutes 提供商使用标准的cpk_...前缀 API Key，配置方式有三种：

1. 图形界面配置

在 CodexBar 的Settings → Providers → Chutes中粘贴 API Key。该设置项在源码中定义为 secure 类型字段，密钥持久化保存在~/.codexbar/config.json：

ProviderSettingsFieldDescriptor( id: "chutes-api-key", title: "API key", subtitle: "Stored in ~/.codexbar/config.json. Paste a Chutes API key.", kind: .secure, placeholder: "chutes key...", binding: context.providerConfigBinding(.apiKey), ...)

（见 ChutesProviderImplementation.swift）

2. 环境变量

export CHUTES_API_KEY="cpk_..."

环境变量名由源码中的apiKeyEnvironmentKey常量固定为CHUTES_API_KEY（见 ChutesSettingsReader.swift）。读取时会做清理：自动去除首尾空白与成对的引号，因此带引号的值也能正确识别。

3. CLI 配置

printf '%s' "$CHUTES_API_KEY" | codexbar config set-api-key --provider chutes --stdin

通过 stdin 传入密钥可以避免密钥出现在 shell 历史记录中。测试用例config API key projects into Chutes environment验证了 config 中的apiKey会被投射为CHUTES_API_KEY环境变量供抓取逻辑读取（见 ChutesProviderTests.swift）。

可用性判定：只要环境变量或配置中存在非空密钥，Chutes 提供商即视为可用（isAvailable逻辑见 ChutesProviderImplementation.swift）。

数据源：三路 API 请求链与降级策略

CodexBar 通过 Chutes 管理 API 读取用量，核心实现位于 ChutesUsageStats.swift 的ChutesUsageFetcher：

请求清单

顺序	请求	说明
1	`GET https://api.chutes.ai/users/me/subscription_usage`	订阅用量，必需
2	`GET https://api.chutes.ai/users/me/quotas`	当订阅数据缺少某个用量窗口时触发
3	`GET https://api.chutes.ai/users/me/quota_usage/{chute_id}`	有配额明细时逐个补充抓取

所有请求统一携带请求头Authorization: Bearer cpk_...与Accept: application/json，请求超时时间为 15 秒（见 ChutesUsageStats.swift）。

降级策略（源码级）

抓取流程是"订阅必选、配额尽力而为"的层层降级：

先请求subscription_usage。若解析结果同时包含滚动窗口和月度窗口，直接返回；
若订阅响应缺失任一窗口，则请求quotas端点补齐；
对quotas响应中每个带有chute_id（兼容chuteId、id键）的定义，再请求quota_usage/{chute_id}补充明细，并将明细合并回原定义；
合并后的配额数据若无有效用量，仍回退使用quotas的基础响应；
配额明细请求失败时不影响整体：除 401/403 会向上抛出外，其余错误一律吞掉并继续使用已有数据；
最终仍优先保留订阅上下文（订阅状态、套餐名、续费时间）——preservingSubscriptionContext(from:)方法会把配额窗口填充进订阅快照缺失的槽位（见 ChutesUsageStats.swift）。

测试no active subscription falls back to quotas endpoint精确验证了上述请求序列：subscription_usage → quotas → quota_usage/0（见 ChutesProviderTests.swift）。

响应结构兼容性

解析器（ChutesUsageParser）对服务端响应结构做了广泛兼容，这也是"先订阅后配额"链路能稳定工作的基础：

根结构：同时支持顶层字典、data/result包装，以及quotas数组直接返回；
字段别名：used/usage/consumed、limit/cap/quota/monthly_cap、remaining/balance/left等多组键名均可识别，且键名匹配忽略大小写与下划线（normalizedKey会去掉非字母数字字符）；
百分比归一化：小于 1 的数值会被视为小数自动乘以 100，且最终 clamp 到 0–100；
窗口时长：支持window_minutes、window_hours、window_days、window_seconds及"4h"、"30 days"这类文本形式；
时间戳：同时支持 ISO 8601（含/不含毫秒）与 Unix 秒/毫秒时间戳（见 ChutesUsageStats.swift）。

测试identical usage values keep distinct quota windows还验证了相同用量值的多个配额窗口不会因去重而丢失（见 ChutesProviderTests.swift）。

显示逻辑：四小时滚动窗口 + 月度订阅用量

Chutes 提供商在菜单栏与菜单卡片中的呈现遵循"主次仪表"模型，元数据定义于 ChutesProviderDescriptor.swift：

主表（primary）：滚动四小时窗口，会话标签为 "4-hour quota"（源码常量rollingWindowMinutes = 4 * 60）；
次表（secondary）：月度订阅用量，标签为 "Monthly quota"（源码常量monthlyWindowMinutes = 30 * 24 * 60）；
无订阅账户：仍可显示按量付费（pay-as-you-go）配额数据；
身份标识：登录方式显示为套餐名（如 "Pro"）；无订阅时显示 "No active subscription"；完全无数据时显示 "No usage data"（见 ChutesUsageStats.swift）。

主次窗口的选取规则

在 ChutesUsageStats.swift 的toUsageSnapshot()中：

primary 优先取滚动窗口；若无滚动窗口则取月度窗口；两者皆无时取第一个配额窗口；
secondary 优先取月度窗口；否则在已有滚动窗口时取第一个配额窗口；
订阅续费时间（subscriptionRenewsAt）优先取快照字段，缺省时回退到月度窗口的重置时间。

配额明细与重置文本分离

ChutesQuotaWindow.rateWindow(defaultWindowMinutes:)会把用量渲染为类似40/100 requests的明细文本（自动格式化为整数或两位小数，并追加单位），而重置倒计时文本（如 "Resets in …"）单独呈现。展示测试专门验证了菜单卡片、CLI 卡片与原生日志菜单中二者不会粘连成 "Resets 40/100 requests"（见 ChutesPresentationTests.swift）。

为什么保留原生抓取器

文档明确指出：Chutes 会明确接受"成功但无可用用量字段"的订阅负载作为无数据快照，而这种形状是当前插件快照契约所拒绝的。因此 Chutes 提供商始终使用原生抓取器（native fetcher）作为权威数据源，不走插件路径。测试missing usage fields returns no data snapshot without decode failure验证了这种负载不会导致解码失败，而是得到 primary/secondary 均为空的快照（见 ChutesProviderTests.swift）。

CLI 用法

命令行下直接指定提供商即可查看用量卡片：

codexbar --provider chutes

提供商在 CLI 中注册名为chutes，别名chutes.ai（见 ChutesProviderDescriptor.swift）。CLI 展示同样遵循主次仪表布局：主表显示四小时配额明细，次表显示月度配额明细。

故障排查

症状	处理方式
无数据	先用`curl`或浏览器确认该 Key 能读取`https://api.chutes.ai/users/me/subscription_usage`
`401`/`403`	Chutes 拒绝了该密钥：重新在 Chutes 控制台生成 Key，并在 CodexBar Settings → Providers → Chutes 中更新（源码中将 401/403 统一映射为`ChutesUsageError.invalidCredentials`，见 ChutesUsageStats.swift）
需要更换 API 地址	设置`CHUTES_API_URL`覆盖管理 API 基础 URL；但 CodexBar 只接受 HTTPS 端点，非 HTTPS 或裸主机格式会被`validateEndpointOverrides`拒绝并抛出`ChutesSettingsError.invalidEndpointOverride`（见 ChutesSettingsReader.swift）
密钥缺失	错误信息会明确提示在`~/.codexbar/config.json`或`CHUTES_API_KEY`中设置`apiKey`（见 ChutesUsageStats.swift）

企业官网建设流程全解析