TrafficMonitor Codex Usage Plugin

中文 | English

把 Codex 的 5 小时额度、周额度、重置时间和今日 Token 用量放进 TrafficMonitor。适合长期把 TrafficMonitor 常驻在任务栏或桌面的 Codex 用户。

截图 / Screenshots

任务栏紧凑显示 / Taskbar view

鼠标悬停详情 / Hover tooltip

右键插件菜单 / Plugin context menu

中文

功能亮点

• 在 TrafficMonitor 显示两个项目：Codex 5 小时额度 和 Codex 周额度。
• 任务栏显示剩余额度百分比，并用小型进度条表现余量高低。
• 鼠标悬停提示框显示 5 小时/周剩余额度、重置时间、今日 Input / Output / Cached Token 明细。
• 悬停提示框还会显示本机今日按模型归属的 Token、前五个模型的 API 等价成本，以及整体定价覆盖率；完整列表保存在状态 JSON。
• 双击任一显示项，或从插件命令选择“立即刷新 Codex 用量”，可立刻触发后台采集。
• 插件命令可打开状态 JSON、配置目录和诊断日志。
• “插件选项”可查看/复制状态文件、日志文件、采集脚本路径，并设置刷新时间间隔。
• “插件选项”可设置语言：自动、中文 或 English；自动模式会跟随 TrafficMonitor 当前语言。
• “插件选项”可关闭 Codex 重置卡查询；关闭后不会读取 auth.json 或请求网络接口。
• 可显示 Codex 额度重置卡数量和过期时间；敏感 token、cookie、完整唯一 ID 不会写入状态文件。

运行要求

• Windows + TrafficMonitor。
• Python 3，采集脚本会优先使用 python，其次使用 py -3。
• 本机存在 Codex 数据目录，默认是 %USERPROFILE%\.codex。
• 从源码构建时需要 Visual Studio C++ Build Tools 或 Visual Studio 的 C++ 工具链。

快速安装

1. 从 Releases 下载 CodexUsage-TrafficMonitor-x64.zip。

2. 将压缩包内容解压到 TrafficMonitor 的 plugins 目录，保持下面的相对结构：

   plugins\
     CodexUsage.dll
     scripts\
       update_codex_usage.ps1
       collect_codex_usage.py
   

3. 重启 TrafficMonitor。

4. 在 TrafficMonitor 的显示项目设置中启用：

   • Codex 5 小时额度
   • Codex 周额度

从源码构建

推荐使用仓库自带脚本：

.\tools\build.ps1 -Platform x64 -Configuration Release

输出文件位于：

build\x64\Release\CodexUsage.dll
build\x64\Release\scripts\

如果当前 TrafficMonitor 环境不要求 DLL 签名，可跳过签名：

.\tools\build.ps1 -Platform x64 -Configuration Release -SkipSign

也可以显式指定证书：

$env:CODEX_TRAFFICMONITOR_SIGN_THUMBPRINT = '<code-signing-cert-thumbprint>'
.\tools\build.ps1 -Platform x64 -Configuration Release

或直接使用 CMake：

cmake -S . -B build\cmake-x64 -A x64
cmake --build build\cmake-x64 --config Release

手动采集

可以先手动生成一次状态 JSON，确认采集链路正常：

.\scripts\update_codex_usage.ps1

默认输出到：

%USERPROFILE%\.codex\trafficmonitor\codex_usage_status.json

插件运行时默认使用 TrafficMonitor 传入的插件配置目录：

<TrafficMonitor 配置目录>\plugins\CodexUsage\codex_usage_status.json
<TrafficMonitor 配置目录>\plugins\CodexUsage\codex_usage_plugin.log
<TrafficMonitor 配置目录>\plugins\CodexUsage\codex_usage_plugin.ini

常用环境变量：

• CODEX_TRAFFICMONITOR_USAGE_JSON：指定 DLL 读取和脚本写入的状态 JSON 路径。
• CODEX_TRAFFICMONITOR_PYTHON：指定 python.exe 路径。
• CODEX_TRAFFICMONITOR_CODEX_BIN：指定 codex.exe 路径，用于 codex app-server 额度和账号级 Token 读取。
• CODEX_TRAFFICMONITOR_APP_SERVER=disabled：关闭 app-server 额度和账号级 Token 读取，强制使用本地回退路径。
• CODEX_HOME：指定 Codex 数据目录，默认 %USERPROFILE%\.codex。

采集器按“显式指定的 CODEX_TRAFFICMONITOR_CODEX_BIN → PATH → Codex 桌面应用安装目录” 查找程序。Windows 桌面应用目录为 %LOCALAPPDATA%\OpenAI\Codex\bin\*\codex.exe； 采集器检查文件及 PE 签名，并选择文件修改时间最新的有效候选，每次查询重新发现，适应版本目录变化。 显式指定的路径无效时会报告配置错误，便于发现过期配置。

插件配置文件 codex_usage_plugin.ini 会保存：

• refresh_interval_seconds：自动刷新间隔。
• language：auto、zh-CN 或 en-US。
• token_usage_mode：account 默认使用 app-server 账号级今日 Token；local 使用本地 Input / Output / Cached 明细。
• reset_credits_enabled：是否查询 Codex 重置卡。

数据来源与隐私

采集脚本只读取本机 Codex 数据：

%USERPROFILE%\.codex\sessions\**\*.jsonl
%USERPROFILE%\.codex\logs_2.sqlite
%USERPROFILE%\.codex\sqlite\logs_2.sqlite
%USERPROFILE%\.codex\state_5.sqlite
%USERPROFILE%\.codex\sqlite\state_5.sqlite

额度优先来自 codex app-server --listen stdio:// 的 account/rateLimits/read，并读取 rateLimitsByLimitId["codex"] 主额度。 采集器根据 windowDurationMins（5 小时为 300 分钟、周额度为 10080 分钟） 识别额度窗口，再把 usedPercent 转成剩余额度百分比后写入状态 JSON。因此官方 临时只返回一个 7 天 primary 窗口时，它仍会显示为周额度。如果 app-server 不可用或协议变化，则回退到 session JSONL 中 event_msg / token_count 携带的 rate_limits，再回退到日志中的 codex.rate_limits websocket 事件。缺少窗口时长的旧记录继续按 primary 为 5 小时额度、secondary 为周额度兼容处理。

今日 Token 默认来自 account/usage/read 的账号级 daily bucket。若在插件选项中 切换为本地明细模式，则读取 rollout JSONL 里的 token_count.info.total_token_usage，按本机当天增量统计 Input、Output 和 Cached。如果 app-server 不可用，账号模式也会回退到本地算法。

模型归属与费用则始终只统计本机今日 JSONL：采集器读取每个 turn_context 的 model，把后续累计 token_count 的增量归属给该模型，并单独显示在 tooltip 中； 它不会与账号级 daily bucket 混算。API 等价成本使用内置的公开 Standard API 文本单价 快照（当前快照日期为 2026-08-24），运行时不会访问定价网页。该数值不是 OpenAI 账单、订阅额度或实际 API 费用；未知模型和没有公开 Cache Write 单价的 token 会明确计为 未定价，定价覆盖率因此可能小于 100%。完整 JSON 字段说明见 docs/data-format.md。

为了显示 Codex 额度重置卡，采集脚本会读取 %USERPROFILE%\.codex\auth.json 中的 tokens.access_token，并请求 ChatGPT 的 reset-credit 接口。状态 JSON 和 tooltip 只保留可用数量、状态、标题、获取时间和过期时间； 不会写出 access token、refresh token、cookie 或完整唯一 ID。若 auth 缺失、401 或请求失败，则不显示重置卡区域。

重置卡查询可以在插件选项中关闭。开启时采集脚本会使用本地 sanitized reset-credit cache 缓存安全字段约 1 小时，避免每次 TrafficMonitor 刷新都请求网络；缓存不包含 token、 cookie 或完整唯一 ID。

常见问题

插件没有加载

确认 CodexUsage.dll 与 scripts\ 位于 TrafficMonitor plugins 目录下，并且 TrafficMonitor 与 DLL 架构一致。某些 Windows Code Integrity 策略会拦截未签名 DLL； 这种情况下请用本机代码签名证书重新构建。

显示 旧 或重置时间过期

最新额度事件超过 6 小时没有刷新，或窗口重置时间已过时，插件会显示 旧。 自动采集正常执行不代表实时额度查询成功：实时接口失败后，采集器仍可读取本地历史记录。 悬停提示会显示实时查询失败的原因、是否正在使用本地记录，以及额度记录时间。

请通过插件菜单打开状态 JSON 或诊断日志，检查 app_server_rate_limits： not_found 表示找不到 Codex 程序，invalid_override 表示显式路径失效， launch_failed、timeout、api_error 分别表示启动失败、查询超时、接口错误。 修复程序路径或接口访问问题后执行“立即刷新 Codex 用量”，确认 rate_limits_source 为 app-server:account/rateLimits/read。 账号 Token 查询使用同一套程序发现逻辑，独立诊断保存在 app_server_token_usage。

Token 明细为空

确认 CODEX_HOME 指向正确的 Codex 数据目录，并检查诊断日志是否能找到 Python。 如果 rollout 统计不可用，状态 JSON 会保留旧日志/线程汇总字段作为兼容数据。

开发与发布

运行测试：

python -m unittest discover -s tests -v

推送 v* tag 会触发 GitHub Actions：

• 运行 Python 单元测试。
• 构建 x64 Release DLL。
• 打包 CodexUsage.dll 和 scripts/。
• 将 CodexUsage-TrafficMonitor-x64.zip 上传到 GitHub Release。

发布包默认未签名；如果你的 TrafficMonitor 环境要求代码签名，请用本机证书重新构建并签名。

本机替换测试

本机 TrafficMonitor 目录通常是：

D:\03-RequiredSoftware\系统-TrafficMonitor\

替换测试时只复制：

build\x64\Release\CodexUsage.dll -> <TrafficMonitor>\plugins\CodexUsage.dll
build\x64\Release\scripts\       -> <TrafficMonitor>\plugins\scripts\

不要覆盖 <TrafficMonitor>\plugins\CodexUsage\，它是运行时配置、状态 JSON 和日志目录。

许可证

MIT License。详见 LICENSE。

---

English

TrafficMonitor Codex Usage Plugin shows Codex usage limits inside TrafficMonitor: the 5-hour quota, weekly quota, reset time, today's account token usage or local token breakdown, local per-model token usage with an API-equivalent estimate, and optional reset-credit cards.

Features

• Adds two TrafficMonitor items: Codex 5-hour quota (5h) and Codex weekly quota (wk).
• Renders remaining quota as compact percentage text plus a small bar.
• Shows reset times and today's account-level token usage in the tooltip by default.
• Lets you switch the token display to the local Input / Output / Cached breakdown.
• Shows the top five local models for today plus their API-equivalent cost; the status JSON keeps the complete model list and token categories.
• Reports pricing coverage and leaves unknown models or unpublished cache-write rates visibly unpriced rather than treating them as free.
• Refreshes on item double-click or through the plugin command menu.
• Opens the status JSON, config directory, and diagnostic log from plugin commands.
• Provides an options dialog for refresh interval, language, and file-path inspection/copying.
• Lets you disable reset-credit fetching from the options dialog; disabled mode does not read auth.json or call the network endpoint.
• Keeps reset-credit output sanitized; access tokens, refresh tokens, cookies, and full IDs are not written to the status JSON.

Requirements

• Windows + TrafficMonitor.
• Python 3 available as python or py -3.
• A local Codex data directory, usually %USERPROFILE%\.codex.
• Visual Studio C++ Build Tools only if you build from source.

Install

1. Download CodexUsage-TrafficMonitor-x64.zip from Releases.

2. Extract the zip contents into TrafficMonitor's plugins directory:

   plugins\
     CodexUsage.dll
     scripts\
       update_codex_usage.ps1
       collect_codex_usage.py
   

3. Restart TrafficMonitor.

4. Enable Codex 5-hour quota and Codex weekly quota in TrafficMonitor's display-item settings.

Language

The options dialog supports Auto, Chinese, and English. Auto follows the current TrafficMonitor language, and other non-Chinese host languages fall back to English. The setting is saved in codex_usage_plugin.ini as language=auto, zh-CN, or en-US.

Build

.\tools\build.ps1 -Platform x64 -Configuration Release

To skip code signing:

.\tools\build.ps1 -Platform x64 -Configuration Release -SkipSign

The build output is:

build\x64\Release\CodexUsage.dll
build\x64\Release\scripts\

Data And Privacy

The collector resolves CODEX_TRAFFICMONITOR_CODEX_BIN first, then PATH, then %LOCALAPPDATA%\OpenAI\Codex\bin\*\codex.exe on Windows. Desktop candidates must have a valid DOS/PE signature; the newest valid file by modification time wins. Discovery runs on each query so desktop updates can change the install directory. An invalid explicit override is reported instead of silently ignored. Both quota and account-token queries use this resolver. Failed live queries are reported in the diagnostic log, status JSON, and hover tooltip; local quota fallback includes the original record time. Diagnostics store fixed error summaries and numeric codes, never raw RPC errors, credentials, or response bodies.

The collector prefers codex app-server --listen stdio:// and calls account/rateLimits/read, using rateLimitsByLimitId["codex"] as the main Codex quota source. It converts primary.usedPercent / secondary.usedPercent into remaining percentages before writing the status JSON, classifying the 5-hour and weekly quotas from windowDurationMins (300 and 10080 minutes). A lone 7-day primary window is therefore displayed as the weekly quota when the 5-hour limit is temporarily unavailable. If app-server is unavailable or its protocol changes, the collector falls back to local Codex session/log/state files under %USERPROFILE%\.codex: session JSONL rate_limits first, then legacy codex.rate_limits log events. Older records without window duration metadata retain the positional fallback: primary is the 5-hour quota and secondary is the weekly quota.

Today's token display defaults to account/usage/read from codex app-server, using the app-server daily bucket. The options dialog can switch to the local rollout JSONL token_count.info.total_token_usage breakdown for Input / Output / Cached. If app-server is unavailable, account mode falls back to the local token algorithm.

Per-model usage and the API-equivalent estimate always come from local JSONL, not from the account bucket: the collector attributes each cumulative token_count delta to the active turn_context.model. It uses an embedded 2026-08-24 snapshot of public Standard API text-token prices and never fetches pricing at runtime. The result is an estimate, not an OpenAI invoice, subscription quota, or actual API charge. Unknown models and token categories without a public cache-write price remain unpriced and lower the reported pricing coverage. See docs/data-format.md for the status JSON schema.

For reset-credit display, the collector may use the local Codex auth.json access token to call the ChatGPT reset-credit endpoint. The output is sanitized and omits credentials and full unique IDs. If auth is missing or the request fails, the reset-credit section is hidden. When enabled, a sanitized reset-credit cache is reused for about one hour to avoid repeated network calls.

Development

python -m unittest discover -s tests -v

Pushing a v* tag runs GitHub Actions tests, builds the x64 Release DLL, packages the DLL plus scripts, and uploads CodexUsage-TrafficMonitor-x64.zip to the GitHub Release.

For a local TrafficMonitor smoke test, close TrafficMonitor, replace only plugins\CodexUsage.dll and plugins\scripts\ from build\x64\Release, then restart TrafficMonitor. Do not overwrite plugins\CodexUsage\; that directory contains runtime config, status JSON, and logs.

License

MIT License. See LICENSE.