# CC Switch v3.16.1

> Codex 稳定性补丁：由于部分用户反映不希望改变配置文件的写入方式，因此为 Codex 增强模式添加开关并默认关闭。开启此开关后，你可以在使用第三方 API 的情况下继续使用 Codex 的手机远程操作、官方插件等功能；本版本也包含一系列稳定性修复。

**[English →](v3.16.1-en.md) | [日本語版 →](v3.16.1-ja.md)**

---

## 使用攻略

如果你希望在使用第三方 API 的时候解锁官方订阅才可以使用的远程操作 Codex、解锁官方插件，或希望在 Codex 中使用 DeepSeek / Kimi / GLM / MiniMax 等 Chat Completions 上游，建议先看这些文档：

- **[使用第三方 API 时保留 Codex 远程操作和官方插件](../guides/codex-official-auth-preservation-guide-zh.md)**：说明如何先完成官方登录，再开启 Codex 应用增强，让官方登录态留在 `auth.json`，同时把模型流量切到第三方 API。
- **[在 Codex 中使用 DeepSeek：本地路由实战攻略](../guides/codex-deepseek-routing-guide-zh.md)**：从添加 Codex 供应商、开启本地路由，到验证请求转发的完整路径。
- **[添加 Codex 供应商：Chat Completions 路由与模型映射](../user-manual/zh/2-providers/2.1-add.md)**：覆盖「需要本地路由映射」、模型映射表与思考能力配置。
- **[本地代理服务](../user-manual/zh/4-proxy/4.1-service.md)** 与 **[本地路由](../user-manual/zh/4-proxy/4.2-routing.md)**：了解代理服务、接管 live 配置、以及相关风险提示。

---

> [!WARNING]
>
> ## 唯一官方渠道声明（请务必阅读）
>
> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
>
> | 类别     | 唯一官方                                                                       |
> | -------- | ------------------------------------------------------------------------------ |
> | 官网     | **[ccswitch.io](https://ccswitch.io)**                                         |
> | 源码     | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
> | 下载     | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
> | 作者     | **[@farion1231](https://github.com/farion1231)**                               |
> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
>
> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。

---

## 概览

CC Switch v3.16.1 是 v3.16.0 之后的一版 Codex 稳定性补丁。v3.16.0 让第三方 Codex 供应商通过 Chat Completions 路由成为一等公民；这一版则主要处理真实使用中暴露出的几个高风险边角：官方 ChatGPT / Codex OAuth 登录态在第三方供应商切换或本地路由接管期间被覆盖，Codex 模型目录在 live 回填、热切换、关闭接管恢复或编辑当前供应商时被清空，以及 Codex 的 `tool_search`、插件 / 连接器命名空间、自定义工具在 Chat Completions 上游路径中没有完整恢复为 Responses 事件。

这版也加固了本地路由接管的所有权判断：切换供应商和开启 / 关闭接管现在按应用串行执行，判断 live 文件是否由代理接管时不再只看滞后的 `enabled` 或代理服务是否正在运行，而是结合备份和 live 中的代理占位符。这样可以避免刚开启接管、代理临时停止，或热切换时的普通 live 写入把代理托管配置覆盖掉。

**发布日期**：2026-06-01

**更新规模**：23 commits | 62 files changed | +5,603 / -1,113 lines

---

## 重点内容

- **Codex OAuth 与第三方供应商切换更安全**：新增可选的官方认证保留设置；开启后，第三方供应商 token 写入 `config.toml`，官方 ChatGPT / Codex OAuth 登录继续留在 `auth.json`。
- **Codex 模型目录不再被静默清空**：`modelCatalog` 以数据库为真相来源，live 回填、供应商切换、接管关闭恢复、编辑弹窗都会避免用丢失投影的 live 配置覆盖数据库。
- **Codex Chat 工具 / 插件路由恢复**：Chat Completions 上游返回的 `tool_search`、已加载命名空间工具、自定义工具会重新映射回 Codex Responses 形态；流式自定义工具现在发出原生 `response.custom_tool_call_input.*` 事件。
- **本地路由接管与热切换更稳**：供应商切换和接管开关按 app 串行，热切换会刷新 Codex live 中的供应商显示信息，但 endpoint 仍保持指向本地代理。
- **诊断与平台兼容性修复**：Codex 代理错误返回更丰富上下文；Codex CLI 模型模板发现支持更多平台并提供 GPT-5.5 静态兜底；Windows 工具版本探测修复乱码与误判。

---

## 新功能

### Codex 官方认证保留设置

新增一个可选设置，用于在切换第三方 Codex 供应商时保留官方 ChatGPT / Codex OAuth 登录态。开启后，CC Switch 会把第三方供应商的 API key 放进 Codex `config.toml` 的 provider-scoped `experimental_bearer_token`，而不是覆盖 `auth.json` 里的官方登录缓存。

由于部分用户不希望此功能改变配置文件的写入方式，因此该设置默认关闭，保持 v3.16.0 之前的兼容行为。需要同时使用官方 Codex 登录和第三方供应商的用户，可以在“设置 → Codex 应用增强”里手动开启。

### Codex DeepSeek 路由指南

新增中 / 英 / 日三语的 Codex DeepSeek 路由指南，包含供应商路由要求、DeepSeek Codex 供应商表单配置，以及本地路由接管的截图说明。

---

## 变更

### Codex 认证保留默认改为 opt-in

官方认证保留设置默认关闭。这样第三方 Codex 供应商切换继续沿用旧行为，避免已有用户在不知情的情况下改变 `auth.json` / `config.toml` 的写入方式。

### Codex 切换供应商后提示重启

Codex 的模型目录与部分配置在客户端启动时加载。现在成功切换 Codex 供应商后，界面会提示用户重启 Codex，让模型目录和配置变化真正生效。

### 供应商切换与接管开关串行化

Codex / Claude / Gemini 的供应商切换与本地路由接管开关现在共享 per-app 锁，避免两个流程同时修改 live 配置和备份。判断 live 是否由代理接管时，也会优先看 live 备份与 `PROXY_MANAGED` 占位符，而不是只看代理服务是否正在运行。

### Codex 热切换刷新显示信息

在本地路由接管期间热切换 Codex 供应商时，CC Switch 会刷新 live 配置中的 provider id、模型和显示名称，让 Codex 客户端菜单能跟随当前供应商；同时 base URL 仍保持本地代理地址，避免真实上游 endpoint 泄回 live 文件。

---

## 修复

### Codex 接管期间编辑弹窗误显示 live OAuth

当 Codex 处于本地路由接管状态时，live `auth.json` / `config.toml` 已被代理临时改写。编辑当前供应商如果继续读取 live，就会把代理占位符或官方 OAuth 登录误显示成供应商配置。现在编辑弹窗会明确提示：此处显示的是数据库中存储的供应商配置，而不是代理托管的 live 文件；即使代理服务暂时停止，只要该 app 仍处于接管状态，也会按接管逻辑处理。

### Codex OAuth 在接管期间被清空或覆盖

修复多条 preserve-mode 接管路径，它们此前可能清空或覆盖官方 ChatGPT / Codex OAuth `auth.json`。现在接管检测会识别 `config.toml` 里的 `PROXY_MANAGED`，清理流程只移除代理占位符 token，第三方供应商错误归类为 official 时也不会再走官方 auth 覆盖路径。供应商同步与切换会把 live 备份和占位符视为接管所有权信号，避免正常 live 写入覆盖刚接管或代理暂停时的代理配置。

### Codex 模型目录数据丢失

修复 `modelCatalog` 在 live 回填、当前供应商编辑弹窗、供应商切换、关闭接管恢复等场景被清空的问题。快照备份会保留已有 `model_catalog_json` 指针；由供应商重建的备份会从数据库真相来源重新生成目录投影；编辑当前供应商时会优先使用数据库里的模型目录，而不是信任可能已经丢失投影的 live 反解结果。

同时，供应商切换现在会始终刷新生成的 Codex 模型目录 JSON（[#3360](https://github.com/farion1231/cc-switch/pull/3360)，感谢 @Postroggy）。

### Codex Chat 工具、插件和自定义工具恢复

修复第三方 Codex 供应商走 Chat Completions 路由时，`tool_search`、已加载的 MCP / connector 命名空间工具、自定义工具无法完整恢复为 Codex Responses 形态的问题。非流式与流式 Chat 响应现在都会根据原始 Responses 请求恢复正确的工具类型、namespace、call id 与参数；自定义工具流式输出会发出原生的 `response.custom_tool_call_input.delta` 和 `response.custom_tool_call_input.done` 事件。

### Codex 代理错误诊断更完整

Codex 转发失败时，现在返回包含 provider、model、endpoint、上游 HTTP 状态、稳定 `cc_switch_*` 错误码和规范 HTTP 状态的 JSON 错误。这样排查「到底是哪个供应商、哪个 endpoint、哪种上游错误」会清楚很多。

### Codex 原生余额 / Coding Plan 查询凭据

修复原生余额与 Coding Plan 查询时跨 app 错用凭据的问题。现在每个 app 会解析自己的供应商凭据，不再把其他应用面的认证假设带进查询流程（[#3355](https://github.com/farion1231/cc-switch/pull/3355)，感谢 @SiskonEmilia）。

### Codex CLI 发现与模型目录模板兜底

修复第三方 Codex 模型目录投影对 Codex CLI 发现路径过窄的问题。现在后端会在多平台常见安装位置寻找 Codex CLI，并在仍找不到模板时使用内置 GPT-5.5 模型目录模板兜底（[#3382](https://github.com/farion1231/cc-switch/pull/3382)，感谢 @chofuhoyu）。

### Claude Desktop 官方供应商添加失败

修复添加 Claude Desktop 官方供应商时报错的问题（[#3405](https://github.com/farion1231/cc-switch/pull/3405)，感谢 @Eunknight）。

### Kimi / Moonshot 工具思考历史规范化

把 Kimi / Moonshot 加入 Anthropic 兼容工具思考历史 normalizer。后续轮次现在能正确重放 reasoning 与 tool-call 上下文，避免因为历史消息形态不符合上游要求而失败（[#3377](https://github.com/farion1231/cc-switch/pull/3377)，感谢 @Neon-Wang）。

### Windows 工具版本探测

修复 Windows 上 `.cmd` / `.bat` 版本命令被错误加引号，以及本地化命令输出被解码成乱码的问题。此前这些问题会让可运行的工具显示为「已安装但无法运行」。

---

## 升级提醒

### 官方 OAuth 保留需要手动开启

如果你希望官方 ChatGPT / Codex OAuth 登录长期保留在 `auth.json`，同时又频繁切换第三方 Codex 供应商，请在设置中开启 Codex 官方认证保留。默认关闭是为了保持老用户的兼容行为。

### 修改模型映射后仍需重启 Codex

Codex 在启动时读取 `model_catalog_json`。因此即使 v3.16.1 已修复模型目录被清空的问题，只要你修改了模型映射表，仍然需要重启 Codex 才能让 `/model` 菜单刷新。

### 接管期间编辑的是存储配置，不是 live 文件

本地路由接管开启后，live `auth.json` / `config.toml` 会临时指向 CC Switch 代理。此时编辑供应商时看到的是数据库里保存的供应商配置，属于预期行为；关闭接管后，CC Switch 会按备份或数据库真相来源恢复 live 配置。

---

## 风险提示

本版本继续沿用此前版本对反向代理类功能的风险提示。

**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。

**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。

**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。

用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。

---

## 致谢

感谢以下贡献者在 v3.16.1 中提交修复：

- [#3360](https://github.com/farion1231/cc-switch/pull/3360)：Codex 供应商切换时始终更新模型目录 JSON，感谢 @Postroggy。
- [#3355](https://github.com/farion1231/cc-switch/pull/3355)：原生余额 / Coding Plan 查询按 app 解析凭据，感谢 @SiskonEmilia。
- [#3405](https://github.com/farion1231/cc-switch/pull/3405)：修复 Claude Desktop 官方供应商添加报错，感谢 @Eunknight。
- [#3382](https://github.com/farion1231/cc-switch/pull/3382)：Codex CLI 多平台发现与 GPT-5.5 模型模板兜底，感谢 @chofuhoyu。
- [#3377](https://github.com/farion1231/cc-switch/pull/3377)：Kimi / Moonshot 工具思考历史规范化，感谢 @Neon-Wang。

也感谢所有在 v3.16.0 发布后反馈 Codex OAuth、模型目录、本地路由接管和 Chat Completions 工具调用问题的用户。很多补丁都来自这些真实使用场景里的复现线索。

---

## 下载与安装

访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。

### 系统要求

| 系统    | 最低版本                   | 架构                                |
| ------- | -------------------------- | ----------------------------------- |
| Windows | Windows 10 及以上          | x64                                 |
| macOS   | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
| Linux   | 见下表                     | x64 / ARM64                         |

### Windows

| 文件                                     | 说明                                |
| ---------------------------------------- | ----------------------------------- |
| `CC-Switch-v3.16.1-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
| `CC-Switch-v3.16.1-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |

### macOS

| 文件                             | 说明                                          |
| -------------------------------- | --------------------------------------------- |
| `CC-Switch-v3.16.1-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
| `CC-Switch-v3.16.1-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
| `CC-Switch-v3.16.1-macOS.tar.gz` | 用于 Homebrew 安装和自动更新                  |

Homebrew 安装：

```bash
brew install --cask cc-switch
```

更新：

```bash
brew upgrade --cask cc-switch
```

### Linux

Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：

- `CC-Switch-v3.16.1-Linux-x86_64.AppImage` / `.deb` / `.rpm`
- `CC-Switch-v3.16.1-Linux-arm64.AppImage` / `.deb` / `.rpm`

| 发行版                                  | 推荐格式    | 安装方式                                                               |
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm`  |
| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
| Arch Linux / Manjaro                    | `.AppImage` | 添加执行权限后直接运行，或使用 AUR                                     |
| 其他发行版 / 不确定                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
