最近 Codex 和 Cursor 用得多，额度时不时就得切到用量页面看一眼：5 小时窗口还剩多少、这周用了多少、Cursor 这个月的 Auto 池到哪了。看多了嫌烦，干脆把它做到桌上的小屏幕里，顺手起了个名字叫 余刻（QuotaClock）。标语是「时间一眼可见，额度心中有数。」

代码放在 GitHub：akechi1980/QuotaClock。这里笔记一下它是什么、怎么用、有哪些限制。

先说明：本文的图都是设计示意图和示例数据，不是实机照片，不含真实账号或网络配置。

QuotaClock MONO 灰阶桌面时钟与三行额度进度设计示意
图 1：余刻 QuotaClock 设计示意（示例数据，非实机照片）

一，是个什么东西

一块 240×240 的小屏幕桌面时钟固件，目标硬件是 ESP32-S3（8MB flash + 8MB OPI PSRAM）+ ST7789 240×240，音频是 ES8311 + NS4150B。它是在 SmallDesktopDisplay（SDD V1.4）的基础上增量开发的，界面风格叫 MONO，就是灰阶、比较克制的那种。当前版本 0.2.2。

要强调一下：这不是通用的 ESP32-S3 固件，换了板卡、接线不一样就不要直接刷。

屏幕上显示：

  • 七段数字时钟，加完整年月日和星期
  • 三行已用额度：OpenAI（Codex）5 小时窗口、Codex 每周窗口、Cursor 月度 Auto 池（autoPercentUsed）
  • 底部状态：LIVE 是真实数据，SIM 是服务端测试数据，DEMO 是设备本地演示

原来 V1.4 的天气时钟界面也保留了，可以切换过去用。

固件五个画面设计：主画面、启动、连接网络、热点配网、整点提醒
图 2：固件的 5 个画面：主画面、启动、连接、配网、整点提醒（设计示意）

二，数据怎么到屏幕上

思路很简单：Token 只留在电脑上，屏幕只拿百分比。

  • 电脑上跑一个本地服务 progress_service，纯 Python 标准库实现，默认监听 8766 端口
  • 服务启动就在后台取数，成功后每 5 分钟刷新一次（失败每 1 分钟重试），结果缓存起来
  • 设备通过局域网请求 /api/progress，默认也是 5 分钟一次，直接读缓存，不等外部接口
  • /health 只表示进程活着，不代表上游认证成功
  • 没准备好、刷新失败或缓存超过 10 分钟就返回 503，设备保留上次的值，不会把异常显示成 0%
OpenAI / Codex (5小时 · 每周) ─┐
                               ├─> 本地 Python 服务 (取数 · 缓存) ──局域网 HTTP·三个百分比──> ESP32-S3
Cursor (月度 Auto)  ──────────┘
浏览器管理页 ──显示与提醒设置──> ESP32-S3

三，网页管理

小屏幕上不加按键，设置都放在设备自带的网页管理页里：亮度、方向、进度源、天气参数，还有整点提醒。管理页的 CSS/JS 都是内嵌的，不加载外部框架和字体。

整点提醒默认关闭，打开后到点切到提醒页、嘟三声，再回到原来的页面。音量默认 30%，设成 0% 就只显示提醒画面。未校时、启动或配网期间不提醒，也不补报过去的整点。

MONO 网页管理界面设计：三行额度、显示设置、整点开关与音量试听
图 3：网页管理页：额度、显示设置、整点提醒（设计示意，示例数据）

四，怎么用

Windows 上装好 Python 3.9+，双击 progress_service/start.cmd。第一次会创建 .venv 并生成一个空的 config.private.json，填好凭据后再双击一次就在后台跑起来了。关闭用 stop.cmd。

{
  "openai": {
    "access_token": "<你的 Codex 登录访问令牌>",
    "account_id": "<对应的账号 ID>"
  },
  "cursor": {
    "session_token": "<WorkosCursorSessionToken 的值>"
  }
}

注意 access_token 是 Codex 登录用的访问令牌，不是 sk- 开头的 API Key。这个文件已经在 .gitignore 里，不要提交也不要截图。

然后连上设备的 Wi-Fi，在管理页里填电脑的局域网地址（不是 localhost）：

http://电脑局域网IP:8766/api/progress

要刷固件的话，仓库里有成品镜像 rom/sdd_mono_0.2.2.clean.bin（8MB 完整镜像，NVS 区已检查为全 FF，不含任何 Wi-Fi 或 Token），附带 SHA256SUMS。刷之前一定先核对芯片、容量、PSRAM 和接线，完整备份自己的 flash 并校验，整片写入会清掉原来的配置。有成品 BIN 不等于可以盲刷。

五，限制和注意

  • 额度用的是非公开的仪表盘接口，上游一改可能就失效；Token 过期需要手动换
  • 只用于可信局域网：管理页没有登录，服务也没有认证，不要做端口转发
  • 0.2.2 已在我自己的设备上写入并校验过，但整点音效、完整天气功能和其他板卡还需要分别验证
  • 出了红灯先查：服务是否在跑、/api/progress 是否 200、电脑和设备是否互通、IP 是否变了、Token 是否过期

六，致谢

感谢 SmallDesktopDisplay / SDD V1.4 的原作者 Misaka、微车游，余刻是在它的天气时钟和配网功能上增量开发的，保留了原作者署名。也感谢 Espressif、TFT_eSPI、WiFiManager、ArduinoJson 等配套库的开发者。

东西不大，就是个桌面小玩意儿，有同款硬件又刚好在用 Codex / Cursor 的可以试试。

最后修改日期: 2026年10月15日

作者