把 Codex 装进 Mac 刘海:Codex Notch 安装与使用指南

使用 Codex 编程时,经常需要在编辑器、终端和 Codex 窗口之间来回切换:任务还在运行吗?是不是在等我确认?额度和上下文还剩多少?

Codex Notch 是一个原生 macOS 小工具,把这些信息放到屏幕顶边的"灵动岛"里。本文结合项目文档介绍它的安装方法、界面效果和数据口径。

项目地址:github.com/github-bian...

这是非官方社区项目,与 OpenAI 没有隶属或背书关系,采用 MIT 许可证。

先看实际效果

下面的截图来自项目仓库:由应用真实界面渲染,使用演示数据,展示的是无物理刘海显示器上的模拟岛面,不是 MacBook 实机照片,也不是账号的实时用量。

运行中:随时查看进度

展开面板后,可以查看项目、额度窗口剩余百分比、重置时间和上下文等信息。鼠标移到岛面可展开,点击收起态可以钉住面板,再点击面板上的 × 收起。

等待审批:及时发现需要处理的任务

青色状态点表示需要处理。注意,等待审批需要实际收到受支持的审批事件;Codex Notch 只负责提示,不会替用户批准命令。

完成、失败与额度预警

绿色状态点表示回合完成,红色状态点提示失败。面板未展开或钉住时,这两种状态会短暂显示后消失。

当窗口额度已使用 90% 时,剩余百分比会变红,方便你提前留意使用情况。

它能显示哪些信息?

  • 状态:运行中、等待审批、已完成或已失败。
  • 额度:可用窗口的剩余百分比和重置倒计时。
  • 上下文:已用 Token 和估算剩余空间。
  • 会话累计:整个会话的累计 Token,不是当前回合单独消耗的数量。
  • 运行时长:在能取得开始时间的情况下显示。

如果额度或上下文数据缺失,对应区域会隐藏。项目展示的是 Codex 返回的一个额度窗口,窗口长度由数据决定,可能是 5 小时、7 天或其他时长,不应简单理解为固定周期。

安装:从源码构建

1. 准备环境

需要 macOS 14 或更新版本,安装并至少使用过一次 Codex。从源码构建还需要 Xcode Command Line Tools 和 Swift。

2. 克隆并安装

打开终端,依次执行:

bash 复制代码
git clone https://github.com/github-bian/codex-notch.git
cd codex-notch
./scripts/install.sh
open "$HOME/Applications/CodexNotch.app"

安装脚本会替换已有的 ~/Applications/CodexNotch.app。本地构建使用临时签名且尚未公证,macOS 可能显示安全提示;请先确认来源并按照系统提示处理。

3. 启动 Codex 并观察状态

正常使用 Codex 后,把鼠标移到屏幕顶边的岛面查看详情;点击收起态可将面板钉住。没有物理刘海的显示器也会显示模拟岛面。

菜单栏图标提供打开 Codex、复制 hook 配置、显示数据文件夹和退出等操作。当前版本可以打开 Codex,但不保证跳转到特定会话。

可选:接收事件通知

不配置 hook 也能通过轮询使用。如果需要转发 Codex 支持的通知,可以从菜单栏复制 hook 配置,加入 ~/.codex/config.toml。路径请以自己的实际安装位置和菜单栏复制出的配置为准,例如:

toml 复制代码
notify = ["/Users/<you>/Applications/CodexNotch.app/Contents/MacOS/codexnotch-hook"]

把 <you> 换成实际用户名,保存后重启 Codex。不同 Codex 版本支持的 notify 事件可能不同,尤其是等待审批状态,需要对应审批事件实际到达 hook。修改配置前建议先检查现有配置,避免覆盖已有的通知设置。

它是怎么工作的?

正常模式下,Codex Notch 从本机 ~/.codex/sessions 读取会话文件:每秒检查增量,约每 5 秒查找最近写入的会话。可选的 hook 则用于接收 Codex 支持的事件通知。

这也意味着,多会话并行时,最近写入的会话不一定是当前前台会话;长期未更新的会话不会一直显示运行中。启动时只扫描最新会话末尾的有限数据,特别长的回合可能无法恢复原始开始时间,因此运行时长不一定可用。

隐私与使用边界

项目文档说明,会话文件只在本机读取,不读取 ~/.codex/auth.json,不上传数据,也不主动联网。新写入的 hook 事件记录事件类型、会话与回合 ID、工作目录,不保存提示词和回答正文。旧版本可能留下原始通知文件,升级不会自动删除。

物理刘海、多显示器、键盘焦点和 VoiceOver 仍需在对应设备上验证。如果你需要自行排查屏幕几何或数据位置,可以参考仓库中的 --probe 说明;诊断输出可能包含本地路径,分享前记得检查。

值得试试吗?

如果你经常让 Codex 在后台运行,又希望随时掌握状态和额度,Codex Notch 提供了一种轻量的查看方式。它适合辅助观察,涉及审批的操作仍需回到 Codex 自己处理。

项目开源地址:github.com/github-bian...。安装细节、兼容性与后续变化,请以仓库最新文档为准。

相关推荐
吕炘嵘18 分钟前
DPO loss 降了 75%,模型却没变好:我给手搓 LLM 补了一套评估系统
人工智能
程序员cxuan21 分钟前
推荐 10 个 WorkBuddy 中的邪修用法
人工智能·后端·程序员
花椒技术23 分钟前
数字人为什么突然爆发?从 H3 Max Lip Sync 看生成式数字人的临界点
人工智能·aigc
初学AI的小高25 分钟前
VFM:让 Agent 同时接受上千条自然语言规则的运行时检查
人工智能
我si绝版33 分钟前
OpenClaw 安装步骤
人工智能
Seiran36 分钟前
用Grok 4.7在ZEEKEAI啃长文档的提效实战
人工智能
Bacon39 分钟前
给项目做一次"全身 CT":Agent Skills 生态里的代码体检全链路
前端·人工智能·后端
培培说证41 分钟前
大专商务数据分析与应用可以报考哪些职业证书?
人工智能·数据挖掘·数据分析
pursuit_c44 分钟前
关于 Personal Agent 的思考碎片
人工智能