CodexBar 集成指南Moonshot / Kimi 开放平台余额接入、双区域密钥路由与余额端点解析【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar本文以 CodexBar 仓库中的 docs/moonshot.md 为核心结合 Moonshot 提供商源码 与 测试用例系统讲解 CodexBar 如何接入 Moonshot / Kimi 开放平台的余额接口包括 API Key 的三种来源、国际/中国大陆双区域密钥绑定机制、GET /v1/users/me/balance余额端点的请求与解析细节以及余额在菜单栏卡片中的货币化展示逻辑。读完本文你可以理解该提供商的完整配置流程、环境变量语义与底层实现原理并能在自己的 CodexBar 部署中正确配置与排障。概览API-only 的余额型提供商Moonshot / Kimi 开放平台是纯 API 形态的服务API-only其账户余额通过GET /v1/users/me/balance上报。因此CodexBar 接入它只需要一个有效的 API Key无需任何登录会话即可在菜单栏卡片中显示当前账户余额。这一特性在提供商元数据中被标记为balanceOnly: true见 MoonshotProviderDescriptor.swift并且没有会话session或周窗口weekly window——Moonshot / Kimi API 不通过接口暴露任何按窗口计算的配额所以菜单卡片只呈现余额没有成本明细与 Token 计价——ProviderTokenCostConfig(supportsTokenCost: false)当用户查看成本摘要时会提示 Moonshot / Kimi Open Platform cost summary is not available.不参与主提供商primary链路isPrimaryProvider: falsewidgetSelectable: false默认不启用defaultEnabled: false。为什么保留原生抓取器native fetcher而不是走插件文档特别强调原生抓取器native fetcher保持权威地位。原因在于余额型结果是刻意只以快照身份snapshot identity形式表示的——不携带 rate window、cost、detail 等字段而插件契约plugin contract拒绝纯身份快照identity-only snapshots。也就是说余额这种只有身份信息、没有任何用量维度的表示方式只能由内置原生实现承担无法降级为插件输出。这一点从 MoonshotUsageSummary.toUsageSnapshot() 的实现可以印证primary、secondary、tertiary、providerCost全部为nil只有identity.loginMethod携带余额文本。为什么提供商命名为 Moonshot 而非 KimiKimi 官方 API 文档当前版本沿用的是Moonshot API 接口面示例代码读取MOONSHOT_API_KEY请求https://api.moonshot.ai/v1包括 Kimi K2.6 快速开始示例也是如此。因此 CodexBar 将这个提供商命名为Moonshot——命名依据是账户与计费面account and billing surface而不是某个具体 Kimi 模型版本。同时CodexBar 只对接Moonshot 官方账户与计费接口不接入任何非官方的第三方 Kimi 中转/relay 服务。这解释了品牌层面的一个细节虽然提供商 ID 是moonshot但其品牌图标刻意复用 Kimi 的图标资源ProviderIcon-kimi颜色为#205DEB见 MoonshotProviderDescriptor.swift因为 Moonshot 开放平台产品本身就使用 Kimi 品牌。数据来源与配置1. API Key三处来源与优先级API Key 可以来自三个位置来源取值方式优先级设置界面保存的密钥~/.codexbar/config.json通过 Settings → Providers → Moonshot 写入ProviderConfig.apiKey最高配置注入的环境变量CODEXBAR_MOONSHOT_API_KEYCODEXBAR_MOONSHOT_API_KEY_REGION次之直接环境变量MOONSHOT_API_KEY/MOONSHOT_KEY最低设置配置优先于环境变量当~/.codexbar/config.json中存在已保存密钥且其绑定区域与当前区域一致时它覆盖所有环境变量。直接环境变量的解析优先级MOONSHOT_API_KEY优先于MOONSHOT_KEYMoonshotSettingsReader.apiKeyEnvironmentKeys数组中前者在前两者均为空或缺失时才继续回退。环境变量值会被trimmingCharacters(in: .whitespacesAndNewlines)清理且自动剥离成对包裹的引号...或...方便在 shell 中直接以带引号形式导出见 MoonshotSettingsReader.cleaned。典型的 shell 导出示例国际区export MOONSHOT_API_KEYsk-... # 或 export MOONSHOT_KEYsk-...2. 区域Region密钥绑定与跨区域隔离CodexBar 支持两个区域均由MoonshotRegion枚举建模见 MoonshotRegion.swift区域rawValue余额端点控制台国际internationalhttps://api.moonshot.ai/v1/users/me/balancehttps://platform.moonshot.ai/console/account中国大陆chinahttps://api.moonshot.cn/v1/users/me/balancehttps://platform.kimi.com/console/account区域配置方式GUISettings → Providers → Moonshot →API region选择器选项为International (api.moonshot.ai)与China (api.moonshot.cn)见 MoonshotProviderImplementation.swift。环境变量MOONSHOT_REGIONchina可选值international/china未设置或为未知值时默认回退到国际区MoonshotSettingsReader.region的?? .international兜底测试region defaults to international for unknown values覆盖此行为。关键安全设计——密钥绑定区域region-bound keyCodexBar 会把保存的密钥绑定到当前选定的区域主机。切换区域时不会把已保存的密钥发送给另一个主机只有切回原区域或替换为新区域签发的密钥后才能恢复取数。这一机制的实现核心是ProviderConfig.apiKeyRegion扩展字段见 MoonshotProviderConfig.swift每次写密钥时同时把entry.apiKeyRegion置为当前区域 rawValue读取密钥时MoonshotSettingsStore.moonshotAPIToken要求sanitizedAPIKeyRegion moonshotRegion.rawValue才返回见 MoonshotSettingsStore.swift。hasMoonshotAPIToken(for:)同理做区域匹配从而保证凭证永不跨 Moonshot 主机流动。区域相关的完整环境变量清单见 MoonshotSettingsReader.swift环境变量含义MOONSHOT_API_KEY直接 API Key国际区默认语义MOONSHOT_KEYAPI Key 的回退键名MOONSHOT_REGION区域international/china默认国际CODEXBAR_MOONSHOT_API_KEY供配置注入的 API Key由 descriptor 的environmentOverride写入CODEXBAR_MOONSHOT_API_KEY_REGION与上一条配对的区域标记注意直接环境变量MOONSHOT_API_KEY/MOONSHOT_KEY默认按国际区语义解析需要搭配中国大陆密钥时必须同时设置MOONSHOT_REGIONchina。3. 余额端点Balance Endpoint请求规范方法GET请求头Authorization: Bearer api keyAccept: application/json超时15 秒MoonshotUsageFetcher.timeoutSeconds响应体包含三个核心字段JSON 中为 snake_case解码时映射为 camelCase 属性见 MoonshotBalanceData响应字段类型说明available_balanceDouble可用余额voucher_balanceDouble代金券余额cash_balanceDouble现金余额为负时表示透支/赤字响应外层同时带有code0表示成功、statustrue与scode字段。解析器只有在code 0 status true时才接受数据否则抛出MoonshotUsageError.apiError(code \(code), scode \(scode))。错误模型MoonshotUsageError错误触发条件.missingCredentials清理后的 API Key 为空.networkError底层传输返回badServerResponse等网络错误.apiError非 200 状态码或code/status校验失败.parseFailedJSON 解码失败使用细节与展示规则菜单卡片只显示余额菜单卡片menu card通过快照身份的loginMethod呈现余额文本identityPresenter将余额同时用作 badge 与 plan见 MoonshotProviderDescriptor.swift。货币按区域显示不做换算国际区USD金额使用UsageFormatter.usdString格式化如$49.58中国大陆区CNY金额使用UsageFormatter.currencyString(value, currencyCode: CNY)格式化如CN¥49.58金额按 API 原样显示不进行任何汇率换算。赤字deficit提示当cash_balance 0时卡片除显示可用余额外还会追加赤字文本Balance: $49.58 · $0.42 in deficit对应的格式逻辑见 MoonshotUsageSummary.toUsageSnapshot() 中的cashBalance 0分支赤字金额取绝对值显示。无会话、无周窗口由于 API 不暴露分窗配额Moonshot 提供商没有会话时长、没有周用量窗口、没有重置倒计时等维度sessionLabel与weeklyLabel均被设置为BalancesupportsOpus: false、supportsCredits: false。配置优先级总结GUI/config.json中保存的区域绑定密钥区域匹配时CODEXBAR_MOONSHOT_API_KEYCODEXBAR_MOONSHOT_API_KEY_REGION区域匹配时MOONSHOT_API_KEY/MOONSHOT_KEY仅当MOONSHOT_REGION与当前区域一致时。源码级原理一次余额抓取的完整调用链可用性判定MoonshotAPIFetchStrategy.isAvailable对当前区域调用MoonshotSettingsReader.apiKey(for:environment:)有密钥才进入抓取GUI 侧则由 MoonshotProviderImplementation.isAvailable 额外检查hasMoonshotAPIToken(for:)。区域决策context.settings?.moonshot?.region ?? MoonshotSettingsReader.region(environment:)——设置优先环境变量兜底。HTTP 请求MoonshotUsageFetcher.fetchUsage组装Authorization: Bearer与Accept头通过可注入的ProviderHTTPTransport发出 GET 请求15 秒超时非 200 状态直接抛apiError。JSON 解析parseSummary解码MoonshotBalanceResponse校验code/status构造MoonshotUsageSummary。快照化toUsageSnapshot()将三余额与区域渲染为身份文本含赤字分支产出 identity-only 的UsageSnapshot。配置归一化configNormalizer若配置中有密钥但未显式写区域自动以当前区域补写apiKeyRegion保证密钥与区域的一致性。抓取策略的shouldFallback恒为false——因为 Moonshot 只有唯一一种 API 数据源不存在可回退的其他模式。测试验证行为即契约仓库用 MoonshotUsageFetcherTests.swift 与 MoonshotSettingsReaderTests.swift 固定了上述行为可对照理解解析文档化响应available_balance: 49.58、voucher_balance: 50.00、cash_balance: 12.34→Balance: $49.58负现金余额cash_balance: -0.42→Balance: $49.58 · $0.42 in deficit中国区渲染region 为.china时 →Balance: CN¥49.58赤字同样以 CNY 呈现环境变量优先级同时存在MOONSHOT_API_KEY与MOONSHOT_KEY时取前者引号剥离quoted-token→quoted-token区域解析MOONSHOT_REGIONchina→.china未知值如moon→.international区域绑定绑定在某区域下的配置密钥对另一区域不可见region bound config key is unavailable to the other host另有 MoonshotCurrencyNativeProofTests.swift 印证货币原生展示不换算的契约。关键文件索引docs/moonshot.md —— 本文依据的原始设计文档MoonshotProviderDescriptor.swift —— 提供商描述descriptor与 API 抓取策略MoonshotUsageFetcher.swift —— HTTP 客户端与 JSON 解析、余额格式化MoonshotSettingsReader.swift —— 环境变量解析API Key 与区域MoonshotRegion.swift —— 双区域模型与余额端点 URLMoonshotProviderConfig.swift —— 密钥区域绑定字段MoonshotProviderImplementation.swift —— 设置界面字段与激活逻辑MoonshotSettingsStore.swift —— SettingsStore 扩展区域匹配的密钥读写MoonshotUsageFetcherTests.swift、MoonshotSettingsReaderTests.swift —— 解析与配置测试。快速配置清单打开 CodexBar 设置 → Providers →Moonshot / Kimi Open Platform启用该提供商在API region中选择国际区api.moonshot.ai或中国大陆区api.moonshot.cn并通过 Open regional console 跳转到对应控制台获取密钥粘贴该区域签发的 Open Platform API keysk-...密钥会被绑定到当前区域若使用环境变量方式请按区域导出MOONSHOT_API_KEY国际区或MOONSHOT_API_KEYMOONSHOT_REGIONchina中国大陆区回到菜单栏查看卡片余额若cash_balance为负卡片会同时显示赤字金额。【免费下载链接】CodexBarShow usage stats for OpenAI Codex and Claude Code, without having to login.项目地址: https://gitcode.com/GitHub_Trending/co/CodexBar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考