Codex 最近会话切换器

通过 CDP 向 Codex 桌面端注入最近会话弹窗：

• macOS：Cmd+E 打开或关闭弹窗
• Windows：Ctrl+E 打开或关闭弹窗
• ↑ / ↓ 选择
• Enter 打开选中会话
• 鼠标悬停选择、点击打开
• Esc 关闭
• 当前正在查看的会话不会出现在候选列表中
• 会话状态与 Codex 侧边栏保持一致：处理中、待确认、待输入、错误、未读蓝点/计数
• 会话名下显示 Codex 项目名，不显示完整工作目录

蓝点的准确语义是“有尚未查看的结果”，不是所有空闲任务都会显示蓝点。任务完成后通常会产生未读结果，所以视觉上常表现为完成时出现蓝点。待确认可以和处理中动画同时出现；待输入会替代普通处理中图标，与 Codex 原界面一致。

“最近”的判断方式

列表优先展示你最近实际查看过的会话，并按最后查看时间倒序排列。切换侧边栏任务、通过弹窗打开任务，以及重新聚焦一个包含任务的 Codex 窗口时，都会更新查看时间。第一次使用、或数量不足时，再用 Codex 的 recency_at（最近有任务活动的时间）补齐。

查看记录保存在 ~/.codex-recent-switcher/recent.json，最多保留 100 条。它不会读取 Cookie 或账号凭据。检测依据是 Codex 页面为当前侧边栏任务设置的 data-app-action-sidebar-thread-active="true" 状态；若未来 Codex 改掉这个内部属性，需要同步更新兼容逻辑。

使用

最简单：npx

发布到 npm 后，用户只需要先完全退出正在运行的 ChatGPT/Codex，然后执行：

npx -y @kepoai/codex-recent-switcher

如果使用当前尚未发布的本地 tarball：

npx -y --package=file:./kepoai-codex-recent-switcher-0.3.5.tgz codex-recent-switcher

npx 会临时下载依赖并启动切换器，不需要全局安装。关闭运行该命令的终端后，注入器会退出，但 Codex 会继续运行。

双击启动

第一次使用前，请完全退出 ChatGPT/Codex：

• macOS 双击 start.command
• Windows 双击 start.cmd

也可以执行：

cd codex-recent-switcher
npm install --omit=dev
npm start

启动器会使用以下参数打开官方客户端：

--remote-debugging-address=127.0.0.1
--remote-debugging-port=9222

如果 Codex 已经运行但没有开放 CDP，启动器会停止并提示退出，不会结束现有进程。

Windows

Windows 需要 Node.js 20+ 和新版 ChatGPT 桌面客户端。官方 Microsoft Store 安装命令：

winget install --id 9PLM9XGG6VKS -s msstore

完全退出 ChatGPT 后，在 PowerShell 中执行：

npx -y @kepoai/codex-recent-switcher

启动器会依次尝试：

1. CODEX_DESKTOP_APP 或 --app 指定的路径。
2. Windows App Execution Alias 中的 ChatGPT.exe / Codex.exe。
3. %LOCALAPPDATA%、%ProgramFiles% 下的常见安装路径。
4. where.exe。
5. PowerShell Get-AppxPackage 和 Appx manifest 中的真实 executable。

随后优先寻找客户端迁移到 %LOCALAPPDATA%\OpenAI\Codex\bin 的 codex.exe，再从客户端的 resources 目录和 PATH 查找。这样可以避开部分 Windows Store 安装对 WindowsApps 目录的直接执行限制。自动发现失败时可以显式指定：

$env:CODEX_DESKTOP_APP = "C:\path\to\ChatGPT.exe"
$env:CODEX_BINARY = "C:\path\to\codex.exe"
npx -y @kepoai/codex-recent-switcher

切换会话时，Windows 会优先直接执行 ChatGPT.exe / Codex.exe 并传入 codex://threads/<id>，以兼容没有正确注册 codex:// URL scheme 的客户端版本。

配置

# 使用其他本地端口
node ./src/cli.mjs --port 19322

# 连接已经启动的 CDP 实例，不负责启动 Codex
node ./src/cli.mjs --no-launch --port 9222

# 指定桌面客户端位置
node ./src/cli.mjs --app "/Applications/ChatGPT.app"

# Windows PowerShell
node .\src\cli.mjs --app "C:\path\to\ChatGPT.exe"

# 输出注入和 app-server 调试信息
node ./src/cli.mjs --debug

# 自定义快捷键；macOS 解析为 Cmd+K，Windows 解析为 Ctrl+K
node ./src/cli.mjs --shortcut "CmdOrCtrl+K"

# 验证交互但不真正跳转会话
node ./src/cli.mjs --dry-run

也可以使用环境变量：

• CODEX_CDP_PORT
• CODEX_DESKTOP_APP
• CODEX_BINARY
• CODEX_RECENT_SWITCHER_SHORTCUT（例如 CmdOrCtrl+K）
• CODEX_RECENT_STORE_PATH（自定义最近查看记录文件，主要用于测试或多配置隔离）

命令行参数优先于环境变量；修改快捷键后需要重启注入器。支持单字母、数字和 F1–F12，并且至少需要 Cmd、Ctrl 或 Alt 修饰键。

为什么没有出现在 Codex 的“快捷键”设置里

当前 Codex 桌面版的“设置 → 快捷键”只显示客户端内置的静态命令，主进程也会拒绝未知 command ID；CDP 页面注入没有动态注册命令的接口。强行修改 app.asar 或占用一个内置命令槽会破坏签名、容易被升级覆盖，也可能与未来官方命令冲突，因此本工具不伪造原生设置项。

用户仍可通过一条命令自行修改，例如：

npx -y @kepoai/codex-recent-switcher --shortcut "CmdOrCtrl+K"

Windows PowerShell 也使用相同写法，CmdOrCtrl会自动映射为 Ctrl。

安全说明

CDP 可以控制客户端渲染页面。工具只监听 127.0.0.1，但同一台机器上的其他进程仍可能连接该端口。不要把调试端口绑定到 0.0.0.0，也不要转发到局域网或公网。

分发建议

当前目录适合内部测试和小范围分发。正式公开分发建议封装成签名的 macOS 菜单栏 App和 Windows 托盘 App：

1. 菜单栏 App 负责启动 Codex、选择随机 CDP 端口并保持 injector 生命周期。
2. injector 和 Node runtime 一起打包，用户不需要安装 npm。
3. macOS 使用 Developer ID Application 签名并公证；Windows 使用代码签名证书签名。
4. 首次运行清楚说明 CDP 权限与本机数据访问范围。
5. 每个 Codex 新版本执行兼容性测试；状态和项目标签使用的是客户端内部 DOM 属性，若官方调整结构需要同步适配。

不要通过修改或重签名 OpenAI 的客户端来分发。