CodexBar CLI 快速参考：本地 Token 用量与费用统计实战指南

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 是社区开发的开源 CLI（CodexBar 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 公式在 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 + Claude），JSON + 美化 codexbar cost --format json --pretty # 只看某一个 provider codexbar cost --provider codex --format json codexbar cost --provider claude --format json

• cost是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 } } ]

字段语义如下：

这些字段在 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/*_*/*.jsonl
• Claude：~/.config/claude/projects/**/*.jsonl或~/.claude/projects/**/*.jsonl

实践中的几个注意点：

1. 路径里的*是 shell 通配符，实际是一层「会话目录/会话文件」的结构，Codex 每个会话一个目录、每个会话一个.jsonl；
2. Claude 侧两个候选路径是历史版本兼容——新版配置目录在~/.config/claude，老版本可能在~/.claude，CodexBar 会做兼容探测；
3. 若这些目录为空或不存在，cost拿不到数据，此时应改用usage（走 Web 来源）；
4. 本地日志不包含 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 定义一一对应）：

「当前模型」的判定逻辑在 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 为聚合口径。

常见问题与注意事项

1. codexbar未找到：脚本会报codexbar not found on PATH，请先按上文「安装」一节补齐 CLI，并确认在PATH中。
2. cost返回空/报错：先检查~/.codex/sessions与 Claude 两个候选目录是否有.jsonl文件；确认无误后再检查 provider 名是否拼写为codex/claude。
3. 数值为字符串的 JSON：某些 CodexBar 版本会把 cost 序列化成字符串，openclaw 的脚本通过 coerce_finite_cost() 兼容处理，若你自写解析器也建议做同样的防御（拒绝 bool/NaN/Infinity）。
4. 本地费用 ≠ 总账单：Web 端用量需要走codexbar usage，cost仅覆盖本机 Codex/Claude 会话日志。

总结

• 安装：macOS/Linux 用 Homebrew 公式brew install steipete/tap/codexbar，Arch Linux 用 AUR，或下载官方 tarball；macOS 应用可在 Preferences → Advanced 中一键安装 CLI。
• 两条核心命令：codexbar usage（Web/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