## 项目概述

Codex++（CodexPlusPlus）是一个面向 OpenAI Codex / ChatGPT 桌面应用的外部启动器与管理工具。它通过 Chromium DevTools Protocol（CDP）和本地辅助服务，为官方桌面应用提供供应商切换、协议转换、会话管理与界面增强等功能。项目不修改官方应用的 `app.asar`，也不向安装目录写入补丁文件，而是以外部工具的形式增强 Codex 的使用体验。项目使用 Rust 和 Tauri 构建，遵循 AGPL-3.0 许可证。

## 核心功能

- **供应商配置**：支持官方登录、官方登录混入 API、纯 API、聚合供应商等多种模式；支持 Responses / Chat Completions 协议；提供模型测试、模型列表、Provider Doctor 等功能。
- **模型与上下文**：支持为每个模型配置上下文窗口（如 `1M`、`200K`），自动生成 `model_catalog_json` 文件，使 Codex 客户端按模型识别真实上下文窗口；支持自动压缩阈值设置。
- **会话管理**：支持扫描本地会话、批量删除、Markdown 导出、Token 用量历史、Provider metadata 同步与备份。
- **Codex 界面增强**：提供插件市场解锁、模型白名单、会话操作、粘贴修复、中文界面、快速启动、会话宽度与滚动恢复、服务层级控制、Goals、Stepwise 等功能。
- **开发工作流**：支持项目移动、Upstream worktree 创建、线程 ID、Zed Remote 项目识别与打开。
- **脚本与维护**：支持用户脚本安装与启停、应用检测、快捷方式、Watcher、环境冲突、日志诊断、健康检查和 Release 更新。

## 适用与不适用场景

**适用场景：**

- 需要为 Codex 桌面应用配置多个 API 供应商（官方、第三方中转等）的用户。
- 需要按模型设置不同上下文窗口（如 1M、200K）的开发者。
- 需要批量管理 Codex 会话（删除、导出、备份）的用户。
- 希望增强 Codex 界面（如中文界面、插件市场解锁）的用户。
- 需要从上游分支创建 Git worktree 的团队协作场景。

**不适用场景：**

- 不使用 Codex 桌面应用的用户。
- 需要修改 Codex 官方应用内部文件或补丁的场景（Codex++ 明确不修改 `app.asar`）。
- 需要官方支持或保证的场合（Codex++ 依赖官方应用的页面结构和 CDP，官方更新后可能需要适配）。
- 对安全要求极高、不允许外部工具注入的环境。

## 技术架构与依赖

- **编程语言**：Rust（后端核心）、TypeScript/React（前端管理界面）。
- **框架**：Tauri 2（桌面应用框架）、Vite（前端构建）。
- **核心库**：`serde`、`serde_json`、`toml_edit`、`rusqlite`、`tokio`、`reqwest`、`tokio-tungstenite` 等。
- **架构**：项目采用 Cargo workspace，包含 `codex-plus-core`（核心逻辑）、`codex-plus-data`（数据操作）、`codex-plus-launcher`（静默启动器）、`codex-plus-manager`（Tauri 管理工具）等模块。
- **注入机制**：通过 Chromium DevTools Protocol（CDP）向 Codex 渲染端注入增强脚本。

## 安装与快速开始

从 [GitHub Releases](https://github.com/BigPizzaV3/CodexPlusPlus/releases) 下载最新版安装包：

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

安装后会有两个入口：

- `Codex++`：静默启动官方桌面应用，并加载已保存的供应商配置与增强功能。
- `Codex++ 管理工具`：管理供应商、模型、工具插件、会话、增强功能、脚本、更新和诊断。

首次使用建议先打开管理工具，确认应用路径和运行状态，再配置供应商与增强功能，最后从 `Codex++` 入口启动。

## 典型使用方法

1. **配置供应商**：打开管理工具，在“供应商配置”中添加或导入供应商（支持官方登录、纯 API、聚合供应商等）。
2. **设置模型与上下文**：在供应商详情中配置模型列表，可为每个模型指定上下文窗口（如 `deepseek-v4-pro[1M]`），保存后 Codex++ 会自动生成 catalog 文件。
3. **切换供应商**：在管理工具或 Codex++ 菜单中切换供应商，Codex++ 会保存当前配置并写入目标配置。
4. **管理会话**：在管理工具中扫描本地会话，可批量删除、导出 Markdown 或备份。
5. **使用增强功能**：在 Codex++ 菜单中启用/关闭各项增强（如中文界面、插件市场解锁、Upstream worktree 等）。
6. **创建 Upstream worktree**：在 Codex++ 菜单中填写仓库路径、分支名等，从 `upstream/<base>` 创建新 worktree。

## 配置与部署要点

- **数据位置**：Codex 配置位于 `~/.codex/config.toml`，登录状态在 `~/.codex/auth.json`，本地数据库在 `~/.codex/sqlite/*.db`（旧版为 `~/.codex/state_5.sqlite`）。Codex++ 状态与日志在 `~/.codex-session-delete/`。
- **供应商切换**：切换供应商时会先保存当前配置，再写入目标配置。真实 API Key 只保存在本机，请勿放入日志、截图或 issue。
- **模型 catalog**：Codex++ 会生成独立的 `model_catalog_json` 文件，让 Codex 按当前模型使用对应窗口。
- **macOS 安全**：若提示“已损坏，无法打开”，需在终端执行 `sudo xattr -rd com.apple.quarantine /Applications/Codex++\ 管理工具.app` 和 `sudo xattr -rd com.apple.quarantine /Applications/Codex++.app`。
- **兼容性**：Codex++ 依赖官方桌面应用的页面结构、CDP 和本地数据格式，官方应用更新后可能需要适配。

## 限制、风险与许可证

- **限制**：Codex++ 不修改官方应用文件，但依赖官方应用的内部结构和 CDP，官方更新可能导致部分功能失效。
- **风险**：切换供应商或修改配置前应保留备份；API Key 仅保存在本机，需注意安全。
- **许可证**：CodexPlusPlus 采用 [GNU Affero General Public License v3.0](LICENSE)，SPDX 标识为 `AGPL-3.0-only`。修改并分发本项目，或通过网络提供修改后的版本时，需要按 AGPLv3 提供对应源代码。许可证只覆盖 CodexPlusPlus 自身代码，不授予 OpenAI、ChatGPT、Codex 的商标、应用资源或其他第三方内容的权利。

## 官方链接

- GitHub 仓库：<https://github.com/BigPizzaV3/CodexPlusPlus>
- Releases：<https://github.com/BigPizzaV3/CodexPlusPlus/releases>
- Telegram 频道：<https://t.me/CodexPlusPlus>
- QQ 交流群：619480492（链接：<https://qm.qq.com/q/Erf1F1zwqs>）

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、CHANGELOG、文档（docs/ 目录）、发布信息。
- 分析时间：2026-08-10（基于最新 Release 日期）。