Touch Bar 被很多人判定为失败:手感差、容易误触、苹果自己也不再更新。这些我都同意。但在我的 MacBook Pro 上,它是离键盘最近的一块屏------手不用离开主键区,视线只需要上移两厘米。
对一天里大半时间都在跟 Codex 打交道的人来说,这两厘米比想象中重要。
打断心流的往往不是什么大问题
写代码时最烦的常常不是难题,而是那种"顺手查一下"的小事:
- 额度还剩多少?按现在的速度,下午够不够用?切到 Codex 窗口,翻到用量。
- 什么时候重置?还有几个小时?再翻一次。
- 刚才那几个对话分别是什么标题、哪一个已经归档了?打开侧栏,在一堆标题里找。
单独看,这些都不值得为它做个工具。但它们有个共同点:答案很短,找答案的路径却很长。而路径越长,越容易在途中被别的东西带走。
单次三五秒,一天几十次。真正消耗人的不是切窗口的时间,而是每次切回来都要重新把上下文捡起来------刚才那个函数写到哪了,我为什么打开这个文件。
我缺的不是一个更漂亮的用量面板,而是一个不用主动去查、抬头就能看见的东西。
一块 30pt 高的迷你工作台
Codex Touch Bar 是我写的小工具,Swift 编写,MIT 协议,从 Daytimeflow/codex-touchbar-usage 二次开发而来,属于非官方社区作品,和 OpenAI 没有隶属关系。
它只做一件事:Codex 位于前台时,把 Touch Bar 变成一块迷你工作台。

使用示例数据生成的原生界面预览。实际显示宽度取决于设备及系统控制条。
从左到右四块内容:
- 重置卡:可用数量,票券图标里就是数字。
- 额度:环形进度条 + 百分比,低额度时变色。
- 重置倒计时:放大的时钟图标 + 数字,每秒走一格。
- 对话列表 :最近 50 条未归档的本机对话横向排列,滑动查看更多,点标题用
codex://threads/<id>直接打开。
每条对话前面有一个状态点:蓝点表示根据近期事件推测还在进行中,绿点表示最近一次任务完成,灰点表示状态未知。最近一次从 Touch Bar 上点开的对话,会多一圈银灰猫耳描边和一只青色猫爪------这个纯属个人审美。
切到别的应用,面板消失,恢复系统控制条。这既是"不打扰",也是私有 API 下最稳妥的存活方式。
整体架构

三条数据流,各自独立:
- 额度 :起一个
codex app-server子进程,用 JSON-RPC 问它要account/rateLimits/read。 - 对话 :只读打开
~/.codex/state_5.sqlite取标题,再 tail 每个会话的 rollout 文件推断状态。 - 前台与渲染 :监听应用切换决定显隐,把前两条产出的快照画进 30pt 高的
NSView。
我没有做统一的数据源抽象。三条链路刷新频率不同、失败方式也不同,强行抽象只会让降级逻辑更难写。现在的做法是各自降级、在渲染层合并:额度挂了,列表照常;数据库读不到,环形进度还在转。渲染层只认快照,不关心快照从哪来,甚至不知道网络的存在。
额度:和 Codex app-server 说话
额度不解析界面,而是走官方 app-server。起一个子进程,往 stdin 写 JSON-RPC,一行一个对象,从 stdout 按行读回来,请求带自增 id,响应按 id 归位。
这样做的好处是边界清晰:抓 UI 反而更容易被版本更新打断。
实际发出去的就是四条消息:
swift
static func requestMessages() -> [JSONObject] {
[
["method": "initialize", "id": 0,
"params": ["clientInfo": ["name": "codex_touchbar_usage",
"title": "Codex Touch Bar Usage",
"version": "0.3.6"]]],
["method": "initialized", "params": JSONObject()],
["method": "account/rateLimits/read", "id": 2, "params": JSONObject()],
["method": "account/usage/read", "id": 3, "params": JSONObject()],
]
}
读回来的时候按行切 JSON,按 id 分发;id == 2 是额度,id == 3 是 token 用量。两条响应都到齐就 signal 信号量,等不到就按超时收工------客户端把超时下限卡在 10 秒,因为再等也没有收益:这一轮拿不到,30 秒后还会再来,卡住读线程反而会拖累其他数据。
拿到 rateLimits 之后还要做一层兼容解析。Codex 的响应结构改过几版,rateLimitsByLimitId、additional_rate_limits、主窗口与模型专属窗口的命名都出现过,所以解析器既认 5小时 / 1周 这种旧标签,也认 1周 / Spark 这种新标签。
降级是三级链:
| 顺序 | 数据来源 | 特点 |
|---|---|---|
| 1 | app-server 的 account/rateLimits/read |
最准,需要 ~/.codex/auth.json 登录态 |
| 2 | ~/.codex/touchbar-usage/ 下的本地缓存 |
过时但结构完整,重启后先显示它 |
| 3 | 本地会话的 token 统计 | 只能估算,没有重置卡信息 |
缓存这条路是必要的:codex app-server 起不来、超时、返回错误,任何一件发生,界面都不该变空白。启动时先读一次缓存再发起远程请求,用户看到的是"旧数字",而不是"加载中"。
对话列表:只读 SQLite,tail 会话事件
列表来自 ~/.codex/state_5.sqlite。注意是只读打开:
swift
sqlite3_open_v2(path, &db, SQLITE_OPEN_READONLY | SQLITE_OPEN_FULLMUTEX, nil)
sqlite3_busy_timeout(db, 100) // 100ms 拿不到锁就放弃这一轮
Codex 自己在写这个库,读方不能跟它抢锁。100ms 拿不到就放弃、等下一次 tick,而不是重试到把界面拖住。
查询条件也不复杂,但每一条都有原因:
sql
SELECT id, COALESCE(NULLIF(name, ''), title), rollout_path
FROM threads
WHERE archived = 0
AND source = 'vscode'
AND (thread_source = 'user' OR thread_source IS NULL)
AND attached_thread_parent_id IS NULL
AND preview <> ''
ORDER BY recency_at_ms DESC
LIMIT 50
过滤归档、过滤空标题、过滤子线程,按最近活跃排序取 50 条。标题通过 codex://threads/<id> 交给系统打开,helper 自己不做任何跳转逻辑。
状态点不是查出来的,是读出来的 。每条对话对应一个 rollout 文件,只 tail 最后 256KB------够覆盖最近若干轮事件,又不会把整个文件读进内存------从末尾往前找 event_msg:
swift
for line in text.split(separator: "\n").reversed() {
guard /* 解析成 event_msg */ else { continue }
if type == "task_complete" { return .completed }
if type == "turn_aborted" || type == "task_failed" { return .unknown }
if type == "task_started" {
// 旧的 started 可能来自已经崩溃的进程
guard Date().timeIntervalSince(startedAt) < 120 else { return .unknown }
return .active
}
}
这里有个不得不做的妥协:task_started 之后超过 120 秒没有收尾事件,就当成 unknown。因为进程被杀、长任务还没结束、事件还没落盘,呈现出来的样子是一样的。
必须说清楚:这是推断,不是 Codex 提供的实时状态接口。 拿它扫一眼可以,当任务监控不行。
Touch Bar:私有 API 与 30pt 画布
界面是 NSTouchBar + NSCustomTouchBarItem + 自绘 NSView,画布 720×30pt,靠 intrinsicContentSize 撑开。
额度环、票券、时钟、倒计时数字、对话标题,全部是 Core Graphics 画出来的,没有用系统控件。原因很实际:30pt 的高度里,系统控件的边距和内建样式会吃掉太多空间,而这里的每一像素都要用来放信息。
真正的麻烦在"常驻显示"。公开的 NSTouchBar 只能挂在自己的响应链上,没有提供"别的应用在前台时,把我的 bar 顶到系统控制条位置"的入口。于是只能走私有方法:
swift
func presentSystemModalTouchBar() {
performClassSelector("presentSystemModalTouchBar:systemTrayItemIdentifier:",
first: touchBar, second: trayIdentifier)
}
private func performClassSelector(_ name: String, first: AnyObject, second: AnyObject?) {
let host = NSTouchBar.self as AnyObject
let selector = NSSelectorFromString(name)
guard host.responds(to: selector) else { // 系统不认就安静退出
NSLog("CodexTouchBarHelper: selector unavailable: \(name)")
return
}
_ = host.perform(selector, with: first, with: second)
}
用 NSSelectorFromString + responds(to:) + perform,而不是直接调私有符号,是为了让它在系统改接口时"静默失效"而不是启动即崩。这是一个有意的选择:宁可面板不出现,也不要让用户看到崩溃报告。
显隐做了淡入淡出:NSAnimationContext 配 CAMediaTimingFunction,进场 0.28s,退场 0.22s。有个坑是后台状态下 Touch Bar 的动画 completion 不一定会回调,所以除了 completion 还用 asyncAfter 兜底提交最终状态,否则面板会卡在半透明或者没收起来的中间态。
前台监听用 NSWorkspace.didActivateApplicationNotification,封装成 FrontmostAppMonitor。应用切换时通知会连着来,所以加了一层 0.15s 的防抖再决定 show / hide。
刷新与并发:三个节奏,一个计数器
刷新节奏分三档:
- 本地数据(SQLite + 会话事件):Codex 前台 3s 一次,其他时候 15s;
- 远程额度:30s 一次;
- 倒计时:1s tick,只改数字,不触发整表重绘。
这三档不是拍脑袋定的。本地读便宜,可以勤一点;远程额度要走一次子进程往返,勤了只是浪费;倒计时必须每秒动,但改一个字符串的代价接近于零。
另一个必须处理的问题是旧结果覆盖新状态。切换前台应用、切回 Codex、额度重置后的补刷,都可能让两个刷新任务同时在飞。解法是一个自增的 generation:发起时记下,结果回来先比对,不是最新一代就丢掉。
swift
private func handleTargetChange(_ next: ForegroundTarget) {
guard target != next else { return }
stopRefresh()
generation += 1 // 旧任务的结果到此作废
target = next
...
scheduleStartup() // 0.15s 后再启动新一轮
}
所有同步 I/O 都挪出了主线程:CodexUsageLoader 用 actor 包住 UsageStore,SQLite 扫描和会话文件读取放在后台队列,主线程只负责 needsDisplay = true。倒计时 tick 也在主线程,但只更新一个 label 的字符串。
效果是 3 秒一轮的轮询没有可感知的掉帧------这是我这台机器上的主观感受,没有做帧率测量。
装之前先确认三件事
- 机型:带 Touch Bar 的 MacBook Pro。没有 Touch Bar 就没有显示目标。
- 系统:macOS 12 或更高。
- Codex 已登录 :额度那一路要读
~/.codex/auth.json,没登录就只能看降级数据。
路径一:Release 包
从 Releases 下载 CodexTouchBarUsage-v0.2.1-universal.zip 和对应的 .sha256。universal 表示 Apple Silicon 和 Intel 通用,装的时候不用编译。
bash
# 先校验完整性,再解压
shasum -a 256 -c CodexTouchBarUsage-v0.2.1-universal.zip.sha256
unzip CodexTouchBarUsage-v0.2.1-universal.zip
cd CodexTouchBarUsage-v0.2.1-universal
# 双击 Install.command,或者直接跑
./install.sh
脚本会装到 ~/Applications/CodexTouchBarHelper.app,注册 LaunchAgent com.local.codex-touchbar-helper,登录后自启。
需要提前知道:这个包没有经过 Apple 公证,用的是临时签名。macOS 可能阻止运行,处理顺序是先到「系统设置 → 隐私与安全性」看看有没有可点的"仍要打开"。校验和只能证明文件没坏,证明不了发布者是谁------这一点得自己判断。
路径二:源码编译
bash
git clone https://github.com/github-bian/codex-touchbar-usage.git
cd codex-touchbar-usage
./scripts/install_touchbar_helper.sh
要求本机有 Xcode Command Line Tools 或完整 Xcode。更新就是 git pull 之后重跑一次安装脚本。
自测和检查界面:
bash
cd helper/CodexTouchBarHelper && swift test # 单元测试
./scripts/test_touchbar_ui.sh # 原生界面渲染检查(回仓库根目录跑)
出问题了看哪里
bash
# 确认 agent 在不在跑
launchctl print gui/$(id -u)/com.local.codex-touchbar-helper
# 日志
tail -f ~/.codex/touchbar-usage/helper.err.log
# 卸载(在解压目录里)
./scripts/uninstall_touchbar_helper.sh
常见的三个现象:
| 现象 | 先查什么 |
|---|---|
| Touch Bar 上没有面板 | Codex 是否在前台。切走后恢复系统控制条是设计行为,不是崩溃 |
| 面板在,额度空着或不动 | ~/.codex/auth.json 在不在;日志里 app-server 有没有报错;远程额度是 30s 一刷 |
| 列表里找不到某条对话 | 是否已归档、是否在云端、source 是否为 vscode |
几个必须说清楚的局限
私有 API,随时可能失灵。 NSTouchBar、NSCustomTouchBarItem、自绘视图都是公开的,问题只在"常驻显示"这一步。苹果改掉那两个私有方法,它就废了,而且失效方式通常不是崩溃,是面板不出现。
状态是推测的。 蓝点绿点灰点来自文件尾部的事件,不是实时接口。长任务、异常退出、Codex 更新导致事件格式变化,都会让它不准。
只覆盖本机、未归档、来源为 vscode 的对话。 云端会话和已归档会话不在列表里,50 条是写死的上限。数据库 schema、rollout 格式、app-server 的方法名,都是内部实现而非公开约定,Codex 一改,这边就得跟着改。
隐私上它是干净的,但你要小心自己。 它只读本机数据,对话内容不上传,缓存和日志都在 ~/.codex/touchbar-usage/。但 auth.json 是凭证:别把它、别把整个 ~/.codex 目录、也别把带对话标题和额度数字的截图贴到公开仓库或 issue 里。
写在最后
这个工具解决的问题很小:少切几次窗口,少丢几次上下文。但这类小问题会按天累积。
我也不认为它适合所有人。如果你不用 Codex,或者你的 Mac 没有 Touch Bar,它对你没有任何意义;如果你把 Touch Bar 当成"苹果失败的实验",那也完全合理。
但如果你恰好是"旧款 MacBook Pro + Codex 重度使用"这个交集里的人,它可能是这块屏幕最实用的一种用法:不打扰,但一直在。
仓库地址:github.com/github-bian...。感谢上游 Daytimeflow/codex-touchbar-usage 打下的基础。