v3.20.2

# CC Switch v3.20.2

> 这一版仍以 Codex 为主线，但形态从上一版的「一次重设计」变成「一波兼容性修复」：**Grok 终于能经 xAI 原生 Responses API 在 Codex 路由下跑通**——xAI 拒收的工具 schema、Codex 拒收的整数浮点、多智能体注入的邮箱消息、xAI 不认识的 Codex 角色型号，四道坎逐一拆掉；围绕它的一族「一因一果」修复：Grok OAuth 卡不再被 v3.20.1 的切换闸误拦、接管不再把 Codex 卡在登录屏、GPT-6 走 Codex OAuth 不再报「需要更新 Codex」、Claude Code 在 Codex OAuth 上恢复并行工具调用、内置图片生成走通本地路由、四个 catalog 缺陷（旧版 Codex 拒载、DeepSeek 下 MCP 工具全隐身、视觉型号被判纯文本、Kimi 工具 schema 400）关闭，智谱 GLM 预设改指官方 Responses 端点。用量侧，Codex resume 后统计停摆与代理每轮打断前缀缓存两条硬修复落地。预设阵营新增腾讯云 Token Plan、QwenCloud、AICodeWith 与两家赞助商 9527CODE、SoleAPI，定价表补入七个新模型并做了一轮九月调价。**本版不含数据库迁移。**

**[English →](https://github.com/farion1231/cc-switch/blob/v3.20.2/docs/release-notes/v3.20.2-en.md) | [日本語版 →](https://github.com/farion1231/cc-switch/blob/v3.20.2/docs/release-notes/v3.20.2-ja.md)**

---

## 重点内容：你现在可以

- **在 Codex 里经 xAI 原生 Responses 跑 Grok**（[#6917](https://github.com/farion1231/cc-switch/pull/6917)，修复 [#6815](https://github.com/farion1231/cc-switch/issues/6815)）：xAI 拒收的 Codex Desktop 工具 schema 被折叠、Grok 回传的整数浮点被改写、多智能体子任务的 `agent_message` 被翻译成普通消息、`gpt-5.6-sol` 一类角色型号被映射到你配置的 Grok 模型——子智能体不再 422，工具调用不再被拒。
- **正常切换 Grok OAuth 卡、正常接管**：v3.20.1 的无密钥安全闸误拦了代理注入令牌的 OAuth 卡；接管在直接切换删除 `auth.json` 之后不再把 Codex 困在登录屏。
- **用 GPT-6 走 Codex OAuth 接管**（[#7132](https://github.com/farion1231/cc-switch/pull/7132)）：自报的 Codex 客户端版本升到 0.153.4，不再被 ChatGPT 后端以「需要更新 Codex」拒绝。
- **让 Claude Code 在 Codex OAuth 上并行调用工具**（[#7024](https://github.com/farion1231/cc-switch/pull/7024)，修复 [#5719](https://github.com/farion1231/cc-switch/issues/5719)）：`parallel_tool_calls` 默认改为 true，每轮不再只允许一个工具调用。
- **在 Codex 路由下使用内置图片生成与编辑**（[#7036](https://github.com/farion1231/cc-switch/pull/7036)，修复 [#5429](https://github.com/farion1231/cc-switch/issues/5429)、[#6745](https://github.com/farion1231/cc-switch/issues/6745)）：`/images/generations` 与 `/images/edits` 两条路由经本地代理透传，用量按 token 记账。
- **在 DeepSeek 原生预设下看到 MCP 工具**（[#6653](https://github.com/farion1231/cc-switch/pull/6653)，修复 [#6647](https://github.com/farion1231/cc-switch/issues/6647)）：catalog 不再声明 DeepSeek 不支持的 `tool_search`，MCP 工具直接列出。
- **Codex 桌面端经本地代理接 Kimi/Moonshot 不再必现 400**（[#6863](https://github.com/farion1231/cc-switch/pull/6863)，修复 [#6867](https://github.com/farion1231/cc-switch/issues/6867)）：带兄弟关键字的 `$ref` 只对 Moonshot 域名改写成 `allOf`，其他供应商的 schema 逐字节不变。
- **让智谱 GLM 在 Codex 直连**（#6957，修复 [#6944](https://github.com/farion1231/cc-switch/issues/6944)）：预设改指官方 Responses 端点 `/api/v1`、默认 glm-5.3，存量卡需重新导入。
- **resume 之后用量继续累计**（[#6905](https://github.com/farion1231/cc-switch/pull/6905)，修复 [#6904](https://github.com/farion1231/cc-switch/issues/6904)）：回退过的线程再 resume 时写入的双 UUID rollout 文件不再被永久搁置，积压用量自动回填到原日期。
- **在 OpenAI 格式上游重新命中前缀缓存**（[#6941](https://github.com/farion1231/cc-switch/pull/6941)，修复 [#6789](https://github.com/farion1231/cc-switch/issues/6789)）：Claude Code 每轮注入的中途 system 消息不再被合并到对话开头，DeepSeek、GLM、Kimi 一类端点的缓存命中率不再从 99% 掉到 20%。
- **一键添加新供应商**：腾讯云 Token Plan（六应用，[#7011](https://github.com/farion1231/cc-switch/pull/7011)）、QwenCloud（七应用，[#6214](https://github.com/farion1231/cc-switch/issues/6214)）、AICodeWith（八应用）、赞助商 9527CODE 与 SoleAPI（九应用）；Pi 补齐腾讯 TokenHub / Token Plan（[#7159](https://github.com/farion1231/cc-switch/pull/7159)）与 PPIO（[#6870](https://github.com/farion1231/cc-switch/pull/6870)）。
- **看到 Fable 5.1 / Mythos 5.1、GPT-6 Astra、GLM-5.3、Gemini 3.8 Flash 的真实成本**：此前这些请求按 $0 记账；Sonnet 5 按 Anthropic 转正口径改回 $2/$10。
- **再次看到 Hermes 的升级按钮**：最新版本改读 GitHub Releases，不再永远停在 PyPI 的 0.19.0。

---

## 使用攻略

- **[添加供应商](https://github.com/farion1231/cc-switch/blob/v3.20.2/docs/user-manual/zh/2-providers/2.1-add.md)**：新增预设的导入入口，以及「预设改动只影响新建供应商」的含义。
- **[请求路由](https://github.com/farion1231/cc-switch/blob/v3.20.2/docs/user-manual/zh/4-proxy/4.2-routing.md)**：Grok 经 xAI 原生 Responses、Codex 图片端点透传都走这条路径。
- **[用量统计](https://github.com/farion1231/cc-switch/blob/v3.20.2/docs/user-manual/zh/4-proxy/4.4-usage.md)**：定价表回填与 resume 积压用量的记账口径。

---

> [!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 反馈。

---

## 概览

v3.20.1 之后的开发依旧由 Codex 领衔，但这一次是一波兼容性修复而不是一次重设计。最长的一条线是 Grok：xAI 的原生 Responses API 在几处与 Codex 的假设相左——它在采样前就拒收 Codex Desktop 的工具 schema、Grok 回传的 JSON 整数带小数点而 Codex 的解析器拒收、Codex 多智能体模式注入的 `agent_message` 邮箱项 xAI 无法反序列化、Codex 自己的角色型号（如 `gpt-5.6-sol`）xAI 直接 404。本版把这四道坎在同一个原生 Responses 闸门后逐一拆掉，Grok 终于能在 Codex 路由下完整工作，包括子智能体。

围绕它是一族「一因一果」的修复：v3.20.1 引入的无密钥安全闸误拦了代理注入令牌的 Grok OAuth 卡；直接切换删掉 `auth.json` 之后再开接管，Codex 会被过时的 `requires_openai_auth = true` 困在登录屏；GPT-6 走 Codex OAuth 接管被后端以客户端版本过旧拒绝；Claude Code 在 Codex OAuth 上被强制串行调用工具；内置图片生成在本地路由下 404；四个 catalog 缺陷——旧版 Codex 拒载 catalog、DeepSeek 预设下 MCP 工具全部隐身、DeepSeek 视觉型号被判纯文本、Kimi 工具 schema 必现 400——各自关闭；智谱 GLM 预设从 Chat 端点改指官方 Responses 端点。用量侧两条硬修复：Codex resume 之后统计静默停摆，以及代理把 Claude Code 每轮注入的中途 system 消息合并到开头、打断上游前缀缓存。

预设库新增腾讯云 Token Plan、QwenCloud、AICodeWith 与赞助商 9527CODE、SoleAPI，Pi 补齐腾讯与 PPIO；定价表补入七个新模型行并按各厂商九月官方价页做了一轮调价。本版不改数据库 schema。

**发布日期**：2026-09-07

**更新规模**：52 commits | 71 files changed | +10,483 / -573 lines

---

## 新功能

### 新增预设

腾讯云 Token Plan（六产品 × 六应用，[#7011](https://github.com/farion1231/cc-switch/pull/7011)）、QwenCloud（三计划 × 七应用，[#6214](https://github.com/farion1231/cc-switch/issues/6214)）、AICodeWith（八应用）与两家赞助商 9527CODE、SoleAPI（九应用）加入预设库；Pi 补齐腾讯 TokenHub / Token Plan（[#7159](https://github.com/farion1231/cc-switch/pull/7159)）与 PPIO（[#6870](https://github.com/farion1231/cc-switch/pull/6870)）。存量供应商不受影响；需要重新导入的情形见升级提醒。

### 七个新模型的定价行

Claude Fable 5.1 与 Mythos 5.1：$10/$50 每百万，缓存读 $0.25、缓存写 $12.50（[#7051](https://github.com/farion1231/cc-switch/pull/7051)，修复 [#7050](https://github.com/farion1231/cc-switch/issues/7050)）——此前没有行，这些请求一律按 $0 入账，因为前缀规则只找更长的带日期 id、无法回落到 `claude-fable-5`；GLM-5.3：$1.40/$4.40，缓存读 $0.26，与 Z.ai 官方价一致（[#6591](https://github.com/farion1231/cc-switch/pull/6591)）；GLM-5.3 Flash：$0.15/$0.50，缓存读 $0.03（[#7163](https://github.com/farion1231/cc-switch/pull/7163)）；GPT-6 Astra：$10/$50，缓存读 $1、缓存写 $12.50，low/medium/high/xhigh 后缀回落到基础行（[#7162](https://github.com/farion1231/cc-switch/pull/7162)）；Gemini 3.8 Flash：$0.75/$3.75，缓存读 $0.075，无缓存写费（[#7164](https://github.com/farion1231/cc-switch/pull/7164)）；Qwen3.8 Flash：$0.15/$0.47，1M 窗口内不分档，缓存读/写 $0.016/$0.20。全部只是 seed 行、不改 schema；存量安装下次启动即拿到，启动时的成本回填会把这些 id 此前按 $0 记录的历史行补上价格。

---

## 变更

### 2026 年 9 月定价刷新

Sonnet 5 改回 $2/$10——Anthropic 价页现已注明介绍价即标准价、9 月 1 日涨到 $3/$15 的计划不再执行——并带一条守卫修复：仍是 seed 值 3/15/0.30/3.75 的安装被纠正，用户自定义过的行不动（[#7051](https://github.com/farion1231/cc-switch/pull/7051)）。GPT-5.6 Sol、裸名 `gpt-5.6` 及其五个档位后缀行同步从 $5/$30（缓存读 $0.50、写 $6.25）降到促销价 $4/$20（缓存读 $0.40、写 $5），至少持续到 2026-11-21。Gemini 3.6 Flash 从 $1.50/$7.50/$0.15 降到与 3.8 Flash 相同的介绍价 $0.75/$3.75/$0.075，至 2026-12-31。MiniMax M2、M2.1、M2.5 统一为官方按量价 $0.30/$1.20，缓存读 $0.03、缓存写 $0.375——后者此前记为零。每项调价都是 seed 加一条按旧值守卫的修复条目，追加在既有链条之后，老数据库会逐级经过中间价位。

---

## 修复

### Grok 经 xAI 原生 Responses API 在 Codex 路由下跑通

一组贡献者提交关闭了原生 Responses 通往 xAI 路径上四个互相独立的故障。xAI 在采样前就拒收 Codex Desktop 的内置工具 schema，于是请求路径上折叠根级 `oneOf`/`anyOf` 函数参数（[#6815](https://github.com/farion1231/cc-switch/issues/6815)），各分支的 required 取交集而不是并集，压平后的 `oneOf` 不会强求所选分支没有的字段。Grok 回传的 JSON 整数带小数点，Codex 的解析器拒收为整数，于是已完成 `function_call` 参数里的整数浮点被改写（恰好 2^64 现在直接拒绝而不是静默改写差一）。Codex 多智能体模式注入的 `agent_message` 邮箱项 xAI 无法反序列化，每个子任务在任何工具运行前就 422，于是这些项被改写成普通 user 消息、加密内容压平为文本。xAI 对 Codex 的角色型号（如 `gpt-5.6-sol`）直接 404，于是未知的请求模型被映射到供应商配置的模型（catalog 里的 `grok-4.5` 一类与任何 `grok` 前缀 id 原样放行），且映射先于清洗执行，落到 grok-4.5 上的子智能体也会被剥掉不支持的采样字段。全部逻辑收在一个原生 Responses 闸门后的独立模块里，便于在上游覆盖同样场景之前 rebase 或 cherry-pick。grok-4.5 的 xAI 预设现在声明 low/medium/high/xhigh：2026-08-30 实测该端点接受这四档、对 `max` 报 HTTP 400，而 Codex 不会把目录外的档位夹回范围。（[#6917](https://github.com/farion1231/cc-switch/pull/6917)）

### 切换到 Grok OAuth 的 Codex 卡不再被拒绝

v3.20.1 的 config-only 切换重构把无密钥安全闸推广到所有写入路径，误伤了代理托管的 OAuth 卡（xAI Grok OAuth）：它们本来就无密钥——本地代理逐请求注入真实令牌——但预设快照继承了 0.149 之前模板的 `requires_openai_auth = true`，安全闸把它当作「会回落到官方登录」而拒绝切换。修的是快照而不是给闸门开例外：对代理注入的 OAuth 供应商（xAI OAuth 与 GitHub Copilot；Codex OAuth 刻意排除，官方登录*就是*它的凭据）在活跃自定义表上把该标志强制为 `false`，挂在共享的有效供应商构建器里，预检、普通写入与代理备份/接管投影看到同一形状，Codex 0.149 无需读 `auth.json` 即判定为未鉴权。预设源头现在就输出 `false`，存量卡在下一次切换时自愈。

### 接管不再把 Codex 困在登录屏

「非接管切换时保留官方登录」关闭（默认）时，直接切换到第三方供应商会删除 `~/.codex/auth.json`；此后再开启代理接管，`config.toml` 从存量卡重建，而卡上仍带 0.149 之前的 `requires_openai_auth = true`，于是 Codex ≥ 0.149 即使已有代理占位 bearer token 也停在登录屏——接管中执行 `codex logout` 后热切换也踩同一个坑。接管写入器现在按 Codex 自己会观察到的登录状态戳记活跃自定义表的标志，与直接切换的计划对齐：先按 Codex 的规则解析鉴权模式（显式 `auth_mode` 优先，其次个人访问令牌、Bedrock API 密钥、Bedrock 访问密钥、`OPENAI_API_KEY`、ChatGPT）再核对凭据，紧邻过期 API 密钥的 Bedrock 凭据永远不会被抬举为 OpenAI 登录；先判定凭据存储再碰 `auth.json`——keyring 与 auto 存储无法从磁盘判定、保留卡上原值，ephemeral 存储一律视为未登录，只有 file 存储才读文件，文件缺失、不可读或损坏都视为未登录且不再让接管写入失败。代理注入的 OAuth 卡无论磁盘上是什么都保持中和后的 `false`；官方透传与托管官方分支不动。

### 重复的托管 ChatGPT 账号会被拒绝

普通托管账号登录若 ChatGPT workspace _与_ 稳定用户身份（id_token 的 subject）同时匹配已有账号，会以本地化提示拒绝而不是新建第二行。检查在存储锁内执行，并发完成的登录无法漏进重复；刷新锁现在只在定向重鉴权时获取，被拒的添加不会留下锁条目。同一 workspace 的不同用户仍可并存。（[#7061](https://github.com/farion1231/cc-switch/pull/7061)）

### GPT-6 走 Codex OAuth 接管不再被拒为「需要更新 Codex」

Claude 转 Codex OAuth 路由上的 `gpt-6-astra` 请求自报 Codex 0.144.1，低于该模型 0.153.0 的最低客户端版本，ChatGPT 后端回 HTTP 400。自报版本升为 0.153.4，originator 与版本常量在生成与模型发现之间共享——后者此前发的是 cc-switch 自己的包版本与 originator。（[#7132](https://github.com/farion1231/cc-switch/pull/7132)，关联 [#7129](https://github.com/farion1231/cc-switch/issues/7129)）

### Claude Code 在 Codex OAuth 上恢复并行工具调用

来自 Anthropic 的请求没有显式给值时，Codex OAuth 请求把 `parallel_tool_calls` 默认为 false，迫使 Claude Code 每轮只能调用一个工具。默认改为 true（与 codex-rs 一致），Anthropic 的 `tool_choice.disable_parallel_tool_use` 映射为 Responses 侧的反值，显式串行仍被保留。接力自 [#5722](https://github.com/farion1231/cc-switch/pull/5722)。（[#7024](https://github.com/farion1231/cc-switch/pull/7024)，修复 [#5719](https://github.com/farion1231/cc-switch/issues/5719)）

### Codex 内置图片生成在路由下可用

Codex 的 ImageGen 工具调用旧版 OpenAI Images API，而本地代理只注册了 Responses、Chat Completions、Compact 与 Alpha Search 路由，`/v1/images/generations` 返回空 404。generations 的别名（裸路径、`/v1`、`/v1/v1`、`/codex/v1`）现在作为与 Alpha Search 共用的 Codex 独立透传转发，Alpha Search 的完整 URL 改写被泛化为从完整的 Responses/Compact/Chat URL 推导兄弟 Images URL（已有 Images URL 原样保留，不透明的完整 URL 关闭失败），响应里的输入/输出 token 经 Codex 用量解析器记账。后续一笔补上 `/images/edits`——ImageGen 一旦引用已有图片（显式路径或最近生成的 N 张）就切换到它，此前仍打到空路由；两条路由共享一张后缀表，把任一条配成完整 URL 的供应商都能推导出另一条。（[#7036](https://github.com/farion1231/cc-switch/pull/7036)，修复 [#5429](https://github.com/farion1231/cc-switch/issues/5429)、[#6745](https://github.com/farion1231/cc-switch/issues/6745)）

### 旧版 Codex 重新能加载 catalog

Codex 0.144.5 到 0.148.0-alpha.15 把 `supports_parallel_tool_calls` 声明为 catalog 必填字段，而上游 2026-08-14 已把它从模型信息里删除——新版刷新的 `models_cache.json` 没有该字段，从它克隆出的 ProxyChat catalog 被同机的旧版 Codex 以「missing field」拒载。该字段加入必填回填清单、从内置 gpt-5.5 模板取值（true）；已有值绝不覆盖，新版对多余键视而不见。用真实二进制验证：旧 catalog 被 0.147.0 与 0.148.0-alpha.15 拒绝，新 catalog 在两者与 0.148.0 上都能加载。（[#6666](https://github.com/farion1231/cc-switch/pull/6666)，修复 [#6661](https://github.com/farion1231/cc-switch/issues/6661)、[#6709](https://github.com/farion1231/cc-switch/issues/6709)）

### DeepSeek 原生预设下 MCP 工具重新可见

内置的官方 catalog 为 deepseek-v4-pro 与 deepseek-v4-flash 声明了 `supports_search_tool = true`，而 Codex 用这个标志决定是否把 MCP 工具延迟到 `tool_search` 之后——DeepSeek 的 Responses API 根本不提供 `tool_search`，于是所有 MCP 工具被藏起来、一个都调不到。两个模型现在声明 false，Codex 直接列出 MCP 工具；托管 web search 由供应商能力门控而不是这个标志，不受影响，DeepSeek 服务端的联网搜索也照常工作。（[#6653](https://github.com/farion1231/cc-switch/pull/6653)，修复 [#6647](https://github.com/farion1231/cc-switch/issues/6647)）

### DeepSeek 镜像 catalog 里的视觉型号不再被判纯文本

内置 DeepSeek catalog 里没有的型号会克隆旗舰条目、继承它的纯文本输入模态，`deepseek-v4-flash-vision-exp` 一类视觉型号因此失去图片输入。未匹配的型号现在与非厂商路径一样经注册表解析模态、失败即放行；用户显式设置的模态仍优先，匹配到的型号逐字保留厂商声明。另外 `glm-5.3` 加入已确认纯文本清单，其 `[1M]` 变体被识别、`glm-5.3v` 不受波及（[#6851](https://github.com/farion1231/cc-switch/pull/6851)）。（[#6750](https://github.com/farion1231/cc-switch/pull/6750)，修复 [#6725](https://github.com/farion1231/cc-switch/issues/6725)）

### Codex 桌面端经本地代理接 Kimi/Moonshot 不再因工具 schema 必现 400

Moonshot 的 Chat Completions 校验器（`api.moonshot.cn`、`api.moonshot.ai` 与 Kimi For Coding 端点 `api.kimi.com`）拒收带兄弟关键字的 `$ref`，而 Codex Desktop 的内置工具 schema 正是这种形状——经本地代理路由到 Kimi 的每一轮桌面请求都失败。解析出的上游域名是 Moonshot/Kimi 时，Responses 转 Chat 之后每个带兄弟键的 `$ref` 被移入 `allOf`、兄弟键留在原位；遍历只进入 schema 值的关键字，改写幂等。其他供应商的工具 schema 逐字节不变，Codex 转 Anthropic 路径不动——Moonshot 的 Anthropic 兼容端点接受原始形状。（[#6863](https://github.com/farion1231/cc-switch/pull/6863)，修复 [#6867](https://github.com/farion1231/cc-switch/issues/6867)）

### 智谱 GLM 的 Codex 预设改指官方 Responses 端点

智谱每个站点文档写明三个 Base URL——Anthropic `/api/anthropic`、Chat `/api/coding/paas/v4`、Responses `/api/v1`——并警告用错端点无法消耗 Coding Plan 额度；Codex 直连说的是 Responses，而 400 `unknown variant custom` 正来自 Chat 端点那个严格的旧网关。「Zhipu GLM」与「Zhipu GLM (en)」预设改为 `/api/v1` 上的原生 Responses（shell 命令式编辑、不发 freeform apply_patch），并镜像官方模型列表：glm-5.3（1M 窗口，low/high/max，默认 max），国内站另有 glm-5-turbo；glm-5.2 与 `none` 档被删。一条域名回退让「保存时还是 Chat 格式、但 Base URL 已是原生 Responses」的行无需重存即拿到 Responses catalog（Chat 端点路径排除在外）；厂商域名按 DNS 标签边界匹配，`z.ai` 不再误捕 `xyz.ai`；`bigmodel.cn`、`z.ai` 与 `glm` 前缀加入 Codex 托管 web search 的拒绝清单。（#6957，修复 [#6944](https://github.com/farion1231/cc-switch/issues/6944)）

### Codex resume 之后用量不再停摆

线程被回退（revert）时，Codex 会新建一个带两个 UUID 的替换 rollout 文件（`rollout-<ts>-<threadId>_<rolloutId>.jsonl`），此后该线程的每次 resume 都追加到它；文件的根元数据保留原线程 id，而导入器的一致性校验只拿它对比文件名末尾的 UUID——这类文件被永久搁置，用户 resume 该线程起用量就静默停止累计（现场复现：152 条未导入的 token 计数事件，搁置警告每 60 秒一轮重复）。校验现在也接受与双段文件名前置 UUID 匹配的元数据 id；单 UUID 文件名维持严格校验，从未回退过的普通会话从来不受影响。这类文件存入的会话 id 改为前置的逻辑线程 id——会话列表以它为键——而不是末尾的 rollout id；末尾 id 继续充当 request id 前缀，避免同一线程多个分段的去重键碰撞。（[#6905](https://github.com/farion1231/cc-switch/pull/6905)，修复 [#6904](https://github.com/farion1231/cc-switch/issues/6904)）

### 前缀缓存不再每轮被打断

Anthropic 转 OpenAI 的转换把所有 system 消息合并到对话开头，而 Claude Code 每轮都把 `<total_tokens>` 元数据作为一条中途 system 消息注入——合并让前缀每轮都变，上游的 radix 前缀缓存形同虚设。顶层 system 块仍合并为一条开头的 system 消息（跨轮字节稳定），消息列表里的 system 消息现在留在原位、不合并不重排。报告者在 DeepSeek、GLM、Kimi 一类 OpenAI 格式端点上实测，命中率曾因此从 99% 掉到 20%。（[#6941](https://github.com/farion1231/cc-switch/pull/6941)，修复 [#6789](https://github.com/farion1231/cc-switch/issues/6789)）

### Hermes「最新版本」改读 GitHub Releases

工具面板此前问的是 PyPI，而上游 0.19.0（2026-07-20）之后就停止在那里发布、只走 GitHub Releases——用户看到的「最新 0.19.0」永远不变、常常低于已装版本，升级按钮从不出现。PyPI 从来不是 cc-switch 安装或升级 Hermes 的渠道（官方安装脚本与 `hermes update` 都走 git），探测现在先查 GitHub Releases，仅在 GitHub 不可达或限流时回退 PyPI。语义化版本从发布名（`Hermes Agent v0.21.0 (v2026.8.31)`）解析，因为 tag 是日历版本；两条路径都拒绝日历数字，`2026.8.31` 永远不会被报成一个永久的「有更新」；本地版本已领先时隐藏 PyPI 回退值；两个探测都加 15 秒超时，不再沿用共享客户端的 600 秒——那曾在 `api.github.com` 挂起时卡住 Hermes 卡片与刷新/全部升级按钮。（关联 [#6475](https://github.com/farion1231/cc-switch/issues/6475)、[#6618](https://github.com/farion1231/cc-switch/issues/6618)、[#7033](https://github.com/farion1231/cc-switch/issues/7033)；取代 [#6621](https://github.com/farion1231/cc-switch/pull/6621)）

### 接管模式下 Claude Code 的模型菜单出现 Opus 5 与 Sonnet 5

接管写给 Claude Code 的稳定角色别名从 `claude-opus-4-8`/`claude-sonnet-4-6` 换成 `claude-opus-5`/`claude-sonnet-5`，与早已迁移的 Claude Desktop 默认路由和预设默认值对齐。`opus-5` 加入自适应思考分类器，在模型映射之前按客户端别名运行的 Bedrock 思考优化器继续发自适应思考而不是已被移除的 `budget_tokens`。路由不受影响——代理按角色关键字映射客户端别名——别名在代理下次启动时自动改写。（[#5882](https://github.com/farion1231/cc-switch/pull/5882)，修复 [#5876](https://github.com/farion1231/cc-switch/issues/5876)）

### PPIO、JieKou 与 Novita 的 Claude 预设能「获取模型」了

三家都在一个路径下提供 Anthropic 兼容 API、却把 OpenAI 兼容的模型列表挂在 `/openai/v1`，从 Base URL 推导的每个候选都 404，模型发现从未成功过。三张预设现在各钉一条显式的模型列表地址，表单在获取时按卡片的 Base URL 反查取用——仍在预设默认地址上的存量卡无需任何改动即生效；JieKou 一条把错误行为锁死的测试被删除。（[#6870](https://github.com/farion1231/cc-switch/pull/6870) 及后续）

### 杂项修复

- **Claude 会话列表不再出现幽灵「journal」会话**：Claude Code 的 workflow 功能把 `journal.jsonl` 写进会话目录，扫描器只排除了 `agent-*` 文件，每个 journal 都被解析成一条标题为「journal」的空会话。（[#6043](https://github.com/farion1231/cc-switch/pull/6043)，修复 [#6042](https://github.com/farion1231/cc-switch/issues/6042)）
- **检查更新失败时显示真实原因**：更新插件以纯字符串拒绝，`instanceof Error` 判断永远不成立，真正的失败原因（网络错误、限流、清单畸形）被通用兜底文案替换、还停在一个无人读取的状态里；恢复出的信息现在直达失败提示。（[#6482](https://github.com/farion1231/cc-switch/pull/6482)）
- **代理地址脱敏不再因多字节字符崩溃**：代理 URL 解析失败时的回退分支在第 20 字节硬切，多字节 UTF-8 字符跨过该偏移就 panic——往全局代理地址里粘一段中文即可触发；切点现在对齐字符边界。（[#6908](https://github.com/farion1231/cc-switch/pull/6908)）
- **Pi 的重复键错误与折叠标签显示文案而不是原始 key**：Pi 后端的重复键错误映射到的翻译键在四种语言里都不存在，思考映射折叠按钮的无障碍标签同样缺失；两者补齐 zh/en/ja/zh-TW 并由语言覆盖测试锁定。（[#6768](https://github.com/farion1231/cc-switch/pull/6768)）
- **屏幕阅读器能读出纯图标控件的名称**：仅图标的返回按钮、顶栏本地路由开关、项目切换弹层、Claude JSON 编辑器与已有 Skills 的导入复选框现在都带程序化名称，尽量复用既有文案，另加两条短标签。（[#7049](https://github.com/farion1231/cc-switch/pull/7049)，修复 [#7048](https://github.com/farion1231/cc-switch/issues/7048)）
- **用量趋势图 Token 轴改用本地化紧凑格式**：刻度此前固定为「数值/1000 加 k」，大数据日显示成 `1500k`；现在按语言环境的紧凑记法（`1.5M`）显示，轴宽相应调整。（[#7016](https://github.com/farion1231/cc-switch/pull/7016)）
- **定价来源下拉框放得下本地化文案**：用量成本设置表里的定价模型来源选择器只留约 70 px 给标签，英文与日文需要约 107 px；已加宽并与相邻输入框对齐高度。（[#6980](https://github.com/farion1231/cc-switch/pull/6980)）

---

## 升级提醒

### 本版不含数据库迁移

schema 版本保持 18，不产生迁移备份。

### 预设改动只影响新建的供应商

存量卡片保存的是创建时的快照。本版涉及：智谱 GLM 预设（存量智谱 Codex 卡仍指向 Chat 端点、直连依旧失败——重新导入预设即可拿到 `/api/v1`）、腾讯 Pi 预设的思考控制（重新导入才有真正生效的「off」与修正后的 Kimi 档位）、grok-4.5 的 xhigh 档、以及腾讯预设里 `minimax-m2.5` 的移除。PPIO、JieKou 与 Novita 的模型列表地址是例外：表单按卡片的 Base URL 反查预设，仍在默认地址上的存量卡无需改动。

### Codex catalog 类修复在下一次切换供应商时生效

catalog 文件在切换时重新生成：DeepSeek 的 MCP 可见性（[#6653](https://github.com/farion1231/cc-switch/pull/6653)）、`supports_parallel_tool_calls` 回填（[#6666](https://github.com/farion1231/cc-switch/pull/6666)）、视觉模态（[#6750](https://github.com/farion1231/cc-switch/pull/6750)）与 glm-5.3 纯文本条目（[#6851](https://github.com/farion1231/cc-switch/pull/6851)）都属此类。在受影响的卡上切走再切回一次即可。

### Codex OAuth 接管现在自报 Codex 0.153.4

无需配置。若你绕过 cc-switch 直接使用 Codex CLI，GPT-6 需要你本机的 Codex ≥ 0.153.0。

### 认证中心里已存在的 ChatGPT 账号不能再重复添加

同一用户、同一 workspace 再次添加会被拒绝，请改用该账号行上的「重新登录」。同一 workspace 的不同用户仍可并存。

### Grok OAuth 卡在下一次切换时自愈

`requires_openai_auth` 标志会被回填为 `false`，无需重新添加。

### 接管写入时 `requires_openai_auth` 按 Codex 的凭据存储覆盖

活跃第三方表上的该标志现在在每次接管写入时按 Codex 会观察到的登录状态覆盖：file 存储（默认）跟随 `auth.json` 是否持有官方登录；ephemeral 存储下 Codex 每次启动都是未登录，标志写为 `false`；keyring 与 auto 存储无法从磁盘读出登录状态，卡上原值保持不动。

### 被 resume 停摆的用量会在下一次扫描时补入

补入的条目按实际发生日期入账，那几天的看板总数可能跳升。回退过的线程从现在起会话 id 记录正确；此前按 rollout id 写入的行不做改写。

### 定价

Sonnet 5 的守卫只纠正仍是 seed 值 3/15/0.30/3.75 的行；自定义过的 Sonnet 5 行不动，历史 Sonnet 5 费用*不会*重算——费用在记录时冻结，回填只补按 $0 记录的行（Fable 5.1、GLM-5.3、GLM-5.3 Flash、GPT-6 Astra 与 Gemini 3.8 Flash 的历史因此*会*被补价）。MiniMax M2 系列新增此前为零的缓存写价格，这部分费用往后会上升。GPT-5.6 的促销价（至少到 2026-11-21）与 Gemini 3.6/3.8 Flash 的介绍价（到 2026-12-31，之后 $1.50/$7.50/$0.15）都有到期日，而定价表表达不了日期，后续版本会重新 seed。

### 经 Codex 路由的图片生成按 token 计数、暂无内置定价

图片模型还没有定价行，在补上之前其费用显示为 $0。

### Hermes 版本探测降级时显示「未知」

GitHub 不可达且 PyPI 回退值低于你已安装的版本时，显示「未知」而不是误导性的「最新 0.19.0」。

### 中途 system 消息现在原位转发

发往 OpenAI 格式上游的中途 system 消息不再被合并到开头，这正是前缀缓存命中恢复的原因，也与 Claude Code 原生发送的形状一致。两点连带影响：升级后第一轮请求的前缀字节会变化，缓存一次性重冷后即恢复；而要求 system 消息必须全部位于开头的严格后端（[#1881](https://github.com/farion1231/cc-switch/issues/1881) 里 Nvidia、Qwen 一类端点，报 `System message must be at the beginning`）在中途 system 消息出现时会重新 400——原来的合并逻辑正是为它们引入的，前缀稳定与严格后端校验在同一个全局行为里无法兼得。如果你的上游属于后者，请在 issue 里反馈。

---

## 风险提示

### 沿用的提示

**xAI Grok OAuth 登录**：复用官方 Grok CLI 的公开 OAuth 客户端身份，使用可能导致账号被限制或封禁——详见 [v3.18.0 release notes](https://github.com/farion1231/cc-switch/blob/v3.20.2/docs/release-notes/v3.18.0-zh.md#风险提示)。

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

**SuperGrok 配额查询**：供应商卡片的配额展示依赖 grok.com 的非公开计费端点，xAI 调整接口后可能失效——详见 [v3.19.0 release notes](https://github.com/farion1231/cc-switch/blob/v3.20.2/docs/release-notes/v3.19.0-zh.md#风险提示)。

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

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

---

## 致谢

本版 52 个提交里有 36 个来自 26 位外部贡献者。

### 代码贡献

- 感谢 @loocor：Grok 经 xAI 原生 Responses 的整条主线（[#6917](https://github.com/farion1231/cc-switch/pull/6917)）——工具 schema 折叠与整数浮点改写、`agent_message` 邮箱项改写、子智能体未知型号映射、闸门收敛与 CI 清理，六个提交。
- 感谢 @szupzj18：三条 Codex catalog 修复——DeepSeek 的 MCP 可见性（[#6653](https://github.com/farion1231/cc-switch/pull/6653)）、`supports_parallel_tool_calls` 回填（[#6666](https://github.com/farion1231/cc-switch/pull/6666)）与未知型号的输入模态（[#6750](https://github.com/farion1231/cc-switch/pull/6750)）；Moonshot `$ref` 兄弟键的修法他也更早在 [#6627](https://github.com/farion1231/cc-switch/pull/6627) 尝试过。
- 感谢 @yovinchen：GPT-6 Astra、GLM-5.3 Flash 与 Gemini 3.8 Flash 三条定价（[#7162](https://github.com/farion1231/cc-switch/pull/7162)、[#7163](https://github.com/farion1231/cc-switch/pull/7163)、[#7164](https://github.com/farion1231/cc-switch/pull/7164)）。
- 感谢 @thisTom：Codex 图片生成端点透传（[#7036](https://github.com/farion1231/cc-switch/pull/7036)）与用量趋势图的紧凑轴标签（[#7016](https://github.com/farion1231/cc-switch/pull/7016)）；同一透传 @Komikawayi 更早在 [#5484](https://github.com/farion1231/cc-switch/pull/5484) 提出过修法。
- 感谢 @zmq1121：腾讯云 Token Plan 六产品×六应用的预设（[#7011](https://github.com/farion1231/cc-switch/pull/7011)），端点与思考开关全部真实密钥实测。
- 感谢 @2691176649-cloud：Pi 的腾讯 TokenHub / Token Plan 八条预设与思考控制声明（[#7159](https://github.com/farion1231/cc-switch/pull/7159)）。
- 感谢 @SaladDay：重复托管账号的拒绝（[#7061](https://github.com/farion1231/cc-switch/pull/7061)），拆自他自己报告的 [#7055](https://github.com/farion1231/cc-switch/issues/7055)。
- 感谢 @RemindZ：Codex OAuth 客户端身份对齐 GPT-6（[#7132](https://github.com/farion1231/cc-switch/pull/7132)），首次投稿。
- 感谢 @liqimore 与 @li-keli：Codex OAuth 并行工具调用（[#7024](https://github.com/farion1231/cc-switch/pull/7024)，接力自 [#5722](https://github.com/farion1231/cc-switch/pull/5722)；@li-keli 同时是 [#5719](https://github.com/farion1231/cc-switch/issues/5719) 的报告者）。
- 感谢 @czhmartinez：Moonshot/Kimi 的 `$ref` 兄弟键改写（[#6863](https://github.com/farion1231/cc-switch/pull/6863)）；同一问题 @jacker-son（[#5125](https://github.com/farion1231/cc-switch/pull/5125)）与 loulanyue（#6869）也各自提出过修法。
- 感谢 loulanyue：智谱 GLM 预设改指官方 Responses 端点（#6957）。
- 感谢 @htyvista：中途 system 消息原位保留、前缀缓存修复（[#6941](https://github.com/farion1231/cc-switch/pull/6941)，修复 [#6789](https://github.com/farion1231/cc-switch/issues/6789)）。
- 感谢 @3351163616：Codex resume 后用量停摆的修复（[#6905](https://github.com/farion1231/cc-switch/pull/6905)），自报自修 [#6904](https://github.com/farion1231/cc-switch/issues/6904)。
- 感谢 @Eureka0w0v0：Fable 5.1 / Mythos 5.1 定价与 Sonnet 5 改回标准价（[#7051](https://github.com/farion1231/cc-switch/pull/7051)），自报自修 [#7050](https://github.com/farion1231/cc-switch/issues/7050)，首次投稿。
- 感谢 @nightcityblade：接管别名升级到 Opus 5 / Sonnet 5（[#5882](https://github.com/farion1231/cc-switch/pull/5882)）。
- 感谢 @hu-miao：PPIO 扩展到 Pi 与 Claude 预设的模型列表地址（[#6870](https://github.com/farion1231/cc-switch/pull/6870)），自报自修 [#6868](https://github.com/farion1231/cc-switch/issues/6868)。
- 感谢 @arichyx：GLM-5.3 定价（[#6591](https://github.com/farion1231/cc-switch/pull/6591)）。
- 感谢 @teddyli18000：glm-5.3 纯文本标记（[#6851](https://github.com/farion1231/cc-switch/pull/6851)），首次投稿。
- 感谢 @jintonglu6688：无障碍名称补齐（[#7049](https://github.com/farion1231/cc-switch/pull/7049)），自报自修 [#7048](https://github.com/farion1231/cc-switch/issues/7048)，首次投稿。
- 感谢 @SailingLoong：检查更新失败显示真实原因（[#6482](https://github.com/farion1231/cc-switch/pull/6482)），首次投稿；Hermes 版本源的问题也由他在 [#6621](https://github.com/farion1231/cc-switch/pull/6621) 率先提出修法。
- 感谢 @nasymonk：幽灵「journal」会话（[#6043](https://github.com/farion1231/cc-switch/pull/6043)），自报自修 [#6042](https://github.com/farion1231/cc-switch/issues/6042)。
- 感谢 @xu-kai-quan：代理地址脱敏的多字节 panic（[#6908](https://github.com/farion1231/cc-switch/pull/6908)）。
- 感谢 @ntdatt812：Pi 缺失的两条翻译键（[#6768](https://github.com/farion1231/cc-switch/pull/6768)）。
- 感谢 @Chang-Yo：定价来源下拉框宽度（[#6980](https://github.com/farion1231/cc-switch/pull/6980)）。
- 感谢 @wanwan-doudou：测试隔离 `LOCALAPPDATA`（[#6078](https://github.com/farion1231/cc-switch/pull/6078)），自报自修 [#6077](https://github.com/farion1231/cc-switch/issues/6077)。
- 感谢 @why19970628：README 目录树的翻译路径修正（[#6100](https://github.com/farion1231/cc-switch/pull/6100)）。

### 问题反馈

- 感谢 @elizax 在 [#6789](https://github.com/farion1231/cc-switch/issues/6789) 用实测数据（命中率 99% → 20%）定位到中途 system 消息被合并——本版前缀缓存修复的起点。
- 感谢 @jonneyz：xAI 拒收根级 `oneOf`/`anyOf` 工具 schema（[#6815](https://github.com/farion1231/cc-switch/issues/6815)）与 Moonshot `$ref` 兄弟键 400（[#6867](https://github.com/farion1231/cc-switch/issues/6867)）两份精确到字段的报告。
- 感谢 Moonshot 工具 schema 400 家族的其他报告者：@Cinnamanthus（[#6614](https://github.com/farion1231/cc-switch/issues/6614)，附已验证的修法）、@IchenDEV（[#6834](https://github.com/farion1231/cc-switch/issues/6834)）、@ghostman-git（[#6861](https://github.com/farion1231/cc-switch/issues/6861)）、@dolami0（[#6976](https://github.com/farion1231/cc-switch/issues/6976)）、@RN0817（[#7000](https://github.com/farion1231/cc-switch/issues/7000)）与 @Lw2xy（[#7028](https://github.com/farion1231/cc-switch/issues/7028)）。
- 感谢 @loveyang2012 报告智谱 Codex 直连的 `unknown variant custom`（[#6944](https://github.com/farion1231/cc-switch/issues/6944)）。
- 感谢 @vdiskg 报告 DeepSeek 预设下 MCP 工具不可用（[#6647](https://github.com/farion1231/cc-switch/issues/6647)），以及在评论里给出源码级根因与已验证修法的 @wqzhellohhwy。
- 感谢 @OhtoAi583 与 @dydydd 报告 catalog 缺 `supports_parallel_tool_calls`（[#6661](https://github.com/farion1231/cc-switch/issues/6661)、[#6709](https://github.com/farion1231/cc-switch/issues/6709)）；@dydydd 还在 [#6710](https://github.com/farion1231/cc-switch/pull/6710) 提交了同样的修法，@zmzwynzj 在 #6661 补充了 Windows 复现、证明问题不限于 Kimi 或 macOS。
- 感谢 @deadman49 报告 DeepSeek 视觉型号无法读图（[#6725](https://github.com/farion1231/cc-switch/issues/6725)）。
- 感谢 @zhou0722jack 报告 GPT-6 无法使用（[#7129](https://github.com/farion1231/cc-switch/issues/7129)），以及在同一 issue 里贴出 400 原文并验证修复的 @AiIsBetter。
- 感谢 @Hewitt-Qiao 与 @JerryChen001 报告本地路由下图片生成 404（[#5429](https://github.com/farion1231/cc-switch/issues/5429)、[#6745](https://github.com/farion1231/cc-switch/issues/6745)）。
- 感谢 @SHIZHENGYE 报告接管下无法选到 Opus 5（[#5876](https://github.com/farion1231/cc-switch/issues/5876)）。
- 感谢 @matthewdm0816 与 @lagolas 在 [#6904](https://github.com/farion1231/cc-switch/issues/6904) 同报 resume 后用量停摆——前者「切到 1M 上下文后 resume」是同一根因的另一形态。
- 感谢 @FlyinheartLee、@t5yhuangxing 与 @Tsuki-hash 报告 Hermes 最新版本停在 0.19.0（[#6475](https://github.com/farion1231/cc-switch/issues/6475)、[#6618](https://github.com/farion1231/cc-switch/issues/6618)、[#7033](https://github.com/farion1231/cc-switch/issues/7033)）。
- 感谢 @QianWen-AI-Platform 提出 QwenCloud 预设需求（[#6214](https://github.com/farion1231/cc-switch/issues/6214)）。

---

## 下载与安装

访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本，或从官网 [ccswitch.io](https://ccswitch.io) 获取（下载经 Cloudflare 边缘节点分发，不依赖 GitHub 可达）。

### 系统要求

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

### Windows

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

Windows ARM64 设备请选择文件名中带 `arm64` 标识的对应制品。

### macOS

| 文件                             | 说明                                          |
| -------------------------------- | --------------------------------------------- |
| `CC-Switch-v3.20.2-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
| `CC-Switch-v3.20.2-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
| `CC-Switch-v3.20.2-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.20.2-Linux-x86_64.AppImage` / `.deb` / `.rpm`
- `CC-Switch-v3.20.2-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`              |