Codex++ (CodexPlusPlus) 项目详细总结
一、项目概述
Codex++（CodexPlusPlus）是一个面向 OpenAI Codex / ChatGPT 桌面应用的第三方外部启动器与管理工具。它通过 Chromium DevTools Protocol（CDP）和本地辅助服务，为 Codex 桌面应用提供供应商切换、协议转换、会话管理、界面增强等功能。
项目地址：https://github.com/BigPizzaV3/CodexPlusPlus
技术栈：Rust 1.85+ + Tauri 2.x + React/TypeScript 前端
开源协议：AGPL-3.0-only（GNU Affero General Public License v3.0）
最新版本：v1.2.42（发布于 2026-07-22）
核心设计原则：不修改官方应用的 app.asar，不向安装目录写入补丁文件，完全通过外部 CDP 注入和配置重写实现增强。
二、Codex++ 是什么
Codex++ 本质上是一个 Codex Desktop 应用的"外挂管理器"。它的定位介于以下几类工具之间：
- 启动器：代替用户启动 Codex 桌面应用，并在启动时自动加载预设的供应商配置和界面增强
- 供应商管理器：管理多种 API 供应商配置（官方登录、纯 API、中转站等），支持一键切换
- UI 增强注入器：通过 CDP 向 Codex 页面注入 JavaScript 脚本，实现界面增强功能
- 会话管理工具：扫描、备份、导出本地 Codex 会话数据
Codex++ 不是 Codex 的 fork，不修改 Codex 源码，不打包修改版的 app.asar。它与 Codex 的关系类似于浏览器扩展与浏览器的关系——外部注入，不改动核心。
三、核心功能模块
3.1 供应商配置
Codex++ 支持 4 种供应商模式，每种模式的认证边界和功能可靠性不同：
| 模式 | 用途 | 认证边界 | MCP 兼容性 |
|---|---|---|---|
| 官方登录 | 只使用 ChatGPT / Codex 官方账号 | 清理自定义 provider 和 API Key，保留官方登录状态 | 最佳 |
| 官方登录 + API | 保留官方账号与插件入口，模型请求走兼容 API | API Key 写入 provider bearer token，不写入 auth.json |
较好 |
| 纯 API | 不依赖官方账号，完全使用自定义 Base URL / Key | 独立保存 config.toml 与 API Key |
最差 |
| 聚合供应商 | 在多个普通 API 供应商之间路由 | 支持故障转移、按会话/请求轮转、权重轮转 | 视路由和中转站能力而定 |
每个供应商可配置：
- Responses 或 Chat Completions 协议
- 模型列表与测试模型
- User-Agent
- 上下文窗口（支持 1M、200K 或纯数字）
- 自动压缩阈值
- 该供应商启用的 MCP Server、Skill 和 Plugin
3.2 模型与上下文管理
Codex++ 使用 Codex 原生的 model_catalog_json 机制实现每模型粒度的上下文窗口配置：
- 通过 model_list 声明模型名
- 通过 model_windows JSON map 独立存储每模型窗口大小
- Codex++ 生成 catalog 文件并注入 config.toml 指针
- Codex 客户端运行时按当前模型识别对应窗口
旧版的 deepseek-v4-flash[1M] 后缀格式会自动迁移到新格式。
3.3 会话管理
- 扫描本地 Codex 会话（
~/.codex/sqlite/*.db） - 单选、多选、全选、批量删除会话
- Markdown 导出
- Token 用量历史查看
- Provider metadata 同步与备份
3.4 Codex 界面增强
以下增强功能均可独立开关，全部关闭后 Codex++ 仍可作为纯供应商/启动管理工具使用：
| 类别 | 功能 |
|---|---|
| 会话操作 | 会话删除、批量删除、Markdown 导出、项目移动 |
| 插件管理 | 插件市场解锁、插件自动展开、模型白名单处理 |
| 输入优化 | 富文本粘贴转纯文本 |
| 界面定制 | 强制中文界面、启动加速、原生菜单本地化 |
| 布局增强 | 会话宽度调整、滚动位置恢复 |
| 高级功能 | 线程 ID 管理、服务层级切换、Goals、Stepwise 下一步建议 |
| 开发工作流 | Upstream worktree、Zed Remote 项目识别与打开 |
| 自定义扩展 | 自定义图片覆盖层、用户脚本安装与启停 |
3.5 脚本与维护
- 用户脚本安装与启停
- 应用检测与快捷方式管理
- Watcher 服务（监控 Codex 应用状态）
- 环境冲突检测
- 日志诊断与健康检查
- Release 自动更新
四、安装与上手
4.1 下载安装
从 GitHub Releases 下载对应平台的安装包：
| 平台 | 文件名示例 |
|---|---|
| Windows x64 | CodexPlusPlus-1.2.42-windows-x64-setup.exe |
| macOS Intel | CodexPlusPlus-1.2.42-macos-x64.dmg |
| macOS Apple Silicon | CodexPlusPlus-1.2.42-macos-arm64.dmg |
安装后会创建两个入口：
- Codex++ — 静默启动器：自动启动官方桌面应用并加载已保存的供应商配置与增强功能
- Codex++ 管理工具 — 配置管理器：管理供应商、模型、工具插件、会话、增强功能、脚本、更新和诊断
4.2 首次使用流程
- 打开 Codex++ 管理工具
- 在"安装维护"页确认应用路径和运行状态
- 配置供应商（选择模式、填写 Base URL / API Key / 协议类型）
- 按需开启界面增强功能
- 从 Codex++ 入口（而非官方应用直接启动）启动 Codex
4.3 macOS 特殊处理
如果 macOS 提示"已损坏，无法打开"（Gatekeeper 拦截未签名应用），执行：
sudo xattr -rd com.apple.quarantine "/Applications/Codex++ 管理工具.app"
sudo xattr -rd com.apple.quarantine "/Applications/Codex++.app"
五、技术架构
5.1 项目结构
apps/
codex-plus-launcher/ 静默启动入口
codex-plus-manager/ Tauri 管理工具（前端 React+TS）
codex-plus-mobile-relay/ 移动端中继
assets/
inject/
renderer-inject.js 注入到 Codex 渲染端的增强脚本
inject/upstream/ 主题皮肤包（多种皮肤）
codex-models.json 模型元数据
crates/
codex-plus-core/ 核心逻辑：启动、注入、配置生成、catalog 解析、更新
codex-plus-data/ 数据持久化：会话数据、导出、Provider 同步
scripts/installer/
windows/CodexPlusPlus.nsi Windows NSIS 安装包
macos/package-dmg.sh macOS DMG 打包
5.2 关键代码入口
| 功能 | 代码位置 |
|---|---|
| 供应商配置数据模型 | crates/codex-plus-core/src/settings.rs 的 RelayProfile |
| 配置生成 | crates/codex-plus-core/src/relay_config.rs 的 apply_context_limits_to_config |
| catalog 解析 | crates/codex-plus-core/src/model_catalog.rs 的 parse_model_catalog_json_models |
| 供应商切换流程 | apply_relay_profile_to_home_with_switch_rules_and_computer_use_guard |
| 前端模型列表 | apps/codex-plus-manager/src/App.tsx 的 modelList |
| CDP 注入脚本 | assets/inject/renderer-inject.js |
5.3 工作原理
- 启动：用户从 Codex++ 入口启动，launcher 进程静默拉起 Codex Desktop
- CDP 连接：通过 Chromium DevTools Protocol 连接到 Codex 的渲染进程
- 日注入：向 Codex 页面注入
renderer-inject.js，实现界面增强 - 配置写入：重写
~/.codex/config.toml应用供应商配置、模型目录、MCP 服务器等 - 会话管理：读写
~/.codex/sqlite/*.db进行会话扫描和管理
5.4 数据位置
| 类型 | 路径 |
|---|---|
| Codex 配置 | ~/.codex/config.toml |
| Codex 登录状态 | ~/.codex/auth.json |
| Codex 本地数据库 | ~/.codex/sqlite/*.db（旧版回退到 ~/.codex/state_5.sqlite） |
| Codex++ 状态与日志 | ~/.codex-session-delete/ |
| Provider 同步备份 | ~/.codex/backups_state/provider-sync |
六、版本演进
项目经历了从早期 1.1.x 到当前 1.2.42 的持续迭代：
| 版本 | 日期 | 重要更新 |
|---|---|---|
| 1.1.x | 2026-05 | 上游分支 worktree、独立工具与插件页面、供应商切换隔离修复 |
| 1.2.4 | 2026-06-08 | Zed 远程项目支持、单实例启动保护优化 |
| 1.2.18 | 2026-06-25 | 模型列表双输入框、model_windows JSON map、后缀格式迁移 |
| 1.2.20 | 2026-06-27 | 逐行模型控件、本地会话批量删除 |
| 1.2.21 | 2026-06-28 | 插件列表全量展示开关、自动展开 |
| 1.2.22 | 2026-06-28 | 启动时不再自动切换供应商、Computer Use guard |
| 1.2.42 | 2026-07-22 | 确认弹窗修复、Dream Skin companion 图片、多数据库路径修复 |
七、开发指南
7.1 开发环境
# 克隆仓库
git clone https://github.com/BigPizzaV3/CodexPlusPlus.git
cd CodexPlusPlus
# 需要 Rust 1.85+ 和 Node.js
# 前端检查
cd apps/codex-plus-manager
npm ci
npm run check
npm run vite:build
# Rust 检查
cd ../..
cargo fmt --all -- --check
cargo test
cargo build --release
7.2 提交规范
- 使用
feat:/fix:前缀 - 遵循 Rust 标准格式化（
cargo fmt） - 使用
clippy进行代码检查 - 新功能需附带测试
- PR 需确保所有测试通过
7.3 测试约定
- 沿用上游
#[test]+ tempfile 风格 - 断言读取
config.toml文本内容 - 改行为同步改/加对应测试
八、常见问题与排障
8.1 Codex++ 菜单没出现
确认从 Codex++ 入口启动（不是直接打开官方应用）。在管理工具"安装维护"和"关于"页检查应用路径、启动状态与诊断日志。
8.2 切换供应商后请求失败
在供应商详情中运行模型测试或 Provider Doctor，确认协议（Responses / Chat Completions）、Base URL、Key 和测试模型匹配。纯 API 与官方混入模式使用不同认证位置，不要手工复制两种模式的 auth.json。
8.3 MCP 工具不可用（已启用但无法调用）
这是 Codex++ + 纯 API 中转站组合下的已知系统性问题。诊断步骤：
- 运行
codex mcp list— 如果显示 "Unsupported"，说明配置丢失 - 检查
~/.codex/config.toml是否包含[mcp_servers.*]段落 - 如果配置被重写覆盖，关闭 Codex++ 后手动恢复
根因分三层：
- 第一层：Codex++ 切换供应商时重写了 config.toml，MCP 服务器配置段丢失
- 第二层：中转站协议不完全兼容 Responses 工具调用，工具定义未被注入到请求载荷
- 第三层：模型本身不支持函数调用
解决方案：优先使用官方登录模式；或使用 ccx 工具兼容代理进行协议转换。
8.4 config.toml 被反复覆盖
Codex++ 的 UI 操作会触发 config.toml 重写。解决办法：编辑 config.toml 时确保 Codex++ 完全关闭，编辑完成后避免触发 UI 开关操作。
九、社区与生态
9.1 交流渠道
- QQ 群：830629290
- 微信群：通过 https://docs.qq.com/doc/DQ2VOanZTTFZJcUpZ 获取最新二维码
- Telegram 频道：https://t.me/CodexPlusPlus
9.2 中转站生态
Codex++ 与多家 AI API 中转站形成了合作生态，包括 JOJO Code、AIGoCode、APIKEY.FUN、RunAPI、Cubence、火山引擎等。用户可以通过中转站以更低成本使用非官方模型。
十、兼容性与限制
优点
- 不修改 Codex 官方应用，安全无侵入
- 丰富的供应商管理模式，灵活适配各种使用场景
- 强大的界面增强功能，可按需开关
- 活跃的开发迭代和社区支持
- 跨平台支持（Windows / macOS Intel / macOS Apple Silicon）
限制
- 依赖 Codex 桌面应用的页面结构和 CDP 接口，官方更新可能导致部分注入功能失效
- 纯 API 模式下 MCP 工具兼容性较差，依赖中转站协议实现
- 安装包未签名/未公证，macOS 需手动绕过 Gatekeeper
- 目前不支持 Linux 桌面（依赖 Codex Desktop 本身的平台可用性）
十一、总结
Codex++ 是一个成熟且活跃的 Codex 桌面应用增强工具，适合以下用户场景：
- 使用中转站 API 替代官方账号的用户 — 通过纯 API 或混入模式灵活接入
- 多供应商管理需求 — 一键切换不同 API 供应商配置
- 界面定制需求 — 中文界面、插件解锁、会话管理等 Codex 官方未提供的功能
- 团队协作 — 会话导出、Provider 同步备份便于团队共享配置
- 高级开发工作流 — Upstream worktree、Zed Remote 集成等
项目采用 Rust + Tauri 技术栈保证了高性能和跨平台能力，AGPL-3.0 开源协议确保了社区贡献的可持续性。截至 2026 年 7 月，项目已有 347 个文件，持续保持每周迭代节奏。
参考来源： - GitHub 仓库：https://github.com/BigPizzaV3/CodexPlusPlus - README.md（中文版） - CHANGELOG.md - AGENTS.md / CONTRIBUTING.md - 最新 Release v1.2.42（2026-07-22） - Hermes Agent codex-desktop skill 文档