Token Monitor

一个简约、高级、无动效干扰的 Codex 桌面 Token 监测小窗。它以透明、无边框、始终置顶的 Electron 窗口常驻桌面，可一键切换本地 Hook 处理量与 Codex 官方统计；读取过程不调用模型。

Windows 安装包（推荐）

适用于 Windows 10/11 x64。打开 GitHub Releases，下载 Token-Monitor-Setup-2.1.0-x64.exe 后直接运行。安装器会创建桌面与开始菜单快捷方式，并在完成后启动 Token Monitor。

安装版不要求另外安装 Node.js。电脑上需要已有可用的 Codex：

• 首次启动选择“使用官方统计”，会复用当前 Codex 登录并直接读取官方数据；
• 选择“安装本地 Hook”，或稍后从托盘点击“安装 / 更新本地 Hook”，即可启用本地逐轮统计；
• 本地 Hook 使用安装包内 Electron 的本地运行时，不会发起模型请求，也不额外消耗 Token。

当前安装包没有商业代码签名证书，Windows 可能显示“未知发布者”或 SmartScreen 提示。请只从本仓库 Release 下载，并对照 Release 中的 SHA-256 校验文件；确认一致后可点击“更多信息 → 仍要运行”。

功能

• 346 × 80 收起胶囊与完整展开面板
• 本地 / 官方统计一键切换，收起态与展开态同步换源并持久化选择
• 本次请求、今日、近 7 天、本月和累计本地 Token
• Codex 官方今日、近 7 天、本月、累计 Token 与七日趋势
• 当前会话上下文剩余量与进度条
• Codex 官方一周额度剩余及重置日期
• 近 7 天柱状图 / 平滑折线图双向切换
• 40%–100% 窗口透明度调节并持久化
• 始终置顶、拖动、托盘显示 / 退出
• 本地与官方统计统一按北京时间进行日历聚合
• 无过渡动画，状态切换即时呈现
• Windows x64 一键安装、快捷方式与标准卸载入口

从源码一键配置（Windows）

需要 Windows 10/11、Git、Node.js 22.12+ 和 Codex CLI。

git clone https://github.com/fplity/Token-Monitor.git
cd Token-Monitor

双击 一键配置 Token Monitor.cmd。脚本会依次：

1. 检查 Node.js、npm、Codex CLI 与 Codex 登录状态；
2. 安装 Electron 依赖；
3. 安装并启用随仓库提供的 Codex Usage Logger Hook；
4. 验证 account/usage/read 官方只读数据接口；
5. 运行测试并启动 Token Monitor。

安装完成后重启一次 Codex。首次启用或 Hook 内容变化时，在 Codex 中通过 /hooks 查看并信任命令。

也可以直接在 PowerShell 中运行：

powershell -ExecutionPolicy Bypass -File .\setup-token-monitor.ps1

脚本可选参数：-SkipHook、-SkipOfficialCheck、-SkipLaunch。

手动安装

npm ci
codex plugin marketplace add "$PWD"
codex plugin add codex-usage-logger@token-monitor
powershell -ExecutionPolicy Bypass -File .\launch-token-monitor.ps1

官方数据如何取得

Token Monitor 启动本机 codex app-server --stdio，通过以下只读方法读取当前用户自己的 Codex 数据：

• account/usage/read：官方每日 Token 桶和累计总量；
• account/rateLimits/read：Codex 一周额度及重置时间。

它复用 Codex CLI 已有的登录状态，不读取、复制或保存登录令牌。读取统计接口不会调用模型，因此不会额外消耗 Token。最简单的准备方式是先执行：

codex login
codex login status

仅使用 API Key 或 Bedrock 登录时，官方账户统计接口可能不可用；请使用受 Codex 服务支持的 ChatGPT 登录。接口定义参见 Codex App Server 官方文档。

官方每日统计由服务器异步聚合，不保证实时。当天日桶尚未生成时，小窗会显示“待同步”；服务器返回数据后，小窗最多约 60 秒完成下一次同步。本地模式仍会在每轮结束后快速更新。

数据口径

本地模式

• 本次：最近一次请求完成后 Hook 写入的单条 turn_usage.total_tokens。
• 今日 / 7 天 / 本月 / 累计：将本地 Hook 记录按 session_id + turn_id 去重后直接累加，日历按北京时间归档。
• 上下文剩余：model_context_window - last_response_usage.total_tokens。

本地累计包含各轮重复发送的上下文，表示模型实际处理过的本地记录量，通常高于 Codex 官方优惠或配额计量，二者不应直接对比。

官方模式

• 收起态显示官方今日、近 7 天与当前会话上下文剩余。
• 展开态显示官方今天、7 天、本月、累计与七日趋势。
• 官方数据不会与本地 Hook 数据相加，也不会在接口失败时偷偷回退成本地值。

Codex 一周额度始终独立读取，不随本地 / 官方开关变化；重置日期按北京时间显示。

数据与隐私

Usage Logger 将本地记录写到：

%CODEX_HOME%\usage\codex-usage.jsonl

未设置 CODEX_HOME 时使用 %USERPROFILE%\.codex\usage\。Hook 不会保存提示词、回复正文、完整项目路径、登录信息或额度明细；会话与轮次 ID 会先哈希。小窗和 Hook 都不会发起模型请求，因此监测本身不额外消耗 Token。

小窗会自动查找 CODEX_HOME 和用户目录下的 .codex/usage。如需自定义路径，复制 usage-config.example.json 为 usage-config.json 后修改；真实配置已被 Git 忽略。

更新与卸载

下载并运行更高版本安装包即可原位更新。卸载请前往 Windows“设置 → 应用 → 已安装的应用”中的 Token Monitor。

如果曾从托盘安装本地 Hook，并希望一并移除，可在卸载前或卸载后执行：

codex plugin remove codex-usage-logger@token-monitor --json
codex plugin marketplace remove token-monitor

未手动移除 Hook 时，卸载后的本地执行器会在找不到 Token Monitor 与 Node.js 时静默退出，不会影响 Codex 对话。

开发与验证

npm test
npm run verify:official
npm run pack:win
npm run verify:package
npm run dist:win

直接打开 index.html 可进行纯 UI 预览；桌面运行请通过 Electron 启动脚本。

许可证

MIT