CC Switch v3.19.1 技术解析：DeepSeek 等三家中国 Codex 网关直连、官方模型目录镜像与四项关键缺陷修复-平芜编程栈

CC Switch v3.19.1 技术解析：DeepSeek 等三家中国 Codex 网关直连、官方模型目录镜像与四项关键缺陷修复

【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switch

本篇基于 CC Switch v3.19.1 发布说明（docs/release-notes/v3.19.1-en.md）展开，系统梳理该版本的核心变化：DeepSeek、火山方舟 Coding Plan 与腾讯混元 TokenHub 三类中国 Codex 网关从“本地路由转换”切换到“原生 Responses 直连”、官方模型目录镜像机制的源码实现原理，以及 Claude Desktop 用量双计、切回官方 Codex 后 401 死锁、Grok Build 升级失败与 404 等四个实际故障的根因和修复方案，并完整保留升级注意事项与安装信息，帮助读者安全升级并理解底层行为变化。

版本概览

CC Switch v3.19.1 是一个维护性版本（maintenance release），发布说明给出的变更规模为12 个提交 | 71 个文件变更 | +2,324 / -3,680 行，发布日期 2026-07-31。它沿三条主线推进：

中国 Codex 网关集体转向原生 Responses：DeepSeek、火山方舟 Coding Plan 确认原生支持 Responses API，本地路由接管（takeover）不再需要；腾讯混元 TokenHub 作为新预设加入，从第一天起就是直连；
四个日常可见的故障修复：Claude Desktop 用量自 v3.18.0 起被重复计算、切回官方 Codex 提供商后卡在 401 且无法登录、从设置页升级 Grok Build 只报os error 2、Grok Build 开启接管后直接 404；
减重：删除 3,166 行无调用方代码与 4 个未使用的 npm 依赖——这是该项目历史上第一个“删得多、加得少”的版本。

另外还包含：8 个此前按 $0 计费的模型获得内置定价、39 条界面字符串的语言问题修复、深链接导入确认的脱敏加固。本版本没有数据库迁移（schema 版本保持在 v16），升级是轻量的。

适用前提：本文基于当前仓库的实际代码与发布说明撰写，涉及行为均以 v3.19.1 为准；文中引用的源码路径均位于当前仓库中。

核心能力一览

在 Codex 中直连 DeepSeek、火山方舟 Coding Plan 与腾讯混元：三家厂商官方 Codex 文档均确认端点原生提供 Responses API。现有的 DeepSeek 与火山方舟 Coding Plan 预设从 Chat 格式切换为原生格式，提供商卡片上的“需要路由”徽标与切换提示消失，请求不再经过本地代理的协议转换；腾讯混元 TokenHub 是新增预设，自始即原生。
让 DeepSeek 使用其自身发布的模型目录：新增“官方厂商目录镜像”（official vendor catalog mirroring）机制，将厂商发布的models.json原样用于该厂商自己的端点，使自由格式apply_patch注册及其配套的 GPT-5 harness 保持整体一致，而不是被压平进中性模板。
获得正确的 Claude Desktop 用量数字：v3.18.0 起，经本地网关的 Claude Desktop 流量在用量面板中被记录了两次（代理行 + 会话日志导入行），token、成本、请求数大致翻倍。修复后，只要明细行仍在，历史数据在下次启动时自动回到正确数值，无需重建。
切回官方 Codex 提供商后可正常登录：此前从第三方切回内置官方 Codex 条目时，第三方密钥残留在~/.codex/auth.json中，Codex 拿它请求官方端点必然 401，且因文件存在而永远不会回退到登录界面。
从设置页升级 Grok Build：0.2.112 起grok update内部改由 npm 分发，GUI 启动的应用找不到 node，升级永远只报Error: No such file or directory (os error 2)。
Grok Build 开启接管不再 404：此前将 API 格式手工改为 OpenAI Chat 或 Anthropic 的 Grok Build 提供商，一旦开启接管就把请求发往代理未注册的路线，直接 404、无故障转移、无用量记录；同时每次请求都被视为新会话，导致缓存键注入与按会话分组全部失效。
8 个模型的 $0 计费问题：gpt-5.3-codex-spark、gemini-3.5-flash-lite、kimi-k2.7-code-highspeed、glm-5-turbo、glm-5v-turbo、qwen3.6-flash，以及无日期后缀的claude-opus-4-6/claude-sonnet-4-6获得内置定价。
繁体中文工具管理器不再回落英文：30 条字符串此前只补了简中、英语、日语，i18next 静默回退英文，导致自 v3.16.0 起该面板一直是半英文；另有 9 条字符串在所有语言下都显示简体中文。
在官方订阅与 DeepSeek 之间往返切换：auth.json与config.toml都是单槽位文件，官方一键脚本会把配置改写为 DeepSeek 专属，而 CC Switch 按提供商快照与恢复，这是两种方案最实用的差异。

使用指南索引

本版本变化集中在“Codex 如何连接”与“用量如何统计”两个方面，以下文档值得配合阅读（路径均为仓库根目录相对路径）：

本地路由（Local Routing）：哪些提供商需要开启接管、接管做什么。本版本之后，DeepSeek、火山方舟 Coding Plan 与腾讯混元不再需要它。
用量统计（Usage Statistics）：用量面板的数据来源与统计口径——有助于理解 Claude Desktop 双计是如何发生的、以及为什么某些历史天数无法修正。
在 Codex 中使用 Chat 格式 API（如 DeepSeek）：该指南讲解本地路由如何将 Responses 转换为 Chat Completions，已随本版本更新——开头会先判断你处于哪种情形：从预设创建的 DeepSeek 提供商直连、无需路由；升级前保存的提供商以及deepseek-v4-pro仍需路由。机制同样完整适用于 Kimi、智谱 GLM、SiliconFlow 等仍为 Chat 形态的提供商。

DeepSeek、火山方舟与腾讯混元：从路由到直连

预设层面发生了什么

此前 DeepSeek 与火山方舟 Coding Plan 两个预设被标记为 OpenAI Chat 格式，属于“需要接管”：提供商卡片带“需要路由”徽标，不开代理就切换会弹出提示，每条请求走 Codex → 本地代理 → Responses 转 Chat → 上游。

由于两家官方 Codex 接入文档现在都确认端点提供 Responses API——DeepSeek 的api.deepseek.com与火山方舟的/api/coding/v3——两个预设被声明为原生 Responses。两者生成的config.toml实际没有变化（本来就是wire_api = "responses"），变化的是目录生成 profile，以及 DeepSeek 的上下文窗口（从 1,000,000 对齐为厂商自报的 1,048,576）。

在源码中，这类预设的apiFormat字段为"openai_responses"，例如 Tencent Hunyuan 预设的定义：

{ name: "Tencent Hunyuan", auth: generateThirdPartyAuth(""), config: generateThirdPartyConfig( "hy3_tokenhub", "https://tokenhub.tencentmaas.com/v1", "hy3", ), endpointCandidates: [ "https://tokenhub.tencentmaas.com/v1", "https://tokenhub.tencentmaas.cn/v1", ], apiFormat: "openai_responses", modelCatalog: modelCatalog([ { model: "hy3", displayName: "Hy3", contextWindow: 256000, inputModalities: ["text"], reasoningLevels: ["low", "high"], }, { model: "hy3-preview", displayName: "Hy3 Preview", contextWindow: 256000, inputModalities: ["text"], reasoningLevels: ["low", "high"], }, ]), category: "cn_official", icon: "hunyuan", }

其中几个字段值得注意：

endpointCandidates预置两个候选地址：主域名与官方.cn备用域名，地址管理器与延迟测试从创建起就有两个候选；地域独立的国际站被刻意排除，因为 API Key 不跨站通用。
contextWindow: 256000：显式声明 256K 上下文窗口，而不是接受 Codex 的 128K 默认值。
inputModalities: ["text"]：标记纯文本模型，Codex 不再向无法读图的模型发送view_image负载。
reasoningLevels: ["low", "high"]：源码注释指出官方档位枚举只有 low/high，且 hy3 在带 tools 的请求中会把reasoning_effort=low在服务端自动升为 high（Codex 恒带 tools），所以 high 才是带工具调用的真实行为。
源码注释还强调：必须使用勾选了 Hy3 范围的 TokenHub API Key，Coding Plan / Token Plan 订阅 Key 只能走各自的 chat 端点，对这个预设的/v1不通；TokenHub 官方硬性要求的disable_response_storage = true已由generateThirdPartyConfig统一输出。

此外，BytePlus 国际站被刻意保留在 Chat 路由上，直到其文档被单独核实；火山方舟预设还附带一条计费提醒：按量付费的/api/v3端点绝不能加入该预设的备用地址——它单独计费、不消耗套餐配额。

目录显示名与上下文窗口改为“仅显式生效”

这两个字段此前带有本地默认值（模型 ID 与 128,000 token 窗口），在厂商的值有机会参与之前就被套用，镜像目录里 1M 的窗口会被 128K 覆盖。现在两者都是可选字段，回退逻辑下移到条目构建阶段，于是“留空”真正意味着“保留厂商声明的值”。显式设置了这两个字段的提供商、以及所有非镜像 profile，生成的目录与此前逐字节一致。

官方厂商模型目录镜像：让 DeepSeek 用自己的目录

问题背景

Codex 从一个 catalog 文件（models.json）读取模型能力。CC Switch 此前为每个提供商从中性模板生成该目录——这对聚合商（aggregator）是正确做法，但会剥掉厂商自家集成所依赖的能力。

源码实现

镜像机制的核心在 src-tauri/src/codex_config.rs：

/// Hosts whose native `/responses` gateway publishes an OFFICIAL Codex model /// catalog (models.json) that cc-switch mirrors verbatim. Matched against /// `base_url` ONLY — deliberately NOT by model brand, ... const CODEX_DEEPSEEK_OFFICIAL_CATALOG_HOSTS: &[&str] = &["deepseek.com"]; fn codex_official_vendor_catalog_models( config_text: &str, profile: CodexCatalogToolProfile, ) -> Option<Vec<Value>> { if profile != CodexCatalogToolProfile::NativeResponses { return None; } let base_url = extract_codex_base_url(config_text)?.to_ascii_lowercase(); if CODEX_DEEPSEEK_OFFICIAL_CATALOG_HOSTS .iter() .any(|host| base_url.contains(host)) { let models = load_codex_deepseek_official_catalog_models(); ... } None }

设计上有三个刻意的收窄：

只匹配NativeResponsesprofile。ProxyChat（本地路由转换）走的是转换器的 gpt-5.5 模板契约，Anthropic 转换会剥掉自定义工具，两者都必须保持现有模板。
按主机匹配，绝不按模型品牌匹配。官方条目是授予能力（freeformapply_patch、厂商 harness）的；聚合商即使托管同名模型，也未必实现了这些能力。对聚合商的安全失败方向是中性模板（降级但可用）；错误授予 freeformapply_patch会重新引入自定义工具被拒绝的 bug。
主机驱动意味着既有提供商在下一次切换时自动生效，无需重新保存——检查读取的是活动配置（live config）。

被镜像的 DeepSeek 官方目录

DeepSeek 官方目录的打包副本是 src-tauri/src/resources/codex_deepseek_catalog_template.json，包含deepseek-v4-flash与deepseek-v4-pro两个条目。关键能力字段包括：

apply_patch_tool_type: "freeform"、web_search_tool_type: "text"、supports_search_tool: true；
low / high / max 三档推理等级，默认high；
context_window: 1048576（1M 上下文）；
minimal_client_version: "0.144.0"；
以及写在base_instructions与model_messages里的17,644 字符 GPT-5 harness。

这个 harness 必须与 freeform 工具注册整体一起携带：harness 本身指示模型使用apply_patch，拆掉任何一半都会让这一对失去一致性。对目录中未知模型 ID 的处理是克隆旗舰（第一条）条目但保留自己的名字；提供商在自己目录里钉住的条目仍然优先。其他所有 profile 生成的目录与此前逐字节相同。

两个前置条件

镜像目录声明 Codex 客户端最低版本0.144.0，CC Switch 本身不校验这一点——它携带的 freeformapply_patch注册要求该版本或更新。
生成的目录文件会增长到约75 KB（对应两个镜像模型），因为每个条目都携带完整 harness 文本。

官方 DeepSeek 目录的两个限制（DeepSeek V4 Pro 暂不可直连）

预设里仍然列出deepseek-v4-pro，厂商自己的目录里也有它，但DeepSeek 尚未对 pro 开放 Codex 接入（其声明的时间是 2026 年 8 月初）。在此之前，在直连模式下选择 pro 会在上游失败——请使用deepseek-v4-flash（它也是预设默认模型）。

如果现在就需要 pro，把该提供商的 API 格式改回“OpenAI Chat”并启用本地路由接管。这正是 v3.19.1 之前 DeepSeek 的路径：本地代理把 Codex 发出的 Responses 请求转换为 Chat Completions，pro 在该路径上不受影响（参见 DeepSeek 路由指南）。

通过 CC Switch 导入 vs 运行官方脚本

DeepSeek 发布了官方一键 Codex 配置脚本，它能用、有备份、带恢复菜单。如果这台机器只打算用 DeepSeek，直接运行官方脚本完全没问题。CC Switch 解决的是另一种情形：你想在多个提供商之间来回切换。

切换提供商 = 成组交换登录状态与配置，无需手工备份

~/.codex/auth.json与~/.codex/config.toml都是单槽位文件——Codex 本身没有多凭据存储，一份配置只能描述一个提供商。离开某提供商时，CC Switch 把这两个文件的内容快照进该提供商记录；切回时整体写回。因此“ChatGPT 订阅 → DeepSeek → 再回到订阅”通常不需要重新codex login，第三方提供商之间切换则完全无需手工步骤。手工做同样的事意味着每次切换前后都要复制两个文件——漏一次，被覆盖的 OAuth 凭据就只能重新登录找回。

官方脚本做了不同的取舍：它把config.toml改写为 DeepSeek 专属配置——在顶层固定preferred_auth_method = "apikey"与forced_login_method = "api"把认证锁死在 API key，并且删除config.toml里既有的[profiles.*]（Codex 内置的提供商切换机制）。你的 ChatGPT 凭据本身没有被删（auth.json未动），只是在那份配置下用不了；回到订阅要走脚本的恢复菜单做整文件回滚，而该回滚同时丢弃你安装后对config.toml的手工编辑。脚本本身只能在 flash 与 pro 之间切换，没有“切到第三个提供商”的选项。

切换后旧会话仍在`codex resume`里

Codex 按会话中记录的model_provider给 resume 列表分抽屉。CC Switch 创建的每一个第三方 Codex 提供商——DeepSeek、Kimi、聚合商，没有区别——写的是同一个标识custom，所以在它们之间怎么切，codex resume都保持展示完整历史。CC Switch 首次启动时还会执行一次性迁移，把已知的按厂商分桶（包括官方脚本写入的deepseek桶）折叠进这个共享桶，迁移前先把原文件备份到~/.cc-switch/backups/。

这里有一条明确边界：该迁移只在 CC Switch 首次启动时运行一次。如果先装了 CC Switch、之后才运行官方脚本，那些带deepseek标签的会话不会被折叠——它们留在自己的抽屉里。另外，手工写的、不在已知列表中的提供商标识会被刻意原样保留。

官方订阅会话在 CC Switch 中本就与第三方会话混排

CC Switch 的会话面板直接扫描会话目录，不读model_provider，所以官方订阅期间产生的 Codex 会话一直在同一个列表里——可搜索、可恢复、可删除，无需任何开关。

如果你还希望Codex 自己的codex resume列表也合并官方与第三方会话，那是另一件事：设置 → 常规 → Codex 应用增强 →“Unified Codex session history”（统一 Codex 会话历史），默认关闭。启用后只影响新会话；要同时迁移已有官方会话，需要在启用对话框勾选“Also migrate existing official session history”（同样默认不勾选）。两者都是既有功能，并非本版本新增；边界情况参见统一 Codex 会话历史指南。

两条共享前置条件，提前说明以免后面困惑：
第一，以上所有内容都针对 CC Switch 指向的 Codex 目录。默认是~/.codex，可在设置中更改。CC Switch 不读取CODEX_HOME环境变量——如果你用该变量把 Codex 指向别处，CC Switch 看不到那些会话，提供商切换也会写进 CLI 根本没在用的目录。要改目录，请用 CC Switch 自己的配置目录设置。
第二，出现在同一列表里不等于会话可以恢复。Codex 的推理内容（encrypted_content）只能由产生它的后端解密，所以在不同提供商上继续旧会话可能失败——那是上游的设计，CC Switch 无法绕过。

缺陷修复：四个日常可见故障的根因与方案

Claude Desktop 用量被重复计算

现象：Claude Desktop 经本地网关的流量在用量面板中落地两次——一次是代理行，一次是会话导入行——token、成本、请求数大致翻倍。

根因：这是 v3.18.0 引入的回归。代理侧的去重 ID 对除claude之外的每个应用都带作用域前缀，写作session:{app}:{provider}:{message_id}，结果把claude-desktop放进了独立命名空间；与此同时会话导入器仍以裸session:{message_id}形式、带app_type = 'claude'写入同一条 Claude 消息。三道去重防线同时失效：让代理行吸收既有会话行的主键收敛、写入侧的指纹探测、读取侧过滤器——后两者都按严格相等比较应用类型。

修复：两个应用重新共享裸命名空间，两处比较按一条单向规则放宽：claude的会话行可以被claude-desktop的代理行吸收，反向不行。由于读取侧过滤器正是每日汇总（daily rollup）聚合所经过的那条路径，数据库中已存在的重复行从此不再被计入——没有重写或删除任何行。对 Codex、Gemini、OpenCode，放宽后的比较退化为原先的严格相等；配额检查仍使用严格匹配。

切回官方 Codex 提供商后卡在 401、且没有登录界面

现象：在 Codex API key 保留开关关闭（默认）的情况下，切换到第三方提供商会把厂商密钥写入~/.codex/auth.json。之后再切换到内置官方提供商（其存储凭据为空）时走的是“仅配置”分支：config.toml被替换，但第三方OPENAI_API_KEY原样留在磁盘上。Codex 拿这个外来密钥请求官方端点，稳定 401；又因为auth.json存在，Codex 永远不会回退到自己的登录界面，应用内部无路可走。

修复：成功切换到官方 Codex 提供商后，如果auth.json里只有OPENAI_API_KEY、旁边没有任何一等凭据，该文件会被删除——OAuth token、个人访问令牌、agent identity 或 Bedrock key 的存在都标志着文件是“真的”并原样保留；而auth_mode、last_refresh、账号 ID 这类元数据不能再为过期密钥“护航”。

删文件而不是写{}是刻意的：空对象会被 Codex 读成“无 token 的 ChatGPT 模式”并在启动时报错；而文件缺失等价于已登出，直接进入登录流程。清理只在旧提供商成功回填进数据库之后执行，所以被删的密钥不会丢失——它存在该提供商记录里，再次选中即回来。同一改动还放宽了活动配置读取：清理后的状态（无auth.json、有config.toml）不再被报告为“Codex 未安装”。

前置条件：清理只在两个条件同时满足时运行——传入提供商带有显式的官方分类，且 outgoing 提供商回填成功。手工创建、没有官方分类的条目，或回填失败的切换，仍会留下残留。

从设置页升级 Grok Build 只报`os error 2`

现象：设置 → 关于下升级 Grok Build 失败，只有Error: No such file or directory (os error 2)，没有更多信息。

根因：探测路径与执行路径的不对称——探测走登录 shell（读取用户 rc 文件，因此能看到 nvm、Homebrew、Volta），而生命周期脚本在非登录 shell 下运行，继承的是 GUI 启动应用最初那个极窄的 PATH。这本来无所谓，因为锚定命令用绝对路径调用目标——但 grok 0.2.112 把自更新挪到了 npm 分发：grok update内部调用npm view与npm i -g，npm 又通过 shebang 解析 node。内部调用返回 ENOENT，grok 把它原样表面化为那个os error 2。

修复：macOS 与 Linux 上的生命周期命令现在把登录 shell 的真实 PATH合并到继承 PATH 之前，读取方式是执行/usr/bin/env而不是回显变量——因为 fish 把 PATH 存为列表，回显会给出空格分隔的片段。对原生安装的 Grok，升级链还会回退到官方 xAI 安装器，刻意不选npm i -g：npm 与主路径共享两个失败模式（没有 node、镜像缺少该包），会一起失败；官方安装器是唯一不依赖 node 的路径，落到同一位置，并把 CLI 自己的installer设置改回internal——顺带修复了早期 npm 回退被切到 npm 分发的用户。

Grok Build 开启接管后 404，且每次请求都像新会话

现象一：把 API 格式手工改为 OpenAI Chat 或 Anthropic 的 Grok Build 提供商，开启接管后立即 404，无故障转移、无用量记录——接管重写了地址和密钥，却没动 backend 字段，CLI 把请求发往代理未注册的路线。修复：接管现在同时把 backend 钉为 Responses；按提供商降级到 Chat Completions 仍发生在转发层；强制值随整个活动配置备份在代理停止时一并恢复。数据库里存储的提供商记录不受影响。

现象二：代理的会话检测只认识 Codex 与 OpenAI 客户端，导致 Grok Build 每轮都生成新的、标记为“非客户端提供”的会话 ID，缓存键注入与面板里的按会话分组双双失效。修复：现在读取 Grok 自己的头——先会话 ID（conversation ID）、后 session ID，忽略逐请求变化的那个——并放在独立前缀下，记录不会与 Codex 的冲突。

界面字符串：9 条全语言简体中文 + 30 条繁体缺失

9 条字符串在所有语言下显示简体中文：调用点全部用了“内联默认值”形式且默认值是中文字面量，但对应 key 在四个语言文件中一个都没有——i18next 会先走完整个语言链才考虑内联默认值，于是英文回退根本没机会，中文字面量在所有语言下胜出。涉及 Grok Build 表单必填校验、未接管应用的故障转移悬停提示、Claude Desktop 路由停止时另一应用持有接管的警告（含原因行）、提供商标识读取失败、空 Codex 公共配置错误、路由服务停止/停止失败 toast、以及用量表格里“有 token 但算出零成本”的“未定价”标签。现在 9 个 key 在简中、英语、日语、繁体四个语言中齐备。
繁体中文工具管理器回退英文：接口语言设为繁体时，关于页的工具管理区显示英文——版本行、安装/更新按钮、结果 toast、安装冲突诊断、整个升级确认对话框。该面板分三次改动搭成，每次都只补简中、英语、日语；因为 i18next 的策略是回退英文而非报错，30 个缺失 key 在测试中完全不可见，这个缺口从 v3.16.0 一直发到了 v3.19.0。现在 30 条全部翻译完毕，安装提示也对齐其他语言；新增的 locale 测试要求每个工具管理字符串在四语中齐备且插值变量一致，此类漂移今后会让测试套件失败而不是随版本流出。

内置定价漂移修正

成本在请求记录时刻对内置定价表冻结，所以一条过期的种子价会让此后每条请求静默计错。本版本修正四行：

模型	变化
`deepseek-chat`/`deepseek-reasoner`	成为 V4 Flash 的遗留别名：$0.14 / $0.28（每百万 token 输入/输出），缓存读取 $0.0028（原 $0.27/$1.10 与 $0.55/$2.19）
`minimax-m3`	减半至 $0.30 / $1.20（官方标准档）
`gpt-5.6-luna`	降 80% 至 $0.20 / $1.20
`gpt-5.6-terra`	降 20% 至 $2 / $12（跟随 2026-07-30 官方降价；`gpt-5.6-sol`刻意不动，家族缓存写入比例保留）

修复只在四列价格仍精确等于旧的内置值时才重写该行，你自己改过的价——或 models.dev 同步写入的价——绝不被触碰。

安全加固：深链接导入确认的脱敏收紧

这是 v3.19.0 中ccswitch://确认加固的延续。配置预览现在由单一共享模块构建，递归遮蔽嵌套 TOML 表与 JSON 对象内部的密钥，同时修复了两个方向相反的缺陷：Grok Build 导入完全没有渲染配置预览，而 Codex 导入把内嵌api_key明文打了出来。

配置预览的 300 字符截断被移除，完整内容现在在可滚动框中渲染——关掉了确认框隐藏即将写入内容的最后一处位置。脱敏规则本身在所有使用处都更严格，包括 MCP 导入确认：敏感名匹配新增AUTHORIZATION、COOKIE、CREDENTIAL，并对AUTH与BEARER精确匹配；遮蔽后显示的明文前缀从 8 字符缩到 4 字符；长度 ≤ 8 字符的值现在整体替换，而不再是原样展示。

最后，前端 Base64 解码器不再修剪首尾空白——那完全可能是 URL 解码转成的+号空格。这与 v3.19.0 修复的前端/后端解码器分歧属同一类：确认框显示的和导入器写入的必须是同一份数据。

内部：删除 3,166 行无调用方代码、14 个模块与 4 个依赖

这是一次“删除无剩余调用方代码”的清扫，是项目历史上第一个净删除版本：

后端删除：提供商图标推断表、占位健康检查器、从未接线的 SSE 实现（含流式与非流式处理器）、两个未使用的代理会话类型、四个未引用的用量解析器、一个死掉的成本计算入口——在用的计费路径、其自动探测解析器与会话 ID 提取全部未动。维持编译器沉默的 22 个#[allow(dead_code)]抑制一并删除。
前端删除 14 个无导入方模块，包括被面板重写取代的提示词表单模态框与仓库管理器、重复的代理配置 hook、项目历史上从未有过导入方的熔断面板、三个 schema 文件；它们的字符串从四个语言中同步移除。这些模块背后的 Tauri 命令被刻意保留。另删除 4 个未使用的 npm 依赖；两个重新生成手工维护图标索引的脚本被移除，索引文件头现在声明“自动生成有意不被支持”。
配套改动把代理状态与接管状态整合到单一查询层——此前存在第二套覆盖相同命令的并行 hooks，零调用方，其查询 key 从未有观察者，所有针对它们的失效操作都是空操作。查询 key 字符串逐字符不变，幸存 hook 保留原有轮询行为。

升级注意事项（Upgrade Notes）

本版本无数据库迁移

v3.19.1 不含 schema 迁移（版本保持 v16），不会触发升级前备份，升级完即可用。

Claude Desktop 双计的自愈有 30 天窗口（务必阅读）

修复在查询时抑制重复行，而不是重写或删除数据，所以只要明细行仍在，升级后下次启动该日就自动回到正确合计，无需重建。

但 30 天以前的明细行已被聚合成每日 rollup 并清理，而 rollup 只在聚合时刻按当时生效的规则计算一次。已被无修复版本聚合过的日子会永久保留膨胀数字。回归始于 v3.18.0（2026-07-21），升级越早，能找回的历史区间越多。

新定价对历史数据以两种不同方式生效

8 个新定价模型是追溯重算的：启动时，以零成本记录的请求会被填入成本，这些模型的面板数字会上升。已聚合清理的明细行无法重算，保持为零。
4 个改价模型方向相反：回填只触碰零成本行，已记录的请求保留旧价，只有新请求按新价计费——同一模型的历史与新支出会对不上。

两条路径都保护你自己的定价：修复只改仍等于原始内置值的行；~/.cc-switch/model-pricing.json中的手工编辑、models.dev 同步值与删除墓碑在播种与修复之后重放，永远优先。

预设变更只影响新建提供商

已保存的 DeepSeek 或火山方舟 Coding Plan 提供商保持其存储的 API 格式，仍需要本地路由、仍用旧目录。要使用直连，从预设重新创建提供商，或在提供商表单的高级区把 API 格式改为原生 Responses。

不过，已经是原生 Responses、且地址在deepseek.com上的提供商，下一次切换时即拾取镜像的官方目录，无需重新保存——因为检查读取的是活动配置。

直连之后，用量归属从提供商名移到`Codex (Session)`

DeepSeek、火山方舟 Coding Plan 与腾讯混元不再需要接管，流量可以完全绕过本地代理，代理的逐请求记录不再看到它们。用量本身不丢失、也不可区分——Codex 会话日志导入照常记录，只是该路径不带提供商身份：所有未经本地代理的 Codex 用量（含官方订阅消耗）都归入名为Codex (Session)的条目。换言之，DeepSeek 从路由转为直连后，其用量从“DeepSeek”名下移入Codex (Session)。

区分方法是看模型：每条用量记录都带自己的模型 ID，用量面板的按模型统计逐行列出——deepseek-v4-flash、hy3、ark-code-latest与官方订阅的 GPT 模型各得一行，成本与 token 独立。只有你真正需要的维度是按提供商（比如跨聚合商比较同一模型）时，才需要继续使用本地路由接管——那条路线会记录真实提供商名。

工具安装与升级的 PATH 变化（仅 macOS / Linux）

设置 → 关于触发的每次工具安装与升级现在都会把登录 shell 的 PATH 合并到继承 PATH 之前，因此生命周期脚本按名解析的程序可能与之前解析到不同的版本；每个动作还多起一个 shell 来读取该 PATH，即会执行你的交互式启动文件。Windows 不受影响。

使用 grok 0.2.112 及之后的用户可能看到两条安装记录——原生的那条加上grok update自己创建的全局 npm 包；上游保持两者同步，报告同一版本。

环境冲突检测的匹配规则变化

Claude Code、Codex、Gemini 的检测从“包含”收紧为“前缀”，因此仅仅包含应用名的变量——MY_ANTHROPIC_API_KEY、OLD_GEMINI_API_KEY——不再被报告为冲突（CC Switch 自己的GROK_BIN_DIR、GROK_HOME也因此不会被误报）。同时新增 Grok Build 检测：XAI_API_KEY与GROK_DEFAULT_MODEL——两个会在应用内覆盖你所选提供商的变量。

Grok Build 接管会重写 backend 字段

如上所述，开启接管会把活动配置中的 backend 字段重写为 Responses；数据库中的提供商记录不受影响，活动文件在代理停止时从备份完整恢复。

深链接确认展示的密钥明文更少

遮蔽后显示的明文前缀从 8 字符缩到 4，≤ 8 字符的值整体遮蔽；同样影响 MCP 导入确认。

风险提示

xAI Grok OAuth 登录：复用官方 Grok CLI 的公共 OAuth 客户端身份，使用可能导致账号受限或封禁——详见 v3.18.0 发布说明的风险提示。
Codex OAuth 反向代理：通过反向代理使用 ChatGPT 订阅的 Codex OAuth 可能违反 OpenAI 服务条款，详见 v3.13.0 发布说明的风险提示。
SuperGrok 配额查询：提供商卡片上的配额显示依赖 grok.com 的非公开计费端点，xAI 修改接口后可能失效，详见 v3.19.0 发布说明的风险提示。
第三方提供商路由：CC Switch 本地代理把 Codex、Claude Desktop 或 Grok Build 请求转换并转发给第三方提供商时，各提供商在计费、合规与数据留存上的约束不同，使用前请阅读目标提供商的服务条款。

启用这些功能的用户即接受相关风险；CC Switch 不对由此产生的账号限制、警告或服务暂停负责。

下载与安装

可从官方渠道获取各系统安装包，或查看 v3.19.1 发布说明末尾的下载章节。

系统要求

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

Windows

文件	说明
`CC-Switch-v3.19.1-Windows.msi`	推荐——带自动更新的 MSI 安装器
`CC-Switch-v3.19.1-Windows-Portable.zip`	便携版，解压即运行

Windows ARM64 设备应选择文件名带arm64标签的产物。

macOS

文件	说明
`CC-Switch-v3.19.1-macOS.dmg`	推荐——DMG 安装器，拖入 Applications
`CC-Switch-v3.19.1-macOS.zip`	解压后拖入 Applications，Universal 二进制
`CC-Switch-v3.19.1-macOS.tar.gz`	供 Homebrew 安装与自动更新使用

Homebrew 安装：

brew install --cask cc-switch

升级：

brew upgrade --cask cc-switch

Linux

Linux 产物同时提供x86_64与ARM64（aarch64），选择与机器uname -m输出匹配的架构标签：

CC-Switch-v3.19.1-Linux-x86_64.AppImage/.deb/.rpm
CC-Switch-v3.19.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`

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考