CodexBar CLI 快速参考：本地 Token 用量与费用统计实战指南
发布时间：2026/9/11 21:39:09 作者：尧图编辑部 阅读量：1,286
CodexBar CLI 快速参考本地 Token 用量与费用统计实战指南【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw导读CodexBar 是一个面向 macOS 与 Linux 的命令行工具用于统计 Codex 与 Claude 等模型在本地留下的用量与花费记录。本文以 openclaw 仓库中的 CodexBar CLI 快速参考 为骨架完整讲解其安装方式、usage/cost两条命令的使用方法、Cost JSON 的字段结构并结合仓库内的 model-usage 技能 与其 Python 汇总脚本深入剖析这些 JSON 字段在真实消费端如何被解析、聚合与展示。读完本文你将能够独立安装 CodexBar、导出结构化的用量/费用数据并在 openclaw 中一键按模型汇总本地费用。CodexBar CLI 是什么CodexBar 是社区开发的开源 CLICodexBar releases它并不替代 API 密钥或网关而是读取本地落盘日志把「这个月花了多少钱、哪些模型消耗最多」这类问题变成一条命令。它主要解决两件事用量快照usage从 Web/CLI 两类来源读取可用于查看整体用量趋势本地费用统计cost仅针对 Codex 与 Claude 的本地 JSONL 会话日志做费用汇总。在 openclaw 中CodexBar 被 model-usage 技能 声明为前置依赖requires: { bins: [codexbar] }且仅面向 darwin/linux技能运行时直接调用codexbar cost获取费用 JSON再交给 Python 脚本按模型二次加工。因此 CodexBar CLI 是整个「按模型看费用」链路的第一环。安装原文档给出四条安装路径按场景选择其一即可方式命令/说明适用系统Homebrew 公式brew install steipete/tap/codexbarmacOS、Linuxbrew 环境AUR 包yay -S codexbar-cliLinuxArch 系官方发布包从 CodexBar releases 下载 tarballmacOS、LinuxmacOS 应用内安装打开 CodexBar 应用 → Preferences → Advanced → Install CLImacOS其中 Homebrew 公式在 openclaw 的技能元数据里被登记为官方推荐安装器见 SKILL.md 中的install块formula: steipete/tap/codexbar也就是说当 Agent 发现环境缺少codexbar可执行文件时会优先尝试用这条公式补齐环境。安装完成后用codexbar --help确认可执行文件已在PATH中。需要特别提醒cost模式是本地离线统计不依赖登录态但前提是 Codex/Claude 的本地日志真实存在日志路径见下文「数据来源」小节。常用命令原文档把命令分为两类下面逐个说明参数语义与典型用法。用量快照usage# 以 JSON 格式输出pretty 美化缩进web/cli 两个来源都会统计 codexbar usage --format json --pretty # 全量 provider强制 JSON 输出 codexbar --provider all --format json--format json把结果序列化为 JSON便于脚本消费不传则输出人类可读文本。--pretty对 JSON 做缩进美化适合直接阅读或粘贴进文档。--provider all一次性覆盖所有已配置的 provider。usage模式的数据来自 Web 端与 CLI 端两个来源因此即便本机没有本地会话日志也能反映账户级的整体用量——这正是它与cost的关键差异。本地费用统计cost# 本地费用汇总仅 Codex ClaudeJSON 美化 codexbar cost --format json --pretty # 只看某一个 provider codexbar cost --provider codex --format json codexbar cost --provider claude --format jsoncost是local-only它只读本机会话 JSONL不做任何网络请求。--provider codex|claude二选一过滤。openclaw 的 model_usage.py 正是用codexbar cost --format json --provider codex|claude这条命令拉取数据的注意这里没有--pretty因为脚本自己会用json.loads解析紧凑输出。什么时候用 usage什么时候用 cost一句话原则原文档 Notes 原文需要 Web 端非本地用量时用usage需要本地精确费用时用cost。如果你的诉求是「我这个账户整体消耗了多少」用usage诉求是「本地这台机器上的 Codex/Claude 会话分别花了多少钱」用cost。Cost JSON 字段详解原文档指出payload 是一个数组每个元素对应一个 provider。也就是说典型输出形如[ { provider: claude, source: ..., updatedAt: 2026-09-08T12:00:00Z, sessionTokens: 123456, sessionCostUSD: 1.23, last30DaysTokens: 987654, last30DaysCostUSD: 9.87, daily: [ { date: 2026-09-08, inputTokens: 100, outputTokens: 50, cacheReadTokens: 20, cacheCreationTokens: 10, totalTokens: 180, totalCost: 0.01, modelsUsed: [claude-sonnet-4-6], modelBreakdowns: [ { modelName: claude-sonnet-4-6, cost: 0.01 } ] } ], totals: { totalInputTokens: 100, totalOutputTokens: 50, cacheReadTokens: 20, cacheCreationTokens: 10, totalTokens: 180, totalCost: 0.01 } } ]字段语义如下字段含义provider/source/updatedAtprovider 标识、数据来源、最后更新时间sessionTokens/sessionCostUSD会话级累计 token 与费用last30DaysTokens/last30DaysCostUSD近 30 天累计 token 与费用daily[]按天拆分的明细数组daily[].date日期YYYY-MM-DDdaily[].inputTokens/outputTokens输入/输出 token 数daily[].cacheReadTokens/cacheCreationTokens缓存读取/缓存创建 token 数daily[].totalTokens/totalCost当天总 token 与总费用daily[].modelsUsed[]当天使用过的模型名列表daily[].modelBreakdowns[]当天按模型拆分的费用明细modelBreakdowns[].modelName/cost模型名与该模型当天费用totals全量汇总各类 token 与totalCost这些字段在 openclaw 中如何被消费openclaw 的 model_usage.py 围绕上述结构实现了完整的解析链路可作为理解字段语义的「活文档」provider 匹配load_payload() 拿到数组后按entry.get(provider) provider挑选对应元素找不到时抛错Provider xxx not found in codexbar payload。daily 归一化parse_daily_entries() 只保留daily中类型为 dict 的行防御脏数据。按模型聚合aggregate_costs() 遍历modelBreakdowns以modelName为 key 累加cost。成本数值清洗coerce_finite_cost() 是一个值得借鉴的细节——它同时接受原生数字与数字字符串例如1.75并拒绝布尔值与 NaN/Infinity避免单个坏行污染聚合总额。对应单元测试见 test_model_usage.py。近 N 天过滤filter_by_days() 以daily[].date%Y-%m-%d格式与今天比较保留截止日之后的记录。当前模型判定pick_current_model() 从最新一天的modelBreakdowns里选费用最高的模型若该行没有 breakdowns则退回取modelsUsed最后一项。这些实现直接印证了原文档字段清单的用途daily/modelBreakdowns/modelsUsed不只是给人看的报表更是机器聚合的最小数据单元。数据来源本地日志路径cost之所以称为 local-only是因为它直接扫描本机 JSONL 日志Codex~/.codex/sessions/*_*/*.jsonlClaude~/.config/claude/projects/**/*.jsonl或~/.claude/projects/**/*.jsonl实践中的几个注意点路径里的*是 shell 通配符实际是一层「会话目录/会话文件」的结构Codex 每个会话一个目录、每个会话一个.jsonlClaude 侧两个候选路径是历史版本兼容——新版配置目录在~/.config/claude老版本可能在~/.claudeCodexBar 会做兼容探测若这些目录为空或不存在cost拿不到数据此时应改用usage走 Web 来源本地日志不包含 Web 端如网页版会话的消耗因此「本地费用」不等于「账户总账单」。在 openclaw 中一键汇总model-usage 技能关联文档是 model-usage 技能 的 CLI 参考页技能本身把上文所有命令封装成了更上层的用法# 用默认 CodexBar 拉取并汇总「当前模型」费用 python {baseDir}/scripts/model_usage.py --provider codex --mode current # 汇总「全部模型」 python {baseDir}/scripts/model_usage.py --provider codex --mode all # Claude 全模型汇总JSON 美化输出 python {baseDir}/scripts/model_usage.py --provider claude --mode all --format json --pretty脚本完整参数与 main() 的 argparse 定义一一对应参数取值默认说明--providercodex/claudecodex指定数据源 provider--modecurrent/allcurrentcurrent最近一天费用最高模型all全部模型汇总--model模型名自动判定显式指定模型跳过自动「当前模型」逻辑--input文件路径或-空走 CLI直接读取已导出的 CodexBar JSON支持 stdin--days正整数全部只看最近 N 天基于 daily 行过滤--formattext/jsontext输出格式--pretty开关关JSON 美化缩进「当前模型」的判定逻辑在 SKILL.md 中有明确说明与源码实现一致优先取最近一天带modelBreakdowns的行中费用最高的模型缺失 breakdowns 时退回modelsUsed最后一项需要精确指定时用--model覆盖对应 pick_current_model() 与--model参数。无 CodexBar 环境的离线用法先用 CodexBar 导出 JSON再通过--input喂给脚本任意有 Python 3 的机器都可运行codexbar cost --provider codex --format json /tmp/cost.json python {baseDir}/scripts/model_usage.py --input /tmp/cost.json --mode all cat /tmp/cost.json | python {baseDir}/scripts/model_usage.py --input - --mode current输出方面text 模式给出Provider / Current model / Total cost / Latest day cost / Daily rows或Models:列表--format json则输出结构化对象current 模式含model、totalCostUSD、latestDayCostUSD等字段见 build_json_current() 与 build_json_all()。需要留意的是CodexBar 的 JSON 只按模型拆分费用不按模型拆分 token因此脚本输出也以 cost 为聚合口径。常见问题与注意事项codexbar未找到脚本会报codexbar not found on PATH请先按上文「安装」一节补齐 CLI并确认在PATH中。cost返回空/报错先检查~/.codex/sessions与 Claude 两个候选目录是否有.jsonl文件确认无误后再检查 provider 名是否拼写为codex/claude。数值为字符串的 JSON某些 CodexBar 版本会把 cost 序列化成字符串openclaw 的脚本通过 coerce_finite_cost() 兼容处理若你自写解析器也建议做同样的防御拒绝 bool/NaN/Infinity。本地费用 ≠ 总账单Web 端用量需要走codexbar usagecost仅覆盖本机 Codex/Claude 会话日志。总结安装macOS/Linux 用 Homebrew 公式brew install steipete/tap/codexbarArch Linux 用 AUR或下载官方 tarballmacOS 应用可在 Preferences → Advanced 中一键安装 CLI。两条核心命令codexbar usageWeb/CLI 来源的整体用量快照与codexbar cost本地 Codex/Claude 会话费用均支持--format json [--pretty]与--provider过滤。Cost JSON 结构顶层为 per-provider 数组内含sessionTokens/sessionCostUSD、last30Days*、daily[]含modelBreakdowns[]与totals四类信息。落地场景openclaw 的 model-usage 技能直接消费这些 JSON 字段完成按模型费用聚合current/all两种模式与--input/--days等参数可组合出灵活的本地费用报表相关实现细节可在 model_usage.py 与其测试 test_model_usage.py 中继续深挖。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 