Windows 上实时查看 Codex 用量：我做了一个原生桌面挂件

最近我做了一个 Windows 小工具，叫 CodexUsageBar。

项目地址：

https://github.com/luodaoyi/codex-useage-win

一句话概括：它是一个原生 Win32/C++ 桌面挂件，把当前 Codex 账号的 5 小时和每周用量，直接放在桌面上实时显示。

为什么要做这个挂件

Codex 的额度不是一个“用完就知道”的东西。

平时写代码时，最容易遇到的情况是：

一口气跑了几个比较大的任务，不确定当前 5 小时额度还剩多少
任务还没有结束，但不知道是不是已经接近限额
想安排下一次长任务，却不清楚本周额度和当前周期的消耗速度
每次都要打开 Codex 或相关页面，才能确认一次用量

我想要的其实很简单：不用切窗口，抬头就能看到当前额度状态。

所以我做了一个常驻桌面的小面板，让它自己读取 Codex 的授权信息并刷新用量。它不追求复杂的设置，而是把最有用的数字一直放在眼前。

它能显示什么

CodexUsageBar 关注的不只是一个“剩余百分比”，而是把额度周期和使用速度一起展示出来：

信息	用途
5 小时限额已用 / 剩余	判断当前短周期还能不能继续跑任务
每周限额已用 / 剩余	判断本周整体的额度余量
当前周期理论应使用量	按时间进度估算现在应该用到哪里
实际使用量	观察真实消耗
高于进度 / 低于进度	判断自己是在超前消耗还是比较节制
距离重置时间	知道什么时候可以重新安排任务
上次成功刷新时间	确认面板显示的是不是新数据
距离下次自动刷新	知道下一次更新还要等多久

“理论应使用量”和“实际使用量”放在一起很有价值。只看剩余百分比，往往要等到快用完了才发现问题；看使用速度，可以更早决定是继续跑，还是把任务拆开。

为什么选择原生 Win32/C++

这个工具我没有用 C#，也没有嵌 WebView，而是直接使用 Windows 原生能力：

Win32：窗口、消息循环、拖动和缩放
Direct2D：绘制面板、进度条和状态颜色
DirectWrite：文字排版和字体渲染
WinHTTP：请求 Codex 用量接口
C++：把它编译成一个独立的 Windows 可执行文件

这样做的好处很直接：

不需要安装运行时
不需要启动浏览器
不需要额外跑一个本地服务
常驻时更像一个系统小组件
下载一个 exe 就能启动

这个项目的定位不是做一个新的 Codex 客户端，而是做一个尽量安静的桌面状态条。打开以后，它只负责告诉你额度和刷新状态，其他事情不抢你的注意力。

它是怎么拿到数据的

CodexUsageBar 会读取本机的 Codex 授权文件：

1
2
%USERPROFILE%\.codex\auth.json
%CODEX_HOME%\auth.json

程序会使用当前 Codex 账号的授权信息，请求：

1
GET https://chatgpt.com/backend-api/wham/usage

从返回结果中解析 5 小时和每周限额，再计算剩余比例、周期进度、重置倒计时等展示数据。

当前的刷新策略是：

远程用量接口每 60 秒请求一次
本地倒计时每 1 秒重绘一次
右下角显示上一次成功刷新时间和下一次自动刷新倒计时
右键菜单可以随时执行“立即刷新”

这种分工比较合理。真正访问网络的动作不用太频繁，但界面上的倒计时又不会停在一个旧数字上。

三种显示模式

我在面板里做了三种布局，适合不同的桌面习惯。

标准模式

标准模式信息最完整，包含：

顶部状态标题
5 小时和每周的核心指标
周进度条
当前预算标记线
底部明细
刷新时间和倒计时

如果你希望持续观察自己的使用节奏，平时就用这个模式。

简单模式

简单模式只保留两张紧凑卡片：

5 小时剩余
本周剩余

它适合放在屏幕边角，不想让面板占太多空间时使用。

任务栏模式

任务栏模式会变成更小的剩余额度条，自动贴近当前显示器的任务栏边缘。

这个模式比较像一个“状态灯”：

占用空间很小
自动贴边
适合一直显示
不支持拖动和缩放，因为它需要保持贴边状态

常用交互

标准模式和简单模式下，可以直接操作窗口：

拖动面板主体：移动位置
拖动右边缘：调整宽度
拖动下边缘：调整高度
拖动右下角：同时调整宽高

右键菜单提供这些功能：

立即刷新
开机自启
始终置顶
固定位置
显示模式
语言
重置组件位置
退出

位置和尺寸会保存到：

1
%APPDATA%\CodexUsageBar\settings.ini

开机自启使用当前用户的注册表项：

1
HKCU\Software\Microsoft\Windows\CurrentVersion\Run

因此它不需要管理员权限就可以保存自己的设置和开机启动状态。

下载后怎么用

如果只是想直接使用，最简单的方法是打开项目的 Releases 页面。

截至 2026 年 7 月 23 日，最新版本是 v0.1.19，提供两个 Windows 构建：

CodexUsageBar-x64.exe：普通 Intel/AMD 64 位 Windows
CodexUsageBar-ARM64.exe：Windows on ARM

下载对应文件后直接运行即可。程序会尝试读取当前用户的 Codex 授权文件，然后开始刷新用量。

第一次使用时建议确认三件事：

Codex 已经在这台机器上登录过
auth.json 位于 Codex 默认目录，或者已经设置了 CODEX_HOME
Windows 防火墙或网络环境允许访问 Codex 后端接口

如果授权文件不存在、JSON 损坏或接口返回错误，面板会保留错误信息，不会把错误响应当成正常的额度数据。

从源码构建

项目本身是标准的 CMake 工程，使用 C++20。

仓库提供了直接构建脚本：

1
build.cmd

也可以手动使用 Visual Studio 2022 生成器构建：

1
2
cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release

输出文件是：

1
CodexUsageBar.exe

GitHub Actions 会自动构建 x64 和 ARM64，并在推送版本标签后生成 Release。

这个项目适合谁

我觉得它比较适合下面这些人：

经常用 Codex 跑长任务
想在桌面上随时知道额度剩余多少
不喜欢打开网页查看用量
希望工具没有 WebView 和额外后台服务
使用 Windows，希望下载一个 exe 就能运行
想同时观察短周期额度和每周额度

如果你只是偶尔使用 Codex，打开一次页面也完全够用；但如果 Codex 已经成为日常开发工具，一个常驻的小状态面板会省掉很多反复确认的动作。

需要注意的地方

这个工具读取的是本机 Codex 授权文件，auth.json 属于敏感文件。建议：

只从项目 Release 或自己审查过的源码构建版本
不要把 auth.json 发给别人
不要把包含授权信息的目录打包上传
不要在截图或日志中暴露 Token

另外，用量接口属于 Codex 后端实现的一部分，不是承诺长期不变的公开 API。如果后端字段或授权方式变化，解析逻辑也需要跟着更新。这是这类本地用量工具必须面对的现实限制。

它也不是 Windows 7 时代的 Gadget，而是一个普通的原生桌面浮层窗口，运行在现代 Windows 桌面环境中。

最后

CodexUsageBar 没有试图把事情做复杂，它只解决一个很具体的问题：

让 Codex 的额度从“藏在账号里的数据”，变成桌面上随时可见的状态。