Codex Monitor 是一个中文 Windows 托盘工具,帮助你查看本机有多少个 Codex 任务正在运行、各自在哪个项目中工作,以及任务何时完成。适合同时运行多个 Codex 任务、希望在桌面一角查看进度的人使用。
默认用大号数字显示运行中任务数,下方显示涉及的项目数。例如,同一时刻有 5 个任务分布在 2 个工作目录中,卡片主显示 5,副显示"涉及 2 个项目"。点击"显示项目 / 显示任务"即可切换主显示,程序会保存你的选择。
平台:Windows x64 · 中文界面 · 解压运行 · 发布包自带 .NET 运行时
| 功能 | 使用方式 |
|---|---|
| 任务与项目统计 | 约每 1.2 秒刷新运行中任务,显示标题、工作目录和已运行时间;项目数按这些任务的工作目录去重统计。 |
| 桌面显示 | 使用完整面板查看任务列表,切换窄窗只保留统计与用量卡片,也可开启窗口置顶。 |
| 系统托盘 | 关闭窗口后继续监控;点击托盘图标打开面板,右键可调整设置或退出程序。 |
| 完成提醒 | 检测到任务完成后发送桌面通知,可选择播放提示音;开启提醒模式后还会弹出面板。 |
| 任务数阈值提醒 | 开启提醒模式,设置运行中任务数阈值,任务数降到阈值以内时提醒一次。 |
| 开机自启 | 在面板或托盘菜单中启用,登录 Windows 后在托盘中运行。 |
| 官方套餐余量 | 读取本机 Codex 已记录的 OpenAI 套餐限额,显示剩余百分比、限额窗口和重置时间。 |
| 第三方 API 余额 | 读取 CCSwitch 当前 Codex 供应商的余额配置,查询并显示接口返回的余额。 |
任务监控依据本机 Codex 状态库与 rollout JSONL 日志;程序从日志恢复状态,再分块读取新增内容。统计范围取决于这些本地记录,不包含无法在本机读取记录的其他设备或云端任务。Codex 更新若改变数据库或日志格式,可能需要同步调整兼容性。
- 打开 GitHub Actions,选择最近一次成功的
Build。 - 在该次运行的 Artifacts 区域下载
CodexMonitor-win-x64。 - 将整个压缩包解压到准备长期使用的文件夹,运行其中的
CodexMonitor.exe。 - 启动一个本机 Codex 任务,在面板中查看运行状态;按需开启自启、提醒或窄窗模式。
下载 Actions 构建产物可能需要登录 GitHub。发布包包含运行时,无需另行安装 .NET;请保留同目录下的其他发布文件。
程序需要本机已有 Codex 状态记录。若面板提示找不到 state_5.sqlite,请先运行 Codex,并检查是否设置了自定义 CODEX_HOME。使用默认目录时,通常不需要额外配置。
- 任务 / 项目主显示:点击左侧统计卡片右上角的"显示项目 / 显示任务"。切换只改变卡片显示方式,提醒阈值始终按任务数计算。
- 窄窗:点击面板顶部的"窄窗",保留统计和用量卡片;点击"展开"恢复任务列表。
- 提醒模式:开启后隐藏面板,任务完成或达到任务数阈值时弹出。你也可以随时从托盘打开面板。
- 声音:右键托盘图标,勾选或取消"完成时播放声音";"播放测试声音"可用于确认音量。
提醒阈值默认是 5 个任务,可设为 0–99。只有任务数从阈值以上降到阈值以内才触发阈值提醒:例如设为 5,从 6 降到 5 会提醒;启动时已经只有 5 个任务,不会立即触发。任务完成通知独立于这个阈值。
点击面板顶部的"开机自启",或在托盘菜单中勾选"随 Windows 启动"。这里的自启指当前用户登录 Windows 后启动,程序使用 --background 参数进入托盘,默认不弹出主窗口。
如果登录后没有看到面板,先检查任务栏右侧的托盘及隐藏图标区域。若仍找不到:
- 确认程序文件夹仍在原位置,
CodexMonitor.exe及配套文件没有被移动或删除。 - 从要保留的程序目录手动启动一次。已有自启注册时,程序会将路径更新到当前运行的 EXE;尚未启用时,在面板中开启自启。
- 检查 Windows 任务管理器的"启动应用"中是否禁用了 Codex Monitor;若已禁用,将其启用。
更换程序目录或更新版本前,可先从旧程序的托盘菜单退出,再启动新版。自启写入失败时程序会提示原因;仍有问题可使用下方 --diagnostic-startup 命令检查注册路径。卸载时先关闭自启,再退出程序并删除解压目录。
用量卡片约每 30 秒刷新一次。任务监控可以独立使用,用量查询不可用时仍可查看任务状态。
| 数据来源 | 需要什么 | 显示内容与限制 |
|---|---|---|
| 官方 OpenAI 套餐 | 本机 Codex rollout 日志中有可用的套餐限额快照;无需安装 CCSwitch。 | 剩余百分比、主 / 次限额窗口及重置时间。数值来自 Codex 已记录的快照,刷新卡片不会主动向 OpenAI 获取新用量。 |
| CCSwitch 第三方供应商 | 在 CCSwitch 中选择当前 Codex 供应商,启用余额查询并配置接口。 | 余额、单位,以及接口提供的套餐或当日用量。当前支持 Bearer 认证的 JSON 余额接口,从 remaining、quota.remaining 或 balance 读取余额。 |
官方路径没有可用且尚未过期的限额快照时,界面会显示"不可查询"或相关未配置信息。第三方查询只使用 CCSwitch 配置中可识别的地址、密钥和接口路径,不执行任意余额脚本;接口采用其他认证方式或响应结构时,可能需要增加适配。
Codex Monitor 在本机读取以下数据:
%CODEX_HOME%\state_5.sqlite;没有设置CODEX_HOME时读取%USERPROFILE%\.codex\state_5.sqlite。- 状态库中记录的 Codex rollout JSONL 文件,包括任务事件和官方套餐限额快照。
- 可选的
%USERPROFILE%\.cc-switch\cc-switch.db,用于识别当前供应商及读取第三方余额配置。
程序以只读方式打开 Codex 和 CCSwitch 数据库。
官方套餐查询只读取本机限额快照,不读取 OAuth Token,也不请求 OpenAI 私有接口。
第三方供应商需要在 CCSwitch 中启用余额查询并提供相应的接口配置。查询时,Codex Monitor 会临时读取当前供应商的 API Key,并将其作为 Bearer Header 发往该供应商配置的 HTTPS 地址或本机回环地址。程序不显示 API Key,也不会把 Key 写入自己的设置或日志。
个人设置保存在 %APPDATA%\CodexMonitor\settings.ini。自启设置写入当前 Windows 用户的启动注册表项。
在程序所在文件夹打开 PowerShell,按需运行:
# 检查当前 EXE 与 Windows 自启注册路径是否一致 .\CodexMonitor.exe --diagnostic-startup startup.json # 导出任务状态,排查任务数量或状态识别问题 .\CodexMonitor.exe --diagnostic-snapshot snapshot.json # 导出官方套餐快照或第三方余额诊断 .\CodexMonitor.exe --diagnostic-balance balance.json # 播放一次完成提示音 .\CodexMonitor.exe --test-sound
--diagnostic-startup 只读检查当前 EXE 路径、预期与实际自启命令、注册是否匹配以及读取错误,不会改写自启设置。用量诊断中,官方套餐检查本机 rollout 快照,第三方供应商检查 CCSwitch 配置及余额接口。
自启诊断包含程序完整路径;任务快照包含任务标题、Thread ID 和完整工作目录;用量诊断包含供应商、套餐、限额窗口或余额结果,但不包含 API Key 或 OAuth Token。提交 Issue 或把诊断文件发给他人前,请先删除不希望公开的信息。
需要 Windows x64 和 .NET 10 SDK。在仓库根目录运行:
dotnet restore CodexMonitor.sln --locked-mode dotnet format CodexMonitor.sln --verify-no-changes --no-restore dotnet build CodexMonitor.sln --configuration Release --no-restore dotnet test CodexMonitor.sln --configuration Release --no-build
创建自包含发布包:
./scripts/publish.ps1
脚本会把文件写入 artifacts/win-x64,然后在隔离的空 CODEX_HOME 中运行一次诊断冒烟测试。GitHub Actions 使用同一套还原、格式检查、构建、测试和发布流程。
src/CodexMonitor/ WinForms 应用源码
tests/CodexMonitor.Tests/ 状态、用量与自启注册测试
scripts/publish.ps1 Windows x64 发布与冒烟测试
.github/workflows/ GitHub Actions 构建流程
如果你遇到自启、状态识别或余额接口兼容问题,请提交 Issue,说明 Windows 与 Codex 版本、所用构建、复现步骤及实际表现,并附上已脱敏的诊断结果。
本仓库目前没有为项目源码授予许可证。公开可见不代表允许复制、修改或分发源码。自包含构建中使用的第三方组件及其许可信息见 THIRD-PARTY-NOTICES.md。