CodexBar Neuralwatt Provider 接入指南:基于 API Key 的订阅 kWh 与预付费余额配额解析

CodexBar Neuralwatt Provider 接入指南:基于 API Key 的订阅 kWh 与预付费余额配额解析 CodexBar Neuralwatt Provider 接入指南基于 API Key 的订阅 kWh 与预付费余额配额解析【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBarNeuralwatt 是 CodexBar 中一个通过 API Key 读取账户配额的使用量数据源。Neuralwatt Cloud 采用基于能耗energy-based的定价模型配额接口同时暴露订阅 kWh 用量与预付费 USD 余额两套计费表面。本文基于仓库中的 docs/neuralwatt.md 及对应源码实现完整说明该 Provider 的接入方式、配额 API 协议、字段解析逻辑、重试机制与故障排查方法帮助你理解并复用这套配额读取方案。Neuralwatt 的计费模型与三类配额表面Neuralwatt Cloud 是一个 OpenAI 兼容的推理 API但其定价按能耗kWh计费与常见的按 token 计费模型不同。从文档与源码看一个账户下存在三个相互独立的配额表面配额表面关键字段计费行为在 CodexBar 中的呈现订阅 kWh 用量kwh_used/kwh_included按计费周期结算周期结束时重置主配额窗口primary重置日期为订阅周期结束日预付费 USD 余额credits_remaining_usd/total_credits_usd随用随扣不随计费周期重置通过充值补充独立的 pay-as-you-go 余额展示按密钥消费限额spent_usd/limit_usd可选配置按key.allowance.period如 monthly统计额外的配额窗口extraRateWindow这种订阅额度 预付费余额的双轨结构在实现中体现得尤为明确当订阅 kWh 仍可用而预付费余额为 0 时CodexBar 不会把余额归零误判为配额耗尽见下文源码分析。此外配额接口还会返回当前自然月消费usage.current_month.cost_usdCodexBar 会解析它供后续/报表使用但不作为可重置的配额窗口展示。快速接入三种 API Key 配置方式方式一CLI无需打开设置界面文档推荐直接通过codexbar命令写入密钥适合脚本化部署printf %s $NEURALWATT_API_KEY | codexbar config set-api-key --provider neuralwatt --stdin该命令的行为包括修剪输入管道传入的密钥首尾空白会被剔除对应 NeuralWattSettingsReader.swift 中的cleaned(_:)实现同时支持去除单双引号包裹写入配置文件默认写入~/.config/codexbar/config.json若已存在旧版~/.codexbar/config.json则写入该旧路径默认启用 Provider如需只保存密钥而不启用追加--no-enable参数。方式二设置界面打开Settings → Providers启用Neuralwatt打开https://portal.neuralwatt.com/dashboard创建或复制 API Key将密钥粘贴到 CodexBar 的 Neuralwatt Provider 设置中设置界面中的密钥字段在 NeuralWattProviderImplementation.swift 中定义为 secure 类型占位符sk-...密钥存储在 CodexBar 配置文件中同时支持在 CodexBar 中配置多个 Neuralwatt token 账户见 NeuralWattProviderDescriptor.swift 中的TokenAccountSupport其占位符同样为sk-...最小刷新间隔为 1 秒与配额接口限流对齐。方式三环境变量CodexBar 还支持通过环境变量注入NEURALWATT_API_KEYAPI KeyNEURALWATT_API_URLAPI 基础地址覆盖用于测试或自建代理场景值得注意的细节NEURALWATT_API_URL并非无条件生效。从 NeuralWattSettingsReader.swift 源码可见该覆盖值必须通过ProviderEndpointOverrideValidator.normalizedHTTPSURL校验即只允许 HTTPS URL 或裸主机名非法覆盖会抛出NeuralWattSettingsError.invalidEndpointOverride且该校验发生在发起任何请求之前对应测试fetch rejects endpoint override before sending API key见 NeuralWattUsageFetcherTests.swift。配额 API 协议与响应字段详解请求协议端点GET https://api.neuralwatt.com/v1/quota认证头Authorization: Bearer sk-...请求头Accept: application/json超时15 秒见 NeuralWattUsageFetcher.swift 中timeoutSeconds从 NeuralWattUsageFetcher.swift 的quotaURL(baseURL:)逻辑看若基础地址已以v1结尾则直接拼接quota否则拼接v1/quota这保证了NEURALWATT_API_URL指向任意层级地址时都能得到正确的配额路径。响应字段与用途文档明确列出 CodexBar 实际使用的字段结合源码模型NeuralWattQuotaResponse及其子结构可整理如下字段路径类型用途balance.credits_remaining_usdDouble?预付费余额剩余balance.total_credits_usdDouble?预付费余额总额balance.credits_used_usdDouble?预付费已用API 缺省时由 total − remaining 推导balance.accounting_methodString?计费方式Token/Energy用于身份标签兜底usage.current_month.cost_usdDouble?当前自然月消费仅解析不展示为重置窗口usage.current_month.energy_kwhDouble?当前自然月能耗subscription.planString?订阅计划名作为身份标签主来源subscription.current_period_endDate?订阅周期结束即配额重置时间subscription.kwh_includedDouble?周期内含 kWh 额度subscription.kwh_usedDouble?周期内已用 kWhsubscription.kwh_remainingDouble?周期内剩余 kWhkey.allowance.limit_usdDouble?按密钥限额上限key.allowance.spent_usdDouble?按密钥已消费key.allowance.periodString?限额周期如monthly用于窗口标题测试夹具 NeuralWattUsageFetcherTests.swift 给出了一个完整的响应示例可直接用于对照验证{ snapshot_at: 2026-04-16T18:30:00Z, balance: { credits_remaining_usd: 32.6774, total_credits_usd: 52.34, credits_used_usd: 19.6626, accounting_method: energy }, usage: { lifetime: { cost_usd: 243.9145, requests: 37801, tokens: 1235477176, energy_kwh: 15.6009 }, current_month: { cost_usd: 160.1463, requests: 23902, tokens: 1116658995, energy_kwh: 9.7278 } }, limits: { overage_limit_usd: null, rate_limit_tier: standard }, subscription: { plan: standard, status: active, billing_interval: month, current_period_start: 2026-04-11T05:05:25Z, current_period_end: 2026-05-11T05:05:25Z, auto_renew: true, kwh_included: 20.0, kwh_used: 13.9023, kwh_remaining: 6.0977, in_overage: false }, key: { name: my-production-key, allowance: { limit_usd: 50.0, period: monthly, spent_usd: 12.5, remaining_usd: 37.5, blocked: false } } }对应测试断言主配额窗口百分比为13.9023 / 20 × 100重置描述为13.90 / 20 kWh预付费余额作为providerCost展示密钥限额窗口标题为Key Monthly且不会出现current-month-spend窗口——印证了当月消费仅解析不展示的设计。源码级解析快照计算与边界处理缺失字段的推导credits_used_usd可能被 API 省略此时 CodexBar 按total − remaining推导。更细致的是NeuralWattUsageSnapshot中的effectiveUsedCredits/effectiveTotalCredits/effectiveRemainingCredits三套有效值逻辑见 NeuralWattUsageFetcher.swift直接字段有效时优先使用否则由其余两个字段互相推导所有数值必须通过validNonNegative有限且 ≥ 0或validPositive有限且 0校验非法值NaN、无穷、负数一律视为缺失避免污染计算。对应测试parses response with missing credits used derived from remaining验证了remaining30, total100时推导出used70、百分比 70%。预付费余额归零 ≠ 订阅耗尽代码中有一个值得注意的防御hasKnownZeroRemainingBalance在余额明确为 0 且总额未知时将creditUsedPercent置为 100%但同时余额与订阅是两个独立对象。测试zero prepaid balance does not exhaust active subscription证明余额为 0 时订阅窗口照常按2.50 / 10 kWh25%展示预付费余额单独显示$0.00二者互不干扰。订阅窗口与身份标签订阅窗口subscriptionRateWindow由kwh_used / kwh_included计算百分比current_period_end作为resetsAt重置描述格式化为已用 / 总量 kWhkWh 数值按整数舍入规则最多保留两位小数。窗口时长windowMinutes由current_period_start与current_period_end差值计算。身份标签displayLoginMethod的优先级为subscription.plan非空时使用如pro_energy显示为Pro Energy plan下划线转空格并首字母大写否则回退到accounting_method如energy显示为Energy两者皆缺则无标签。测试parses response with null subscription using accounting method验证了订阅为null时的回退行为此时主窗口为nil、无续订日期仅剩预付费余额与身份标签。按密钥限额窗口key.allowance存在且limit_usd 0时生成一个extraRateWindow标题按period生成如monthly→Key Monthly。特殊场景当密钥被标记blocked: true且没有数值限额时窗口百分比直接取 100%测试blocked key allowance is exhausted without numeric limit验证提示用户该密钥已不可用。日期解析订阅周期时间戳使用自定义 ISO8601 解码decodeISO8601Date同时兼容带与不带小数秒两种格式测试parses fractional subscription dates覆盖了2026-04-11T05:05:25.123Z这类带毫秒的时间戳。重试、限流与为何用原生 fetcher瞬态失败重试一次配额接口可能出现 503 等瞬态错误。CodexBar 对 Neuralwatt 使用ProviderHTTPRetryPolicy.transientIdempotent即maxRetries: 1可重试状态码集合为{408, 429, 500, 502, 503, 504}URL 层错误超时、连接丢失、无法连接主机、DNS 失败等同样可重试见 ProviderHTTPClient.swift。测试fetch retries transient quota failure用[503, 200]状态序列验证最终成功取数且请求总数为 2证明重试确实发生。Retry-After 处理重试延迟计算delaySeconds(attempt:response:)会优先读取响应头的Retry-After秒数并封顶在maxDelaySeconds默认 10 秒无该头时按指数退避baseDelaySeconds × 2^attempt默认基数为 1 秒。这一点正是文档强调原生 fetcher 保持权威地位的原因当前插件 HTTP API 没有重试策略或 sleep 能力无法表达这种带延迟的重试行为因此 Neuralwatt 用量读取只能走原生实现NeuralWattUsageFetcher.swift。每秒 1 次限流配额端点的限流为每个客户每秒 1 次请求。CodexBar 按正常刷新周期拉取实际不会触及该限制多账户场景下TokenAccountSupport将账户刷新最小间隔设为 1 秒测试 UsageStoreNeuralWattAccountRefreshTests.swift 专门验证了多账户刷新遵守这一限流节奏。HTTP 错误映射200解析成功401 / 403映射为missingCredentialsMissing Neuralwatt API key测试unauthorized fetch throws missing credentials以 401 响应验证其他状态码映射为apiError(HTTP xxx)取消CancellationError/URLError.cancelled原样透传不转化为 Provider 错误避免刷新取消被误报测试fetch preserves transport cancellation验证。菜单卡片中的最终呈现从 MenuCardNeuralWattTests.swift 可看到用户实际看到的形态订阅窗口以标题Subscription展示百分比 25%详情2.50 / 10 kWh重置文案Resets in 20d预付费余额以独立的Pay-as-you-go卡片展示文案为Balance: $51.00标题与payAsYouGoBalance风格对应见 NeuralWattProviderDescriptor.swift 的costPresenter无订阅窗口时metrics为空仅显示余额。此外Neuralwatt 的 Provider 元数据还定义了品牌色绿色系#38D98C、CLI 名称neuralwatt别名nw、neural、仪表盘地址https://portal.neuralwatt.com/dashboard以及不支持 token 成本历史配额 API 不提供该数据的说明。故障排查Missing Neuralwatt API key按以下任一方式提供密钥即可codexbar config set-api-key --provider neuralwatt --stdinSettings → Providers → Neuralwatt中粘贴设置环境变量NEURALWATT_API_KEY在 CodexBar 中配置 Neuralwatt token 账户Neuralwatt API error确认 API Key 有效401/403会先被映射为 missingCredentials因此该错误通常意味着其他 HTTP 状态码如 5xx确认当前网络可访问api.neuralwatt.com注意配额端点限流为每客户每秒 1 次CodexBar 正常刷新周期下不应触发若自建脚本高频调用需自行限速若使用NEURALWATT_API_URL覆盖地址请确保其是 HTTPS URL 或裸主机名否则会在发请求前被拒绝。相关实现文件速览文档docs/neuralwatt.md取数与快照计算NeuralWattUsageFetcher.swift配置读取与环境变量NeuralWattSettingsReader.swiftProvider 描述与元数据NeuralWattProviderDescriptor.swift应用层实现可用性判断、设置字段NeuralWattProviderImplementation.swift重试策略与 Retry-After 处理ProviderHTTPClient.swift解析与边界测试NeuralWattUsageFetcherTests.swift菜单卡片呈现测试MenuCardNeuralWattTests.swift多账户限流测试UsageStoreNeuralWattAccountRefreshTests.swift【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考