当前项目 fork 自 BigPizzaV3/CodexPlusPlus

CodexElves

中文 | English

CodexElves 是面向新版 ChatGPT 桌面应用中 Codex 工作区的外部增强启动器和管理工具，同时兼容旧版 Codex App。它不修改原始安装文件，而是通过外部 launcher 启动 ChatGPT/Codex，并使用 Chromium DevTools Protocol 注入增强脚本。

桌面应用改名兼容：

• Windows：支持新版 ChatGPT.exe 和旧版 Codex.exe；当前 Microsoft Store 包身份仍为 OpenAI.Codex。
• macOS：支持新版 ChatGPT.app，并保留 Codex.app、OpenAI Codex.app 等旧名称。
• Watcher 只接管带 Codex 运行时的桌面应用，不会把 ChatGPT Classic 或 resources\codex.exe CLI 当作桌面主进程。
• Codex CLI、~/.codex 配置目录、协议字段和会话数据仍使用 Codex 名称，不做错误迁移。

快速使用

从 GitHub Releases 下载最新版安装包：

• Windows：CodexElves-*-windows-x64-setup.exe
• macOS Intel：CodexElves-*-macos-x64.dmg
• macOS Apple Silicon：CodexElves-*-macos-arm64.dmg

安装后会有两个入口：

• CodexElves：静默启动入口，不显示管理界面，只负责启动 ChatGPT/Codex 并注入增强功能。
• CodexElves 管理工具：Tauri 控制面板，用于启动、检查、修复、更新、配置中转注入、管理增强功能和用户脚本。

Windows 安装包会创建桌面和开始菜单快捷方式。macOS DMG 会安装 /Applications/CodexElves.app 和 /Applications/CodexElves 管理工具.app。

主要功能

• Rust 后端和静默 launcher，启动时不依赖额外运行时。
• Tauri + React 管理工具，支持深色/浅色切换。
• 外部 CDP 注入，不改 app.asar，不向 ChatGPT/Codex 安装目录写入 DLL。
• 中转注入模式：支持多个中转配置，写入 CodexElves provider，并可切回官方 ChatGPT 登录态。
• 传统增强模式：插件入口解锁、插件市场解锁、会话删除、Markdown 导出、项目移动等。
• 用户脚本独立管理，可在启动时注入自定义脚本。
• Provider 同步：启动前同步本地会话 metadata，切换供应商后旧会话仍可见。
• Upstream worktree 创建：可从 upstream/<base-branch> 创建新 worktree，创建前自动 fetch 远端分支，降低从陈旧本地 HEAD 派生导致的冲突风险。
• GitHub Release 自动更新，管理工具和静默启动器都会检测可用更新。
• Windows 单实例、无黑框启动、管理员权限清单、系统桌面路径识别。
• macOS x64/arm64 分架构 DMG，静默入口隐藏 Dock 图标。

效果展示

完整功能

本地代理

• 本地代理优化了非gpt模型协议翻译逻辑，可以使用codex内置工具，如web_search，tool_search
• 支持自己设置模型，和上下文大小

本地代理和请求日志

批量会话删除

引入降智雷达

痛点与解决

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

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

CodexElves 启动后会解锁插件入口，并在会话列表悬停时显示删除按钮：

顶部菜单栏会出现 CodexElves，可以查看后端状态并打开设置面板：

中转注入

中转注入适合已经在 Codex/ChatGPT 中完成官方账号登录，同时希望把模型请求转到自定义兼容 API 的场景。

这种混合模式的边界是：

• 官方 ChatGPT/Codex 登录态继续负责桌面应用的账号能力和插件入口。
• 中转配置只接管模型请求使用的 Base URL、Key 和模型名称。
• 兼容 API 供应商不需要固定为某一家；只要上游协议和 Codex 配置匹配即可。
• 清除 API 模式后应能回到官方登录态，继续使用官方账号和插件。

应用中转注入前建议先做一次最小检查：

1. 先确认 Codex 已检测到 ChatGPT 登录状态，插件入口可用。
2. 确认自定义 Base URL 可访问，并且支持所选上游协议（例如 Responses 兼容接口）。
3. 用目标 Key 做一次最小认证测试，例如模型列表或很短的消息请求。
4. 只记录 Key 是否存在和认证结果，不要把真实 Key 写入日志、截图或 issue。
5. 确认 ~/.codex/config.toml 已有备份，便于清除 API 模式后回滚。

在管理工具的“中转注入”页面：

1. 确认已经检测到 ChatGPT 登录状态。
2. 添加一个或多个中转配置，填写 Base URL 和 Key。
3. 选择当前配置并应用中转注入。
4. 启动 CodexElves。

CodexElves 会在 ~/.codex/config.toml 中写入类似配置：

model_provider = "CodexElves"

[model_providers.CodexElves]
name = "CodexElves"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://example.com/v1"
experimental_bearer_token = "sk-..."

如果需要回到官方登录态，在“中转注入”页面点击清除 API 模式即可移除 OPENAI_API_KEY 相关配置并切回官方 ChatGPT 登录模式。

增强功能

增强功能在管理工具中统一开关。默认开启增强注入；关闭后不会注入 CodexElves 菜单和脚本。

如果启用中转注入模式，插件入口解锁和插件市场解锁不再需要，界面会提示“中转注入模式下无需开启”。会话删除、导出、移动和用户脚本等增强仍可继续使用。

自动更新与安装包

CodexElves 通过 GitHub Release 发布安装包。Windows 会生成 NSIS 安装程序，macOS 会生成 Intel x64 和 Apple Silicon arm64 两个 DMG。

管理工具的“关于”页可以检查并启动更新。静默启动器发现新版本时会拉起管理工具并进入更新提示。

数据位置

• Codex 配置：~/.codex/config.toml
• Codex 登录状态：~/.codex/auth.json
• Codex 本地数据库：优先读取 ~/.codex/sqlite/*.db，旧版回退到 ~/.codex/state_5.sqlite
• CodexElves 状态与日志：~/.codex-session-delete/
• Provider 同步备份：~/.codex/backups_state/provider-sync

常见问题

CodexElves 菜单没出现

确认是从 CodexElves 入口启动，而不是直接打开原版 ChatGPT/Codex 应用。也可以打开管理工具的“诊断”和“日志”页面查看注入状态。

插件内显示后端连不上

先在浏览器或 PowerShell 里测试：

Invoke-RestMethod -Method Post -Uri http://127.0.0.1:45221/backend/status -Body "{}" -ContentType "application/json"

如果接口正常，但插件仍显示超时，通常是 Codex 页面里的 CDP bridge 或脚本缓存问题。重启 Codex，或在管理工具里查看日志中的 renderer.script_loaded、bridge.request、bridge.response。

Upstream worktree 和 Codex 原生创建有什么区别

CodexElves 的 Upstream worktree 功能等价于先更新远端分支，再执行：

git worktree add -b <new-branch> <worktree-path> upstream/<base-branch>

这样新 worktree 从最新的远端跟踪分支开始，而不是从当前会话所在的本地 HEAD 开始。如果 CodexElves 无法安全识别当前 Codex 版本的原生 worktree 创建表单，请从 CodexElves 菜单中手动填写仓库路径、分支名、worktree 路径、remote 和 base branch。

macOS 提示无法打开或已损坏

当前安装包未签名/未公证时，macOS Gatekeeper 可能拦截，出现“已损坏，无法打开”的提示：

如果遇到该提示，可以在终端执行下面两条命令，解除苹果系统的安全隔离限制：

sudo xattr -rd com.apple.quarantine /Applications/CodexElves\ 管理工具.app
sudo xattr -rd com.apple.quarantine /Applications/CodexElves.app

执行后重新打开 CodexElves 或 CodexElves 管理工具 即可。

macOS Intel 能用吗

可以。Release 会分别提供 macos-x64.dmg 和 macos-arm64.dmg。Intel Mac 下载 x64 包，Apple Silicon 下载 arm64 包。

开发

# 前端检查
cd apps/codex-elves-manager
npm install
npm run check
npm run vite:build

# Rust 检查
cd ../..
cargo fmt --check
cargo test
cargo build --release

主要结构：

apps/
  codex-elves-launcher/          静默启动入口
  codex-elves-manager/           Tauri 管理工具
assets/inject/
  renderer-inject.js            注入到 Codex 渲染端的轻量 bootstrap
  renderer-features.js          按需安装的完整增强脚本
crates/
  codex-elves-core/              启动、注入、配置、更新、安装、桥接等核心逻辑
  codex-elves-data/              会话数据、导出、Provider 同步
scripts/installer/
  windows/CodexElves.nsi     Windows NSIS 安装包
  macos/package-dmg.sh          macOS DMG 打包

说明

CodexElves 是外部增强工具，不修改 ChatGPT/Codex 桌面应用原始文件。桌面应用更新后，如果页面结构变化，可能需要更新注入脚本。