Codex Usage Receipt 使用指南：把 Windows 与 WSL 的 Token 日志生成可审计用量收据

当 Codex 只使用几轮时，界面中的剩余额度通常已经够用；但会话越来越长、模型越来越多，甚至同时在 Windows、WSL 和多个项目里工作后，就会出现一些很实际的问题：

  • 这一段时间究竟用了多少 Token？
  • 输入、缓存命中和输出分别占多少？
  • Windows 与 WSL 的日志有没有漏算？
  • 哪个模型消耗最多？缓存到底节省了多少？
  • 能不能生成一份方便归档、打印或报销说明的用量收据？

Codex Usage Receipt 就是为这些需求制作的开源 Codex Skill。它不依赖网页截图，也不尝试根据聊天文本长度“猜”Token，而是直接读取本机 Codex 产生的 JSONL 会话日志，提取 token_count 事件，再按模型、日志来源和时间段生成结构化统计。

Codex Usage Receipt 项目预览

先说明最重要的一点：它生成的是本地估算收据，不是 OpenAI 官方发票，也不能直接等同于 ChatGPT 套餐实际扣除的额度或信用点。它更适合做个人统计、内部审计、模型用量分析和成本参考。

一、Codex Skill 是什么

Skill 可以理解为给 Codex 安装的一套“固定工作流程”。普通提示词往往只在当前对话中有效，而 Skill 会把任务说明、执行顺序、脚本和检查规则放进一个目录中。当用户提出匹配的需求时，Codex 可以读取 SKILL.md，再按照其中约定好的流程执行。

Codex Usage Receipt 不只是一个提示词文件。仓库中包含三个可直接运行的 Python 脚本：

codex-usage-receipt/
├── SKILL.md
├── README.md
├── scripts/
│   ├── codex_usage_summary.py
│   ├── render_latex_receipt.py
│   └── render_text_receipt.py
└── evals/
    └── evals.json

三个脚本分别负责：

  1. 从原始 JSONL 日志生成结构化统计 JSON；
  2. 将统计 JSON 填入统一的 LaTeX 收据模板；
  3. 在没有 LaTeX 环境时生成纯文本收据。

Windows    ＋    Ubuntu    →    Python    →    JSON    ＋    LaTeX

上面的链路就是整个项目的核心：Windows/WSL 日志 → Python 统计 → JSON 数据 → LaTeX/PDF 或文本收据。正文中的功能图片优先通过 jsDelivr 加载，通常比 GitHub Raw 在中国大陆网络下更稳定；项目预览图仍由 GitHub Assets 提供，网络状况较差时可能加载较慢。

二、它到底能统计什么

根据仓库当前实现，统计结果可以按模型拆分以下信息：

指标 含义
Fresh input tokens 未命中缓存、需要实际处理的输入 Token
Cache-hit input tokens 命中缓存的输入 Token
Output tokens 模型输出 Token
Reasoning output tokens 推理过程使用的输出 Token 统计
Usage event count 参与统计的 token_count 事件数量
Estimated USD cost 按本次价格表计算的估算美元成本

此外，汇总 JSON 还会记录：

  • 统计生成时间；
  • 用户指定的起止时间；
  • 实际命中的第一条与最后一条使用事件；
  • 扫描到的 JSONL 文件数量；
  • 真正包含用量的会话数量；
  • 按模型拆分的 Token 与成本；
  • 按 Windows、WSL 等来源拆分的用量；
  • 从日志中读取到的最新 Codex 限额快照；
  • 本次计算使用的价格表；
  • 计算口径和注意事项。

这比单纯显示“剩余百分比”更适合做复盘。例如，你可以看出高缓存命中是否真的降低了估算成本，也可以发现大量 Token 是否其实来自 WSL 中被忽略的会话。

三、为什么不直接把累计 Token 相加

Codex JSONL 日志中可能同时出现累计用量和单次事件用量。这个项目默认读取：

payload.type == "token_count"
info.last_token_usage

而不是把 total_token_usage 直接相加。

原因在于 total_token_usage 是会话累计值。会话压缩、恢复、续写、重试或上下文切换后，累计值可能重置，也可能重复出现。假如把每条累计值相加，结果很容易被放大数倍。

项目采用逐事件口径，并将输入进一步拆成：

fresh_input_tokens = input_tokens - cached_input_tokens

估算成本的基本公式为：

cost =
    fresh_input_tokens / 1_000_000 × input_rate
  + cached_input_tokens / 1_000_000 × cache_hit_rate
  + output_tokens / 1_000_000 × output_rate
  + cache_creation_tokens / 1_000_000 × cache_creation_rate

默认情况下，cache creation 单价可以为 0；最终应以生成 JSON 中的 pricing 字段为准。reasoning_output_tokens 用于分析和展示时，不应在已经包含它的输出 Token 之外再次重复计费。

四、它和官方用量页面、CC Switch 有什么区别

工具或数据源 更适合做什么 局限
Codex 官方用量页面 查看套餐剩余额度、重置时间与可购买信用点 通常不会提供本地逐模型、逐来源的完整 Token 收据
CC Switch 等管理工具 快速查看账号、模型和部分用量信息 数据口径取决于工具实现，不一定来自原始 Codex JSONL
API Usage Dashboard 查看 API Key 产生的正式 API 用量 ChatGPT 账号登录的本地 Codex 使用不一定等同于 API 调用
Codex Usage Receipt 本地日志审计、Windows/WSL 合并、逐模型统计、打印归档 是本地估算，不是官方结算凭证

因此，这个 Skill 并不是要替代官方页面。更合理的用法是：

  • 用官方页面看还剩多少套餐额度；
  • 用 Codex Usage Receipt 分析本机到底产生了哪些 Token；
  • 必要时用其他工具交叉验证；
  • 对不上时优先检查时间范围、日志来源和计费口径，而不是强行让几个数字完全一致。

OpenAI 目前也明确说明，Codex 任务对套餐用量的消耗会受到任务复杂度、模型、执行位置和上下文规模影响，因此 API 等价成本不能简单换算成套餐剩余额度。

五、安装前准备

最低需要：

  • 已安装 Codex CLI、Codex App 或支持 Skill 的 Codex 环境；
  • Python 3；
  • Git；
  • 本机已经产生过 Codex 会话日志。

可选组件：

  • TeX Live、Tectonic 或其他 LaTeX 编译环境，用于输出 PDF；
  • pdftoppm 等工具，用于生成灰度打印版；
  • 可访问 WSL 文件系统的 Windows 环境。

这个项目的统计和文本输出没有第三方 Python 依赖要求，通常不需要为了使用它创建庞大的虚拟环境。

六、安装为 Codex Skill

方法一：Windows PowerShell 安装

建议把它安装在 Windows 侧，因为默认配置会同时读取 Windows 本地日志与 WSL 的 UNC 路径。

$SkillRoot = "$env:USERPROFILE\.codex\skills"
New-Item -ItemType Directory -Force $SkillRoot | Out-Null
Set-Location $SkillRoot

git clone https://github.com/wangling-miao/codex-usage-receipt.git

最终目录应当是：

C:\Users\你的用户名\.codex\skills\codex-usage-receipt\SKILL.md

目录名称建议保持为 codex-usage-receipt，不要只把 SKILL.md 单独复制出去，因为 Skill 还需要调用同目录下的脚本。

方法二：Linux 或 WSL 安装

mkdir -p ~/.codex/skills
cd ~/.codex/skills
git clone https://github.com/wangling-miao/codex-usage-receipt.git

安装完成后重启 Codex 最稳妥。部分新版本可能在下一轮会话中自动发现新 Skill，但重启可以避免缓存或索引未刷新的问题。

更新 Skill

Windows：

git -C "$env:USERPROFILE\.codex\skills\codex-usage-receipt" pull

Linux/WSL：

git -C ~/.codex/skills/codex-usage-receipt pull

七、最简单的使用方法：直接对 Codex 说人话

安装完成后，可以直接输入：

打印 2026-05-23 以来的 Codex Token 消费收据，Windows 和 WSL 都要统计，生成适合黑白打印的 PDF。

或者：

统计 2026-07-01 到 2026-07-31 的 Codex 用量，按模型列出输入、缓存命中、输出、推理 Token 和估算成本，同时保留统计 JSON。

若没有给出明确时间段，Skill 按设计应先询问你要统计哪一段时间，而不是自行把“最近”“前段时间”“这个月”解释成一个不透明的范围。

建议在提示词中明确四件事：

  1. 起止时间；
  2. 时区；
  3. 是否合并 Windows 与 WSL；
  4. 需要 JSON、PDF、文本还是直接打印。

八、直接使用命令行

Skill 的本质仍然是调用 Python 脚本，因此即使不使用 Codex，也可以手动执行。

1. 创建输出目录

Set-Location "$env:USERPROFILE\.codex\skills\codex-usage-receipt"
New-Item -ItemType Directory -Force .\work, .\outputs | Out-Null

2. 生成统计 JSON

python .\scripts\codex_usage_summary.py `
  --since 2026-07-01 `
  --until 2026-07-31 `
  --timezone +08:00 `
  --output .\work\codex-usage-summary.json

只想在终端查看 JSON 时，可以不传 --output：

python .\scripts\codex_usage_summary.py `
  --since 2026-07-01 `
  --until 2026-07-31

3. 生成 LaTeX 收据

python .\scripts\render_latex_receipt.py `
  .\work\codex-usage-summary.json `
  --output .\outputs\codex-usage-receipt.tex

然后使用系统已有的 TeX Live、Tectonic 或其他 LaTeX 工具编译。若模板包含中文，通常优先选择支持 Unicode 字体的引擎；具体以生成的 .tex 文件和本机环境为准。

4. 没有 LaTeX 时生成文本收据

python .\scripts\render_text_receipt.py `
  .\work\codex-usage-summary.json `
  --output .\outputs\codex-usage-receipt.txt

Windows 可以直接打印文本：

Get-Content .\outputs\codex-usage-receipt.txt |
  Out-Printer -Name "你的打印机名称"

发送打印任务后应继续检查打印队列和打印机状态。Skill 的说明明确要求：如果打印机离线、任务仍在队列中或系统没有可用打印机，必须如实告知，不能只因为执行了命令就声称“已经打印成功”。

九、时间范围规则

--since 为必填参数，--until 可以省略。省略后表示统计到当前时间。

支持日期：

2026-07-01

也支持带时间的 ISO 格式：

2026-07-01T09:30:00

若 --until 只写日期，例如：

2026-07-31

脚本会按当天 23:59:59 处理，而不是只统计到当天零点。

默认时区为 +08:00，其他地区应显式传入：

--timezone -05:00

时间范围是最容易造成统计差异的地方。对比其他工具时，必须确认它们是否使用同一个时区、是否包含结束日期、是否统计归档会话。

十、Windows 与 WSL 日志为什么容易漏算

项目默认扫描四类路径：

%USERPROFILE%\.codex\sessions
%USERPROFILE%\.codex\archived_sessions
\\wsl.localhost\Ubuntu\root\.codex\sessions
\\wsl.localhost\Ubuntu\root\.codex\archived_sessions

这覆盖了最常见的“Windows 用户目录 + Ubuntu root”组合。但实际环境可能并不一样，例如：

  • WSL 发行版叫 Ubuntu-24.04；
  • 你使用普通 Linux 用户而不是 root；
  • 修改过 CODEX_HOME；
  • 日志放在其他磁盘；
  • 使用了多个 WSL 发行版。

这时可以增加 --root：

python .\scripts\codex_usage_summary.py `
  --since 2026-07-01 `
  --until 2026-07-31 `
  --root "WSL Ubuntu 24.04=\\wsl.localhost\Ubuntu-24.04\home\wangling\.codex\sessions" `
  --output .\work\codex-usage-summary.json

--root 支持两种形式：

label=path
path

带有 label 时，汇总 JSON 的 by_source 会使用这个名称，更方便区分 Windows、WSL、旧环境和其他设备导出的日志。

十一、价格表与 models.dev

仓库包含默认价格表，也允许通过 --price 覆盖。格式为：

model=input,cache_hit,output,cache_creation

例如：

python .\scripts\codex_usage_summary.py `
  --since 2026-07-01 `
  --until 2026-07-31 `
  --price gpt-example=2.5,0.25,15,0 `
  --output .\work\codex-usage-summary.json

上面的模型名和价格只是参数格式示例，不代表当前真实价格。

模型价格变化很快，建议在生成正式收据前检查 models.dev 等公开模型数据库，再通过 --price 显式覆盖。无论价格来自内置表、models.dev 还是人工输入，都应在收据中保留本次 pricing 快照，保证日后可以复算。

如果某个模型没有对应价格，正确做法是标记为 unpriced、询问用户或提供明确的 --price，而不是悄悄套用名称相似模型的价格。

十二、如何理解“估算成本”

这里的美元金额更接近“按指定 Token 单价计算出的 API 等价参考值”，不等于 ChatGPT Plus、Pro 或其他套餐真正向账户扣除的金额。

原因包括：

  • ChatGPT 套餐可能采用用量窗口、信用点或统一 agentic usage 口径；
  • 不同执行位置、模型和任务复杂度可能消耗不同额度；
  • 本地日志记录的是 Token 事件，不一定包含平台内部所有折算规则；
  • API 价格与订阅产品的额度折算不是同一套账单体系；
  • 价格表可能随时间变化。

因此，文章或报告中建议使用以下表述：

按本次报告所附模型单价计算，统计期内的 API 等价估算成本为……；该金额不是 OpenAI 官方结算金额，也不代表 ChatGPT 套餐的实际扣费。

十三、限额快照能看到什么

如果日志中包含对应信息，项目可以保留 Codex 的最新限额快照，包括：

  • primary window 已使用/剩余百分比；
  • secondary window 已使用/剩余百分比；
  • 各窗口重置时间；
  • 原始百分比字段，便于审计。

需要注意，Codex 服务端返回的限额窗口可能随账号、版本和平台策略变化。某次报告只有一个窗口或没有快照，并不一定代表脚本损坏，也可能是当前日志中没有相应字段。官方用量页面仍应作为账户剩余额度的主要参考。

十四、隐私与安全

这个项目的优势之一是本地运行：默认只读取本机 JSONL，不需要上传完整日志。

不过，“本地运行”并不等于完全没有风险。Codex 会话日志可能包含项目路径、模型名称、时间信息和其他元数据，因此建议：

  • 首次使用前先阅读 SKILL.md 和三个 Python 脚本；
  • 不要把真实 JSONL 日志提交到公开 Git 仓库；
  • 不要把真实收据、账号信息和私人路径直接发布；
  • 对外分享 PDF 前检查用户名、目录和用量细节；
  • 只向可信的 Codex 环境授予读取日志目录的权限；
  • 公司或学校设备应先确认内部数据和审计政策。

仓库本身也建议只提交工具代码、Skill 文档和示例，不提交真实日志、真实收据及 outputs/ 目录。

十五、常见问题

1. 输出是 0 Token

优先检查：

  • 起止时间是否正确；
  • 时区是否正确；
  • sessions 与 archived_sessions 是否都扫描；
  • WSL 发行版和用户名是否匹配；
  • 这段时间内是否确实产生过 token_count 事件。

2. Windows 可以用，WSL 一直没有数据

在资源管理器中手动打开：

\\wsl.localhost\Ubuntu\

确认发行版名称、用户目录和 .codex 是否存在。如果实际用户不是 root，就不要继续使用默认 root 路径。

3. 某个模型有 Token，但成本为 0 或 unpriced

这通常说明价格表中没有完全匹配的模型 ID。检查汇总 JSON 中实际记录的模型名称，再通过 --price 补充，不要只看界面上的营销名称。

4. 能生成 .tex，但无法生成 PDF

.tex 生成成功只说明数据渲染正常。PDF 仍需要本机 LaTeX 编译器。没有 LaTeX 时使用 render_text_receipt.py，或者明确同意后再采用其他轻量 PDF 方案。

5. 与官方页面数字不一致

两者本来就不一定使用相同单位。先核对时间、时区和日志来源，再区分：

  • 原始 Token；
  • API 等价估算成本；
  • 套餐用量百分比；
  • 平台信用点；
  • 限额窗口。

不要把这些指标混成一个数字。

十六、优点与不足

优点

  • 直接读取原始 Codex JSONL，用量口径可审计；
  • 默认兼顾 Windows 与 WSL；
  • 按模型拆分输入、缓存、输出和推理 Token；
  • 同时保留总计、来源拆分、价格快照和限额快照；
  • JSON、LaTeX、PDF、纯文本链路清晰；
  • 没有 LaTeX 时仍有可靠 fallback；
  • 既能作为 Skill 自动执行，也能独立作为 CLI 工具运行；
  • 适合制作黑白打印件和归档报告。

不足

  • 只能统计本机能够访问到的日志，云端任务或其他设备可能缺失；
  • Codex 日志格式变化后，解析脚本可能需要同步更新；
  • 估算成本依赖价格表，不能视为官方账单；
  • 默认 WSL 路径只覆盖常见 Ubuntu root 环境；
  • 当前以命令行和 Agent 工作流为主，没有独立 GUI；
  • 报告准确性仍依赖用户给出正确的时间范围和日志目录。

十七、适合哪些人

Codex Usage Receipt 特别适合：

  • 高频使用 Codex CLI、App 或 IDE 插件的开发者；
  • 同时在 Windows 和 WSL 中工作的用户；
  • 想分析缓存命中率与模型用量结构的人；
  • 需要为团队、公司或实验室生成内部用量说明的人；
  • 想保留可复算 JSON，而不满足于一张截图的人；
  • 需要打印、归档或长期比较不同时间段用量的人。

如果只是偶尔使用 Codex，只想知道额度是否快用完，官方用量页面会更简单；如果需要回答“哪段时间、哪个模型、从哪里产生了多少 Token”，这个 Skill 才能体现价值。

十八、项目地址与参考资料

GitHub     OpenAI

本文依据项目当前公开 README 与 Codex Skills 公开资料整理。软件、日志格式、模型名称、价格和限额规则都可能继续变化，实际使用时请以仓库最新版本、生成报告中的价格快照及 OpenAI 官方用量页面为准。

图片来源

  • 项目预览图：GitHub Open Graph Assets；
  • Windows、Ubuntu、Python、JSON、LaTeX、GitHub、OpenAI 图标：Simple Icons，经 jsDelivr CDN 加载，CC0 1.0。