Codex Usage Card for Windows

非官方 Windows 适配：在 Codex 桌面客户端侧栏显示剩余额度圆环。本项目基于 Codex Usage Card v0.9.5 Beta 中的 agent，保留原 MIT 许可证和版权声明。本项目与 OpenAI 及上游作者无官方关联。

状态：实验版。 已有用户在 Windows Codex 客户端中看到圆环。不同账号、客户端版本和 Windows 安装环境的表现可能不同；完整冷启动、退出和客户端更新后的表现尚需进一步实测。

维护说明： 本项目为随手改造的个人实验，不承诺持续维护，也不承诺随 Codex 的版本更新而更新或保持兼容。Codex 后续更新可能导致功能失效。

已验证版本： 曾在 Windows Microsoft Store 版 Codex 26.1103.3517.0 上验证圆环显示；最新修复版的完整冷启动和退出流程仍待实测。后续如果本项目未再更新，有兴趣的用户可以将源码交给自己的 Codex，结合新版客户端继续改造和适配。

安装与启动

需要 Windows、已安装并登录的 Microsoft Store 版 Codex，以及支持 fetch 和 WebSocket 的 Node.js（优先使用客户端自带版本，否则需要 Node.js 22+）。

1. 完整解压本项目，双击 安装快捷方式.cmd。安装器将文件复制到 %LOCALAPPDATA%\CodexUsageCardWindows，在桌面创建“Codex 额度圆环”快捷方式，并从当前 Codex 提取图标。原 Codex 快捷方式保持不变。新快捷方式可手动固定到任务栏，图标和分组效果取决于 Windows。
2. 保存工作并完全退出 Codex，双击新快捷方式。额度助手在后台运行；启动器监视本次连接的客户端主进程，正常结束后会停止它启动的助手。
3. 若 Codex 已运行且连接可用，启动器尝试检查端口归属并复用现有客户端；若未开启所需连接，它会提示先退出，不自动关闭有可见窗口的客户端。后台残留进程只在用户确认后处理。端口冲突、身份无法核实或发现无法安全识别的旧助手时会停止并提示。

安装包中的 检查快捷方式.cmd 和 卸载快捷方式.cmd 可管理安装；安装目录内也有 检查状态.cmd 与 卸载.cmd。状态检查会报告助手连接、圆环挂载和额度数据是否可用，不显示具体额度；状态过期、不可读取或无法核实进程时会显示未知。命令行启动方式 启动.cmd 不提供此状态文件。不要与其他旧版助手同时运行。

额度显示、刷新频率与悬浮窗布局

• 圆环展示账号返回的剩余额度百分比；账号或服务未提供相应窗口时，可能只显示一个圆环或显示不可用。显示的是额度信息，不是对话上下文窗口。
• 将鼠标移到圆环可打开悬浮窗。上方显示额度与各自的重置时间；下方左侧显示重置卡数量和最近到期时间（仅在相应数据可用时出现），右侧显示“额度检测频率”、当前秒数、输入框和“确定”按钮。可用重置卡数量以绿色强调，当前刷新秒数以粉红色强调。
• 输入 10～300 之间、10 的整数倍的秒数并点击“确定”。界面显示的“当前”值变化后表示助手已应用。默认每 60 秒主动查询一次，设置保存在客户端本地存储；不符合当前规则的旧设置会回退默认值。
• 设置的应用、查询和界面更新可能有数秒调度或网络延迟；Codex app-server 主动推送变化时，圆环也可能提前更新。过短的间隔会增加请求频率；上述区间是本项目的限制，不代表 OpenAI 的官方推荐或授权。

Codex 插件

本项目包含本地插件市场清单和 usage-card-windows 指引技能。可在终端将仓库目录添加为本地市场：

codex plugin marketplace add <仓库的绝对路径>

按客户端提示重启并安装插件。该插件提供安装与排错指引，安装插件本身不会自动将圆环嵌入侧栏；圆环仍依赖专用快捷方式及后台助手。插件发现、安装和运行尚未在所有目标客户端完成端到端验证。参见 OpenAI 插件打包文档。

可能存在的问题与限制

• 界面注入和本地 app-server 协议可能随 Codex 更新改变，导致圆环错位、隐藏或额度不可用。遇到不兼容时可使用原 Codex 图标启动客户端。
• 本项目使用本机 127.0.0.1:39222 Chrome DevTools Protocol 调试接口。该接口能控制客户端；本机其他进程可能访问它，不要转发端口或对网络开放。监听进程检查只能降低误连风险，不能提供身份认证，也不能消除检查与连接之间的竞争。
• 不同账号可能没有重置卡、没有重置卡数据或没有某个额度窗口；不可用不等同于零。可用卡缺少有效到期时间时，不显示最近到期。
• 强制结束进程、客户端崩溃或自动重启可能留下后台助手；旧版本或改名后的副本可能造成冲突。应先通过状态检查及任务管理器确认，再关闭自己确认属于本项目的旧助手；不要结束不明进程。
• Codex 升级可能改变应用路径或图标。启动器会重新查找应用路径，但新版兼容性和现有快捷方式图标仍需实测。客户端已运行但未开启调试端口时，需要保存工作并正常退出后重新通过专用快捷方式启动。
• 完整冷启动、正常退出后助手自动退出、崩溃恢复、各 Windows 版本及多账号/多会话场景尚未全部实测。安装插件与任务栏固定、分组效果也需在目标设备验证。

隐私与免责声明

额度由本地 Codex CLI app-server 提供；本项目所审阅的额度读取路径不请求聊天内容。它不代表 Codex 客户端本身的数据处理方式。调试接口对本机其他进程具有风险，使用者应确认自己的设备和本地软件环境可信。

本项目为社区实验性软件，未获得 OpenAI 或上游作者的官方认证、支持或兼容性保证。OpenAI 的产品规则、接口和服务条款可能变化；本项目不能保证任何特定轮询频率或注入方式符合适用于你的账户的条款。使用前请自行审阅代码、上游许可和适用条款。

软件按 MIT 许可证原样提供，不提供明示或默示担保；责任限制以许可证原文及适用法律为准。请自行备份重要工作，并在使用前评估稳定性与安全风险。

卸载

1. 保存工作并完全退出 Codex，等待后台助手结束。
2. 运行解压目录中的 卸载快捷方式.cmd，或安装目录中的 卸载.cmd。卸载器只移除其确认归属的快捷方式和受管理文件；不能确认归属的文件会保留。若自行固定到任务栏，请在任务栏手动取消固定。
3. 完成卸载后可删除解压目录。卸载不删除 Codex 或其数据。如果添加过本项目的插件市场，在适用时运行 codex plugin marketplace remove usage-card-windows-local，并在插件目录移除插件。

开发验证

在项目目录运行 node --test tests/agent.test.cjs 可检查额度回退、CLI 选择和端口核验等逻辑。这些测试不代替真实桌面端的完整启动及兼容性验证。

来源与许可证

原项目与许可证见 Codex Usage Card 和 LICENSE。本仓库未声称获得 OpenAI 官方支持；是否发布及发布位置由维护者决定。