codex-token-usage

Codex Token 用量

概述

使用随附的脚本读取本地 Codex 会话日志，并生成统一的 Token 用量报告。优先使用脚本生成的确定性输出，而不是临时通过 rg 汇总。

默认：生成固定格式的 HTML 仪表板，并在系统默认的外部浏览器中打开。 对“统计本周用量”或“统计下 token”这类普通请求，也采用此默认设置。除非用户明确要求纯文本、Markdown、JSON 或不打开浏览器，否则不要只回复 Markdown 表格。重新执行旧任务时，请重新阅读此已安装文件；早期任务说明可能仍采用旧的 Markdown 默认设置。

工作流

1. 根据用户请求确定报告的时间范围。
   • 如果用户要求“一个月”或“上个月”，但未指定日历月份，则使用截至今天的最近 30 个本地日历日。
   • 如果用户要求“本月”或指定了某个月份，则使用该日历月；如果是当前月份，范围截至今天。
   • 如果上下文中提供了用户的时区，则使用该时区；只有在未提供时区时，才使用本地计算机时区。
   • “本周”指该时区中的周一至今天；传入明确的 --start 和 --end 日期。
2. 在用户的工作区中运行已安装的 scripts/codex_token_usage.py，并传入报告日期和时区。从包含此文件的技能目录中解析脚本路径。日志存在时使用当前的 CODEX_HOME；不要根据旧版技能安装路径推断日志位置。
3. 除非明确另有要求，否则使用 HTML（CLI 默认格式）。脚本会在工作目录下写入 output/token-usage-<start>-<end>.html，并请求系统默认的外部浏览器打开该文件。--output 可覆盖文件路径。报告应保存在技能源目录之外。
4. 不要使用应用内浏览器预览。如果打开失败或被阻止，请提供保存文件的链接，并如实说明文件未打开；不要绕过主机限制。仅成功发出操作系统启动请求，并不能证明页面已成功呈现。
5. 返回可点击的绝对 HTML 文件链接、确切的日期范围和简短摘要。仪表板中包含每日计数、峰值时段和指标定义；不要用冗长的 Markdown 表格替代。
6. 对明确要求纯文本或 Markdown 的请求，传入 --format markdown；对机器可读的请求，传入 --format json。这些格式会将内容打印到标准输出，除非提供了 --output，并且不会打开浏览器。用于自动化或用户要求不打开浏览器时，使用 HTML 并传入 --no-open。

脚本

在用户的工作区中运行，并传入已安装脚本的绝对路径（以下相对路径示例仅为简写）：

python scripts/codex_token_usage.py --days 30 --timezone Asia/Shanghai

常用选项：

python scripts/codex_token_usage.py --start 2026-03-30 --end 2026-04-28 --timezone Asia/Shanghai
python scripts/codex_token_usage.py --month 2026-04 --timezone Asia/Shanghai
python scripts/codex_token_usage.py --codex-home C:\Users\admin\.codex --days 30
python scripts/codex_token_usage.py --days 30 --format json
python scripts/codex_token_usage.py --days 30 --format markdown --language en
python scripts/codex_token_usage.py --days 30 --timezone Asia/Shanghai --format html --output /path/to/output/token-usage.html
python scripts/codex_token_usage.py --days 30 --timezone Asia/Shanghai --no-open

如果 python 不在 PATH 中，且有随附的 Codex 运行时，则使用它：

C:\Users\admin\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe scripts\codex_token_usage.py --days 30 --timezone Asia/Shanghai

定义

• total：所有 token_count 事件中 last_token_usage.total_tokens 的总和。
• input：所有 last_token_usage.input_tokens 的总和。
• cached input：所有 last_token_usage.cached_input_tokens 的总和。
• output：所有 last_token_usage.output_tokens 的总和。
• reasoning output：所有 last_token_usage.reasoning_output_tokens 的总和。
• non-cached input：input - cached input。
• net usage：non-cached input + output。
• cache hit rate：cached input / input。
• daily average total：total / 报告范围内的本地日历日数。

避免对每个事件的 total_token_usage 求和，因为该值在会话中是累计的，会导致重复计数。应改为汇总 last_token_usage。

回复格式

默认情况下，在请求外部浏览器打开后，提供 HTML 文件链接和简短摘要。只有用户明确要求纯文本或 Markdown 时，才使用下方的简明表格。将行标签本地化为用户使用的语言。

| Metric | Tokens | Notes |
|---|---:|---|
| Total | 730,366,547 | Sum of `total_tokens` |
| Input | 724,204,405 | Input tokens, including cached input |
| Cached input | 640,615,168 | Cached input tokens |
| Output | 3,239,893 | Output tokens |
| Reasoning output | 456,198 | Reasoning output tokens |
| Non-cached input | 83,589,237 | `Input - Cached input` |
| Net usage | 86,829,130 | `Non-cached input + Output` |
| Cache hit rate | 88.44% | `Cached input / Input` |
| Daily average total | 24,345,552 | `Total / days in range` |

然后用一句话补充峰值日和最繁忙的一周：

The peak day was 2026-04-01: 72,000,000 tokens.
The busiest week was 2026-03-30 to 2026-04-05: 244,371,620 tokens.

如果结果将用于其他脚本、自动化流程或报告生成器，请使用 --format json。文本回复请使用 Markdown。所有格式均支持通过 --output 将内容写入 UTF-8 文件。

HTML 仪表板

单个 HTML 文件内嵌 CSS、JavaScript 和汇总报告数据；无需构建步骤、服务端或 CDN，即可离线打开。必须启用 JavaScript。使用 --language zh（默认）或 --language en。

始终通过随附脚本和 assets/dashboard.html 生成 HTML。每份报告都重复使用此固定模板；仅替换汇总数据和语言。除非用户要求更改设计，否则不要重新设计页面、临时生成 HTML，或更改布局、颜色或交互方式。响应式布局仍会根据视口尺寸进行调整。

紧凑格式的 Token 值（包括每日明细表）在达到 100,000,000 时使用亿，达到 10,000,000 时使用千万，达到 1,000,000 时使用百万，最多保留两位小数。低于一百万时，显示带分组分隔符的完整数字；不要使用 B、M 或 K。表格提示和 CSV 保留精确的 Token 数量。事件数和会话数始终显示完整数字。

其中包括总用量／净用量、缓存命中率、会话数、日均用量、支持总量／净量模式和键盘访问日期选择的每日堆叠柱状图、Token 构成、峰值日／周、可排序的每日表格，以及 CSV 导出。日期使用所选的报告时区。用量为零的日期计入平均值，并保留在所有输出中。JSON 保留现有字段，并新增 timezone 和 generated_at；daily 现在包含日期范围内的每一天。

图表组件为非缓存输入 + 缓存输入 + 输出。缓存输入属于输入，推理属于输出；不要将任一子集叠加到其所属总项之上。如果来源总量与组件之和不符，仪表板会说明差额。不要将 Token 事件称为工具调用，也不要根据现有解析器臆造模型／项目排名、活跃时间或成功率。这是生成的快照，而非实时监控器。

生成的报告仅包含用量汇总，不含提示词、会话 ID 或来源路径。除非用户要求分享，否则报告保留在本地。安装该技能时，将 assets/dashboard.html 与 scripts/ 一同保留。