CC-Switch/docs/release-notes/v3.17.0-zh.md

CC Switch v3.17.0

这一版带来一个盼了很久的能力：「项目」一键切换——把当前的供应商、MCP、Skills、记忆文件整套保存为命名快照，在标题栏或托盘里一键换成另一套，切换时还会自动把你离开的项目当前状态存回去。Codex 侧同样收获颇丰：官方 ChatGPT 订阅账号现在也能走本地代理路由，享受与第三方供应商相同的路由与用量统计；GPT-5.6 全家的上下文窗口与 Sol / Terra / Luna 三档定价一步到位；还新增了原生 Anthropic Messages 上游格式——所在企业禁用了 Claude Code、但没有禁用 Claude API？现在可以在 Codex 里直接用上 Claude 系列模型。此外是一大波正确性修复：上游失败不再变成「空回复」、缓存写入不再被双重计费、删掉的 MCP 服务器不再复活、Kimi For Coding 的 256K 窗口终于真正生效。

English → | 日本語版 →

---

使用攻略

本版的新能力主要落在主页顶部的项目切换器、Codex 供应商表单与用量看板里，建议结合以下文档了解：

• 在 Codex 中用 Claude（本地路由攻略）：本版新增的分步攻略，配合「原生 Anthropic Messages 上游」功能使用。攻略讲解如何把 Codex 供应商的上游格式选为 anthropic，接入任何只提供 /v1/messages 的 Claude 系网关，在 Codex 里用上 Claude 系列模型。
• 在 Codex 里使用 Kimi（本地路由攻略）：本版新增的分步攻略。较新的 Codex CLI 走 OpenAI Responses 协议，而 Kimi 开放平台与 Kimi For Coding 暴露的是 Chat Completions 端点，直连通常 404；攻略讲解如何用内置的 Kimi / Kimi For Coding 预设配合本地路由完成协议转换。
• Codex 官方登录保留：了解 CC Switch 如何在切换第三方供应商时保留你的官方 ChatGPT 登录。本版在此基础上更进一步——官方账号本身也可以走代理路由（见下方「新功能」）。
• 用量统计：了解用量看板的数据来源与统计口径。本版修正了缓存写入计费、补齐了 Codex 子代理会话统计，并新增 GPT-5.6 与混元 Hy3 定价。

---

Warning

唯一官方渠道声明（请务必阅读）

CC Switch 是完全免费、开源的桌面应用，不会向用户收取任何费用。请仅通过下列官方渠道获取本软件：

类别	唯一官方
官网	ccswitch.io
源码	github.com/farion1231/cc-switch
下载	GitHub Releases
作者	@farion1231
举报山寨	GitHub Issues

任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。

---

概览

CC Switch v3.17.0 是 v3.16.5 之后的一个功能大版本，核心是**「项目」**：你可以把 Claude Code / Claude Desktop / Codex 当前的供应商、MCP、Skills、记忆文件状态保存为命名快照——比如编程目录一套「开发」、写作绘图目录一套「创作」——在主页顶部的切换器或托盘的「项目」子菜单里一键整套切换——切换前会自动把你正要离开的项目状态存回去，所以项目里保存的永远是你上次离开时的样子。第二条主线是 Codex：官方 ChatGPT 订阅账号现在也能走本地代理路由接管（不需要 API Key，Codex 自己的登录凭据原样透传，绝不覆盖你的官方登录）；配合修正后的客户端身份，gpt-5.6-luna 这类最新订阅模型不再误报 404；GPT-5.6 的 372K 上下文窗口注入、Sol / Terra / Luna 三档定价（含 1.25 倍缓存写入费率）与预设默认模型同步就位；Codex 上游格式还新增了原生 Anthropic Messages 协议——它瞄准一个很现实的场景：不少企业禁用了 Claude Code 客户端、但并没有禁用 Claude API，这些用户现在可以让 Codex 直连 Claude API（或任何只提供 /v1/messages 的网关），在 Codex 里照常使用 Claude 系列模型。

围绕日常使用的正确性，本版做了三波集中修复。代理桥：上游在 2xx 里返回的语义失败不再被转成空回复，而是触发 failover；推理内容、工具结果、system 角色跨 Responses↔Anthropic 桥无损往返；提示缓存断点注入更充分，长对话不再每轮全价重发。用量计费：缓存写入 token 此前被同时按输入价和缓存创建价双重计费，现已修正（数据库升级到 schema v13 以保证历史数据口径不乱）；用量与配额查询遇到网络瞬时失败会自动重试、不再把失败体当真实数据缓存。Codex config.toml：在应用里删掉的 MCP 服务器不再随供应商切换复活；live 文件解析失败时同步宁可报错也不再清空整个文件；「使用通用配置」的合并挪到后端执行，注释与键序不再被打乱。另有 Kimi For Coding 256K 窗口真正生效、Codex 子代理与免费版配额统计补齐、智谱团队套餐配额查询、OpenCode 表单增强与一批预设更新。

发布日期：2026-07-13

更新规模：69 commits | 172 files changed | +21,067 / -2,464 lines

---

重点内容

• 「项目」一键切换：把供应商、MCP、Skills、记忆文件整套保存为命名快照（比如编程一套、写作绘图一套），从主页顶部或托盘一键切换；切换时自动保存离开项目的当前状态。覆盖 Claude Code、Claude Desktop、Codex 三个作用域，互不干扰。
• Codex 官方账号也能走代理路由：ChatGPT 订阅登录的 Codex 会话可通过本地代理路由，获得与第三方供应商一致的路由与用量统计；官方登录凭据绝不被覆盖或存储。
• GPT-5.6 全面就位：Claude Code 走 Codex 接管时自动注入 372K 上下文窗口；Sol / Terra / Luna 三档定价入库（缓存写入按 1.25 倍输入价计费）；相关预设默认模型升级到 gpt-5.6 家族；修正客户端身份后 gpt-5.6-luna 不再误报 404。
• 在 Codex 里使用 Claude 系列模型（原生 Anthropic Messages 上游）：不少企业禁用了 Claude Code 客户端、但没有禁用 Claude API——现在把 Codex 供应商的上游格式选为 anthropic，即可直连 Claude API 或任何只提供 /v1/messages 的网关，本地代理完成 Responses↔Anthropic 双向转换，自带标准 5 分钟提示缓存注入。
• 代理桥正确性修复：上游失败 fail-closed 触发 failover 而非空回复；推理 / 工具结果 / system 角色跨桥无损；缓存写入不再双重计费；断点注入更充分。
• Codex config.toml 加固：删掉的 MCP 服务器不再复活；解析失败时 MCP 同步宁可报错也不清空文件；通用配置合并保留注释与键序。
• Kimi For Coding 256K 真正生效：此前的 262144 压缩窗口从未实际生效（被 Claude Code 的 200K 默认钳回），本版补齐模型别名路由与窗口注入；存量供应商需重新套用预设（见「升级提醒」）。

---

新功能

「项目」：整套配置的命名快照与一键切换

这是本版的头号功能。你可以把当前的供应商、MCP、Skills、记忆文件状态保存为一个命名「项目」，之后在主页顶部的项目切换器或托盘的「项目」子菜单里一键整套切换，不必再逐项手动勾选。

举个典型场景：你有一个目录用来编程、另一个目录用来写作或绘图。编程时要的是一套供应商，配上文件系统 / GitHub 这类 MCP、代码审查 Skills 和写着工程约定的记忆文件；写作或绘图时往往换另一家供应商、另一组 MCP 和完全不同的提示词。以前在两件事之间来回，意味着切供应商、逐个开关 MCP 和 Skills、再改记忆文件；现在把两套状态分别存成「开发」和「绘图」两个项目，换目录干活时在 CC Switch 里点一下，整套配置随之就位。

项目功能覆盖 Claude Code、Claude Desktop 与 Codex 三个作用域（Claude Desktop 由 CC Switch 管理的维度只有供应商，因此其快照只含供应商、应用时不动其它维度）。

几个值得了解的设计：

• 项目是全局实体、按作用域切换：同一个项目在 Claude Code / Claude Desktop / Codex 三侧各自记录自己的当前项目与快照槽位，在 Codex 页签切换项目绝不会动到 Claude 的配置。
• 切换即自动保存：切换项目前，会先把你正要离开的项目在当前作用域下的状态自动存回去——所以项目里保存的永远是你上次离开它时的样子，不需要（也没有）手动「更新快照」按钮。
• 应用是尽力而为的：套用快照复用现有的切换原语（先切供应商，再做 MCP / Skills 的最小差异开关，最后启用记忆文件）；快照里引用的某项如果已被删除，只会告警跳过，不会整体回滚。
• 自动关闭代理接管：套用项目前会先关闭该作用域内各应用的代理接管，避免快照状态和路由状态打架。

不用项目功能的用户可以在「设置 → 主页显示」里关闭「显示项目切换」，只隐藏主页入口，托盘子菜单与项目数据不受影响。底层由新的 profiles 表支撑（数据库自动迁移，无需手动操作），四语界面文案同步就位。

Codex 官方 ChatGPT 账号的代理路由接管

用 ChatGPT 订阅（OAuth 或 API-key 登录）的 Codex 会话，现在也可以走 CC Switch 的本地代理路由了——官方账号流量获得与第三方供应商一致的路由、格式转换与用量统计。在供应商面板或托盘里选择内置的「OpenAI Official」条目进行接管即可（如果你此前删掉过它，添加供应商时会自动恢复）；路由中的卡片徽标显示「官方账号路由中」。

实现上刻意做到零凭据存储：不向 auth.json 写任何占位密钥，而是往 config.toml 投影一个指向本地代理的专用 model_provider，Codex 把自己的 ChatGPT 授权头原样发给代理、代理原样透传给官方端点——codex-official 这一行的凭据永远是空的。官方登录本身绝不被覆盖：接管时 OAuth / API-key 材料会保留进备份；官方端返回的 401 / 403 被视为不可重试错误，failover 绝不会把你的对话悄悄挪到另一个账号上。相应地，「切换时保留 Codex 官方登录」这个设置项的文案已更新——路由接管场景下官方登录总是被保留，该开关现在只管不走路由的第三方直切。

GPT-5.6：上下文窗口、预设默认与三档定价

围绕 GPT-5.6 家族做了三件事：

• 372K 上下文窗口注入：Claude Code 经代理接管路由到 ChatGPT Codex（Codex OAuth）后端时，自动往生效的 settings.json 注入 CLAUDE_CODE_MAX_CONTEXT_TOKENS 与 CLAUDE_CODE_AUTO_COMPACT_WINDOW（均为 372000），让 Claude Code 不再按默认 200K 窗口过早自动压缩、也不再撑爆上游。注入门控严格：只有当所有已配置的模型键都指向 gpt-5.6 家族时才注入（gpt-5.5 的目录窗口在 272K / 372K 间摇摆，故意不继承）；你手动设置的值永远优先；切走时按镜像条件剥离，程序默认永远不会固化进你的供应商配置。
• 预设默认模型升级：Claude Code 与 Claude Desktop 的 Codex OAuth 预设默认路由升级到 gpt-5.6 家族（haiku → gpt-5.6-luna，主模型 / sonnet / opus → gpt-5.6），自定义 Codex config.toml 模板的默认模型同步跟进。
• Sol / Terra / Luna 三档定价：用量看板按官方价目为三档入库——Sol 5 / 30 / 0.50、Terra 2.50 / 15 / 0.25、Luna 1 / 6 / 0.10（美元每百万 token，输入 / 输出 / 缓存读）。与 5.5 及更早版本不同，5.6 家族的提示缓存写入按 1.25 倍输入价计费（Sol 6.25 / Terra 3.125 / Luna 1.25），已按此入库并自动修复此前按 0 计的存量行；裸 gpt-5.6 及各 effort 后缀变体按 Sol 价对齐。

在 Codex 里使用 Claude 系列模型：原生 Anthropic Messages 上游

这个功能来自一个很现实的诉求：不少企业出于合规策略禁用了 Claude Code 客户端，但并没有禁用 Claude API。对这些用户来说，模型本身是可用的，缺的只是一个被允许的客户端——现在 Codex 可以补上这个位置。在 Codex 供应商的上游格式选择器里选新增的 anthropic，即可直连 Claude API 或任何只提供原生 Anthropic Messages 协议（/v1/messages）的网关，本地代理完成 Responses↔Anthropic 的请求、响应与流式双向转换，你在 Codex 里照常对话、照常用工具，背后跑的是 Claude 系列模型。表单配套提供：认证字段选择器（ANTHROPIC_AUTH_TOKEN 发 Authorization: Bearer，默认；或 ANTHROPIC_API_KEY 发 x-api-key）、可选的 Claude Code 客户端伪装开关（默认关闭）、以及按供应商的最大输出 token 覆盖（Codex 不发 model_max_output_tokens，不设置时回退到保守的 8192，可能截断长回复或重思考回复）。转换桥自动注入标准 5 分钟提示缓存标记（系统提示、工具与历史走缓存而非每轮全价重发），支持 [1m] 长上下文标记并补发对应 beta 头，截断的流会如实上报为未完成而不是伪装成功。（#5071）

Codex 供应商表单新增「默认模型」输入框

config.toml 顶层的 model 键现在是表单里的一个可编辑字段：新模型（如 gpt-5.6）发布后，你可以直接把现有供应商指过去，不必等预设更新（预设只影响新添加的供应商）。字段与 TOML 编辑器双向同步，候选列表来自模型映射目录与供应商 /models 端点的并集，值不在目录里时提供一键「加入映射」。显式填写的值永远优先于映射第一行的隐式回填；模型名与 base_url 写入时做了 TOML 转义，杜绝 /models 返回的远端数据注入伪造配置行的可能。

通用配置切换自动同步扩展到 Codex

v3.16.5 给 Claude 加的「切走时自动把 live 配置里的共享偏好回写到通用配置」现在覆盖 Codex 了：切走一个启用了通用配置的 Codex 供应商时，会先从它的 live config.toml 重新提取可共享部分更新到通用配置，再带给下一个供应商——你直接在运行中的 Codex 配置里改的偏好不再在切换时丢失，删掉的键也不会被悄悄注回。提取器会严格剥离供应商专属与注入内容（model / model_provider / base_url / wire_api、整个 [model_providers] 表、MCP 投影、API key 兜底字段、模型目录指针与注入的 web_search 哨兵），密钥永远不会进入共享片段。所有失败仅告警、绝不阻断切换。

Claude 子代理模型配置

Claude 供应商表单新增「子代理」模型行，写入 CLAUDE_CODE_SUBAGENT_MODEL，让 Claude Code 派生的子代理跑在你指定的（通常更便宜或更快的）模型上。支持 [1M] 标记；由于子代理模型不会出现在 /model 菜单里，该行显示「不在 /model 中展示」占位而没有显示名字段。代理接管路径与模型映射器已同步支持：请求模型与配置的子代理模型一致时原样放行，不再被折叠到默认模型；该键也被排除在共享通用配置之外，不会跨供应商泄漏。（#4830）

回退模型字段的 1M 上下文复选框

Claude 表单的回退模型字段（ANTHROPIC_MODEL）现在带上了 Sonnet / Opus / Fable 各档早已有的 1M 复选框：回退模型背后是 1M 窗口时可以如实声明，不再被静默当作 200K。勾选即在模型 id 后追加 [1M] 标记，取消即剥离。（#5124，修复 #3679）

智谱团队套餐配额查询

智谱的团队套餐（团队版 Coding Plan）走同一个配额端点但需要 ?type=2 与两个额外请求头（bigmodel-organization / bigmodel-project），个人版查询够不到。用量脚本弹窗新增「Zhipu GLM Team（智谱团队）」模板，填入 API Key + 组织 ID + 项目 ID 即可查询团队配额；三项缺一会明确提示补全。四语文案同步。（#5128）

OpenCode 表单：请求头与模型 Token 上限编辑器

OpenCode 供应商表单补上了两块此前只能手改 JSON 的配置：Headers 编辑器（供应商级 options.headers，如 OpenRouter 排行榜要求的 HTTP-Referer / X-Title，支持增删行、大小写不敏感去重）与按模型 Token 上限（model.limit.context / model.limit.output 数字输入，清空即移除）。「额外选项」块改为可折叠区，已有内容时自动展开；顺带修复了旧占位符过滤会误删真实以 option- 开头的选项键的问题。（#2907）

新增模型定价：腾讯混元 Hy3

为 2026-07-06 发布的腾讯混元 Hy3（256K 上下文）入库定价（按发布日牌价 CNY 1 / 4 / 0.25 每百万 token 折算），hunyuan-hy3 与 hy3 两个 id 都能命中，其用量不再显示 $0。注意 Hy3 实际是按输入长度分档计费，当前单价表按最低档入库，长上下文请求会低估成本，待官方计费页明确后再修正。

---

变更

Codex Chat 路由注入 prompt_cache_key，提升缓存命中

Codex 经本地路由转换到 Chat Completions 上游时，现在会按供应商感知地注入 prompt_cache_key：Kimi Coding 与 OpenAI 官方端点自动启用、Kimi 预设显式开启，未知的 OpenAI 兼容网关保持关闭以避免严格 schema 网关报 400。键值只取显式客户端值或真实的客户端会话 ID，绝不生成随机 UUID（那会让每个请求落到不同缓存桶、适得其反）。高级选项里提供自动 / 启用 / 禁用三态覆盖。

Codex 图片能力自动推断，去掉手动开关

生成的 Codex 模型目录现在只把 CC Switch 确认过的精确文本-only 名录内的模型声明为 input_modalities = ["text"]；GPT、别名、新后缀变体和一切未知模型一律 fail-open 到 ["text", "image"]——修复了 GPT 系模型在 Codex IDE 扩展里被误报「不支持图片」的问题。整流器的「纯文本模型预检」开关继续只管代理侧的主动请求改写，不影响目录声明；目录反向导入也会把可推断的能力坍缩掉，未来名录修正或模型升级多模态时自动生效。

上下文窗口参数钉进预设，不再作为表单字段

Codex（ChatGPT / GPT-5.6）与 Kimi For Coding 预设不再在表单里展示「最大上下文 Tokens」「自动压缩窗口」两个输入框，数值直接钉死在预设 env 里（Codex 372000 / 372000，Kimi For Coding 262144 / 262144）——绝大多数用户从不需要碰这两个数字。两个键刻意保留在 env 里：显式钉住能让本地压缩触发点免疫远端实验性配置的下调。极少数想改数字的用户仍可在供应商的 JSON 编辑器里直接编辑这两个键。

供应商连通性配置简化

移除了过时的按供应商 testConfig 覆盖（超时、重试次数、降级延迟阈值）：轻量的 base_url 探测现在始终使用全局连通性检查配置，自动 failover 仍完全由代理超时与熔断器的独立设置驱动。设置界面与接口命名也从「模型测试」术语统一迁移到「连通性检查」。

通用（多应用）供应商添加后自动同步

通过「添加供应商」弹窗添加通用（多应用）供应商后，现在会立即推送到各 live 目标配置，不再需要手动再点一次同步。同步失败不阻塞添加——供应商已保存但同步失败时给出非阻断的警告提示。（#2811）

预设更新

• LongCat-2.0：美团 LongCat 预设全线（Claude Code / Claude Desktop / Codex / Hermes / OpenClaw / OpenCode）从已退役的 LongCat-Flash-Chat / LongCat-2.0-Preview 升级到 LongCat-2.0，声明真实的 1M（1048576）上下文窗口。LongCat-2.0 是纯文本模型，代理的媒体清洗白名单已同步收录——粘贴进会话的图片会被替换为不支持标记而不是被上游硬拒。（#4838）
• SudoCode：原 sudocode.us 预设原位替换为 sudocode.chat 的新赞助商 SudoCode，覆盖六个客户端（Claude 系直连 Anthropic 透传，Codex / OpenCode / OpenClaw / Hermes 默认 gpt-5.6-sol）。
• 火山 / 豆包 / BytePlus 官网链接：撤销了 v3.16.5 把这三个预设 websiteUrl 改为产品主页的改动，恢复为带归因参数的活动 / 邀请链接（这是有意为之的设计）。
• Code0.ai：邀请链接更新为新的 agent 注册链接；API 端点不变。
• 删除重复的 OpenAI Compatible 预设：OpenCode 与 OpenClaw 预设列表里的 OpenAI Compatible 自定义模板条目被移除——内置的 custom 供应商流程本就提供相同的起点，选择器里不再出现两个指向同一处的入口。存量供应商不受影响。

---

修复

Codex OAuth 客户端身份对齐：修复最新 ChatGPT 模型 404

用官方 Codex OAuth 账号经本地代理接管路由时，最新的订阅模型（如 gpt-5.6-luna）此前会返回误导性的 404 Model not found——明明账号有权限。根因是 ChatGPT 的 Codex 后端按 originator + version 头做模型分组路由，而 cc-switch 此前自报 originator: cc-switch 且不带版本号，被路由到一个 luna 尚未部署的分组。现在接管请求发送与真实 Codex CLI 一致的 originator: codex_cli_rs + version: 0.144.1，满足 luna 的最低客户端版本要求，经真实后端 A/B 实测确认修复。

Responses 上游失败不再变成空回复

代理把 Anthropic 格式客户端（Claude Code / Claude Desktop）桥接到 OpenAI Responses 上游时，上游藏在 HTTP 2xx 体里的语义失败（status:"failed" 对象、error 信封、首个输出前的 response.failed SSE 事件）此前会被转换成一个悄无声息的空回合。现在这些失败在重试循环内就被识别为真实错误，failover 能够换一个供应商重试；干净结束但内容不完整的流会如实标记为截断而非完成；无视 stream:true 直接返回整个 JSON 文档的网关也能被识别并展开为完整的流式生命周期；客户端历史本身格式错误时立即报错，不再拿着必败的请求把每个供应商都重试一遍。

跨 Responses/Anthropic 桥保留推理、工具结果与 system 角色

多轮工具循环里跨 Responses↔Anthropic 桥的内容不再丢失或损坏：加密的推理（reasoning）条目无损往返（往返失败会导致下一轮请求被上游拒绝的问题同步消除）；流式转换器支持官方的推理事件词汇表并在网关跳过增量时从终结事件恢复工具参数；结构化工具结果的 is_error 标志、图片与 PDF 文档在两个方向都完整保留，不再被压平成一个 JSON 字符串；历史里的 system / developer 消息被正确提升为 Anthropic system，不再被静默降级成用户发言。计费上，上游请求成功但后续转换失败时用量照记，不再漏账。

缓存写入 token 不再双重计费

Codex / Gemini 类供应商上报的 input_tokens 同时包含缓存读与缓存写，而成本计算此前只减掉了缓存读——缓存写入 token 被按输入价和缓存创建价计了两次费。现在两者都会先行扣除，并且缓存写入数字在跨格式转换（Chat↔Responses↔Anthropic）时不再丢失。为了让历史数据口径不乱，数据库新增一列记录每行 input_tokens 的存储语义（schema v12→v13 自动迁移）：旧行按旧口径回算、新行按新口径，Claude 类行不受影响。

更强的提示缓存断点注入

在注入 Anthropic cache_control 断点的代理路径上（Codex 接管桥与 Bedrock 原生优化器），注入器现在会更充分地使用四个断点预算：除了工具尾、系统尾与最新可缓存消息外，预算有余时再给较早的用户消息加一个锚点，让稳定前缀保持在 Anthropic 20 块回看窗口内——长的、工具密集的对话能持续命中提示缓存，而不是每轮把系统提示、工具与历史全价重发。调用方自带的断点被原样保留（绝不删除、重排或改写）；注入的标记一律使用标准 5 分钟 TTL。

Kimi For Coding 的 256K 上下文窗口真正生效

Kimi For Coding 预设在 3.16.4 加的 CLAUDE_CODE_AUTO_COMPACT_WINDOW=262144 其实从未生效：Claude Code 对不认识的模型 id 按 200K 窗口封顶，且压缩窗口取 min(模型窗口, 设定值)，262144 被钳回 200K。本版补齐了缺失的两环——预设同时钉上 CLAUDE_CODE_MAX_CONTEXT_TOKENS，并把各档模型显式路由到端点的 kimi-for-coding 别名（claude- 前缀 id 会让 Claude Code 无视这两个窗口参数，非 Claude 别名才是解锁大窗口的关键）。已保存的供应商在切换时也会自动注入这两个窗口默认值，但别名路由只存在于预设里——旧预设存下来的供应商实际仍是 200K，需要重新套用一次预设（见「升级提醒」）。

删除的 Codex MCP 服务器不再复活

MCP 服务器的权威数据在数据库里，Codex live config.toml 中的 [mcp_servers] 只是每次写入后重新同步的投影——但切走供应商时这份投影会被固化进供应商快照，导致你在应用里删掉的服务器在下次激活该供应商时死而复生，且逐条对账永远清不掉这个孤儿。现在切走时会把 [mcp_servers]（含旧式 [mcp.servers]）从存储快照中剥离，已被污染的快照在下次切走时自愈。一个可见的副作用：手写在 Codex 供应商配置里的 [mcp_servers.*] 段会在首次切走时被剥出快照——今后请通过 MCP 管理器定义 Codex 的 MCP 服务器（见「升级提醒」）。

MCP 同步更健壮：解析失败不清空文件、按应用报错

两处修复。其一，向 Codex 写入单个 MCP 服务器时，如果现有 config.toml 解析失败，旧逻辑会退到空文档再整体写回——整个文件被清空、只剩那一个 MCP 条目；现在直接返回校验错误并保持文件原样。其二，「从应用导入」此前把每个导入器的错误吞成 0，坏掉的 Codex 配置只会显示「导入了 0 个服务器」；现在逐应用尽力导入、失败时报出具体是哪个应用出了问题。切换与保存时的投影也改为只针对目标应用，一个应用的 live 文件解析失败不再连坐阻塞其它应用、也不再把已经成功的切换误报为失败。

Codex 通用配置合并保留注释与键序

Codex 供应商表单里勾选 / 取消「应用通用配置」此前走前端 TOML 实现整篇重排（解析 → 合并 → 序列化）：注释被丢弃、键被重排、还会凭空多出 [model_providers] 这类空表头——就是「config.toml 老被重排」的元凶。现在合并走后端命令、与写 live 配置共用同一套合并语义，手写格式在编辑期合并中完整幸存；针对异步化引入的快速切换竞态也加了双重守卫（操作序号 + 配置基线核对），先发后至的旧结果不会覆盖新状态。

受管 Claude 接管只注入单个 auth 占位符

从第三方端点切到 Codex 受管供应商时，~/.claude/settings.json 里会同时写入 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 两个占位符，导致 Claude Code 每次启动都警告「Both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY set」。现在只注入一个：Codex 受管走 ANTHROPIC_AUTH_TOKEN、Copilot 走 ANTHROPIC_API_KEY，其余 token 键一律清除。注意：升级后如果 live 配置已带着双键，由于「配置未变则跳过重写」的短路逻辑，警告可能仍在——把 Claude 路由开关关再开一次（或切换一次供应商）即可触发重写（见「升级提醒」）。（#5095，修复 #4919）

用量与配额查询：瞬时失败可自动重试、不再毒化缓存

用量与配额查询频繁出现手动刷新也清不掉的「查询失败」，根因是所有传输层失败（包括读响应体中途超时）都被折叠成了「成功但结果为失败」——前端的自动重试从不触发，失败体还被当作真实数据缓存。现在传输失败如实返回错误：react-query 自动重试生效，HTTP 429 与 5xx 一样按瞬时失败处理，保留的上次成功数据按 10 分钟窗口正常过期，失败状态下页脚保留重试入口与真实错误信息。（修复 #3820）

Codex 子代理会话用量计入本地统计

Codex 子代理（spawned agent）会话的 token 用量此前完全没进本地统计：子代理日志里携带的是父线程的 session_id，多个子代理的记录互相碰撞、被当作重复丢弃。现在解析器按每个文件自己的 thread_id 建立唯一身份，并识别子代理日志开头对父线程历史的重放、只用它恢复累计基线而不重复计费；归档日志也按文件名继承同步游标，重新解析只导入新增部分。（#5187）

Codex 免费版 30 天配额窗口正常显示

Codex 免费账号按 30 天滚动窗口计量（而非付费版的周窗口），但前端白名单和托盘分组都不认识 30_day 这个档位——免费账号唯一的档位被过滤掉后，配额页脚整个空白、托盘也不显示任何配额。现在 30 天档位在页脚和托盘都正常渲染，四语标签同步。（#4886，修复 #3651）

用量看板刷新间隔持久化

用量看板的自动刷新间隔此前是组件内状态，每次重启都重置回 30 秒。现在通过新的应用设置持久化，改动乐观生效、保存失败自动回滚。（#5057）

Fable 档模型键不再泄漏进通用配置

Fable 是 v3.16.3 加入的第四个 Claude 模型映射档，但它的 ANTHROPIC_DEFAULT_FABLE_MODEL(_NAME) 两个键漏在了供应商专属排除名单之外——某个供应商的 Fable 模型钉选可能泄漏进共享通用配置、再被注入到其它供应商。现已与 haiku / sonnet / opus 三档一样剥离，并顺带补全了 Fable 档的代理接管支持（接管时写入稳定的角色别名、切走时清理陈旧值）。（#5206，修复 #4272）

工具 schema 缺省 type 兜底与无分类供应商的 API Key 输入框

两个供应商侧修复：客户端发来的工具如果 input_schema 缺顶层 type（或干脆是空 {}），代理转换后会被严格网关拒绝，现在根 schema 自动补 type: "object"（只补根、不动嵌套子 schema）；历史导入或手工构建的无分类供应商在编辑时看不到 Claude API Key 输入框的问题也已修复——现在只要不是官方 / 云厂商类供应商就显示该字段。（#5069）

GLM 5.2 纯文本模型的图片请求兜底

本地代理接管火山 Coding Plan 跑 GLM 5.2 时，请求里的图片块不再产生一个无法恢复的 400：文本-only 名录精确收录 glm-5.2（刻意不用前缀匹配，未来的多模态 glm-5.2v 不受牵连），预防路径在请求到达前剥离图片；网关那句不含 image 字样的报错（Model only support text input）也被反应路径的自证短语名录识别，触发媒体兜底。（修复 #5025）

会话与 live 配置同步小修一组

• 显示重命名的 Codex 会话标题：在 Codex 里重命名过的会话，会话管理器现在显示新标题而不是回退到首条消息文本；并发写入时的读取也不再立即失败。（#4927）
• OpenCode / OpenClaw / Hermes 的 live 编辑在启动时同步入库：直接改 live 配置文件（换 base URL、加模型）此前在首次导入后就再也不会被拾取；现在每次启动时对比 live 与库存，差异即更新，全程非致命。（#4712、#5098）
• OpenCode 会话恢复命令更新：会话管理器展示与复制的恢复命令从过时的 opencode session resume <id> 更正为当前 CLI 的 opencode -s <id>。（#2359）
• 官方供应商跳过连通性探测：连通性检查不再对官方类供应商推导出一个无凭据必失败的第一方端点探测（例如裸打 chatgpt.com/backend-api/codex），批量检查直接跳过、单独解析明确报错。

---

文档

Codex + Kimi 本地路由攻略

新增分步攻略（中 / 英 / 日三语，含界面截图），讲解如何借助 CC Switch 的本地路由在 Codex CLI 里使用 Kimi：较新的 Codex CLI 走 OpenAI Responses 协议，而 Kimi 开放平台（按量付费，kimi-k2.7-code）与 Kimi For Coding（会员制，kimi-for-coding）暴露的都是 Chat Completions 端点，直连通常在 /responses 上 404。攻略覆盖从内置预设添加供应商到四步协议转换链的完整流程。

README 赞助商更新

开源 AI 基建项目 new-api 加入四语 README 的赞助商表。

---

升级提醒

Kimi For Coding 供应商需重新套用预设

如果你在用 Kimi For Coding 预设创建的供应商，请重新从预设选择一次并保存：256K 窗口的关键——把各档模型路由到 kimi-for-coding 别名——只存在于新版预设里，旧预设存下来的供应商即使升级后实际仍按 200K 窗口过早压缩。

手写的 Codex [mcp_servers.*] 会被剥出快照

为了根治「删掉的 MCP 服务器复活」，切走 Codex 供应商时会把 [mcp_servers] 段从存储快照中剥离。如果你有直接手写在某个 Codex 供应商配置里的 MCP 服务器，它会在首次切走该供应商时从快照消失——请改用 MCP 管理器（MCP 页签）定义 Codex 的 MCP 服务器，那里的条目才是权威数据、会被自动投影到 live 配置。

双 auth 键警告可能需要手动触发一次重写

如果升级后 Claude Code 仍提示「Both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY set」，这是因为 live 配置未变时接管逻辑会短路跳过重写。把 Claude 的路由开关关掉再打开一次（或切换一次供应商）即可写入修正后的单占位符配置，警告随之消失。

数据库自动迁移

首次启动 v3.17.0 时数据库会自动从 schema v11 迁移到 v13（新增项目表与用量语义列），无需任何手动操作。如果你有回退到旧版本的习惯，建议先备份 ~/.cc-switch/cc-switch.db。

---

风险提示

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

Codex OAuth 反向代理：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 v3.13.0 release notes。本版新增的「官方 ChatGPT 账号代理路由接管」同样属于此类用法，请知悉相同的风险。

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

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

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

---

致谢

感谢以下贡献者在 v3.17.0 中提交的功能与修复：

• #5071：新增原生 Anthropic Messages 协议作为 Codex 上游，感谢 @yeeyzy。
• #4830：新增 Claude 子代理模型配置，感谢 @AkimioJR。
• #5124：给回退模型字段加上 1M 复选框，感谢 @salarkhannn。
• #5128：新增智谱团队套餐配额查询，感谢 @zhanxin-xu。
• #2907：OpenCode 表单新增请求头与 Token 上限编辑器，感谢 @git1677967754。
• #2811：通用供应商添加后自动同步，感谢 @hubutui。
• #4838：LongCat 预设升级到 LongCat-2.0，感谢 @solthx。
• #5095：受管 Claude 接管只注入单个 auth 占位符，感谢 @fengshao1227。
• #5187：Codex 子代理会话用量计入统计，感谢 @starmiaoa。
• #4886：修复 Codex 免费版 30 天配额窗口不显示，感谢 @SaladDay。
• #5057、#4927、#2359：刷新间隔持久化、重命名会话标题显示与 OpenCode 恢复命令修正，感谢 @makoMakoGo。
• #5206：Fable 模型键排除出通用配置，感谢 @fzh365。
• #5069：工具 schema 缺省 type 兜底与 API Key 输入框恢复，感谢 @Komikawayi。
• #4712、#5098：OpenCode / OpenClaw / Hermes live 配置启动同步，感谢 @allenxu09。

也感谢所有反馈 Codex 官方路由、缓存计费、MCP 同步与配额查询问题的用户——本版相当一部分修复来自这些真实使用场景里的复现线索。

---

下载与安装

访问 Releases 下载对应版本。

系统要求

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

Windows

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

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

macOS

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