v3.20.0

# CC Switch v3.20.0

> 这一版由三条结构性主线撑起：**Pi 成为第九个受管应用**——供应商、提示词、Skills、会话浏览与用量统计一站接入；**Codex 支持多个 ChatGPT 账号**——认证中心随便登几个，每张官方卡各绑各的，切换永不串账；**Claude Code 内置 WebSearch 在 GPT 路由下终于可用**。紧急修复也有一条：v3.19.2 在 WSL 路径上已有配置无法更新或切换，受影响用户请直接升级本版。同一批 Windows 修复还包括版本检测大修（五个 issue 一次修）、启动闪屏与 MSI 注册表垃圾键。本版**包含数据库迁移（v16 → v17）**，升级前自动备份，降级需还原备份。

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

---

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

- **用 CC Switch 管理 Pi**：第九个受管应用（[#6064](https://github.com/farion1231/cc-switch/pull/6064)）。供应商表单是针对 Pi 原生 schema 的结构化编辑器，内置 58 个预设与 57 个模型的能力目录；提示词库、`SYSTEM.md` / `APPEND_SYSTEM.md` 编辑器、斜杠命令模板、Skills、会话浏览与安装升级一并接入。Pi 自己的登录、默认供应商与默认模型**永远不被触碰**。首启会导入 `models.json` 里已有的供应商，见[升级提醒](#pi-首次启动会导入既有供应商并回填历史用量)。
- **在看板里看到 Pi 的会话用量**：逐模型的 token、成本、错误与中断轮次，独立的「Pi (Session)」来源与应用筛选；增量同步只解析文件新增部分（[#6463](https://github.com/farion1231/cc-switch/pull/6463)）。
- **添加 Codex 官方供应商时直接选择已授权的 ChatGPT 账号**：认证中心登录任意多个账号，新建官方卡时下拉直选其一完成绑定；也可以照旧添加一张不绑定的空官方卡，跟随 Codex CLI 本地登录、读取本地的 access token。切换到绑定卡会写入该账号完整的令牌包——裸 `codex` CLI 也以该账号运行、且能自行续期。接管下的请求会校验账号一致性，绝不静默把账单记到另一个账号头上（[#3879](https://github.com/farion1231/cc-switch/pull/3879)、[#6535](https://github.com/farion1231/cc-switch/pull/6535)）。
- **在 GPT 路由下使用 Claude Code 的内置 WebSearch**：搜索在上游执行、结果带引用返回、次数进用量；Codex 新客户端的 Alpha Search 端点也不再 404（[#5681](https://github.com/farion1231/cc-switch/pull/5681)）。
- **从 v3.19.2 的 WSL 故障中脱困**：v3.19.2 在 `\\wsl.localhost` 路径上无法更新或切换已有配置（[#6188](https://github.com/farion1231/cc-switch/issues/6188)），该版本内无任何绕过手段——请直接升级本版，并且 CI 从此在真实 WSL2 文件系统上跑测试（[#6233](https://github.com/farion1231/cc-switch/pull/6233)）。
- **让 Windows 版本检测和你的终端看到的一致**：检测改为合并注册表 PATH（用户+机器）、扫描独立安装器目录、优先探测 PATH 默认项——应用内自更新后「未安装」、winget 装的 Claude Code 找不到、旧 npm shim 遮住新版本，五个 issue 一网打尽（[#6284](https://github.com/farion1231/cc-switch/pull/6284)）。
- **给每个模型声明它真实支持的思考档位**：Codex 模型目录支持逐模型多选八个标准档位并指定默认值，各家预设按厂商文档预填了真实档位（[#6228](https://github.com/farion1231/cc-switch/pull/6228)）。
- **信任你的备份**：SQL 备份逐值保真往返、截断文件导入前即被拒绝（[#6146](https://github.com/farion1231/cc-switch/pull/6146)）；备份文件原子发布、恢复先在暂存库整体校验、`.db` 恢复会把各应用 live 配置一并重建，所有同步/恢复路径严格串行（[#6147](https://github.com/farion1231/cc-switch/pull/6147)）。
- **在几百个模型里直接搜**：所有应用的模型下拉都换成了可输入过滤的组合框，按模型 id 和厂商名都能匹配（[#6285](https://github.com/farion1231/cc-switch/pull/6285)）。
- **启动不再白/黑闪屏**：主题在页面绘制前同步应用，Windows 上窗口加载完成前保持隐藏（[#6252](https://github.com/farion1231/cc-switch/pull/6252)）。

---

## 使用攻略

本版改动集中在供应商管理与用量统计上，建议结合以下文档了解：

- **[添加供应商](https://github.com/farion1231/cc-switch/blob/v3.20.0/docs/user-manual/zh/2-providers/2.1-add.md)**：Pi 与新预设的入口。
- **[用量统计](https://github.com/farion1231/cc-switch/blob/v3.20.0/docs/user-manual/zh/4-proxy/4.4-usage.md)**：Pi 会话用量的来源与口径，以及 DeepSeek 调价对读数的影响。
- **[请求路由](https://github.com/farion1231/cc-switch/blob/v3.20.0/docs/user-manual/zh/4-proxy/4.2-routing.md)**：WebSearch 桥接生效的路由场景。

---

> [!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.20.0 横跨了几乎每个子系统，主线有三条。第一条是接入面扩张：Pi 成为第九个受管应用，从供应商编辑到会话用量全链路接入，并带来本版唯一的数据库迁移（v16 → v17，Pi 用量去重账本）；Codex 侧则补上了呼声已久的多 ChatGPT 账号管理，官方卡从此可以逐卡绑定账号，且刻意退出自动故障转移——重试永远不会把账单记到另一个账号。第二条是代理能力：Claude Code 内置 WebSearch 桥接到 OpenAI Responses 与 Codex OAuth 后端，Codex 的 Alpha Search 端点注册为语义透传，「GPT 路由下没有网页搜索」成为历史。

第三条是把 Windows 与数据可靠性欠的账还上：v3.19.2 的 WSL 写入回归热修（并新增真实 WSL2 CI 覆盖）、版本检测按注册表 PATH 大修、启动闪屏消除、MSI 自 v3.4.0 起写入的垃圾注册表键修正；备份/同步经外部贡献者审计后两波加固——SQL 逐值保真、原子发布、暂存校验、严格串行。此外还有 Codex 思考档位体系的整轮梳理（逐模型档位＋各厂真实档位预填＋聚合平台方言修正）、一轮供应商表单一致性打磨、macOS 中日文输入法修复，以及 DeepSeek V4 按厂商新牌价重定价。

**发布日期**：2026-08-18

**更新规模**：69 commits | 284 files changed | +53,108 / -6,678 lines

---

## 新功能

### Pi 成为第九个受管应用

Pi 以累加模式接入（与 OpenCode、Hermes 同类）：供应商的启用与否等于其键是否存在于 `~/.pi/agent/models.json`，多个供应商共存。供应商表单是针对 Pi 原生 schema 的结构化编辑器——API 格式、逐模型的思考等级映射（Pi 的七个等级）、兼容键——内置 58 个预设（覆盖表单五种 API 格式中的四种）与一份人工复核过的 57 模型能力目录；原始 JSON 编辑器与「拉取模型」按钮兜底，既有节点里的未知字段原样保留。每次读改写都有内容版本校验，别的进程改过的文件会以冲突报错拒绝、绝不覆盖。

边界刻意划清并写进文档：CC Switch **绝不**把 Pi 的内置供应商物化进 models.json、**绝不**读写 Pi 的 `auth.json`、**绝不**碰 `defaultProvider` / `defaultModel`——Pi 自己的登录与模型选择归 Pi。供应商之外：提示词库把选中的一条写入 Pi 全局 `AGENTS.md`（已有的不匹配内容先自动备份成库条目）、`SYSTEM.md`（替换 Pi 基础提示词）与 `APPEND_SYSTEM.md` 各有专属编辑器、`~/.pi/agent/prompts/*.md` 斜杠命令模板管理、Skills 按「存在即启用」规则接入（同名但非 CC Switch 所有的 Skill 拒绝覆盖或删除）、JSONL 会话浏览器，以及设置 → 关于里的 Pi 安装与升级。Pi 没有原生 MCP 注册表，因此刻意不参与 MCP 同步；也没有代理接管、故障转移与托盘存在——代理与故障转移命令现在对所有无本地网关的应用显式拒绝，而不是写下一堆死配置。（[#6064](https://github.com/farion1231/cc-switch/pull/6064)）

### Pi 会话用量进入看板

新导入器读取 Pi 的会话文件，在独立的「Pi (Session)」来源下逐模型记录 token、成本、错误与中断轮次，带专属应用筛选。Pi 每条记录自带成本，为正时优先采用；缺失或全零则回退 CC Switch 的价格表。增量同步对每个文件的尾部做指纹，只解析新追加的字节；被改写或分叉的会话通过新的持久去重账本识别——`session_usage_dedup` 表，本版 v16 → v17 迁移的由来——该账本在明细行清理后仍存活，且保持设备本地（云同步排除、导入保留）。由于一个 Pi 会话可能混用 Anthropic 系与 OpenAI 系 API，含 Pi 的汇总带「缓存写不完整」的口径标注而非一个未加限定的数字。（[#6463](https://github.com/farion1231/cc-switch/pull/6463)）

### Codex：多个 ChatGPT 账号，逐卡绑定

认证中心可以持有任意数量的 ChatGPT（Codex OAuth）登录。**添加 Codex 官方供应商时，直接从已 OAuth 授权的账号里选一个完成绑定**——不必先建卡再回头配置；也可以沿用旧方式添加一张不绑定账号的空官方卡，它跟随 Codex CLI 自己的登录、读取本地的 access token。官方卡数量不限，两种方式的卡可以共存，绑定与解绑保留卡的身份、端点与健康历史。切换到绑定卡会把该账号**完整的令牌包**写入 `~/.codex/auth.json`——裸 `codex` CLI 也以该账号运行，且能在访问令牌过期后自行续期；CLI 轮转过的刷新令牌会在每次写入前被回采，重复切换绝不会用旧登录盖掉新登录。

账号选择器是带标签的下拉框，可直接跳转认证中心；账号状态**加载失败**时显示带重试的警告而不再冒充「未登录」，也不再在下次保存时静默解绑。登出与移除账号和供应商切换严格互斥；OAuth 请求超时从十分钟收紧到 30 秒；登出还会取消仍在网络往返中的设备登录——被放弃的登录流程无法再在后台悄悄完成并复活账号（[#6506](https://github.com/farion1231/cc-switch/pull/6506)）。接管下的请求会对照绑定账号校验：仍以另一个 ChatGPT 账号认证的 Codex 会话会得到「请重启 Codex」的明确报错，而不是静默把账单记到错误账号。（[#3879](https://github.com/farion1231/cc-switch/pull/3879)、[#6535](https://github.com/farion1231/cc-switch/pull/6535)、[#6506](https://github.com/farion1231/cc-switch/pull/6506)）

### Codex 模型目录：逐模型思考档位

Codex 供应商表单里的每个模型行现在可以声明其上游真实接受的思考档位——在八个标准档位（none 到 ultra）上多选，外加可选的默认档——生成的目录把它们带进 Codex 的选择器，不再继承基础模板的档位。未知值会被丢弃（笔误永远到不了 Codex），显式默认值会对照声明集校验，覆盖在原生 Responses 与 Chat 转换两条路径上都生效。代理转换层同时学会了 `ultra`：此前在路由供应商上选最深档会静默关闭扩展思考（Anthropic 路径）或丢掉 effort 参数，现在映射到上游合法的最深档。（[#6228](https://github.com/farion1231/cc-switch/pull/6228)、[#6181](https://github.com/farion1231/cc-switch/issues/6181)）

### 各厂预设按官方文档预填真实思考档位

预设现在带上各厂商实际文档化的档位——火山方舟 low/medium/high、DouBaoSeed minimal 到 high、混元 low/high、DeepSeek low/high/max、xAI Grok low/medium/high（无 none：思考关不掉）、智谱 GLM none/high 等——新建供应商的 Codex 选择器从此以事实起步；对智谱 GLM 来说，「关闭思考」终于能在 Codex 里选到。两个 Kimi 预设按 Moonshot 自家接入指南启用推理强度（顶层 `reasoning_effort`，只列网关接受的档位），Kimi For Coding 从一个模型扩到四个官方模型。百度千帆 Coding Plan 预设用平台文档化的 `thinking` 对象获得真实的思考开关。档位一律出自厂商文档或厂商自己的 Codex 目录，并收窄到真正行为有别的档——完全没有依据的模型保持不填。

### Claude Code WebSearch 与 Codex Alpha Search 走通本地代理

两条此前在代理上走死胡同的网页搜索路径打通了。Claude Code 内置 WebSearch 工具桥接到 OpenAI Responses 与 Codex OAuth 后端：搜索在上游执行，结果以成对的 Anthropic 搜索块返回、引用保留并合并、搜索次数计入用量。`max_uses` 在 Responses API 支持处用 `max_tool_calls` 原生限额；Codex OAuth 后端拒绝该参数，仅在请求强制使用该工具时以流中截断本地限额，未强制却带 `max_uses` 的请求显式报错。Responses API 无法表达的约束（`blocked_domains`、非直连调用方、`response_inclusion`、未知工具版本）同样显式报错，绝不悄悄放宽搜索范围。桥接只覆盖 Responses 转换路径——Chat Completions 上游仍不支持托管 WebSearch。另外，Codex 独立的 Alpha Search 端点注册为语义透传，带完整的供应商选择、鉴权、模型映射、重试与日志流水线，新版 Codex 客户端的 404 就此终结。Claude-in-Codex 路由攻略已三语更新：「GPT 路由下没有网页搜索」在这些路径上不再成立。（[#5681](https://github.com/farion1231/cc-switch/pull/5681)、[#5363](https://github.com/farion1231/cc-switch/issues/5363)、[#5378](https://github.com/farion1231/cc-switch/issues/5378)）

### 百度千帆 Token Plan 预设

千帆 Token Plan（个人版）——2026 年 7 月起替代 Coding Plan 面向新购用户——获得 Claude Code、Claude Desktop、Codex、OpenCode、OpenClaw 与 Hermes 六个应用的预设，走 `/tokenplan/personal` 端点。Codex 预设带六模型目录（DeepSeek V4 Pro / V4 Flash / V4 Flash 0731、GLM 5.2/5.1、Kimi K2.6），是首个思考开关与推理强度选择器都真实可用的千帆预设。密钥必须用 Token Plan 订阅的专属 key，而不是通用的千帆应用 key；老的 Coding Plan 预设为存量订阅保留。

### 模型选择器全面支持模糊搜索

供应商表单里所有「选模型」下拉——Claude Code（含 Copilot）、Claude Desktop 映射行、Codex、Gemini CLI、OpenCode、Hermes、OpenClaw 与 Pi——都换成了可输入过滤的组合框，按模型 id 和厂商名都能匹配，顺手把四份内联重复组件合而为一。对着返回几百个模型的供应商尤其好用。（[#6285](https://github.com/farion1231/cc-switch/pull/6285)、[#6353](https://github.com/farion1231/cc-switch/pull/6353)）

### 其他新增

- **接管开启确认动画**：为当前应用打开路由接管时头部品牌区播放一次性彩带——应用启动、切换应用或系统偏好「减少动态效果」时绝不触发。同一改动补上一个真实缺口：接管开关在初始代理状态加载完成前置灰，对未知状态的点击不再可能把接管拨错方向。（[#6209](https://github.com/farion1231/cc-switch/pull/6209)）
- **Codex 表单 1M 上下文开关回归**：上游 Codex 重新接受 `model_context_window = 1000000`，四月隐藏的开关（连同配套的自动压缩阈值输入）回来了，写的还是原来那两个 config.toml 字段。
- **新预设**：PPIO（厂商贡献）、JieKou AI（厂商贡献）、XycAi（合作伙伴）分别接入各自支持的应用。（[#6239](https://github.com/farion1231/cc-switch/pull/6239)、[#6356](https://github.com/farion1231/cc-switch/pull/6356)）

---

## 变更

### Codex 官方账号卡退出自动故障转移

官方 ChatGPT 卡不再被加入、列出或经由故障转移队列重试，官方路由上的所有错误类别一律不可重试——对着另一个供应商重试会把入站的 ChatGPT 授权用到别的账号头上。内置官方卡的存量队列行在读取时过滤。官方卡判定也不再只看类别标签：存了真实 API key 或显式第三方上游的卡按普通供应商对待，保留直连路径与故障转移资格。（[#3879](https://github.com/farion1231/cc-switch/pull/3879)、[#6535](https://github.com/farion1231/cc-switch/pull/6535)）

### Codex OAuth 配额显示逐卡可配置

绑定 ChatGPT 账号的卡获得与脚本类供应商相同的「配置用量查询」入口：配额页脚可以关闭、刷新间隔可改（此前硬编码五分钟且没有关闭开关），对话框的测试按钮查询的是**绑定的账号**而不是 CLI 恰好登录的账号，托盘也不再给账号绑定卡装饰全局订阅百分比。（[#6537](https://github.com/farion1231/cc-switch/pull/6537)）

### OpenCode Go 改为直连

OpenCode Go 网关原生提供 Anthropic Messages，但其 `/v1/messages` 只认 `x-api-key`、静默忽略 Bearer 头——Claude Code 预设改为把密钥存进 `ANTHROPIC_API_KEY` 并去掉 Chat 格式声明，Claude Code 直连网关，不再需要路由接管、不再显示「需要路由」徽章。Claude Desktop 依设计保持代理模式（它自己不能改模型名），但代理现在透传 Anthropic Messages 而不是转成 OpenAI Chat。Codex 侧预设还把 DeepSeek V4 系模型的上下文窗口填到 1,048,576，Codex 不再围着 128K 回退值自动压缩。（[#6171](https://github.com/farion1231/cc-switch/issues/6171)、[#6196](https://github.com/farion1231/cc-switch/pull/6196)）

### 供应商表单一致性打磨

一轮贡献者主导的全应用供应商对话框对齐：Grok Build 与 Claude Desktop 表单搬上与其他应用相同的玻璃卡片；子分区共享同一套左规线层级；空配置编辑器收缩到三行而不是空占 6–14 行；Hermes 与 OpenClaw 的模型编辑器改为可展开详情的紧凑行并补上无障碍标签（展开状态改用稳定行键，删除模型不再让错误的行保持展开）；复选框统一为一个原生组件；Claude 表单的「API 格式」改名「上游格式」并逐选项说明哪些格式需要路由接管。另外，主面板供应商卡片上的合作伙伴星标已移除——合作伙伴标识只保留在预设选择器里。（[#6198](https://github.com/farion1231/cc-switch/pull/6198)–[#6201](https://github.com/farion1231/cc-switch/pull/6201)、[#6203](https://github.com/farion1231/cc-switch/pull/6203)–[#6208](https://github.com/farion1231/cc-switch/pull/6208)）

### Claude Desktop：连接模式改为下拉选择、两套模型列表互不覆盖

直连与模型映射改为带标签的下拉选择而不是开关；来回切换时各模式保留自己的模型行；直连模式的模型列表常驻显示、不再藏在「高级」折叠里；选择直连预设会预填其模型列表而不是丢弃。（[#6208](https://github.com/farion1231/cc-switch/pull/6208)）

### Grok Build 表单重建在 Codex 布局上

Grok Build 供应商对话框现在渲染与 Codex 共享的字段集——端点、密钥、默认模型、含上游格式/思考/User-Agent 的高级区——文案全程 Grok 化（一个 follow-up 抓住了对齐时漏进来的五处 Codex 措辞）。独立的「API Backend」与「客户端模型档案」输入框移除：客户端一律讲 Responses——Chat 或 Anthropic 上游需要转换时对着本地代理、否则直连上游——上游协议经高级 → 上游格式表达；经表单保存会把存储配置的 `api_backend` 钉为 `responses`，当前供应商立即写入 live 配置、其余供应商在下次切换时生效——见升级提醒。（[#6427](https://github.com/farion1231/cc-switch/pull/6427)、[#6511](https://github.com/farion1231/cc-switch/pull/6511)）

### Kimi 上游改为干净透传

应 Moonshot 方面要求，代理不再向 Kimi/Moonshot 端点的工具调用历史注入占位思考块、也不再发出非标准的 `reasoning_content` 字段——其网关已不再要求思考回放，注入的占位符反而扰乱模型思维链。Kimi 路由上的工具调用历史原样转发（代理流水线其余部分不变），对存量供应商立即生效。DeepSeek 与 MiMo 保留该行为——那是文档明载的服务端要求。

### DeepSeek V4 按新峰值档牌价重定价、Gemini 3.7 Flash 播种

DeepSeek 于 2026-08-16 引入峰谷计价并大幅上调：`deepseek-v4-flash`（及其 `-0731`、`deepseek-chat`、`deepseek-reasoner` 别名）的内置价从每百万 token 输入/输出 $0.14/$0.28 调至 **$0.44/$1.32**、缓存读取 $0.014；`deepseek-v4-pro` 从 $0.435/$0.87 调至 **$1.32/$3.96**、缓存读取 $0.044。价格表没有时段维度，**刻意录入峰值档**——高峰时段（北京 9:00–12:00、14:00–18:00）与工作时间重合；一天中其余十七个小时的用量读数因此约为实际账单的两倍。守护式修复会迁移仍持有旧内置价的数据库；你自己改过的价格绝不触碰。`gemini-3.7-flash` 按介绍价 $0.75/$3.75（缓存读取 $0.075）播种，2027 年起恢复牌价；`gemini-3.6-flash` 未调整——它没有拿到促销价。

### 其他变更

- **BytePlus 预设切换到原生 Responses**：BytePlus 自家 Codex 指南在预设所用端点上配置 `wire_api = "responses"`，预设遂与境内的火山兄弟预设一致声明原生 Responses，并预填文档化的 low/medium/high 档位。
- **Codex 表单移除 Goal 模式开关**：codex-cli 0.147.0 起默认启用 goals，开关已具误导性——取消勾选会删掉配置行、进而回落为开启，界面显示关闭而功能仍在。现在无需任何配置；你此前写下的 `goals = true` 留在 config.toml 里，无副作用。
- **项目 Profile 变更触发自动同步**：WebDAV/S3 自动同步的触发表从未加入 `profiles` 表，Profile 编辑只有蹭到其他表变更才会上云；两份传输各自的触发表合并为一份共享清单并纳入 profiles。（[#6147](https://github.com/farion1231/cc-switch/pull/6147)）
- **合作伙伴清单维护**：RunAPI 预设迁移到其新域名 `runapi.host`（预设类型支持处保留旧域名作后备端点）；PPIO 列为项目赞助商。

---

## 修复

### Windows：WSL 路径上无法更新配置（v3.19.2 回归）

v3.19.2 把 Windows 原子写切换到 `ReplaceFileW`，而 WSL 文件系统以 `ERROR_NOT_SUPPORTED` (50) 拒绝它——rename 回退只在 NotFound 时触发，于是 `\\wsl.localhost` / `\\wsl$` 路径上任何替换已有 live 配置的写入都直接失败：存量供应商无法更新或切换（只有配置文件的首次创建——缺失目标本就触发回退——仍然可用）。错误 50 现在落入 WSL 接受的 rename 路径。仅 v3.19.2 受影响；该版本内无任何绕过手段，受影响用户请直接升级。（[#6232](https://github.com/farion1231/cc-switch/pull/6232)、[#6224](https://github.com/farion1231/cc-switch/issues/6224)、[#6219](https://github.com/farion1231/cc-switch/issues/6219)、[#6188](https://github.com/farion1231/cc-switch/issues/6188)、[#6247](https://github.com/farion1231/cc-switch/issues/6247)）

### Windows：CLI 检测终于和终端看到的一致

版本检测此前依赖继承的进程 PATH 加一份硬编码目录清单——且探测顺序还是错的。三种可见故障、各有一个成因：应用内自更新后重启的进程只继承机器 PATH、丢掉用户 PATH，用户安装的 CLI 显示「未安装」，直到从开始菜单完整重启（[#6061](https://github.com/farion1231/cc-switch/issues/6061)）；winget 装的 Claude Code、独立安装器装的 Codex 与自定义 npm prefix 的目录从未被扫描（[#6278](https://github.com/farion1231/cc-switch/issues/6278)、[#6047](https://github.com/farion1231/cc-switch/issues/6047)、[#4366](https://github.com/farion1231/cc-switch/issues/4366)）；硬编码目录先于 PATH 默认项探测，过期的 `%APPDATA%\npm` shim 遮住 PATH 上实际更新的安装——「更新了但还显示旧版本」（[#4701](https://github.com/farion1231/cc-switch/pull/4701)）。检测现在把注册表 PATH（用户+机器，展开 `%VAR%`）合并进有效搜索路径，扫描独立安装器目录，经显式的 `where.exe` 调用优先探测 PATH 默认项（跳过 Microsoft Store 应用别名、绝不搜索当前目录），并把同一份合并 PATH 喂给安装冲突诊断与锚定升级。（[#6284](https://github.com/farion1231/cc-switch/pull/6284)）

### 启动不再白/黑闪屏

窗口在主题类应用之前就被显示，未着色的页面先画了一帧。内联的预绘制脚本现在在包加载前同步应用持久化主题（全平台），Windows 上窗口还会保持隐藏直到页面加载完成。（[#6252](https://github.com/farion1231/cc-switch/pull/6252)、[#6182](https://github.com/farion1231/cc-switch/issues/6182)）

### Windows 安装包不再写入垃圾注册表键

WiX 模板里的 `Software\{{manufacturer}}\{{product_name}}` 用了单反斜杠，被 Handlebars 当作转义序列吞掉——自 v3.4.0 起每个 MSI 都在创建字面量的 `HKCU\Software{{manufacturer}}{{product_name}}` 键而不是预期路径。两处反斜杠已加倍，与模板里其他键对齐。已装机器上的存量垃圾键不会被清理——见升级提醒。（[#6283](https://github.com/farion1231/cc-switch/issues/6283)）

### 代理接管恢复不再抹掉官方 ChatGPT 登录

接管的恢复备份是接管开始时的快照；如果你在接管期间跑过 `codex login`，每次恢复——停止接管、退出应用、崩溃恢复——都会用登录前的快照盖掉新登录，启动时的自动重接管还让这次抹除每次重启都重演。恢复现在会仲裁：live 登录材料永远胜出（只有 Codex 自己能推进它，必然比快照新），备份里的第三方 API key 降级写进 config.toml 保留而不是砸掉 auth.json。被早期版本毁掉的登录不会被恢复——跑一次 `codex login` 即可。（[#6277](https://github.com/farion1231/cc-switch/issues/6277)）

### 环境检查不再在「全部升级」或冲突诊断时挂死

v3.19.2 携带的一次重构把 PATH 探测的登录 shell 放进仍持有控制终端的后台进程组：从终端启动的实例上，作业控制以 SIGTTIN 停住 shell、无限期的等待永不返回——整个预检冻结。即便在不可能发生这种情况的场景（正常启动的构建没有控制终端），该路径也完全没有超时，Windows 亦然——一个挂住的探测（阻塞的 `.zshrc`、不退出的 `--version`）同样冻结整轮检查。探测现在跑在完全分离的会话里、stdin 置空、10 秒硬超时并杀掉整棵进程树；丢失的探测只降级该工具的报告而不是挂死整轮，按钮在探测阶段显示加载指示而不是看似无视点击。（[#5522](https://github.com/farion1231/cc-switch/pull/5522) 的回归）

### macOS 输入法不再打乱供应商表单

使用中文/日文输入法快速输入时，供应商表单字段会间歇性地重复与乱序——报告中的复现里 12 个字符膨胀到 1,396 个。受控输入在输入法仍持有组字区间时把父状态写回 DOM，供应商键字段甚至对每个组字中间态都跑小写化清洗。共享的 IME 安全输入组件现在把组字文本留在本地直到提交、只对成品文本做归一化、并在组字中途失焦时强制提交待定文本（WebKit 的窗口切换路径根本不发 `compositionend`）。应用到所有应用共享的名称/备注/官网字段与 Hermes、OpenClaw、OpenCode 的字段集——腐坏被报告的位置。已存坏的值不会自愈——重新编辑一次即可。（[#6308](https://github.com/farion1231/cc-switch/issues/6308)、[#6333](https://github.com/farion1231/cc-switch/pull/6333)、[#6507](https://github.com/farion1231/cc-switch/pull/6507)）

### SQL 备份逐值保真、截断导入被拒绝

SQL 导出/导入循环的四处缺陷：TEXT 值含非 UTF-8 字节时导出中止、含 NUL 字节时语句被静默截断；REAL 值丢失存储类别（无穷、负零、整数值 REAL）；AUTOINCREMENT 高水位从存活行重推导而不是保留；恢复后数据库的 `auto_vacuum` 模式被降级、下次启动以整库 VACUUM 重建来修补。四处全部修复。校验还移到了建表之前：截断的 SQL 文件——或缺少 CC Switch 核心表的文件——现在带着原库不动被拒绝，此前 schema 迁移可能凭空造出缺失的表、让残缺数据顶替你的数据库。没有供应商或 MCP 的真实导出现在可以导入而不是被拒。（[#6146](https://github.com/farion1231/cc-switch/pull/6146)）

### 备份原子发布、恢复先在暂存库校验、全流程严格串行

备份此前在复制任何页之前就以最终文件名创建、复制结果被忽略——一次被打断的复制变成一个看似有效的备份文件。备份现在在临时文件里构建、完整性校验通过后才发布且不覆盖同名文件。恢复在触碰 live 数据库前先在暂存库校验整个镜像——完整性、schema 表、迁移——损坏或更新 schema 的备份干净地失败而不是替换到一半才发现；保留策略现在同时保护正在恢复的备份与新鲜的安全快照。并发侧：WebDAV 与 S3 此前各持各的锁、两种传输可以同时恢复，手动导入与 `.db` 恢复完全无锁，Skills 文件与其镜像的数据库行之间也没有共享锁。一把全局同步锁现在端到端串行化所有路径，Skills 状态锁让行与文件同进退，自动同步抑制从下载真正开始时才启动——排队等待期间的本地编辑不再被静默吞掉。会话日志读取游标也从云快照中排除：它们是绝对的本地文件位置，导入别的机器的游标会让本机用量摄取失步。（[#6147](https://github.com/farion1231/cc-switch/pull/6147)、[#6129](https://github.com/farion1231/cc-switch/issues/6129)）

### 恢复备份现在会重建依赖数据库的一切

恢复 `.db` 备份此前只改数据库——每个应用的 live 配置保持恢复前内容，直到下次手动切换供应商；SQL 导入与云下载后的收尾例程还跑在一个一次性状态对象上、缓存失效谁也够不着。所有恢复路径现在把恢复后的数据库向外投影——除 Pi 外每个受管应用的 live 配置（Pi 的 `models.json` 仍是事实源、下次启动反向导入）、各应用提示词文件、运行时日志级别与托盘用量缓存——并在恢复行之上重新应用你本地的设置文件与用户自改的模型定价；一个应用失败不再静默跳过其余。（[#6147](https://github.com/farion1231/cc-switch/pull/6147)、[#6129](https://github.com/farion1231/cc-switch/issues/6129)）

### 用量趋势图跨年时高亮与提示框终于一致

跨多年的区间上，悬停会高亮一个年份的点、提示框却描述另一个年份：图表用本地化的 MM/DD 文本作 X 轴键，不同年份的桶共享同一分类值，图表库的活动点查找返回首个匹配——高亮吸到早年份的点、提示框跟着光标走（绘制的点本身从来没错）。X 轴现在以后端完整的桶时间戳为键，刻度标签与提示框分别解析（跨年区间显示年份）。（[#6337](https://github.com/farion1231/cc-switch/pull/6337)、[#6302](https://github.com/farion1231/cc-switch/issues/6302)）

### 火山方舟：Agent Plan 预设终于指向 Agent Plan

以 Agent Plan 命名的预设在关键处指向 Coding Plan——端点与邀请链接——而两个计划是配额不互通的独立订阅。现拆分为六应用各两个预设：Agent Plan 走 `/api/plan[/v3]`（Codex 上原生 Responses）、Coding Plan 走原有 `/api/coding[/v3]`。计划配额检测放宽为识别 Agent Plan 端点，对存量供应商立即生效；预设本身作用于新建供应商——持有旧供应商的 Agent Plan 订阅者请重建或修改 Base URL。（[#6070](https://github.com/farion1231/cc-switch/issues/6070)、[#6448](https://github.com/farion1231/cc-switch/issues/6448)）

### 思考开关与推理档位的一批方言修正

- **ModelScope / Novita / Nvidia 的思考开关方言**：三个聚合平台预设都声明了它们谁也没文档化的智谱式 `thinking:{type}` 对象——ModelScope 与 Novita 上开关无效，Nvidia NIM 上注入字段可能被整体拒绝。前两家改发文档化的 `enable_thinking` 布尔值；Nvidia 的开关整个撤下——真正的控制不在该参数可及之处。平台推断表新增 ModelScope 分支，无存储声明的手建 ModelScope 供应商立即得到纠正。
- **StepFun 推理强度到达 step-3.7-flash**：推断分支此前只给 2603 后缀模型 effort，Codex 里选的档位对 step-3.7-flash 被静默丢弃；现在原样透传 low/medium/high，2603 系保持两档映射，无后缀的 step-3.5-flash 刻意不发 effort 字段——StepFun 没有为它文档化任何强度控制。
- **OpenCode Zen 推理档位到达网关**：路由模式下 Codex 里选的档位从未按原样到达网关——GLM/Kimi/MiMo 模型上代理回落到模型厂商启发式、丢档位、发网关不认的智谱式字段，DeepSeek 模型上发的是 DeepSeek 方言强转后的值。`opencode.ai` 平台规则现在发顶层 `reasoning_effort`，按各模型声明的档位钳制，无强度控制的模型不发而不是瞎猜。存量供应商需重加一次预设携带逐模型档位表。（[#6123](https://github.com/farion1231/cc-switch/pull/6123)、[#6112](https://github.com/farion1231/cc-switch/issues/6112)）
- **SiliconFlow 与 ModelScope 预设指向不存在的模型**：厂商目录盘点发现 SiliconFlow 预设携带两站都没有的 MiniMax id（首个请求即 400「Model does not exist」），ModelScope 预设指向其免费通道不可用的 GLM id。现改为 `Pro/MiniMaxAI/MiniMax-M2.5`（.cn）、`MiniMaxAI/MiniMax-M3`（.com，真实 1M 窗口）与 `ZhipuAI/GLM-5.2`，覆盖七个应用。

### 用量与定价的一批修正

- **DeepSeek 缓存命中在 Chat 路径被计为零**：只转发 DeepSeek 文档字段 `prompt_cache_hit_tokens`、不镜像进 OpenAI 式字段的中转商，其缓存命中被记为 0、命中 token 按新输入计价高估成本。该字段现居标准回退链末位，用量解析与合成的 Codex 用量都覆盖。（[#6126](https://github.com/farion1231/cc-switch/pull/6126)、[#6073](https://github.com/farion1231/cc-switch/issues/6073)）
- **Grok Build 对话不再因缺用量字段失败**：Chat 上游不报缓存 token 的每一轮都以「missing field `input_tokens_details`」失败——报告中的 GLM-5.2 上游恒发 `cached_tokens: 0`，即每轮必炸。Chat→Responses 用量翻译此前只在有缓存 token 时发出该对象，而 Grok 客户端要求它必在；现在恒发出，流式路径同样。（[#6423](https://github.com/farion1231/cc-switch/pull/6423)、[#6140](https://github.com/farion1231/cc-switch/issues/6140)）
- **智谱配额层级在 CREDIT_LIMIT 改名后重新出现**：智谱把境内端点的配额条目类型从 `TOKENS_LIMIT` 改名 `CREDIT_LIMIT`，解析器只认旧值、丢掉全部层级、面板空白。两个值现在都接受。（[#6160](https://github.com/farion1231/cc-switch/pull/6160)、[#6153](https://github.com/farion1231/cc-switch/issues/6153)）
- **Grok 4.5 缓存价修正；Grok 4.6 与一个 DeepSeek 别名补价**：`grok-4.5` 被错播成 grok-4.6 的 $0.50 缓存读取价，修正为实际的 $0.30 并守护式修复存量库。`grok-4.6` 按 $2/$6、缓存读取 $0.50 播种——基础档：xAI 对超过 200K 提示的 Grok 4.5/4.6 全费率翻倍而价格表没有档位列，长上下文 Grok 请求的读数约为账单一半。`deepseek-v4-flash-0731`——id 归一器剥不掉的 4 位日期变体、匹配不到任何价格行、一直按 $0 计费——获得自己的行；其历史 $0 行按现行价回填，该模型历史合计因此上升。

### 其他修复

- **文件丢失的 Skill 显示为可更新**：更新检查此前只信数据库缓存的内容哈希、从不看文件系统——文件没了的 Skill（典型场景：跨机数据库恢复只搬行不搬文件）永远报「无更新」，唯一出路是卸载重装。检查现在先确认 Skill 目录存在；缺目录显示为可更新、安装即重建文件。覆盖仓库安装的 Skill——本地创建的 Skill 不做更新检查，文件缺失仍需手动重加。
- **OpenClaw「设为默认」会询问模型并保留你的后备链**：设为默认此前总是取首个模型、并用合成链替换 `openclaw.json` 里已有的后备链。多模型供应商现在弹出选择器，写入合并进既有默认模型块、保留后备链与未知键。（[#6201](https://github.com/farion1231/cc-switch/pull/6201)）
- **用户自有的 Codex `model_catalog_json` 不再被覆盖**：切换供应商此前无条件把 `~/.codex/config.toml` 的 `model_catalog_json` 指向应用生成的目录、丢弃自定义目录路径。指针现在只在缺失或已是 CC Switch 自有文件名时才认领。仅防今后——被早期版本改写过的指针不会被还原，见升级提醒。（[#6087](https://github.com/farion1231/cc-switch/pull/6087)）
- **镜像的 DeepSeek Codex 目录恢复尖括号文本**：内置的 DeepSeek 官方 Codex 目录镜像提取时先做了 HTML 反转义再剥标签，四个 harness 字符串里的字面尖括号文本被当标记吞掉——`base_instructions` 里的一句指令与一个 markdown 链接示例、两个模型的消息模板都被损坏。镜像恢复逐字节保真，存量 DeepSeek 原生 Responses 供应商在下次切换时自动拾取、无需重存。

---

## 安全加固

### 模型拉取报错不再回显凭据

失败的「拉取模型」调用可能把 API key 反射进可见的错误信息，其他位置的脱敏也只对 8 个字符以上的密钥生效。拉取错误体现在经过严格脱敏——API key 与本版新支持的自定义请求头值，短至 1 个字符也隐藏——覆盖所有应用的供应商表单。拉取本身还为 Pi 变得格式感知：凭据头随供应商的 API 格式走，支持校验过的自定义请求头、包括仅请求头认证。（[#6064](https://github.com/farion1231/cc-switch/pull/6064)）

---

## 升级提醒

### 本版包含数据库迁移，降级需还原备份

schema 从 v16 迁移到 v17（Pi 导入器的会话用量去重账本），迁移前自动创建备份。本版运行过一次后，旧版 CC Switch 会拒绝打开数据库——降级需还原该备份。

### Pi 首次启动会导入既有供应商并回填历史用量

Pi 默认作为新应用页签出现。首启时 `~/.pi/agent/models.json` 里已写入的供应商被导入为可管理卡片；首次用量同步扫描所有可发现的 Pi 会话并回填历史用量，**看板总数可能跳涨**。Pi 自己的登录、默认供应商与默认模型永不触碰。配置为相对路径的 Pi `sessionDir` 无法枚举——会话浏览与用量导入请设绝对路径。

### v3.19.2 的 WSL 用户请直接升级

如果你在 v3.19.2 上使用 WSL 托管的配置目录，该版本无法更新或切换已有配置——请直接升级到本版。

### MSI 存量垃圾注册表键不会被清理

从 v3.4.0 到 v3.19.2 之间任何 MSI 安装过的 Windows 机器，升级后仍保留过期的 `HKCU\Software{{manufacturer}}{{product_name}}` 键；本修复不删除它。想清掉请用 regedit 手动删除——注意删除可能触发一次性的 Windows Installer 修复弹窗，因为它曾被注册为安装的键路径。

### 部分 ChatGPT 账号需要重登一次

本版之前登录进认证中心的 ChatGPT 账号早于 id_token 持久化，会显示「需要重新登录」徽章；绑定到供应商卡之前请重登一次。被修复前的接管恢复缺陷抹掉的 ChatGPT 登录同样不会被找回——跑一次 `codex login` 即可。

### 故障转移队列里的官方卡被移出

如果内置的 Codex 官方卡在你的自动故障转移队列里，它现在会被过滤，Auto 模式不会从官方卡启动；请选一个第三方 Codex 供应商作为主选。

### WSL / exFAT 上停止 Codex 接管改为拒绝恢复

在 WSL 或 exFAT 配置目录上，停止 Codex 接管现在以明确的「文件系统不支持安全恢复」报错拒绝执行，而不是冒险写出半份 auth 文件。不会删除任何东西，但接管前的凭据也**不会被写回**——之后请重跑 `codex login`，或把 Codex 目录放在支持安全探测的文件系统上。

### 预设改动只作用于新建供应商（例外见文末）

存量供应商保留创建时的配置。本版涉及：火山 Agent Plan 端点、ModelScope/Novita/Nvidia 思考方言、Kimi 推理强度、BytePlus 原生 Responses、SiliconFlow/ModelScope 模型 id 替换、OpenCode Go 直连与 1M 窗口、预填的推理档位、RunAPI 新域名。重新从预设创建（或手动改相应字段）即可获得。**立即对存量供应商生效的例外**：Kimi 透传变更、无存储声明供应商的平台推断修正（ModelScope、StepFun、opencode.ai）、火山 Agent Plan 端点的配额检测、DeepSeek 官方目录修复（下次切换时）。

### 被改写过的 `model_catalog_json` 指针需要手动指回一次

早期版本已改写过 `~/.codex/config.toml` 里 `model_catalog_json` 的用户，本版不会还原你原来的指针——手动指回你自己的文件一次，此后它不再被动。指向用户自有文件期间，CC Switch 的逐供应商模型表（显示名、上下文窗口、推理档位）不会到达 Codex。

### Grok Build 保存表单会钉住 `api_backend`

经表单保存存量 Grok Build 供应商会把其存储配置的 `api_backend` 钉为 `responses`——当前供应商立即写入 live 配置，其余供应商在下次切换到它时生效；上游协议改经高级 → 上游格式设置。

### IME 缺陷已存坏的文本需要重新编辑

本版之前被输入法缺陷弄坏的文本仍留在数据库与 live 配置里——把受影响的供应商名称/密钥/模型字段重新编辑一次即可。

### DeepSeek V4 成本读数将显著上升

看板中 DeepSeek V4 今后的成本大约：输入 3 倍、输出 4.5–4.7 倍、缓存读取 5 倍（Flash）到 12 倍（Pro）——这是厂商新的峰值档牌价，不是统计口径变化。成本在记录时冻结，历史不会重新计价——例外是此前无价的 `deepseek-v4-flash-0731` 行从 $0 按现行峰值价回填，这些历史合计会偏高。你手动改过的价格永不触碰。Gemini 3.7 Flash 按厂商标注持续到 2026 年底的介绍价播种。

### 备份与恢复行为变化

早期版本导出的 SQL 备份保留其原有的保真损失——依赖精确往返请导出一份新备份。截断或缺核心表的 SQL 文件现在在导入时被拒绝（早期版本可能会接受）；恢复 `.db` 备份现在会按恢复后的数据库重写除 Pi 外所有受管应用的 live 配置（此前只改数据库）。启用 WebDAV/S3 自动同步后，项目 Profile 的编辑现在也会排队上传快照。

### WebSearch 不可表达的约束显式报错

Claude Code WebSearch 请求携带 Responses API 无法表达的约束时（`blocked_domains`、非直连调用方、`response_inclusion`、或未强制工具时在 Codex OAuth 上带 `max_uses`），现在显式报错而不是搜得比要求更宽；Chat 格式上游仍不支持托管 WebSearch。

### Kimi 端点升级后若报思考类 400

先检查重加预设后新发送的 `thinking` / `reasoning_effort` 字段——Moonshot 的参数文档与其 Codex 接入指南对 kimi-k3 是否接受 `thinking` 说法相反，预设按接入指南执行。只有「要求回传思考历史」形态的 400 才指向已移除的历史注入。

---

## 风险提示

### 沿用的提示

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

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

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

---

## 致谢

这一版 69 个提交里有 38 个来自 11 位外部贡献者——本版的三条主线全部有外部贡献者的深度参与。

### 代码贡献

- 感谢 @SaladDay——19 个提交，本版最大贡献者：Pi 整条主线（[#6064](https://github.com/farion1231/cc-switch/pull/6064)、[#6463](https://github.com/farion1231/cc-switch/pull/6463)）、Codex 多账号整条主线（[#3879](https://github.com/farion1231/cc-switch/pull/3879)、[#6535](https://github.com/farion1231/cc-switch/pull/6535)、[#6506](https://github.com/farion1231/cc-switch/pull/6506)、[#6537](https://github.com/farion1231/cc-switch/pull/6537)）、十个 PR 的表单一致性打磨、Windows 启动闪屏修复（[#6252](https://github.com/farion1231/cc-switch/pull/6252)）与 Grok Build 用量字段修复。
- 感谢 @YUZHEthefool：备份与同步两波加固（[#6146](https://github.com/farion1231/cc-switch/pull/6146)、[#6147](https://github.com/farion1231/cc-switch/pull/6147)）——「修复」章节的三大数据可靠性条目尽出于此；还有 Windows CLI 检测大修（[#6284](https://github.com/farion1231/cc-switch/pull/6284)）、模型选择器模糊搜索（[#6285](https://github.com/farion1231/cc-switch/pull/6285)、[#6353](https://github.com/farion1231/cc-switch/pull/6353)）、智谱 CREDIT_LIMIT 与 Grok Build 表单对齐。
- 感谢 @allenxu09：v3.19.2 WSL 写入回归的热修（[#6232](https://github.com/farion1231/cc-switch/pull/6232)）与真实 WSL2 文件系统的 CI 覆盖（[#6233](https://github.com/farion1231/cc-switch/pull/6233)）——修完还把同类缺陷的测试缺口补上了。
- 感谢 @Program120：WebSearch 与 Alpha Search 的代理桥接（[#5681](https://github.com/farion1231/cc-switch/pull/5681)），一个人打通了本版第三条主线。
- 感谢 @stofancy：Codex 目录逐模型推理档位（[#6228](https://github.com/farion1231/cc-switch/pull/6228)）——本版思考档位整轮梳理的地基。
- 感谢 @zayokami：OpenCode Zen 推理档位路由（[#6123](https://github.com/farion1231/cc-switch/pull/6123)）、DeepSeek 缓存命中统计（[#6126](https://github.com/farion1231/cc-switch/pull/6126)）与 Grok Build 文案修正（[#6511](https://github.com/farion1231/cc-switch/pull/6511)）。
- 感谢 @yovinchen：macOS 输入法腐坏修复及其加固（[#6333](https://github.com/farion1231/cc-switch/pull/6333)、[#6507](https://github.com/farion1231/cc-switch/pull/6507)）。
- 感谢 @Hexc01：用量趋势图跨年错位修复（[#6337](https://github.com/farion1231/cc-switch/pull/6337)）。
- 感谢 @misaka-myu：尊重用户自有 `model_catalog_json`（[#6087](https://github.com/farion1231/cc-switch/pull/6087)）。
- 也感谢 @hu-miao 与 @jiekouai 分别贡献各自平台的预设（[#6239](https://github.com/farion1231/cc-switch/pull/6239)、[#6356](https://github.com/farion1231/cc-switch/pull/6356)）。

### 问题反馈

- 感谢 @vxzhong 在 [#6188](https://github.com/farion1231/cc-switch/issues/6188) 对 WSL 写入回归的报告——os error 50 的精确定位直接框定了热修方向。
- 感谢 Windows CLI 检测五 issue 家族的各位：@RonsonNamek（[#6061](https://github.com/farion1231/cc-switch/issues/6061)）、@gaoqiong001（[#6278](https://github.com/farion1231/cc-switch/issues/6278)）、@lovelyhjqhs（[#6047](https://github.com/farion1231/cc-switch/issues/6047)）、@baoyu0（[#4366](https://github.com/farion1231/cc-switch/issues/4366)）——@jiangliushi666 更早在 [#4701](https://github.com/farion1231/cc-switch/pull/4701) 就指出了 PATH 探测顺序问题。
- 感谢 @HyskoaMorroh 报告接管恢复抹掉 ChatGPT 登录（[#6277](https://github.com/farion1231/cc-switch/issues/6277)）、@CacinieP 以精确复现报告输入法腐坏（[#6308](https://github.com/farion1231/cc-switch/issues/6308)）、@FishV6A 报告启动闪屏（[#6182](https://github.com/farion1231/cc-switch/issues/6182)）、@Destiny4073 报告 MSI 注册表错写（[#6283](https://github.com/farion1231/cc-switch/issues/6283)）。
- 感谢 @totoneei（[#6302](https://github.com/farion1231/cc-switch/issues/6302)）、@zju-zhanglu（[#6153](https://github.com/farion1231/cc-switch/issues/6153)）、@xiaoyu753（[#6073](https://github.com/farion1231/cc-switch/issues/6073)）、@GengchenXU（[#6140](https://github.com/farion1231/cc-switch/issues/6140)）、@HOnnTaka（[#6112](https://github.com/farion1231/cc-switch/issues/6112)）、@Xiao0219（[#6171](https://github.com/farion1231/cc-switch/issues/6171)）、@STEVENTAN100（[#6181](https://github.com/farion1231/cc-switch/issues/6181)）、@20130101（[#6070](https://github.com/farion1231/cc-switch/issues/6070)）与 @leoncdq（[#6448](https://github.com/farion1231/cc-switch/issues/6448)）——用量、配额与档位的一整批修正都始于这些报告。

---

## 下载与安装

访问 [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.0-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
| `CC-Switch-v3.20.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |

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

### macOS

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