Codex++ 图标

中文 | [English](README_EN.md)

Release Stars License Python

Codex++ 是面向 Codex App 的外部增强启动器。它不修改 Codex App 原始安装文件,而是通过外部 launcher 启动 Codex,并使用 Chromium DevTools Protocol 注入增强脚本。

• 讨论交流
• 赞赏支持
• 快速使用
• 功能亮点
• 界面预览
• Provider 同步
• 友情链接
• 工作方式
• 环境要求
• Windows 使用
  • 图形菜单安装/卸载
  • 命令行安装
  • 命令行卸载
  • Windows 自动接管(可选)
• 自动更新
• macOS 使用
• 直接启动
• 数据与备份
• 常见问题
• 贡献者与 Star
• 开发

欢迎扫码加入 Codex++ 交流群,反馈问题、交流使用体验或提出新功能建议:

Codex++ 交流群二维码

如果 Codex++ 帮到了你,可以请我喝杯咖啡,或者随手赞赏支持一下继续维护。

支付宝赞赏码 微信赞赏码

Windows 用户可以直接双击项目根目录的:

setup.bat

然后选择:

[1] Install Codex++

安装后桌面会生成 Codex++.lnk,双击即可启动带增强功能的 Codex。

也可以在项目目录通过命令行安装和启动:

python -m pip install -e .
python -m codex_session_delete setup
python -m codex_session_delete launch

macOS 用户可以执行:

python -m codex_session_delete setup

安装后会生成 /Applications/Codex++.app。

• 顶部菜单栏加入 Codex++ 菜单,可集中管理增强功能。
• 插件选项解锁:让 API Key 模式显示并启用插件入口。
• 特殊插件强制安装:解除 App unavailable / 应用不可用导致的前端安装禁用。
• 会话删除:在会话列表悬停显示删除按钮,删除前确认并支持撤销。
• Markdown 导出:按本地 rollout 导出带时间戳的会话 Markdown。
• 会话项目移动:把会话移动到普通对话或其他本地项目。
• 对话 Timeline:在对话右侧显示用户提问时间线,悬停查看摘要并快速跳转。
• Provider 同步:切换 model_provider 或供应商时不丢历史会话。
• Windows 快捷方式安装/卸载、常驻 watcher 自动接管、GitHub Release 自动更新。
• macOS 生成 /Applications/Codex++.app。

API Key 登录模式下,Codex 原生插件入口会提示需要登录 ChatGPT,导致插件功能无法正常使用:

API Key 模式下插件入口不可用

Codex 原生会话列表只有归档入口,没有真正的删除按钮:

原生会话列表缺少删除能力

Codex++ 启动后会解锁插件入口,并在会话列表悬停时显示删除按钮:

Codex++ 解锁插件入口并添加删除按钮

顶部菜单栏会出现 Codex++,可以查看后端状态并打开设置面板:

Codex++ 后端状态指示灯

Codex++ 设置面板

启用 Provider 同步 后,Codex++ 会在启动 Codex 前同步本地会话 metadata。它会把 rollout 文件、SQLite 线程记录和项目路径缓存同步到当前 model_provider,让你切换供应商时不丢历史会话。

适合这些场景:

• 从 OpenAI 切换到第三方 provider 后,旧会话在 Desktop 或 /resume 中不可见。
• 切回其他 provider 后,希望历史对话继续出现在原项目下。
• Windows 路径带有 \\?\ 前缀导致 Desktop 项目列表匹配不到旧会话。

同步只修复会话可见性相关 metadata,不改写对话内容;如果 Codex 正在占用某个会话文件或 SQLite 忙碌,Codex++ 会跳过并继续启动,避免阻塞 Codex。

• LINUX DO

Codex++ 使用外部启动方式运行 Codex:

1. 启动 Codex App,并附加:
   • --remote-debugging-port=9229
   • --remote-allow-origins=http://127.0.0.1:9229
2. 如果启用了 Provider 同步,启动 Codex 前先同步历史会话 metadata。
3. 启动本地 helper 服务,保留健康检查和运行生命周期。
4. 通过 CDP 注入 renderer-inject.js。
5. 渲染端通过 CDP bridge 调用本地服务;默认不开放 HTTP 删除/撤销入口,避免本机其他页面误触发删除类操作。
6. 启动 Codex 时继承现有 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY;如果这些环境变量未设置,会自动探测常见本地代理端口(如 127.0.0.1:7897),帮助 Codex 加载需要访问 GitHub 的技能资源。

这种方式不会修改 Codex 的 app.asar,也不需要往 Codex 安装目录写 DLL。

• Python 3.11+
• Windows 或 macOS
• 已安装 Codex App

安装依赖:

python -m pip install -e .

如需运行测试:

python -m pip install -e .[test]
python -m pytest -q

双击项目根目录的:

setup.bat

然后按菜单选择:

[1] Install Codex++
[2] Uninstall Codex++
[3] Update Codex++
[4] Exit

在项目目录执行:

python -m codex_session_delete setup

安装后会在桌面生成:

Codex++.lnk

双击该快捷方式启动 Codex++。

可以在系统"设置 → 应用 → 已安装的应用"里卸载 Codex++。

也可以在项目目录执行:

python -m codex_session_delete remove

如需同时删除 Codex++ 自己的日志和备份数据:

python -m codex_session_delete remove --remove-data

默认情况下 Codex++ 只在你从 Codex++ 快捷方式启动时生效。如果你从开始菜单、任务栏或系统原生入口直接启动 Codex,那一次不会有注入,Codex++ 菜单和插件解锁都不会出现。

Windows 可以注册一个常驻 watcher 解决这个问题。它会每 3 秒探测一次本机 CDP 端口,发现 Codex 在跑但 CDP 没起来,会先短暂等待并二次确认,确认仍没有 CDP 后再把 Codex Desktop App 进程重拉为带注入的版本。

安装:

python -m codex_session_delete watch-install

卸载:

python -m codex_session_delete watch-remove

临时开关:

python -m codex_session_delete watch-disable
python -m codex_session_delete watch-enable

日志:

%USERPROFILE%\.codex-session-delete\watcher.log

Codex++ 会在启动时检查 GitHub Release。如果发现比本地版本更新的 Release,会在控制台提示版本号、Release 地址和更新命令;检查失败不会影响 Codex++ 启动。

手动检查更新:

python -m codex_session_delete check-update

从最新 GitHub Release 更新:

python -m codex_session_delete update

更新流程:

1. 请求 https://api.github.com/repos/BigPizzaV3/CodexPlusPlus/releases/latest。
2. 比较最新 Release tag 与本地版本。
3. 优先下载 Release 中的 .whl asset。
4. 执行 python -m pip install --upgrade <wheel>。
5. 自动重新执行 python -m codex_session_delete setup,刷新快捷方式、Windows 卸载项或 macOS app bundle。

发布新版本时,请在 GitHub Release 里附加 wheel 文件,例如:

python -m build

然后把 dist/codex_session_delete-<version>-py3-none-any.whl 上传到对应 Release。

python -m codex_session_delete setup

默认会自动查找 /Applications/Codex.app、/Applications/OpenAI Codex.app 或用户 Applications 目录下的 Codex 应用,并生成:

/Applications/Codex++.app

python -m codex_session_delete remove

不安装快捷方式时,也可以直接运行:

python -m codex_session_delete launch

常用参数:

python -m codex_session_delete launch \
 --app-dir "/Applications/OpenAI Codex.app" \
 --debug-port 9229 \
 --helper-port 57321

Windows 也可以手动指定 Codex 安装目录:

python -m codex_session_delete launch \
 --app-dir "C:/Program Files/WindowsApps/OpenAI.Codex_xxx/app" \
 --debug-port 9229 \
 --helper-port 57321

Codex++ 默认读取 Codex 本地数据库:

~/.codex/state_5.sqlite

删除前会把相关记录备份到:

~/.codex-session-delete/backups

Provider 同步会把同步前状态备份到:

~/.codex/backups_state/provider-sync

隐藏启动失败日志位于:

~/.codex-session-delete/launcher.log

先查看日志:

%USERPROFILE%\.codex-session-delete\launcher.log

常见原因:

• Codex App 没有安装或路径变化
• 9229 端口被占用
• Python 环境不可用

如果技能页提示 git fetch failed、unable to access 'https://github.com/openai/skills.git/' 或无法连接 GitHub,通常是本机网络不能直连 GitHub。Codex++ 启动时会优先继承现有代理环境变量;如果未设置,会自动探测常见本地代理端口。也可以手动指定:

$env:HTTP_PROXY="http://127.0.0.1:7897"
$env:HTTPS_PROXY="http://127.0.0.1:7897"
python -m codex_session_delete launch

确认是从 Codex++ 快捷方式启动,而不是直接启动原版 Codex。

也可以检查 Codex 是否带了 CDP 参数:

--remote-debugging-port=9229

打开 Codex++ 设置面板,启用 Provider 同步 后重新启动 Codex++。它会在启动 Codex 前同步当前 model_provider,让历史会话重新匹配当前供应商。

请先更新到当前版本后重新安装一次:

python -m codex_session_delete setup

新版会写入稳定的系统卸载项,并使用绝对 Python 路径执行卸载。

运行测试:

python -m pytest -q

项目结构:

codex_session_delete/
 cli.py CLI 入口
 launcher.py 启动 Codex 并注入脚本
 cdp.py CDP 通信与 bridge
 helper_server.py 本地 helper 服务
 storage_adapter.py 本地 SQLite 删除/撤销
 provider_sync.py Provider 同步
 settings_store.py Codex++ 后端设置
 windows_installer.py Windows 快捷方式与卸载项
 macos_installer.py macOS app bundle 安装
 watcher.py Windows 常驻 watcher(可选,原生启动接管)
 inject/renderer-inject.js
tests/ 自动化测试

Codex++ 是外部增强工具,不修改 Codex App 原始文件。Codex App 更新后,如果页面结构变化,可能需要更新注入脚本。