我做了一个 Codex 额度插件:把剩余额度和重置时间放到侧栏,不用反复翻页面

项目地址:https://github.com/fengguanghuai/codex-quota-rail
技术栈:Node.js / JavaScript / Shadow DOM / macOS Swift 原生助手
关键词:Codex、AI 编程、额度监控、桌面工具、开源、效率工具
之前我分享过 AI Token Dashboard,用来回看不同 AI 工具的 Token 消耗。最近我又做了一个更小的工具,解决另一个日常问题:写代码的时候,能不能一眼看到 Codex 还剩多少额度、什么时候重置?
于是有了 Codex Quota Rail。它是一个非官方的桌面侧栏扩展,把周剩余额度做成一个小圆环,放在 Codex 的头像上方。平时看一眼百分比,需要更多信息时,把鼠标移过去就能展开详情。
一、为什么做这个插件
用 AI 编程工具做长任务时,我比较关心两件事:
- 当前还有多少额度,接下来适不适合继续做一轮较大的修改?
- 额度什么时候重置,是否需要调整一下任务安排?
这些信息如果需要离开当前工作界面再去查,就会打断思路。我希望它像电池电量一样,平时安静地待在角落,需要时随手就能看到。
这个项目的目标很直接:把额度状态放到工作现场,减少来回查找。 它展示剩余比例和重置时间,不估算“还能完成几个任务”,也不改变账户本身的额度。
二、界面上能看到什么
1. 侧栏里的剩余额度圆环

侧栏实机截图:圆环位于头像上方,显示每周剩余额度。
头像上方会出现一个小圆环,中心显示每周剩余额度百分比。随着额度减少,颜色会从绿色逐渐转向橙色、红色,帮助你快速判断当前状态。
这里显示的是剩余比例:比如 44%,代表剩余 44%,不是已经用了 44%。
2. 悬浮展开详情,点击可以固定

实机截图:额度、重置时间和点数为截图时的账户状态,仅作界面展示,不代表所有账户都有相同字段。
鼠标悬浮在圆环上可以查看详情,点击后可以固定面板;再次点击、点击外部或者按 Escape 都能关闭。
详情按账户实际返回的数据展示:
- 每周剩余额度、重置时间和倒计时;
- 可用时展示 5 小时窗口的剩余额度和重置时间;
- 周期已经过去的时间进度;
- 可用时展示重置卡次数、最近到期时间和额外点数余额。
不是所有账户都会返回所有字段。没有提供的数据不会补成虚构数字;数据读取失败或过期时,也会显示暂不可用,避免把旧数字当成实时额度。
3. 中英文切换与自动刷新
面板支持中英文切换,并保存语言偏好;时间按电脑本地时区显示。额度默认每分钟同步,也可以手动刷新。
三、它和 AI Token Dashboard 有什么区别
两个项目关注的问题不同:
| 工具 | 主要回答的问题 | 使用方式 |
|---|---|---|
| AI Token Dashboard | 过去用了多少 Token,消耗主要来自哪里? | 打开看板做统计和复盘 |
| Codex Quota Rail | 当前剩余额度是多少,什么时候重置? | 在 Codex 侧栏随时查看 |
如果说 Dashboard 更适合事后复盘,那么这个小插件更适合工作中的即时查看。它也不需要为了显示额度一直让 AI 对话运行,安装后的同步由本地后台助手完成。
四、快速开始
目前项目是预览版。macOS 需要 macOS 14+、Node.js 22+,以及已经安装、登录并具备兼容接口的 Codex / ChatGPT 桌面客户端。Windows 10/11 有实验支持,真实客户端界面的兼容性仍需要继续验证。
1. 获取项目并安装
▼bash复制代码git clone https://github.com/fengguanghuai/codex-quota-rail.git cd codex-quota-rail node src/cli.mjs install
也可以在项目目录中双击 macOS 的 Install.command;Windows 对应 Install.cmd。日常运行不需要先执行 npm install,开发测试时才需要安装开发依赖。
2. 从原来的应用图标启动
首次安装后,先保存工作,完全退出客户端,再点击原来的应用图标打开。
它不会修改应用安装包、签名或原图标。为了建立连接,新启动时后台助手可能正常退出并重开客户端一次;如果你已经开始操作,就会跳过这次自动重开。安装操作本身不会退出正在使用的客户端。
3. 检查状态
▼bash复制代码node src/cli.mjs status
如果没有显示圆环,可以先检查是否已连接、是否成功附着到窗口,再按仓库 README 排查。客户端更新可能改变界面结构,跨版本兼容性还在持续验证。
4. 不需要时可以卸载
▼bash复制代码node src/cli.mjs uninstall
卸载后完全退出客户端,再正常打开,以关闭这次运行的调试端口。卸载不会删除客户端、登录信息或聊天记录。
五、实现思路
整体流程并不复杂:
▼text复制代码本机 Codex app-server 的只读额度接口 ↓ 本地后台助手读取并整理额度窗口 ↓ 通过本机 CDP 连接挂载侧栏组件 ↓ Shadow DOM 隔离样式,显示圆环与详情
界面层使用原生 JavaScript;macOS 的启动监听由 Swift 原生助手负责,Windows 使用 PowerShell / CIM 事件。运行时没有引入 npm 第三方包,尽量保持轻量。
我也做了几个使用上的约束:找不到合适的侧栏锚点就不显示,数据失效就不继续显示旧额度,已经开始操作的会话不强制重启。一个常驻小组件,除了能显示数据,也应该尽量少打扰工作。
六、使用前需要了解的边界
这是我独立开发的非官方扩展,不是 OpenAI 官方插件,也不是官方插件商店中的扩展。当前主要完成了自动化 DOM / 协议测试及本机客户端嵌入验证,不能据此保证所有系统、账户和客户端版本都兼容。
组件不扫描工程、不读取会话数据库,但实现需要开启本机调试接口 127.0.0.1:39333。这个接口的能力超过额度展示,监听 localhost 也不等于有身份认证;不要对外转发端口。安装前建议阅读仓库的 安全说明。
七、欢迎试用和反馈
这个项目解决的是一个很小的需求:写代码时,不用反复离开当前界面查看剩余额度。
如果你也经常用 Codex 做长任务,欢迎试用。遇到兼容性问题,可以在 GitHub Issue 中附上系统版本、客户端版本和必要的状态信息;截图时记得避开聊天内容和账户信息。
项目采用 MIT 许可证,欢迎提 Issue、PR,也欢迎 Star 支持。
项目地址:https://github.com/fengguanghuai/codex-quota-rail
之前的项目分享:AI Token Dashboard · llm-wiki
