cc-switch

CC Switch v3.18.0

这一版你可以做两件全新的事：把 xAI 的 Grok CLI（Grok Build）交给 CC Switch 管理——它成为第八个受管应用，供应商一键切换、MCP / Skills 同步、代理接管与用量统计一应俱全；以及把 Grok 接进 Claude Code、Claude Desktop 和 Codex——既可以直接用 xAI Grok 账号登录（设备码授权、无需 API Key，跑你的 Grok 订阅，Codex 侧自带严格网关兼容层，codex 0.142+ 也能跑通），也可以用 xAI API Key 接入（Codex 有原生 Responses 直连预设，Claude Code 可走本地路由）。同样重要的是一波修复：v3.17.0 引入的 Codex 用量双计已修，升级后自动重建数据，看板数字恢复真实；codex 0.144.5+ 因模型目录无法启动的问题已修；Windows 上切换供应商不再闪黑窗、不再卡住界面。诊断日志也从「每次启动清空」变为跨重启持久保留、按大小轮转、全面脱敏，界面崩溃会落盘留证而不再只剩一片白屏。

English → | 日本語版 →

---

重点内容：你现在可以

• 管理 Grok Build（xAI 的 Grok CLI）：像管理 Claude Code / Codex 一样添加、导入、一键切换 Grok Build 的供应商；MCP 服务器与 Skills 双向同步、提示词首启自动导入、会话管理与用量看板全覆盖；还可以走本地代理接管，获得独立的路由、failover 与计费。
• 把 Grok 接进 Claude Code / Claude Desktop / Codex——账号登录与 API Key 双路径：订阅用户在「设置 → OAuth 授权中心」用设备码完成 xAI 账号登录（支持多账号），三个客户端直接跑你的 Grok 订阅、全程无需 API Key；按量付费用户则用 xAI API Key 接入——Codex 有现成的「xAI (Grok)」预设原生直连 api.x.ai，Claude Code 可按本版新攻略走本地路由接入。默认模型均为 grok-4.5。
• 把 Codex 的用量数字修回真实值：v3.17.0 的 fork / 子代理双计问题已在解析器层根治；升级后首次启动自动备份并重建 Codex 用量，用量页里也新增了手动「重建 Codex 用量」按钮。注意首次启动时历史记录是逐渐修复的——看板数字先变少、再随后台重导逐步回填，属预期行为（见「升级提醒」）。
• 放心升级 codex CLI：codex 0.144.5 起严格解析模型目录导致的「无法启动」已修复，生成目录会自动补齐解析器必需字段。
• 在 Windows 上顺滑切换：切换供应商 / 开关接管不再闪过黑色控制台窗口，也不再卡住界面约 2 秒（卡顿修复对全平台生效）。
• 更放心地排查与分享日志：诊断日志跨重启保留（20 MB × 4 轮转）、所有出口统一脱敏——URL 凭据、请求响应体、敏感请求头都不会再落盘；界面崩溃有错误卡片和重载按钮，错误详情写入磁盘。
• 多轮重推理、并行工具调用不再翻车：Responses↔Chat 桥修复了推理内容错挂、并行工具调用 ID 丢失 / 乱序、工具 schema 为 null 被严格上游整单拒绝三类问题。
• 用上 Kimi K3：Codex / Hermes / OpenClaw / OpenCode 的 Kimi 开放平台预设加入 K3（1M 上下文），内置定价同步入库，用量不再显示 $0。

---

使用攻略

本版新能力主要落在供应商预设、「设置 → OAuth 授权中心」与用量看板里，建议结合以下文档了解：

• xAI Grok 账号登录（设置 → OAuth 授权中心）：设备码登录流程、多账号管理与集成边界说明；使用前请先阅读下方「风险提示」中的客户端身份披露。
• 在 Claude Code 中使用 GPT 模型（本地路由攻略）：本版新增的中文分步攻略。Claude Code 始终对本地 /v1/messages 路由说 Anthropic Messages 协议，由本地代理把每个请求转换成上游的 Responses 协议——网关 API Key、xAI 这类原生 Responses 端点，或 ChatGPT 订阅的 Codex 服务都适用。
• 在 Codex 中使用 Claude 模型（本地路由攻略）：本版新增的三语分步攻略，配合 v3.17.0 的「原生 Anthropic Messages 上游」功能，把 Codex 接到任何只提供 /v1/messages 的 Claude 系网关。
• 用量统计：了解用量看板的数据来源与统计口径。本版修复用量双计并新增「重建 Codex 用量」维护操作。

---

[!WARNING]

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

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

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

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

---

概览

CC Switch v3.18.0 的两条主线都围绕 xAI Grok。第一条是 Grok Build 加入受管应用：xAI 的 Grok CLI（live 配置 ~/.grok/config.toml）成为与 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes 并列的第八个受管应用——供应商添加 / 导入 / 一键切换、MCP 与 Skills 双向同步、深链导入、独立预设列表，以及带专属路由命名空间的代理接管；配套的「Grok 官方」条目支持官方登录态识别与导入，CC Switch 绝不触碰官方凭据。第二条是 xAI Grok 账号 OAuth 登录：设备码授权替代 API Key，本地代理逐请求注入访问令牌，Claude Code / Claude Desktop 侧完成 Anthropic Messages → xAI Responses 转换；Codex 侧则提供受管 OAuth 预设并自带兼容层——codex 0.142+ 发出的 ChatGPT 后端私有形态（namespace 工具声明、私有字段）会被确定性地展平与剥离，严格解析的 xAI 网关不再返回 422；API Key 用户则另有一条「xAI (Grok)」原生 Responses 直连预设，不经任何转换。

围绕正确性，本版集中修复了 v3.17.0 的 Codex 用量双计：fork / 子代理日志开头对父线程历史的重放不再被当作新用量导入（解析器改为只认显式父身份 + 令牌签名对齐），升级后自动执行一次性用量重建（schema v16），用量页新增手动重建按钮；代理侧用量记录改为幂等（同一响应重放不再堆叠重复行），大量会话导入时用量页不再卡死。Codex 转换层另有四处修复：工具 schema 归一为 object 类型、推理内容跨轮前向附挂、流式并行工具调用保 ID 保序、生成的模型目录补齐 codex 0.144.5+ 必需字段。诊断体系也走向成熟：日志跨重启持久、按大小轮转、所有出口脱敏，界面崩溃被错误边界捕获并落盘。此外还有 Kimi K3 预设与定价、OpenClaw 预设成本修正、SudoCode.us 回归、托盘首启语言跟随系统等一批改进。

发布日期：2026-07-21

更新规模：52 commits | 217 files changed | +21,452 / -6,285 lines

---

新功能

Grok Build：第八个受管应用

xAI 的 Grok CLI（Grok Build，live 配置 ~/.grok/config.toml）现在是 CC Switch 的一等公民：供应商添加 / 导入 / 一键切换（切换后提示重启 Grok Build 生效）、应用显隐与配置目录覆盖设置、会话管理与用量看板覆盖、提示词首启自动导入、ccswitch:// 深链导入供应商，以及本地代理接管——拥有专属的 /grokbuild/v1/responses 路由命名空间、独立的 failover 队列与按应用代理设置；转发复用 Codex 的 Responses 通路，但绝不与 Codex 共享供应商命名空间或熔断状态。

MCP 服务器与 Grok 的 [mcp_servers] 表双向同步，方言差异已被抹平：Grok 靠 command / url 推断传输类型且用 headers 字段，导出时会剥掉显式 type 并把 http_headers 重命名为 headers，导入时反向推断回来。Skills 也获得 Grok Build 启用开关。

预设方面刻意没有借用 Codex 列表（早期版本曾把国产直连供应商和 Codex 默认模型漏进 Grok 表单），而是独立整理了一份：只收录真正承载 Grok 模型的聚合与中转站，默认模型归一为 grok-4.5（命名空间路由站为 x-ai/grok-4.5）。工具面板安装 Grok 优先走 xAI 官方安装器（x.ai/cli/install.sh / install.ps1），npm 包 @xai-official/grok 作为兜底；被确认是原生安装的走 grok update 自更新，npm 安装保持 npm 锚定更新——自更新门控在「确定检测为原生」上，绝不会误伤另一种安装。四语界面文案同步就位。（#5453）

Grok 官方登录：识别、导入与保护

新增「Grok 官方」供应商条目，对应 Grok CLI 自带的 xAI OAuth 登录：选中它会隐藏连接字段并写入一个空的 ~/.grok/config.toml，CC Switch 从不存储、也从不触碰官方凭据。live 配置的读取、备份与官方态写入改用仅语法级的 TOML 校验，官方登录态（空配置）可以正常往返；Grok 处于官方登录态时「从 live 导入」会得到「已设 Grok 官方为当前」而不是报错，与 Codex 行为一致。官方态识别刻意只接线到手动导入命令——启动时的自动导入器仍会拒绝官方态配置，所以你删掉的「Grok 官方」条目绝不会在下次启动时复活。对官方登录配置的代理接管会被自动跳过，手动路径给出明确拒绝，与现有「不代理官方供应商」的策略一致。

用 xAI Grok 账号登录：Claude Code 与 Claude Desktop

Claude Code 与 Claude Desktop 新增「xAI (Grok)」预设，用 OAuth 设备码登录代替 API Key：请求经本地代理完成 Anthropic Messages → xAI Responses API 转换并逐请求注入访问令牌，各档默认模型都是 grok-4.5（Claude Desktop 预设把 claude-* 形式的角色 ID 映射到上游 grok-4.5，以通过 Desktop 的第三方模型校验）。

「设置 → OAuth 授权中心」新增 xAI 区块：设备码登录（用户码带复制按钮、验证链接、等待 / 取消 / 重试）、多账号与默认账号选择、按账号移除、重授权徽标——刷新令牌被吊销的账号会以「已过期」状态保留可见而不是消失，授权状态每 15 秒自动刷新，服务端吊销会自己浮现出来。

集成边界是钉死的：无论表单里的端点 / 格式字段怎么改，上游始终是 https://api.x.ai/v1/responses（Responses 格式）；OAuth 端点经 OIDC 发现解析，但强制校验为 https 的 auth.x.ai；刷新令牌存于 ~/.cc-switch/xai_oauth_auth.json（Unix 上 0600；访问令牌只存内存）；OAuth 错误响应体绝不进入错误信息或日志。grok-4.5 定价（$2 输入 / $6 输出 / $0.50 缓存读，每百万 token）同步入库，用量不再记 $0，存量数据库下次启动自动补行。四语文案同步。使用前请阅读「风险提示」中的客户端身份披露。

不用 OAuth、只有按量付费的 xAI API Key？同样能接进 Claude Code：xAI 的 API 端点就是标准 Responses 协议，把它当作一个普通的 Responses 供应商添加——自定义供应商填 https://api.x.ai/v1 与 API Key、上游格式选 Responses，经本地路由完成 Anthropic Messages ↔ Responses 转换，与〈在 Claude Code 中使用 GPT 模型〉攻略是同一套玩法。Codex 侧则有现成的 API Key 预设，见下一节。

Codex 直连 xAI：OAuth 受管与 API Key 原生双预设

Codex 获得两条直连 xAI 的路——有 Grok 订阅走 OAuth 受管，有 API Key 走原生直连：

• 「xAI (Grok) OAuth」受管预设：让 Codex 跑在 Grok 订阅上。表单隐藏密钥 / 端点 / 格式字段、显示账号选择器，「获取模型」用已登录账号发起；供应商被钉死为原生 Responses，base URL 与逐请求令牌由代理强制执行——改了也会被忽略，受管路由无法被重定向。由于 codex 0.142+ 会发出 ChatGPT 后端私有的请求形态（type:"namespace" 工具声明会让 xAI 严格解析器直接 422，另有 prompt_cache_retention、safety_identifier、external_web_access、additional_tools 载体字段和 grok-4.5 不支持的采样参数），OAuth 路由在原生透传上加了一层兼容层：namespace 工具被展平为顶层 function 工具（与 Chat 路径同款 sha256 截断命名）、响应侧流式与非流式都还原回 namespace 形态，不支持的字段被剥除——全部是确定性的字段删除 / 结构提升，绝无语义改写，prompt 缓存前缀保持稳定。兼容层只门控在 xAI OAuth 供应商类型上，任何其它供应商的流量都不受影响。
• 「xAI (Grok)」API Key 预设：直连 api.x.ai/v1 的原生 Responses，自带 500K 上下文的 grok-4.5 目录条目。该预设不会应用上述 xAI 专属兼容转换——codex 0.142+ 的 API Key 用户仍可能撞上 xAI 的严格解析器，OAuth 预设才是完全兼容的路径。

xAI OAuth 的令牌失败被归为不可重试错误，failover 绝不会把你的对话悄悄挪到另一个 Grok 账号上。

界面崩溃捕获：错误落盘与重载页

React 错误边界现在包住整个界面（包括数据库恢复界面）：渲染进程崩溃时显示「界面出错了」卡片和重载按钮，而不是一片白屏；全局 error / unhandledrejection 处理器把渲染端错误持久化到磁盘——此前一次 JS 崩溃在盘上零证据。前端写出的所有日志经过两层脱敏：结构化序列化器按敏感属性名（tokens / apiKeys / credentials 等变体归一匹配，整值含嵌套对象一起隐藏）与值形态（令牌前缀、PEM 头、高熵不透明串）脱敏，再经唯一文本出口的有序正则链覆盖 URL 查询值与凭据、认证头与 scheme、命名密钥容器（双重编码的 JSON 也覆盖）。字符串形态到达的 JSON 会被重新解析后做结构化脱敏；超大结构化输入整体丢弃而非截断——截断的 JSON 串会退化到较弱的文本正则，可能泄漏。设置里的开关文案也改为名副其实：「应用诊断日志」（cc-switch.log）与代理的「记录请求用量」（统计数据库，本来就不是文本日志）。四语同步。

「重建 Codex 用量」维护按钮

用量看板的维护区新增「重建 Codex 用量」：备份数据库后，只清除 codex_session 来源的明细行、对应的 _codex_session 日汇总与 Codex 同步游标，然后用修正后的解析器从头重导所有 rollout 文件——这是被下述双计 bug 污染的数据库的恢复路径，也是父日志恢复后延迟 fork 文件的重试路径。手动重建在备份写不出时会硬失败（自动迁移版只告警，因为在升级后因备份目录不可写而卡死启动是更糟的结局）；整个「备份 → 重置 → 重导」序列持有会话同步锁，60 秒后台同步无法与清除交错；完成时保证恰好发出一次前端刷新通知——包括重导为零行或失败的路径——看板绝不会停留在重置前的数字上。游标清理按路径形态匹配（sessions / archived_sessions 段下的 rollout-{uuid} 文件名），旧 CODEX_HOME 下记录的游标也能清到。四语同步。

会话导入可观测性：延迟文件与疑似重复

会话同步结果现在报告 filesScanned、deferredFiles——父日志缺失或父标记冲突的 fork rollout 会被搁置且不写游标，等后续同步或手动重建重试，而不是靠猜导入——以及 suspectedDuplicates：插入后逐行探测是否已存在同指纹行（走 idx_request_logs_dedup_lookup_expr 表达式索引），每次命中记一条警告。双计 bug 未来若复发，会在日志里自己喊出来，而不是无声地吹大总数。

Kimi K3 预设与定价

Codex / Hermes / OpenClaw / OpenCode 的 Kimi 开放平台预设加入 Kimi K3（1M 上下文窗口），追加在 K2.7 Code 之后，现有默认模型行为不变。内置定价表新增 kimi-k3（官方牌价 $3 输入 / $15 输出 / $0.30 缓存读，每百万 token）与裸 k3 别名——Kimi For Coding 订阅上报的模型短 id 是 k3，否则匹配不到任何定价行（与现有 hunyuan-hy3 / hy3 同款先例）。存量数据库下次启动自动补齐两行，不碰用户改过的定价。

SudoCode.us 回归，与 SudoCode.chat 并存

两家恰好同名「SudoCode」的无关公司现在是两个独立预设：赞助商更名为「SudoCode.chat」，此前被原位替换掉的「SudoCode.us」带着原有端点、模型与图标回归，Hermes slug 也做了区分，两者可在累加式的 ~/.hermes/config.yaml 中共存。算上新的 Grok Build 预设列表，SudoCode.chat 覆盖七个应用、SudoCode.us 覆盖全部八个。

---

变更

诊断日志：跨重启持久、按大小轮转、绝不记录密钥

cc-switch.log 不再在每次启动时被清空——过去能解释崩溃的日志，等应用重开时已经没了——改为 20 MB 轮转、保留 4 个归档（上限约 100 MB，对比过去单文件可膨胀到 1 GB）；此前无上限的 crash.log 改为 5 MB 轮转、保留 2 个归档，检查 / 轮转 / 追加序列在同一把锁下，并发 panic 不会丢归档。

日志持久化让明文密钥成为真实的暴露面（用户会把日志附到公开 issue 里），所以同一批改动里把后端所有日志出口都做了清洗：上游 URL 只记剥掉 userinfo / query / fragment 的形式（没有已知密钥可替换时只记 origin，因为凭据可能嵌在路径里）；请求与响应体一律不记——换成字节数、短哈希或安全分类（sse / html / json-like / binary-or-encoded 等），排查转换问题的信号还在、内容没了；响应头走白名单（名单外只记名字）；正在使用的密钥值（API Key、访问令牌）会从任何携带它的 URL 里被替换掉；MCP 自定义字段值一律省略。日志插件注册提前（更新器 / 启动期故障可诊断），持久化的日志级别在数据库打开后立即生效、故障时收敛到 Info，「启用诊断日志」开关现在也管前端发起的日志写入。升级前的旧日志文件不会被追溯清洗——见「升级提醒」。

预设选择器：赞助商分组，其余按名称排序

预设选择器的默认顺序改为四层：官方最前，其次首要合作伙伴，然后是赞助商预设（与 README 赞助商表同序，预设文件已物理重排对齐），最后所有其余预设按显示名字母序排列，不再按文件序。命中多层的条目只落在最早一层，不会重复出现。

预设「获取 API Key」链接更新

RunAPI、ClaudeCN、ZetaAPI、APINebula 预设的密钥申请链接更新为各家当前的注册 / 推荐页（ClaudeCN 同时迁移了域名：claudecn.top → claudecn.ai）。推荐标签仅限这些链接与 README——官网链接和 API 端点保持不动。

---

修复

Codex fork / 子代理不再把重放的父历史当新用量（v3.17.0 双计根治）

修复 v3.17.0 的用量膨胀：fork 一个 Codex 任务或以复制模式派生子代理时，父对话的 token 历史被当作新用量重复计入——有用户报告单日用量跳涨数十亿 token、父子行字节级相同、空 fork 背着从未消耗过的用量。fork / 子代理的 rollout 文件开头会重放父线程历史，旧解析器靠启发式找接管边界（第一个 thread_settings_applied 事件、对象形态的 subagent 来源标记）：父线程自己的设置变更出现在重放里时边界落得太早，而当前字符串形态的来源标记则完全识别不到，整段父历史被原样导入。新解析器只认显式父身份——子方 session_meta 上的 forked_from_id 或 source.subagent.thread_spawn.parent_thread_id，两者冲突时搁置该文件——线程身份锚定到 rollout 文件名 UUID，加载父 rollout 自己的 fork 前 token 计数序列，用令牌签名对齐剥掉子方的重放前缀：重放事件只用于恢复累计基线，绝不插行。不带重放历史的子代理日志现在按真实用量计入，反方向的漏计（真实子代理消耗被当作疑似重放跳过）同步修复。（#5335、#5433、#5381）

代理用量记录改为幂等：响应级稳定键

终态用量事件不带消息 id 时（经本地代理的 Codex /responses 流量是常态），去重键此前回退到随机 UUID——同一上游响应的每次重试 / 重放都造一个新键，INSERT OR REPLACE 每次都堆一行新的；有用户的数据库里同一用量组合出现了 2,078 次。解析器现在从响应信封本身取键——Codex response.completed 事件的 response.id（丢弃 response.created 的 id）、Chat Completions 的 chatcmpl id、Gemini 的 responseId——并按 session:{app_type}:{provider_id}:{id} 作用域化：failover 时同一响应打到不同供应商仍按供应商各记一次、互不碰撞（Claude 保持裸 session:{id} 形态，代理行继续与会话日志导入合流）。完全没有信封 id 时，兜底从响应的用量语义做确定性 SHA-256——相同重放必须撞进同一个键，去重才成立——最终写库也从无条件 REPLACE 改为去重窗口内的「不存在才插入」。（#5496）

大量会话导入时用量页不再卡死

导入大批会话时打开用量页可能整个卡住：每插入一行就发一次刷新通知，每次通知让前端重跑全部约 10 个用量查询，这些查询又与正在逐行解析几十 MB rollout 文件的导入器争抢唯一数据库连接——在被重复行吹大的数据库上三者互相放大。现在会话同步改为每轮完成只通知一次；所有会话导入器串行在单飞锁后（手动「立即同步」排队等待运行中的一轮，而不是与之竞争）；阻塞式解析挪到专用阻塞线程，不再饿死驱动界面命令的异步运行时；60 秒后台节拍错过就跳过，不再突发补跑。

codex 0.144.5+ 不再因 CC Switch 生成的模型目录无法启动

codex ≥ 0.144.5 严格解析外部模型目录，条目缺 supports_reasoning_summaries 时整个文件被拒——Codex CLI 和桌面端都起不来，删掉生成目录也没用，因为任何一次供应商保存都会按同样方式重新生成。根因是 CC Switch 从机器共享的 models_cache.json 克隆目录模板，而它的字段集取决于最后写它的那个 codex 进程——共存的旧版 codex 一直在用缺字段的形态重写缓存。生成目录现在会从内置静态模板回填解析器必需字段，且只在缺失时回填（动态值永远优先）；「缺失即解析器默认值」的可选能力字段刻意不回填，语义必须保留。

Windows：切换供应商不再闪黑窗、不再卡死

Windows 上切换供应商或开关接管会闪过一个控制台窗口、界面卡住约 2 秒。三个原因、三处修复：codex debug models --bundled 探测经 cmd.exe 启动 codex.cmd，GUI 子系统应用里这会弹出自己的控制台——子进程现在带 CREATE_NO_WINDOW 创建；模型目录模板此前每次切换都重新生成——现在首次成功加载后进程级缓存（失败保持可重试，坏的首次探测不会毒化缓存），Codex CLI 每次应用运行至多启动一次；switch_provider 此前是跑在主线程上的同步命令——现在异步化、真实工作在阻塞线程上，仍由按应用切换锁串行。卡顿修复对全平台生效，闪窗修复是 Windows 专属。

工具 schema 为 null / 缺失 / 联合类型不再被严格上游整单拒绝

Codex 内置工具（如 codex_app__automation_update）声明 parameters: null（或 type: null），DeepSeek 这类严格的 OpenAI 兼容上游会对整个请求返回 400，经代理路由的工具会话直接被杀。Responses→Chat 桥现在把每个工具的 parameters 归一为 type:"object" schema：null 或缺失（含嵌套形态的缺失）变为 {"type":"object","properties":{}}，非 object 的 type（含 type: null）原位纠正为 "object"，顶层 oneOf 联合 schema 补根 type:"object"、分支原样保留。同样的 object 类型保证扩展到了 Codex→Anthropic 工具路径的 input_schema。已有的 properties / required 绝不丢弃。（#4706、#5315，修复 #4705、#4783）

推理模型在多轮 Codex Chat 对话中保住思考

推理模型（如 kimi-k2-thinking）走代理的 Responses→Chat 桥时，多轮历史会弄坏思考内容：每轮的 reasoning 条目被粘到上一条助手消息的尾巴上，紧随的助手轮反而没有 reasoning_content——模型会肉眼可见地中途断片。Responses 语义里推理位于它所属消息之前，桥现在把推理前向附挂到其后的助手消息或工具调用上；真正的尾部推理只在确凿的尾部（输入结束，或用户消息这样的轮次边界——此前在这里会被静默丢弃）向后附挂，并追加到已内嵌的推理之后；悬挂中的推理在边界处必被消费，绝不会跨过用户轮泄漏进后面的助手消息。（#5508）

流式并行工具调用保住 ID 与顺序

Chat→Responses 流式桥的两个 bug 会弄坏「身份分散在多个 chunk」的上游发来的并行工具调用：携带空 id 的续传增量会覆盖真实 call_id（Codex 客户端看到 call_id:""，工具结果对不上调用）；工具调用各自就绪就立即发出，名字先到的靠后索引能插到靠前索引前面——并行调用被重排。现在空 id 一律忽略；发射经过连续索引闸门，严格按 Chat index 顺序放行，未识别的靠前索引没就绪就等待；流中途绝不合成假 call id（只在流终结时作为最后手段，且防御性跳过无名调用、稀疏索引照常发出）。（#5310）

受管 OAuth 供应商可靠地标记为「需本地路由」

「需路由」徽标与切换时警告此前由供应商的 API 格式推导，对受管 OAuth 供应商（Copilot、Codex OAuth、xAI）这是错误信号——它们的凭据由代理注入、与上游格式无关，原生格式的受管供应商拿不到警告、不开接管就静默失败。路由需求现在由唯一共享谓词决定：官方供应商永不需要路由，受管 OAuth 供应商恒需要，格式规则只适用于其余情况。切换时的门槛也按应用查对了就绪信号：多数应用查按应用接管状态（旧门槛只看全局代理运行标志，漏掉「代理在跑但当前应用没被接管」），Claude Desktop 继续看代理进程本身——后端接管状态没有 Claude Desktop 字段，统一按应用查会让 Desktop 永远弹警告。Claude Desktop 供应商表单对所有受管 OAuth 类型强制代理模式并锁定模型映射开关，不再只对 xAI。四语同步。

Node 装在 nvm / fnm / mise 里时工具更新可用

锚定的 npm 更新与修复命令按绝对路径调 npm，但 npm 启动器靠 #!/usr/bin/env node shebang 从 PATH 找 node——GUI 启动的应用只继承系统 PATH，不含版本管理器目录，nvm / fnm / mise 安装的工具更新静默失败。现在每个锚定 npm 调用都把 npm 自己的同级 bin 目录前置到 PATH，npm 与它的 shebang 解析到同一个 Node；Codex 自修复（卸载 + 重装）路径同样覆盖。

删除的默认 Skill 仓库不再复活

默认 Skill 仓库此前每次启动被「补齐缺失默认项」逻辑重新播种，删掉的默认仓库下次启动又静默回来。播种改为按数据库一次性，用设置标志记录；升级时已有仓库的数据库直接置标志、不再补种，现有选择不受影响。（#5356）

托盘首启语言跟随系统

设置里还没选过语言时，托盘菜单被硬编码为简体中文——英文 / 日文 / 繁中系统上主界面正确跟随系统语言、托盘却不一致，直到用户手动切一次语言。托盘现在按与前端相同的优先级从系统 locale 推导首启语言（含 zh-TW / zh-HK / zh-Hant → 繁体中文）；显式选择的语言永远优先，locale 读不到时照旧回落中文。（#4355）

导入失败显示真实错误并刷新列表

每次「从 live 配置导入」失败都弹一个空错误提示，因为 Tauri 的 invoke 以后端错误字符串拒绝，而处理器从它上面读 .message。现在显示后端真实报错（带本地化的通用兜底），失败时也会刷新供应商列表——报错前已提交的副作用立即可见。

OpenClaw 预设模型成本修正为官方牌价

15 个 OpenClaw 预设条目的成本值单位错误或未换汇——cost 字段是美元每百万 token，例如 glm-5.1 记成 0.001/0.001（低估约 1000 倍，用量成本近乎 0），deepseek-v4-pro 则带着未换算的人民币值（高估）。所有条目改为官方牌价 $/M；订阅套餐与免费档端点也刻意展示牌价，套餐用户能看到自己用量的标准价值。今后从预设新建的供应商拿到修正值；已创建的供应商保持创建时的配置。

界面小修一组

• AiHubMix 图标：Codex 应用的 AiHubMix 预设此前缺品牌图标字段、渲染成通用图标，现与其它应用一致。
• 两个缺失文案键补齐：Codex「因使用 Anthropic Messages 格式需要路由」提示里的原因片段此前在非中文界面显示中文（proxyReasonAnthropicMessages 不存在于任何语言文件）；供应商表单的密钥状态加载标签自 4 月起只有硬编码默认值。两者已在 zh / en / ja / zh-TW 全部补齐。

---

文档

Codex ↔ Claude 双向路由攻略

两篇新攻略把「Codex 客户端用 Claude 模型」「Claude Code 客户端用 Responses 供应商」补成了双向：

• 在 Codex 中使用 Claude 模型（中 / 英 / 日三语，含截图）：配合 v3.17.0 的原生 Anthropic Messages 上游，把 Codex 接到 Claude 系 /v1/messages 网关；v3.17.0 的 release notes 已回链本攻略。
• 在 Claude Code 中使用 GPT 模型（中文，含截图）：用 Responses 协议的供应商（网关 API Key，或 ChatGPT 订阅的 Codex 服务）驱动 Claude Code——Claude Code 始终对本地 /v1/messages 路由说 Anthropic Messages，由代理把每个请求转换成上游的 Responses 协议。

README 赞助商更新

SubRouter 加入四语 README 赞助商表；置顶的 Kimi 赞助文案更新到 K3、横幅改由 Moonshot CDN 提供；RunAPI 权益文案刷新，赞助商行序与应用内预设顺序对齐。

---

升级提醒

数据库自动迁移与 Codex 用量一次性重建

从 v3.17.0 升级会连续执行三次 schema 迁移（v13 → v16）：v14 重建 proxy_config 表以纳入 Grok Build（现有按应用代理设置全部保留，并新增 grokbuild 行）；v15 给 MCP 服务器表与 Skills 表加 Grok Build 启用列；v16 触发一次性的 Codex 用量自动重建——数据库先备份到 backups/ 下，codex_session 数据与游标被重置，随后正常的启动同步用修正后的解析器重导全部数据。典型数据量只需数秒；实测最重的数据集（1,801 个 rollout 文件 / 1.5 GB）约 65 秒。之后的启动照旧增量。若有回退旧版本的习惯，建议先自行备份 ~/.cc-switch/cc-switch.db。

首次启动时请留意：历史记录的修复是逐渐完成的——重建随启动同步在后台进行，这段时间里用量看板的 Codex 历史数字会先清零、再逐步回填，属预期行为，不是数据丢失。重建完成后的总数通常会比升级前更小：被双计吹大的那部分被挤掉了，剩下的才是真实用量。

重建的边界

• 重建从 rollout JSONL 文件重新计算用量，源日志已被删除的历史无法重建。
• 父 rollout 缺失的 fork 文件会被搁置并报告，而不是靠猜导入；恢复父日志后运行「重建 Codex 用量」可补导。
• 历史上代理来源的重复行会永久保留——迁移只重建会话来源的数据，不存在针对过往代理膨胀的清理逻辑；幂等记录只保证从此不再产生新重复。

旧日志文件不会被追溯脱敏

诊断日志从本版起不再在启动时清空、跨重启持久保留（运行日志轮转上限约 100 MB，另有约 15 MB 崩溃日志）。早期版本写下的日志文件不会被追溯清洗，可能含有 API Key、令牌或带凭据的 URL——公开分享前请先检查升级前的旧日志。

Grok Build 安装走官方安装脚本

安装或重装 Grok Build 现在优先使用 xAI 官方安装器，安装时会外联获取 x.ai/cli/install.sh（Windows 为 install.ps1），npm 作为兜底；已有的 npm 安装继续经 npm 更新。

内置定价自动补行

新定价行（grok-4.5、kimi-k3、k3）在下次启动时按「不存在才插入」自动追加；用户编辑过的定价行绝不被覆盖。

---

风险提示

xAI Grok OAuth 登录（本版新增，请阅读）

本版的 xAI Grok OAuth 集成复用官方 Grok CLI 注册的公开 OAuth 客户端身份与权限范围（client_id b1a00492-073a-47ea-816f-4c329264a828，scope 含 grok-cli:access），而不是 CC Switch 自己注册的应用身份。xAI 可能不支持这种用法，使用可能导致账号被限制或封禁——风险自担。该功能完全可选：不添加 xAI 供应商，一切照旧。首次登录会创建 ~/.cc-switch/xai_oauth_auth.json（仅存刷新令牌，Unix 上权限 0600；访问令牌只存内存），并经你配置的出站代理访问 auth.x.ai 与 api.x.ai，无本地回调端口。

沿用的反向代理类提示

Codex OAuth 反向代理：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 v3.13.0 release notes。

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

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

---

致谢

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

• #5453：Grok Build 一等公民支持（第八个受管应用的主体实现），感谢 @YUZHEthefool。
• #5508：Responses→Chat 桥推理内容前向附挂，感谢 @ka79376046。
• #5310：流式并行工具调用保 ID 保序，感谢 @SaladDay。
• #5315：Codex 工具 parameters 归一为 object schema，感谢 @Komikawayi。
• #4706：严格 OpenAI 兼容上游的工具类型归一，感谢 @Ryan2128。
• #5356：删除的默认 Skill 仓库不再复活，感谢 @allenxu09。
• #4355：托盘首启语言跟随系统 locale，感谢 @LaiYueTing。
• #5138：后端 CI 扩展到 Linux / Windows / macOS 三平台，感谢 @zayokami。

也感谢所有反馈 Codex 用量异常、codex 新版启动失败与工具调用问题的用户——本版最重要的几个修复都来自这些真实场景里的复现线索。

---

下载与安装

访问 Releases 下载对应版本。

系统要求

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

Windows

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

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

macOS

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

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 里使用 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

CC Switch v3.16.5

这一版的重头戏是让原生 Responses 格式的国产模型供应商真正适配到位——为小米 MiMo、火山豆包、千问 Qwen3-Coder、美团 LongCat、MiniMax 等具备原生 Responses 端点的供应商生成 Codex 模型目录，让 Codex 桌面能看到这些模型、内置工具也能正常工作，并对少数拒收 web_search 的国产网关自动禁用该工具、避免请求被硬性拒绝。另有两处重要改进：切换供应商时，你在应用内新增的插件、环境变量等会自动回写到通用配置并带给下一个供应商；Linux（Wayland + NVIDIA）上「标题栏能点、页面点不动、缩放黑屏」的问题，现在也能用一个环境变量开关自救。本版还带来 Claude Sonnet 5 定价与默认档升级、两级分组的会话视图，以及一批凭据安全与平台兼容修复。

English → | 日本語版 →

---

使用攻略

本版的新能力主要落在 Codex 供应商表单、会话面板与用量 / 通用配置里，建议结合以下文档了解：

• Codex 桌面看不到自定义模型？：本版重做了原生直连时的模型目录生成——当 Codex 供应商使用原生 Responses（openai_responses）直连时，CC Switch 会生成 ~/.codex/cc-switch-model-catalog.json，让 Codex 桌面能显示配置的自定义模型、工具也可用。若你此前配过原生 Codex 供应商，请重新保存一次以生成新目录（详见下方「升级提醒」）。
• 用量统计：了解用量看板的数据来源与统计口径。本版新增了 Claude Sonnet 5 定价，并修复了用量脚本凭据被当作「显式覆盖」持久化的问题。
• 设置：Codex 上游格式选择器与本地路由开关、Claude 通用配置（现更名为「应用通用配置」并支持切换时自动同步）都在供应商表单的高级选项里。

---

[!WARNING]

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

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

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

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

---

概览

CC Switch v3.16.5 是 v3.16.4 之后的一版维护更新，核心是把国产模型供应商的 Codex 原生直连做通。v3.16.4 已经把千问 / 百炼、小米 MiMo、火山豆包、美团 LongCat、MiniMax 等供应商切到了原生 Responses 端点，本版进一步为它们生成 Codex 所需的模型目录（~/.codex/cc-switch-model-catalog.json），让 Codex 桌面真正能看到这些自定义模型、内置工具也能正常调用，并把模型映射从「本地路由」开关里彻底解耦。针对少数第一方模型不支持 OpenAI 内置 web_search 的国产网关（MiMo、LongCat、MiniMax、Qwen3-Coder），本版还会自动禁用该工具，避免 Codex 默认带上它触发硬 400。

围绕日常使用体验，本版让 Claude 的通用配置在切换供应商时自动同步并传递——你在应用内新增的插件、环境变量、主题等会先回写到通用配置、再带给下一个供应商，不会在切换时丢失；给 Linux（Wayland + NVIDIA）上点击失灵 / 黑屏的用户加了一个可自救的环境变量开关；补上 Claude Sonnet 5 定价并把默认 Sonnet 档升级到它；带来「供应商 → 项目目录」两级分组的会话视图；并修了一串凭据安全（通用配置片段剥离全部密钥、用量脚本凭据仅作显式覆盖）、平台兼容（Hermes Windows 配置目录、Windows Codex npm 影子命令）与界面（长下拉滚动、窄窗口日期选择器）的问题。此外也新增了若干供应商预设，开箱即可选用。

发布日期：2026-07-01

更新规模：36 commits | 93 files changed | +5,678 / -2,804 lines

---

重点内容

• 让国产模型供应商的 Codex 原生直连真正可用：为小米 MiMo、火山豆包、千问 Qwen3-Coder、美团 LongCat、MiniMax 等国产供应商生成 Codex 模型目录（~/.codex/cc-switch-model-catalog.json），让 Codex 桌面能看到这些模型、内置工具可用；并对拒收 web_search 的国产网关（MiMo、LongCat、MiniMax、Qwen3-Coder）自动禁用该工具、避免硬 400。存量原生供应商需重存一次以生成新目录。
• 通用配置切换时自动同步并传递：切走一个启用了通用配置的 Claude 供应商时，你在应用内新增的插件、环境变量、主题、hooks 会先自动回写到通用配置，再带给下一个供应商——不再在切换时被覆盖丢失。
• Linux Wayland 点击失灵 / 黑屏的自救开关：遇到 Wayland + NVIDIA 上「标题栏能点、页面点不动、缩放黑屏」时，用 CC_SWITCH_GDK_BACKEND=wayland 启动即可切回原生 Wayland（平铺式合成器上遇到反向问题可设为 x11）。
• Claude Sonnet 5：新增 Sonnet 5 定价，并把各预设的默认 Sonnet 档升级到 claude-sonnet-5。
• 会话分类视图与分组管理：会话面板新增「供应商 → 项目目录」两级分组视图，分组头支持三态复选框一键批量选择。
• 新增供应商预设：新增七牛云、FennoAI、ZetaAPI、TeamoRouter、NekoCode、Code0.ai、Amux 等供应商预设，覆盖各受管应用，开箱即可选用。

---

新功能

国产模型供应商的 Codex 原生直连（生成模型目录）

本版把国产供应商的 Codex 原生直连做通了。继 v3.16.4 把小米 MiMo、火山豆包、千问 Qwen3-Coder、美团 LongCat、MiniMax 等供应商切换到原生 Responses（apiFormat: "openai_responses"）之后，本版推翻了当时「原生直连就删掉模型目录」的做法：这些供应商不经过本地代理直连时，CC Switch 会为它们生成 ~/.codex/cc-switch-model-catalog.json，让 Codex 桌面真正显示这些自定义模型、内置工具也能用——不会触发像 MiMo 这类原生网关会拒绝的 freeform apply_patch（type=custom）工具（编辑回退到 shell_command）。目录生成按 apiFormat 判定、与「本地路由」开关解耦，因此一个原生供应商无需开启本地路由映射也会持久化目录；而 openai_chat 格式仍保持既有的 Responses↔Chat 代理转换不变。由于 Codex 解析器要求每个条目都带 base_instructions，原生模板携带一个中性默认值、由各厂商官方文案覆盖（MiMo、MiniMax）。存量原生供应商需重新保存一次以生成有效目录（无需数据库迁移）。

配套地，对少数第一方模型不支持 OpenAI 内置 web_search 工具的国产网关（MiMo、LongCat、MiniMax、Qwen3-Coder），本版会在切换时自动禁用该工具，避免 Codex 默认带上它、被网关以硬 400 拒绝（详见下方「修复」）。

会话分类视图与分组管理

会话管理面板在原有平铺列表之外新增了分组视图，通过工具栏的 List / ListTree 选择器切换，视图模式与展开状态都持久化到 localStorage。分组构建「供应商 → 项目目录」两级层级：按项目目录名归组，缺少项目目录的会话落入「未知目录」桶。两级都是可折叠区块，并提供「全部折叠」按钮；在批量模式下，每个分组头会出现一个三态复选框，可一键选中 / 取消该组内全部可选会话，并显示已选 / 可选计数徽标。四语（zh / en / ja / zh-TW）文案已同步。该改动完全在前端，不涉及后端命令或数据访问层。（#4776）

Claude Sonnet 5 模型定价

在 schema.rs 里按 Anthropic list 价新增 claude-sonnet-5 定价行——输入 / 输出 $3 / $15 每百万 token、缓存读写 $0.30 / $3.75，与 Sonnet 4.6 一致。介绍期 $2 / $10 促销（有效期至 2026-08-31）刻意不入表，让记账反映稳态 list 价而非临时折扣。该行在应用下次启动时通过 ensure_model_pricing_seeded 应用，无需 SCHEMA_VERSION 变更。

新增供应商预设

本版新增了一批供应商预设，选中后填入自己的 API Key 即可使用：

• 七牛云（Qiniu）：覆盖全部 7 个受管应用（含 Gemini），中转原生 Claude / GPT / Gemini。
• FennoAI / ZetaAPI / TeamoRouter / NekoCode：各覆盖 6 个应用（Claude、Claude Desktop、Codex、OpenCode、OpenClaw、Hermes）。
• Code0.ai：覆盖全部 7 个应用（含 Gemini）。
• Amux：覆盖 6 个应用。

各预设的端点与默认模型已按对应应用配好——Claude 类走 Anthropic 兼容主机直连、Codex 走原生 Responses、其余走 OpenAI 兼容 /v1。

---

变更

切换供应商时自动同步并传递通用配置

这是本版一个很实用的改动：切走一个启用了通用配置的 Claude 供应商时，服务会先从它的 live settings.json 里重新提取可共享部分、更新到通用配置，再带给下一个供应商，而不再只是单向写入。这样一来，你在运行中的应用里直接新增的插件（enabledPlugins）、hooks、环境变量（env）、主题（theme）等共享配置就不会在切换时被静默丢失，而是自动跟着走到下一个供应商；删除也会同步（移除的键不会被再次注入）。该同步严格限定在启用了通用配置的 Claude 供应商，被显式清空时会跳过，且所有失败都是非致命（仅告警）、永不阻断切换。

Codex 模型映射与「本地路由」开关解耦

Codex 供应商表单向 Claude Code 对齐——模型映射目录现在独立于路由接管，因为原生 Responses 供应商（MiMo、豆包、MiniMax）需要它来做无代理直连，而 Chat 供应商无论如何都走代理。「需要本地路由」开关被移除（它没有后端字段，只是门控目录 / 推理的持久化，等价于「映射是否填了」）。模型映射现在对非官方供应商始终显示、非空即持久化，而推理能力的显示 / 持久化改由 Chat 格式门控。四语（zh / en / ja / zh-TW）文案随之重写。顺带修复了 useCodexConfigState 在加载已存供应商时丢掉 supportsParallelToolCalls / inputModalities / baseInstructions 的问题（会在编辑时静默丢失并行工具、图像输入与官方 base instructions）。

默认 Sonnet 档升级到 Claude Sonnet 5

把各供应商预设里的默认 Sonnet 档从 claude-sonnet-4-6 升级到 claude-sonnet-5（覆盖 claude / claude-desktop / hermes / openclaw / opencode 预设与通用 NEWAPI_DEFAULT_MODELS），涉及 ANTHROPIC_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL / ANTHROPIC_DEFAULT_OPUS_MODEL 等键及其带前缀变体。Claude Desktop 的默认路由 sonnet route_id 也一并迁移到 claude-sonnet-5。非 Anthropic 的 pin（gpt / gemini / glm / sonnet-4-5）保持不变。

豆包带日期 model id 与定价归一化

豆包（DouBaoSeed）预设的 model id 切换到带日期的 doubao-seed-2-1-pro-260628（覆盖各应用），因为火山方舟会以 404 拒绝裸名 doubao-seed-2-1-pro、只接受完整带日期 id。由于真实用量现在带日期后缀，strip_model_date_suffix 扩展为也能剥掉火山的 6 位 YYMMDD 形式（并校验月 01-12、日 01-31 以免误伤 -123456 这类非日期版本后缀），从而归一化命中定价表里的裸名 seed 行、修复豆包模型显示 $0 成本的问题。

###「写入通用配置」更名为「应用通用配置」

原标签「写入通用配置」在数据流向上有歧义（读起来像「把当前配置写进通用配置」），而实际行为相反——是把已存的通用配置片段合并进本供应商配置。复选框在四语（zh / en / ja / zh-TW）里更名为「应用通用配置」，包括所有提示 / 攻略 / 说明引用，日文用户手册与 README_JA.md 也一并同步。（#4829）

其它预设与资源调整

• OpenClaw 豆包上下文对齐 262144：OpenClaw 的 DouBaoSeed 预设此前硬编码 128000，而 Codex 侧同模型用 262144，导致 OpenClaw 用户窗口偏小；已对齐并加了跨预设一致性测试防止再次漂移。
• 火山 / 豆包 / BytePlus 官网链接订正：这三个预设的「访问官网」链接被误设成了控制台 / 注册链接，已恢复为干净的产品主页。
• 过大的供应商图标降采样到 256px：一批捆绑图标此前远大于其 ~32px 的实际渲染尺寸，降采样后显著减小体积、无代码 / 文件名 / 导入改动（如 ZetaAPI 940KB→40KB、relaxcode 1.16MB→42KB），并删除了从未被引用的 1.4MB dds.svg 孤儿。

---

修复

对拒收 web_search 的原生 Codex 网关禁用该工具

一些原生 /responses 网关的第一方模型不具备 OpenAI 内置的 web_search 工具，会以「tool type 'web_search' is not supported」拒绝，而 Codex 默认就会带上该工具，导致硬 400。CC Switch 现在会为这些厂商写入顶层 TOML 行 web_search = "disabled"。作用域是一份黑名单（默认开启）：仅命中 base_url 主机（xiaomimimo.com、longcat.chat、minimax.io、minimaxi.com）或模型品牌前缀（mimo、longcat、minimax、qwen3-coder）的供应商会被禁用，因此中转真 GPT、豆包、通用 Qwen 及任何未知供应商都保持 Codex 默认。其中 qwen3-coder 前缀只压制原生 qwen3-coder-plus（百炼 / DashScope 对 coder 系标记内置工具不支持），共享同一主机的通用 Qwen 保持开启；匹配走模型轴（会剥掉聚合器的 vendor/ 路径段），因此也能兜住硅基流动这类中转拒收厂商模型的情形。选黑名单而非模糊的「是不是 GPT」白名单，是因为误让 web_search 保持开启会以硬 400 失败；同时用归属哨兵保证 CC Switch 只会移除由它自己写入的 disabled 值，因此存量供应商无需重存、切回也会重新启用。此外顺带把 LongCat-2.0-Preview 预设的上下文窗口从 131072（128K）订正为真实的 1048576（1M）。

通用配置片段剥离全部凭据类键

extract_claude_common_config 此前只脱敏 ANTHROPIC_API_KEY 与 ANTHROPIC_AUTH_TOKEN，但 Claude 供应商合法地携带其它凭据（OPENROUTER_API_KEY、GOOGLE_API_KEY，可能还有 OpenAI / Gemini / AWS Bedrock / Vertex 密钥），这些可能泄漏进共享片段、再被注入到其它供应商。提取现在会按模式匹配并剥掉任何凭据形态的环境变量键（*_API_KEY / *_AUTH_TOKEN / *secret* / *token* 等），同时保留 MAX_OUTPUT_TOKENS 这类合法可共享的复数 *_TOKENS 值。手动「提取」与一次性自动提取路径的同一泄漏也一并堵上。

用量脚本凭据仅作显式覆盖持久化

供应商用量脚本存有可选的 api_key / base_url 字段用于查询配额时覆盖 live 凭据，但它们此前会静默镜像供应商自身的凭据——因此复制供应商或修改主 API key / base URL 后，用量脚本仍 pin 在旧端点旧 key，配额查询一直打向陈旧目标。现在 ProviderService 在持久化前会归一化：若脚本的 api_key 或 base_url 与供应商解析出的用量凭据相同（或为空）就清为 None，让查询回退到 live 配置；真正不同的覆盖才保留（token_plan 类脚本不动）。deeplink 导入路径也加了对应的归一化，前端在更新时会失效相关缓存键让首页用修正后的配置重新查询。（#4654）

Hermes 配置目录在 Windows 上正确解析

CC Switch 此前硬编码 ~/.hermes 作为 Hermes 配置目录，但 Hermes 自身是按 HERMES_HOME 环境变量、再退到平台默认（Windows 上 %LOCALAPPDATA%\hermes）解析的。在 Windows 上这意味着 CC Switch 把供应商配置写到了 Hermes 根本不读的路径，导致供应商切换无效。get_hermes_dir() 现在镜像 Hermes 自己的解析顺序——显式覆盖、HERMES_HOME（原样取用、不做 ~ 展开）、平台默认——从而重新尊重被 #3470 丢掉的 HERMES_HOME（Hermes 的 Windows 安装器把它作为重定位安装的首要机制）。（#4680，参见 #3178、#3470）

Linux Wayland：允许覆盖 AppImage 强制的 GDK_BACKEND=x11

AppImage 的 GTK 启动钩子无条件导出 GDK_BACKEND=x11 以规避一个历史上的原生 Wayland 崩溃。在较新的 Wayland + NVIDIA 环境上，这个被强制的 XWayland 会让 WebKitGTK 网页内容收不到指针事件（标题栏可点、页面却死了）、并在缩放时黑屏，而既有的 WEBKIT_DISABLE_* 缓解不起作用，因为根因是被强制的窗口后端而非渲染。main.rs 现在会在 GTK 初始化前读取一个可选的 CC_SWITCH_GDK_BACKEND 逃生开关（AppImage 的启动钩子从不改动它）：不设保持现状（零回归）。遇到上述问题时，用它切回原生 Wayland 启动即可：

CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage

该覆盖是通用的——若你在平铺式 Wayland 合成器上遇到的是反向的输入问题，则改设为 CC_SWITCH_GDK_BACKEND=x11。（#4351，修复 #4350）

Claude Desktop / OpenClaw / Hermes 表单显示「获取 API Key」链接

API key 输入框下的「获取 API Key」链接与合作推广块此前只对 claude / codex / gemini / opencode 生效。Claude Desktop 渲染的是不显示它的裸输入框，而 OpenClaw / Hermes 则被两处遗漏挡住（白名单只列了那四个 appId、供应商分类解析只认那四类预设 id 模式）。现在 Claude Desktop 改用共享的 ApiKeySection，白名单与分类解析都补上了 claude-desktop / openclaw / hermes；此外 Hermes / OpenClaw 表单不再让「官方」分类禁用 key 输入（这两个应用没有只走 OAuth 的官方供应商，如 Hermes 的 Nous Research 虽是官方但仍需用户自填 key）。

去重 Windows 上的 Codex npm 影子命令

在 Windows 上，npm 会把一个工具装成三个同名兄弟文件——codex.cmd、codex.exe 和一个无扩展名的 Unix shim codex——而 CC Switch 此前把三者都列为候选，导致无法直接执行的无扩展名 shim 被当作多余 / 失败候选去探测。现在仅当相邻没有可执行的 .cmd / .exe 兄弟时才追加无扩展名路径，路径解析也会优先选可执行的 .cmd / .exe，从而把版本探测与启动锚定到真正可运行的 Windows shim 上。（#4782）

长下拉列表的滚动边界

SelectContent 弹层此前用 overflow-hidden 且没有高度上限，因此选项很多的下拉（如长模型 / 供应商列表）会渲染得比视口还高、把溢出项裁掉且无法触及。现在它设了 max-h-[min(24rem,var(--radix-select-content-available-height))] 与 overflow-y-auto，把内容限制在 24rem 或 Radix 计算出的可用高度内并允许纵向滚动。（#4798）

日期范围选择器的日历在窄弹层里保持可见

自定义日期范围选择器此前按视口宽度（Tailwind sm: 640px 断点）切换两列布局（日期字段 | 日历），但弹层被夹在 100vw - 2rem 且锚定到触发器，实际可用宽度比视口窄。在窄窗口上，两列布局可能在弹层只放得下一列时被激活，把日历列挤出右边界裁掉（月份头与 7 列里的 4 列被切掉且无法触及）。现在布局改用 CSS 容器查询按弹层自身的行内尺寸切换，因此只有当弹层本身窄时才收成一列，让日历在任意窗口宽度下都完整可见。（#4860）

---

文档

CC_SWITCH_GDK_BACKEND 逃生开关文档

为可选的 CC_SWITCH_GDK_BACKEND 环境变量新增了 FAQ 条目，覆盖全部四种 README 语言与 zh / en / ja 用户手册的排障页，说明 Wayland + NVIDIA 用户如何在网页内容「点击失灵 + 缩放黑屏」时切回原生 Wayland，以及平铺式 Wayland 用户如何设为 x11 处理反向输入问题。

Kimi 海外 README 指向 platform.kimi.ai

英语、德语、日语 README 的 Kimi K2.7 Code 合作段落的横幅与内联行动号召改指 https://platform.kimi.ai?aff=cc-switch（保留推荐标签），四语 README 也都新增了一行指向 https://www.kimi.com/code/?aff=cc-switch 的 Kimi For Coding 订阅推广。

---

升级提醒

原生 Codex 供应商需重存一次

本版重做了原生 Responses 直连的模型目录生成。如果你此前配过使用原生 Responses（openai_responses）的 Codex 供应商，请重新从预设选择或打开该供应商并保存一次，以生成新的 ~/.codex/cc-switch-model-catalog.json——这样 Codex 桌面才能显示自定义模型、工具才可用。此过程无需数据库迁移，也不影响走 openai_chat 格式的供应商。

web_search 黑名单是默认行为

对小米 MiMo、美团 LongCat、MiniMax、千问 Qwen3-Coder 这些已知拒收 web_search 的原生网关，本版会在切换时自动写入 web_search = "disabled"。中转真 GPT、豆包、通用 Qwen 及未知供应商不受影响、保持 Codex 默认。该开关由 CC Switch 用归属哨兵管理，切回到未命中黑名单的供应商会自动恢复，无需手动干预。

默认 Sonnet 档变化

新从预设创建的 Claude 类供应商，其默认 Sonnet 档现在指向 claude-sonnet-5。已配置好的存量供应商不受影响、配置保持原样；如需改用 Sonnet 5，可重新从预设选择一次并保存。

---

风险提示

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

Codex OAuth 反向代理：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 v3.13.0 release notes。

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

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

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

---

致谢

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

• #4776：新增会话分类视图与分组管理，感谢 @alkaid616。
• #4829：把「写入通用配置」更名为「应用通用配置」，感谢 @arichyx。
• #4654：让用量脚本凭据仅作显式覆盖持久化，感谢 @yyhhyyyyyy。
• #4680：修复 Windows 上 Hermes 供应商配置不生效，感谢 @thisTom。
• #4782：去重 Windows 上的 Codex npm 影子命令，感谢 @justjavac。
• #4798：修复长下拉列表无法滚动，感谢 @xwil1。
• #4351：允许通过 CC_SWITCH_GDK_BACKEND 覆盖 AppImage 强制的 GDK_BACKEND=x11，感谢 @BoneLiu。
• #4860：让日期范围选择器的日历在窄弹层里保持可见，感谢 @SaladDay。

也感谢所有在 v3.16.4 发布后反馈 Codex 原生直连、通用配置、凭据复用与平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。

---

下载与安装

访问 Releases 下载对应版本。

系统要求

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

Windows

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

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

macOS

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

🎉 CC Switch 跻身 GitHub 全球 Star 排行榜前 100！ 感谢每一位用户、贡献者与 Star —— 是你们让它走到这里。🙏

继 v3.16.3 把「用量计费做准」之后，这一版把重心放在打磨 Codex 代理链路与丰富用量 / 定价工具上——国产供应商原生 Responses 迁移、上游格式选择器与模型映射解耦、zstd 请求 / 错误体解压，以及一批工具调用与 OAuth 走代理的修复；同时新增本地代理请求覆盖、数据库版本过新时的应用内恢复屏、原生 Windows ARM64 构建，并带来一波预设与品牌更新（SubRouter、OpenCode Go、CTok→ETok 改名、Kimi 品牌刷新与 prime-partner 徽标）。

English → | 日本語版 →

---

使用攻略

本版以打磨与扩展为主，新增的能力主要落在用量面板与供应商表单的高级选项里，建议结合以下文档了解：

• Codex 桌面看不到自定义模型？：不少用户反馈在 Codex 桌面应用里看不到配置的第三方 / 自定义模型。这是 Codex 桌面应用上游自身的门控行为（按官方登录状态放行模型选择器），并非 CC Switch 的本地配置问题，本版（v3.16.4）未对此做改动；文档里说明了原因，以及可用的缓解办法（保留官方登录 + 路由接管）。
• 用量统计：了解用量看板的数据来源与统计口径。本版新增了从 models.dev 批量导入模型定价、火山方舟 Coding / Agent Plan 的 AK/SK 用量查询，以及自定义日期范围的「实时结束时间」。
• 设置：本地代理请求覆盖（自定义请求头 / 请求体）、Codex 上游格式选择器与本地路由开关等都在供应商表单的高级选项里。

---

[!WARNING]

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

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

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

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

---

概览

CC Switch v3.16.4 是 v3.16.3 之后的一版维护更新。这一版围绕 Codex 代理链路做了一轮收紧——为多家具备原生 OpenAI Responses 端点的国产供应商切换到原生格式（省去 Responses→Chat 的路由接管转换）、把「上游格式」从「本地路由」开关里独立出来、补上 zstd 请求与错误响应体的解压，并修了一串工具调用与「OAuth 模块绕过全局代理」的问题。

与此同时，本版还丰富了用量与定价工具（从 models.dev 导入定价、火山方舟 Coding / Agent Plan 的 AK/SK 用量查询、自定义日期范围的实时结束时间、GLM-5.2 与豆包 Seed 2.1 定价），新增了一批代理与韧性能力（自定义请求头 / 请求体覆盖、数据库版本过新时的应用内恢复屏、原生 Windows ARM64 构建），并带来一波预设与品牌更新（SubRouter 与 OpenCode Go 订阅、CTok→ETok 改名、Kimi 品牌刷新与 prime-partner 徽标、Kimi K2.7 Code 赞助横幅）。

发布日期：2026-06-27

更新规模：53 commits | 126 files changed | +8,149 / -1,016 lines

---

重点内容

• 国产 Codex 供应商走原生 Responses：千问 / 百炼、小米 MiMo、火山豆包、美团 LongCat、MiniMax（国内 / 国际）现在直连各自的原生 Responses 端点，不再经过 Responses→Chat 的格式转换接管，链路更短、更稳。
• 本地代理请求覆盖：供应商可配置自定义请求头与请求体覆盖，由本地代理在转发时应用，并对受保护的安全请求头做了拦截校验。
• 数据库版本过新的应用内恢复屏：当 SQLite 版本比当前应用支持的更新时，不再死在「重试只会再次失败」的原生弹窗里，而是引导到一个可一键升级应用的恢复界面。
• 更丰富的用量 / 定价工具：从 models.dev 批量导入模型定价、火山方舟 Coding / Agent Plan 的 AK/SK 用量查询、自定义日期范围的「实时结束时间」，以及 GLM-5.2 与豆包 Seed 2.1 的定价。
• 新预设与品牌更新：新增 SubRouter 与 OpenCode Go 订阅预设，CTok 改名为 ETok，刷新 Kimi 品牌标识并为官方 Kimi 预设加上 prime-partner 心形徽标。
• 原生 Windows ARM64 构建：发布产物新增原生 ARM64 版本，ARM 架构的 Windows 设备不再依赖 x64 模拟。

---

新功能

数据库版本过新时的应用内恢复屏

当 SQLite 的 user_version 比当前应用支持的 SCHEMA_VERSION 更新时（例如降级回旧版、或被第三方客户端写过该文件），启动过去会死在一个原生的「重试 / 退出」弹窗里——而「重试」只会再次失败。现在应用会引导到一个专门的恢复界面：有可用更新时提供一键「升级应用」按钮（下载 + 安装 + 重启，带进度条），没有可用更新时则提示即便是最新版也读不了这个数据库。该「版本过新」检查在任何写库动作之前进行，因此应用永远不会对一个读不懂的数据库执行 DDL；恢复模式下的原生关闭会干净退出（此时托盘尚未创建）。（#4575）

本地代理请求覆盖（自定义请求头与请求体）

供应商配置现在可以定义自定义请求头与请求体覆盖，由本地代理在转发时应用，并通过 Claude 与 Codex 供应商表单里的新字段暴露。输入会经过校验，其中包含一份受保护的请求头名单，用于阻止覆盖安全敏感的请求头。（#4589）

火山方舟 Coding / Agent Plan 用量查询

用量面板现在可以查询火山方舟（Volcengine Ark）的 Coding Plan 与 Agent Plan 配额。由于方舟控制面 OpenAPI（open.volcengineapi.com）要求的是账号级 AccessKey 签名、而非推理 API key，用量脚本新增了独立的 AK/SK 输入区，并配有一个直达火山 IAM 密钥管理控制台（https://console.volcengine.com/iam/keymanage）的可点击链接；代理实现了火山签名 V4（一个 AWS SigV4 变体：固定的 canonical header 顺序、HMAC-SHA256 算法、ark 服务 scope）。它会先探测 GetAFPUsage（Agent Plan 的 5 小时 / 周 / 月配额）自动判定套餐，失败再回退到 GetCodingPlanUsage，从 Level 字段解析窗口标签（并对 ResetTimestamp <= 0 做守卫），同时在用量页脚、托盘菜单与四种语言里补上了 monthly 档标签。

从 models.dev 导入模型定价

「添加定价」面板新增了一个「从 models.dev 导入」按钮：拉取 https://models.dev/api.json，支持全文搜索整个目录，并通过与手动录入相同的 update_model_pricing 路径导入所选条目。导入的 model id 会按后端的 clean_model_id_for_pricing 规则归一化（剥供应商前缀、转小写、截断 : 后缀、把 @ 映射为 -、丢掉 [1m] 标记），让落库的行真正能匹配成本归因查询。配套修复让「按范围回填零成本」改用 Rust 端按原始 model 别名（路由前缀、:free 变体、日期后缀）匹配，而不再用精确 SQL 字符串匹配，从而新定价的别名行能立刻被计价、而不必等下次启动回填（修复 #4017）。（#4079）

原生 Windows ARM64 构建

发布产物现在包含原生的 Windows ARM64 制品，ARM 架构的 Windows 设备可以拿到对应的原生构建，不必再依赖 x64 模拟。发布矩阵也改为各平台独立运行（关闭 fail-fast），因此某个任务缺少密钥而失败（例如 fork 里的 macOS 签名）不会再把尚未完成的同级任务一并取消。（#3950）

自定义日期范围的实时结束时间

自定义日期范围选择器新增了一个「结束时间跟随当前时间」勾选框；开启后结束时间变为只读并自动跟随此刻，因此用量数据始终反映从所选起点到当下的实时消耗。这在 Coding Plan 的 5 小时配额窗口里尤其有用。liveEndTime 已纳入 React Query 的缓存键，因此一个实时范围和一个端点相同的固定范围不会再共用同一个陈旧缓存项。（#4438）

会话详情头显示源文件名

会话详情头现在会在项目目录旁显示会话日志的文件名（悬停看完整路径、可点击复制），方便用户直接从界面定位并打开底层的 JSONL 文件。对于像 ~70 字符的 Codex rollout 这类没有空格的长文件名，会截断到 max-w-[200px]，避免在窄窗口里溢出到操作按钮区。（#4113）

导入按钮的未托管 Skill 提示

顶栏的 Skills 导入按钮现在会在本地存在未托管的 Skill 可导入时显示一个绿点与提示，让你一眼看出磁盘上的 Skill 还没被纳管。该扫描在挂载时执行一次，并在多次导航间共享（30s staleTime + keepPreviousData），避免重复磁盘 IO。

OpenCode Go 订阅预设

新增 OpenCode Go（opencode.ai/zen/go）预设，覆盖 Claude、Codex 与 OpenCode，使用可直接粘贴的纯 API key（无 OAuth）。Codex 预设走 openai_chat 转换并带 GLM / Kimi / DeepSeek / MiMo 模型目录（且不带静态 codexChatReasoning，按每个模型推断能力），OpenCode 则通过 @ai-sdk/openai-compatible 指向 /zen/go/v1。四个 OpenCode Go 预设——Claude、Claude Desktop、Codex、OpenCode——都带上了推荐链接与应用内推广文案；推广横幅现在仅凭 partnerPromotionKey 即可展示（不再绑定 isPartner），因此一个预设可以展示推荐推广却不获得金色付费合作伙伴星标（这也顺带让既有的 MiniMax 推广重新显示出来）。

Prime-Partner 预设徽标与排序

第一方 Moonshot Kimi 预设（Kimi / Kimi For Coding / Kimi K2.7 Code）现在被标记为 prime partner：不再显示金色星标，而是渲染一颗实心金色心形（无徽标边框），并在默认（Original）排序里浮到官方分类预设之后、其余之前。分组用三路 partition 实现，每组保持内部顺序，且一个同时被标为 prime-partner 的官方预设只会留在官方组里。

GLM-5.2 与豆包 Seed 2.1 定价

种子模型定价现在包含 GLM-5.2（#4385）与豆包 Seed 2.1 Pro / Turbo，让这些模型的用量被正确计价、而不是记成零成本。豆包价格采用火山官方 list 价（按约 7.14 的汇率折算）；cache_creation 保持为 0，因为豆包按时间而非按 token 写入计费缓存存储，既有的 2.0 行也保留以供历史记账。

Kimi For Coding 自动压缩窗口

Kimi For Coding 预设现在把 CLAUDE_CODE_AUTO_COMPACT_WINDOW 默认设为 262144，与 Kimi 官方文档一致，并通过 templateValues 暴露，方便用户为将来的模型或性能调优自定义该值。（#4401）

SubRouter 合作伙伴供应商

新增 SubRouter（subrouter.ai，一个让一把 key 访问多模型多供应商的 AI 中转聚合商）作为预设，覆盖全部 7 个受管应用——Anthropic 格式端点用于 Claude Code / Claude Desktop / OpenClaw / Hermes，OpenAI 兼容的 /v1 端点（gpt-5.5）用于 Codex 与 OpenCode，Gemini 兼容的 /v1beta 端点（gemini-3.5-flash）用于 Gemini CLI——带上自有品牌图标、金色合作伙伴星标、四语推广文案，以及预填为 API key 注册地址的推荐注册链接（?aff=l3ri）。（#4522）

---

变更

国产 Codex 供应商走原生 Responses API

多家国产供应商（千问 / DashScope 百炼、小米 MiMo、火山豆包、美团 LongCat、MiniMax 国内 / 国际）现在暴露了原生的 OpenAI Responses 端点，因此它们的 Codex 预设切换到 apiFormat: "openai_responses"，直连上游而不再经过 Responses→Chat 的路由接管转换。丢掉不再需要的 codexChatReasoning 与 modelCatalog 也让「本地路由映射」开关默认保持未勾选。SiliconFlow 托管的 MiniMax 仍保持 openai_chat，因为那是第三方端点、并非 MiniMax 自家 base_url。其余仍走 chat 的供应商也刷新了过期的 model id（GLM 5.1→5.2、StepFun 3.5-flash-2603→3.7-flash、Ling 2.5-1T→2.6-1T）。

上游格式选择器与模型映射开关解耦

Codex 供应商表单此前把 Chat 格式转换与路由接管（模型映射）绑在同一个开关上，导致一个提供原生 Responses API 的供应商无法在不强制 Chat Completions 转换的情况下使用模型映射。现在「上游格式」（Chat Completions / Responses）成了一个独立、始终可见的选择器，而本地路由开关只负责控制高级子区（模型映射目录，以及格式为 Chat 时的推理能力）。它的初始状态由已保存目录是否存在派生，不新增持久化字段；codexConfig 的四语（zh / en / ja / zh-TW）文案也随之重写。

豆包 Seed 2.1 Pro 预设

DouBaoSeed 预设现在在全部 6 个客户端（claude、claude-desktop、codex、opencode、openclaw、hermes）指向 doubao-seed-2-1-pro（替换 doubao-seed-2-0-code-preview-latest），展示名更新为「Doubao Seed 2.1 Pro」，并把 OpenClaw 的成本字段从 0.002 / 0.006 订正为 0.84 / 4.2 美元每百万 token 以匹配新模型。

CTok 改名为 ETok

随着厂商对域名、端点与商标的更名，所有面向用户的品牌从 CTok 迁移到 ETok（ctok.ai→etok.ai、api.ctok.ai→api.etok.ai，以及内部 id、展示名、图标和 README 合作伙伴横幅），覆盖每一个客户端预设。Codex 历史迁移白名单里仍保留 ctok 作为旧 id、与新 etok 并存，以保证改名后存量用户的本地会话历史仍被正确分桶。

Kimi 预设命名统一

OpenCode 与 OpenClaw 此前被标为「Kimi K2.7 Code」的 Kimi 预设，更名为与其它应用一致的「Kimi」（OpenCode 的供应商展示名也一并更名）；模型标签仍保留「Kimi K2.7 Code」，因为它描述的是实际模型。

JSON 编辑器暗色模式

用量脚本弹窗、供应商表单与通用供应商表单里的 CodeMirror JsonEditor 现在会通过 useDarkMode() 跟随应用主题，切换到 oneDark 编辑器主题，而不再在应用其余部分已是暗色时仍停留在亮色。（#4556）

更紧凑的「添加供应商」标题与底部提示

「添加供应商」对话框把标题到页签、页签到卡片的纵向间距从 24px 收到 12px，并新增一个始终可见的固定底部提示，引导用户在选好预设后填写下方字段。FullScreenPanel 新增可选的 contentClassName 属性，让内边距覆盖只作用于此面板、不影响其它共用它的面板。

主题自适应的 Kimi 标识

内联的 Kimi 占位标记替换为厂商刷新后的标识。K 字形使用 currentColor，因此会跟随主题文字色（亮色模式深、暗色模式白），而品牌点缀色固定为新的 #1783FF，元数据回退色也相应对齐。

移除 Fable 5 Verified 纪念横幅

设置「关于」页不再显示 3.16.3 为标明特别构建而加在应用名旁的 Fable 5 Verified 纪念横幅；横幅图片及其标记被移除，「关于」面板回到标准的版本徽标布局。

---

修复

Copilot / Codex OAuth 请求现在遵循全局代理

CopilotAuthManager 与 CodexOAuthManager 在构造时写死了 Client::new()，导致它们的认证流程（换 token、拉 /models 列表、判定 model vendor、device-code 与 OAuth 刷新请求）无视配置的全局代理、直连目标服务。在 Copilot 上，直连会让 /models 返回 0 个 Claude 模型，使 live 模型解析失效，上游以 400 model_not_supported 拒绝请求。现在两个 manager 都改为每次请求从共享客户端现取（crate::proxy::http_client::get()），从而遵循全局代理 URL 并支持运行时热更新。修复 #2016、#2931。（#4583）

压缩请求体与错误体的解压

Codex Desktop 在对 Codex 后端认证时会发送 zstd 压缩的请求体，这会破坏本地代理路由，因为处理器直接用 serde_json 解析原始压缩字节。代理现在会在 JSON 解析前对请求体解压（gzip / br / deflate，外加新增的 zstd 支持，包括 gzip, zstd 这类堆叠编码），覆盖三个 Codex 处理器，并剥掉过期的 content-encoding / content-length / transfer-encoding 请求头让转发器重新生成。上游非 2xx 的错误体也以同样方式解压，因此压缩过的限流与鉴权细节不再被丢弃、对客户端隐藏。修复 #3764、#3696。（#3817）

DeepSeek 端点 thinking: disabled 的 400 错误

DeepSeek 的 Anthropic 兼容端点会拒绝 thinking.type=disabled 与 effort 参数共存的请求、返回 HTTP 400，这会破坏 Claude Code 2.1.166+ 那些硬编码 thinking: disabled 的子 agent（Workflow / Dynamic Workflow）。代理现在不是去覆盖客户端的意图，而是对官方 DeepSeek 端点剥掉冲突的 output_config.effort / reasoning_effort 参数，因为子 agent 本就不需要展示推理。（#4239）

回滚 Anthropic system 消息上提

回滚了 #3775 把 Anthropic 兼容供应商的 role=system 消息从 messages[] 上提到顶层 system 字段的改动。DeepSeek 端点本就原生接受内联的 system 消息，而该重写改变了请求前缀；保持消息原位能保留 prompt 前缀，避免一处疑似的缓存命中率回退（参见 #4297）。来自 #3775 的、不相关的 Windows 测试修复以及 tool-thinking-history 归一化都保留。

Chat 工具调用缺函数名

一些上游会在流式工具调用增量里发送空的或缺失的函数名，过去这会产生无效的 Codex Chat 输出项（或一个 unknown_tool 回退）。现在累积的工具调用状态不会再被空增量覆盖，而那些始终没拿到 call_id 与有效名字的工具调用会在最终化阶段被跳过，覆盖流式、非流式与旧版 function_call 三条路径。（#4159）

恢复 Codex 缓存的工具调用字段

当 Codex 发起一个引用 previous_response_id 的后续 Chat 请求时，它的 function_call 项可能只携带 call_id。历史增强此前只回填 reasoning / reasoning_content，留空了函数的 name、arguments、status 等字段；现在它会从历史里恢复全部缓存的工具调用字段，让该调用能为 Chat 上游正确重建。（#4160）

config.toml 里重复的 Codex base_url 条目

把 Codex 的 base_url 写入 config.toml 时此前每个区段只替换或移除一个匹配的赋值，因此一个已经含多行 base_url 的区段会留下多余项、累积重复。setCodexBaseUrl 现在会折叠目标区段或顶层的所有匹配（替换第一处、移除其余），TOML 的 base_url 正则也处理了转义引号。（#4316）

历史迁移探测 CODEX_SQLITE_HOME 的状态库

Codex 会话历史迁移此前只扫描 ~/.codex/state_5.sqlite 与 config.toml 的 sqlite_home 位置，因此当 Codex 的 SQLite 状态通过 CODEX_SQLITE_HOME 环境变量被重定位时，状态库从未被扫描、其 threads 仍留在旧的供应商分桶里。第三方与统一会话两套迁移共用的 codex_state_db_paths 辅助函数现在会回退到 CODEX_SQLITE_HOME（config 里的 sqlite_home 仍优先）。

供应商终端尊重用户 shell

在 macOS / Linux 上启动供应商终端时此前硬编码了 bash，导致 zsh / fish 用户的 rc 文件不会加载。启动器现在会从 $SHELL 检测用户默认 shell（macOS 回退 /bin/zsh、Linux 回退 /bin/bash）并以干净启动的 flag exec 进去，而启动脚本本身改走 POSIX sh 以保证可移植性（例如 fish，以及 /bin/sh 可能不存在的 NixOS）。（#4140，修复 #1546）

Claude MCP 路径尊重自定义配置目录

当配置了自定义的 Claude 配置目录时，MCP server 的读写现在会解析到该目录下的 MCP 文件、而非默认位置，让 MCP 状态按 profile 隔离。此前对旧文件的「访问即拷贝」迁移被移除，改为直接解析覆盖路径。（#3431）

搜索后预设结果可点击

在「添加供应商」预设选择器里搜索后，结果一度无法点击或选中。那个与输入打架、会吃掉首字符（如「gateway」→「ateway」）的 requestAnimationFrame select() 被移除，开箱即点路径的输入自动聚焦被恢复，当搜索框已打开时按 Ctrl/Cmd+F 也接上了重新聚焦。供应商列表的打字守卫也被收窄到 Ctrl/Cmd+F 分支，从而 Escape 仍能关闭搜索面板。（#4315）

Skills 浏览与供应商卡片显示修复

修复了若干显示与交互问题：浏览 skills.sh 时仓库管理操作保持可用，仓库返回空结果时刷新也保持可用；供应商卡片上过长的供应商名与网站 URL 现在会截断而非溢出；OMO 模型变体下拉会截断所选标签并配全文提示；Select 菜单项会在当前选中项上显示对勾。（#4323）

切换设置页签时重置滚动

在设置对话框里切换页签会保留上一个页签的滚动位置，有时会停在新页签的中途；现在每当激活页签变化时，滚动容器都会重置到顶部。（#4165）

---

文档

Kimi 置顶赞助横幅

全部四种 README 语言（en / zh / ja / de）顶部的置顶赞助横幅现在换成了 Kimi K2.7 Code，取代此前的 MiniMax M2.7 横幅。文案反映 K2.7 Code 发布（一个面向编程的 agentic 模型，思考 token 用量较 K2.6 降低约 30%），横幅改由仓库内资源（assets/partners/banners/kimi-banner-en.png / kimi-banner-zh.png）提供、不再走 Moonshot CDN，并附一个指向 aff=cc-switch Moonshot 控制台的可点击行动号召。

Codex 统一会话历史攻略

新增三语（zh / en / ja）攻略，讲清统一 Codex 会话历史开关的开启迁移（启用时）与按账本还原（禁用时）到底做了什么、为什么会话数据从不会真正删除（只改标记 + 自动备份），以及如何核对文件是真在磁盘上、还是只是被归到了另一个供应商抽屉里。它包含一张针对常见「我的会话不见了」误解的症状对照表，以及 macOS / Linux / Windows 的磁盘核对命令，并作为首项链入 v3.16.3 的「使用攻略」release notes。

简化 Homebrew 安装说明

安装指南不再要求用户在 brew install --cask cc-switch 之前先运行 brew tap farion1231/ccswitch；这个已废弃的 tap 步骤已从 en / ja / zh 用户手册里移除，cask 现在可直接安装。（#4319）

Star-History 全球排名徽标

在全部四种 README 语言里、既有的 Trendshift 徽标旁新增了一个 star-history 全球排名徽标，并带亮 / 暗主题变体。

火山方舟 Coding Plan 活动链接

ByteDance / 火山方舟赞助条目里的「中国大陆地区的开发者请点击这里」链接现在指向火山的 ai618 活动页，取代此前的 codingplan 推荐 URL，覆盖全部四种 README 语言。

CCSub 赞助横幅矢量资源

把低分辨率的 ccsub.jpg 赞助 logo 替换为矢量的 ccsub.svg，并从 2046x648 letterbox 到 2046x850（约 2.406:1），使其与其它赞助表横幅匹配、以相同的 62px 高度渲染。全部四种 README 语言都指向新资源。

---

升级提醒

国产 Codex 供应商原生 Responses 迁移

本版把多家具备原生 Responses 端点的国产供应商（千问 / 百炼、小米 MiMo、火山豆包、美团 LongCat、MiniMax 国内 / 国际）的 Codex 预设切换为 openai_responses 并移除了 modelCatalog。已经基于这些预设配置过的存量供应商不受影响、配置保持原样；如果你希望改用原生 Responses（省去格式转换接管），可以重新从预设选择一次并保存。SiliconFlow 托管的 MiniMax 仍走 openai_chat，不在此次迁移之列。

数据库版本过新的恢复

如果你曾用更高版本的 CC Switch 打开过数据库、再切回旧版，旧版启动时会进入新的「数据库版本过新」恢复屏，并引导你升级到能读懂该数据库的版本。这是预期行为——升级到最新版即可恢复正常。

---

风险提示

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

Codex OAuth 反向代理：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 v3.13.0 release notes。

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

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

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

---

致谢

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

• #3817：转发前解压请求体并支持 zstd，感谢 @chenx-dust。
• #4583：修复 Copilot / Codex OAuth 模块绕过全局代理导致 Claude 模型 400，感谢 @zymouse。
• #4589：新增本地代理请求覆盖（自定义请求头与请求体），感谢 @mfzzf。
• #4575：新增数据库版本过新时的应用内恢复屏，感谢 @SaladDay。
• #4556：为多处 JsonEditor 接入暗色模式，感谢 @TanKimzeg。
• #4438：新增自定义日期范围的实时结束时间，感谢 @arichyx。
• #3950：新增 Windows ARM64 发布支持，感谢 @MOON-DREAM-STARS。
• #4401：为 Kimi For Coding 预设添加 CLAUDE_CODE_AUTO_COMPACT_WINDOW，感谢 @cyijun。
• #4323：修复 Skills 管理与模型配置的交互展示，感谢 @thisTom。
• #3431：对齐自定义配置目录的 Claude MCP 路径，感谢 @makoMakoGo。
• #4159：跳过缺函数名的 Chat 工具调用，感谢 @hueifeng。
• #4385：新增 glm-5.2 定价，感谢 @arichyx。
• #4079：支持从 models.dev 导入模型定价，感谢 @kingcanfish。
• #4315：修复搜索预设后结果无法点击选中，感谢 @RuixeWolf。
• #4316：防止重复的 Codex base_url 条目，感谢 @jeffwcx。
• #4140：让供应商终端尊重用户 shell，感谢 @zkforge。
• #4113：在会话详情头显示源文件名，感谢 @xu-song。
• #4160：恢复 Codex 缓存的工具调用字段，感谢 @chen-985211。
• #4239：DeepSeek 端点 thinking:disabled 时剥掉 effort 参数，感谢 @maskshell。
• #4165：切换设置页签时重置滚动，感谢 @Muleizhang。
• #4319：移除已废弃的 Homebrew tap 步骤，感谢 @tianpeng-dev。
• #4522：新增 SubRouter 供应商预设，感谢 @abingyyds。

也感谢所有在 v3.16.3 发布后反馈 Codex 代理链路、用量计费、本地代理稳健性与平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。

---

下载与安装

访问 Releases 下载对应版本。

系统要求

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

Windows

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

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

macOS

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

🎉 CC Switch 突破 100,000 Star！ 感谢每一位用户、贡献者与 Star —— 是你们让它走到这里。🙏

💎 本版由 Claude Fable 5 模型协助开发——它帮忙梳理清楚了多处关键且容易出错的逻辑：路由接管时按真实上游模型计费的归因链、格式转换路径上缓存 token 的计量与去重、应用内更新的重启死锁，以及 Codex 统一会话历史的迁移 / 还原不变量。这也是本版在「关于」页新增 Fable 5 Verified 标识的由来。

在 v3.16.2 拓宽数据可携带性与用量观测之后，这一版把重心放在「让用量计费真正准确」——按真实上游模型计费、修正格式转换路径上的缓存双算、把 Claude Code Workflow 子 agent 的用量纳入统计（schema v11），并对用量看板做了一轮改版（全局供应商 / 模型筛选、品牌图标工具栏、更稳的额度查询）；同时加固了一批本地代理与平台问题，新增自定义 User-Agent 覆盖、Codex 统一会话历史开关与 Claude Fable 5 档位。

English → | 日本語版 →

---

使用攻略

本版新增了 Codex 统一会话历史 开关——它涉及会话的迁移 / 还原，操作不当时容易让人误以为"会话丢了"，强烈建议先读这篇攻略；用量统计的口径和看板这一版也做了较多调整，一并附上：

• Codex 统一会话历史：功能介绍与使用攻略：讲清"统一 / 迁移 / 还原"到底改了什么、为什么数据不会真正丢失，以及看不到会话时如何自查与精确还原。用过这个开关、或担心会话丢失，请务必先读。
• 用量统计：了解用量看板的数据来源（代理日志、会话同步）与统计口径，本版新增了全局的供应商 / 模型筛选，并把路由接管的真实计价模型展示了出来。
• 设置：自定义 User-Agent 覆盖、Codex 统一会话历史等开关都在供应商表单的高级选项与设置页里。

---

[!WARNING]

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

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

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

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

---

概览

CC Switch v3.16.3 是 v3.16.2 之后的一版维护更新。在上一版集中拓宽数据可携带性与用量观测之后，这一版把重心放在「让用量计费真正准确」这件事上——按真实上游模型计费而非上游回显、修正格式转换（Chat / Responses / Gemini 转 Anthropic）路径上的缓存 token 双算、把 Claude Code Workflow 子 agent 的用量纳入本地统计，并以 schema v11 持久化每条记录实际使用的定价依据；用量看板也随之做了一轮改版，新增全局的供应商 / 模型筛选、品牌图标工具栏，以及更稳的额度查询（失败重试 + 保留上次成功结果）。

此外，本版还加固了一批本地代理的稳健性问题（错标 Content-Type 的 SSE 响应聚合、Codex /responses 文本模型图像整流、Codex OAuth 凭据与接管残留的恢复、Hermes 配置重复 YAML 键），重做了供应商配置体验（自定义 User-Agent 覆盖、Codex 表单统一进高级选项、预设搜索与排序、Claude Fable 5 档位），新增 Codex 统一会话历史开关，并修复了应用内更新卡死、Codex 升级损坏安装、macOS 重复终端窗口等问题。

发布日期：2026-06-14

更新规模：59 commits | 130 files changed | +10,223 / -4,232 lines

---

重点内容

• 用量计费更准：路由接管的流量现在按真实上游模型计费（而非上游回显的别名），格式转换路径不再把缓存 token 重复计入 input，Claude Code Workflow 子 agent 的用量也纳入了统计——以 schema v11 持久化定价依据。
• 用量看板改版：供应商 / 模型筛选从请求日志表提升为全局筛选，应用筛选改用品牌图标，额度查询加入失败重试与「保留上次成功结果」，单次网络抖动不再让卡片变红。
• 自定义 User-Agent 覆盖：供应商可设置自定义 UA，并在转发、连通性检测、模型列表三处一致生效，绕过按 UA 白名单放行的 Coding Plan 上游（借此恢复了 Codex「Kimi For Coding」预设）。
• Codex 统一会话历史：新增可选开关，让官方 Codex 会话与第三方会话共享同一份 resume 历史桶，附带可选的存量迁移与按账本精确还原。
• 代理与平台加固：错标 SSE 响应聚合、Codex 图像整流、接管残留恢复、Hermes YAML 去重；应用内更新不再卡在「重启中」，Codex 升级不再把安装弄坏。

---

新功能

自定义 User-Agent 覆盖

供应商配置现在可以设置自定义 User-Agent，并由代理在请求转发、连通性检测和模型列表（GET /v1/models）三条路径上一致应用，因此按 UA 白名单放行的 Coding Plan 上游不会再出现「检测失败 / 模型列表 403、但代理本身却能正常工作」的不一致。Claude 和 Codex 表单都在高级选项里暴露该字段，配有精选的 UA 预设下拉（Claude Code / Kilo Code 等能通过 UA 白名单的家族）和实时、非阻塞的格式校验；切换到官方预设时会丢弃残留的自定义 UA，避免悄悄改动请求头（#3671）。

Codex 统一会话历史

新增一个可选开关（设置 → Codex 应用增强），让官方 Codex 会话与 CC Switch 的第三方会话共享同一份 resume 历史桶，resume 选择器不再把两者互相隐藏。开启后，live 的 config.toml 会把官方运行路由到一个镜像内建 OpenAI 供应商的共享 custom model_provider（auth.json 不动）。默认只对未来会话生效；开启弹窗提供一个勾选项，可把已有官方会话迁入共享桶（含逐代备份），关闭弹窗则提供按备份账本精确还原——只回退备份中记录为 openai 的会话，开启期间新建的会话永不被改动。

用量看板全局供应商 / 模型筛选

供应商和模型筛选从请求日志表内部提升到了顶栏，对 Hero 汇总、趋势图、请求日志和两个统计页签全局生效，可以把整个看板按某个来源和模型缩小范围。来源按展示名精确匹配（因此像「Claude (Session)」这样的会话占位行也可选），模型按有效计价模型匹配，模型下拉会随所选来源级联，且两个列表只列出当前时间范围内有数据的选项。

模型定价种子刷新

对 seed_model_pricing 做了一次全量核价：新增 9 个模型的定价（含 Claude Fable 5、Grok 4.3、Mistral Medium 3.5 / Small 4、Qwen 3.7 Max/Plus 等），并按各厂商官方 list 价订正了 28 处既有价格（GLM、Grok、MiMo、Doubao、Kimi、MiniMax、Mistral、Qwen），让用量成本估算更准确。每处改动都同时更新种子（影响全新安装）并向 repair_current_model_pricing 加一条旧→新守卫（修复存量数据库，且不覆盖用户手改过的行）。

Claude Fable 5 模型档位

供应商表单现在在 Claude Code 和 Claude Desktop 两条代理路径上都暴露 claude-fable-5 作为第四个模型映射档位，回落链为 fable → opus → default，与官方降级一致，并为 Claude Desktop 1.12603.1+ 的校验器放行了 fable- 前缀。四语回落提示也做了澄清：在第三方端点上把某一档留空，会原样透传该档的字面模型名并 404（#3980、#4026、#4049）。

Unity2.ai 合作伙伴供应商

新增 Unity2.ai（一个 AI API 中转合作伙伴）作为预设，覆盖全部 7 个受管应用（Claude Code、Codex、Gemini、OpenCode、OpenClaw、Claude Desktop、Hermes），每个预设都带上推广注册链接，并在四种语言里补充了合作伙伴推广文案。Codex 使用裸 base URL（该网关在根路径暴露 /responses），OpenCode / OpenClaw / Hermes 使用 /v1 chat-completions 端点并以 gpt-5.5 为预设模型。

Kimi K2.7 Code 模型

新增 kimi-k2.7-code 模型（输入 $0.95 / 输出 $4.00 / 缓存读取 $0.19，每百万 token，256K 上下文），并把全部 6 个官方 Moonshot Kimi 预设（Claude Code、Codex、Claude Desktop、Hermes、OpenCode、OpenClaw）指向它，OpenCode / OpenClaw 预设更名为「Kimi K2.7 Code」。定价种子通过启动时的幂等插入路径生效，存量用户无需迁移即可获得新价。

恢复 Codex「Kimi For Coding」预设

重新加入 Codex「Kimi For Coding」预设（openai_chat、kimi-for-coding、256K 上下文），默认开启思考模式。此前它被移除是因为该编程端点会以 403 拒绝 Codex 默认的 codex-cli User-Agent；现在借助代理接管 + 自定义 User-Agent 覆盖（设为 claude-cli/* 等白名单 UA）即可正常使用。

请求详情的计价模型审计

请求详情面板现在会在「请求的模型」「计价模型」与响应模型不一致时把它们都显示出来，让路由接管产生的账单可以直接在用量界面里核对。

预设供应商搜索与排序

预设供应商选择器现在是一个可搜索、可排序的列表，配有内联搜索框（点放大镜图标切换，按 ESC 或点击外部收起）。按钮改为响应式网格、尺寸统一并显示默认图标，搜索只匹配供应商的展示名 / 原始名，因此 URL 片段和共享的分类标签不会再产生噪声匹配（#3975、#4183）。

Claude Mythos 5 定价

在内置模型 / 定价表里登记 claude-mythos-5 模型（输入 $10 / 输出 $50，每百万 token；缓存读取 $1.00、缓存写入 $12.50），让用量统计能正确计价并展示（#4077）。

Fable 5 Verified 标识

设置「关于」页现在会在应用名与版本旁展示 Fable 5 Verified 标识，标明这是一个特别构建，版本徽标也居中到了应用名下方。

---

变更

Claude Desktop 用量折叠进 Claude

看板不再展示独立的「Claude Desktop」分桶——它一直只能显示一个不完整的数字（Desktop 聊天用量根本不经过代理，而其 Code 页签的会话只是内嵌的 Claude Code 运行时写进共享的 ~/.claude/projects 目录）。Desktop 的代理流量现在在展示上折叠进 claude，但记账层仍按它自己的 app_type 记录以便路由接管计费审计，真实值可在请求详情面板看到。

轻量化供应商健康检查

供应商健康检查不再发送真实的流式模型请求（很多第三方供应商会以 401/403/WAF 拦截，造成误报不可用），改为对供应商 base_url 做一次轻量的 HTTP 可达性探测：任何 HTTP 响应都视为可达，只有 DNS / 连接 / TLS / 超时才算失败。官方供应商（使用 OAuth、base_url 故意为空、没有可靠的可达性目标）会隐藏连通性按钮，原先「发送真实请求」的确认弹窗以及测试模型 / 提示词字段都被移除，降级延迟阈值设为 6s、超时 8s。该可达性检查永不重置熔断器——可达不等于可用（403 的 host 可达，但对真实流量是坏的），失败转移仍只由真实代理流量驱动。

Codex 高级选项区整合

Codex 供应商表单现在把本地路由、模型映射、推理覆盖和自定义 User-Agent 折叠进一个可展开的高级选项区，与 Claude 表单一致（设置了 UA 或开启本地路由时自动展开）。自定义 User-Agent 现在对原生 Responses 供应商也可配置，此前它只有在开启 openai_chat 路由时才能触及。

用量工具栏与布局刷新

应用筛选改用品牌图标（经 ProviderIcon，「全部」用网格图标）渲染，取代在窄窗口下换行难看的文字页签；用量 Hero 也会显示所选应用的品牌图标，并把 Codex 的主题色从翠绿改为中性灰，贴合 OpenAI 的单色品牌。点击循环切换的刷新按钮改成了带本地化「关闭」标签的下拉选择，顶栏控件也压缩并对齐成统一的宽度分组，过长的日期范围标签做了截断处理。

关于面板加载更快

设置「关于」面板现在渐进式加载：应用版本徽标在解析完成的瞬间就显示，不再等待工具探测；每张工具卡片在自己的版本检测完成时立即更新（探测并发执行而非串行）；探测结果在应用会话期内缓存并带 10 分钟 TTL，因此再次打开「关于」页签会复用缓存值、并在后台对过期项重新校验，而不是每次都把 6 个工具全部重探一遍。

火山方舟 Coding Plan 推广更新

把火山方舟（Volcengine Ark）预设在全部 6 个应用里更新到新的 Coding Plan 邀请链接（替换旧的 Agent Plan / 活动链接），并在四种语言里刷新了合作伙伴推广文案（两个月 75% 折扣 + 邀请码 6J6FV5N2），把产品名从 Agent Plan 订正为 Coding Plan。

MiniMax 降为普通供应商

移除 MiniMax 的金色合作伙伴星标和 API key 推广横幅（从所有预设里删掉 isPartner 标志），它继续作为常规 cn_official 供应商保留图标与主题。推广文案保持休眠状态，必要时一行即可重新启用合作关系。

移除 LemonData、SudoCode 降级

彻底移除 LemonData 供应商预设（连同其推广文案、图标和赞助商条目），并把 SudoCode 从合作伙伴降为常规 third_party 供应商（去掉 isPartner 标志和推广文案，保留图标）。

AtlasCloud Codex GLM 5.1 上下文窗口

为 AtlasCloud Codex 预设里的 zai-org/glm-5.1 模型声明 200,000 token 的上下文窗口，与其他 GLM 5.1 预设条目对齐。

---

修复

路由接管流量按真实上游模型计费

当请求被路由到了不同的上游（env 模型映射、Claude Desktop 路由、Copilot 归一化、Codex chat 覆盖）时，代理过去会按上游回显的模型来归因和计价，把 kimi / glm 的 token 记成、并按 claude-* 计价，成本被高估约 5–25 倍。现在转发器会捕获真实的出站模型，按「上游回显 → 出站模型 → 客户端别名」的顺序归因，并在每行持久化实际使用的定价依据（schema v11），该依据会贯穿成本回填和 30 天 rollup 裁剪；Claude Desktop 流量现在也记在它自己的 app_type 下，使其定价覆盖能正确生效。

格式转换路径的用量计量

审计并修复了代理各条格式转换路径（Chat、Responses、Gemini 转 Anthropic）上的 token / 缓存计量。代理现在会记录实际返回的模型，注入 stream_options.include_usage 让 OpenAI 兼容上游在流式时吐出 usage，在 Claude←OpenAI 路径上把 cache_read 和 cache_creation 从 input 中排除以阻止缓存 token 双计费，扣减 Gemini 的缓存提示 token，仍记录完全命中缓存的请求，并跳过过去会虚增请求数的合成全零 usage（#2774）。

应用内更新不再卡死

从应用内安装更新时不再卡在「重启中」界面——过去会出现新版已装好、却必须手动强制退出的情况。下载—安装—重启整条链路现在完全在后端执行（新增 install_update_and_restart 命令），按平台决定安装顺序，并在重新执行前先销毁单实例锁，而不再依赖旧 WebView 在应用包已被替换之后继续跑 JS；退出请求也做了分类，让重启请求落到 Tauri 默认流程，而不是在窗口状态插件的互斥锁上死锁（#4069、#4074）。

Codex 升级不再损坏安装

从设置「关于」页升级 Codex 不再让它抛出「Missing optional dependency @openai/codex-…」错误。升级链此前会先跑 codex update，而它在 npm 安装下其实是一次裸的重装、即便对应平台的二进制没装上也会报告成功；现在 Codex 已从「优先 self-update」路径里移除，并由一个 runnable 检测触发「卸载 + 重装」自愈（仅限 npm 管理的安装），这是唯一能真正补回缺失平台二进制的修复。

接管时保留 Codex OAuth 凭据

为 Codex 供应商开启代理接管时不再剥掉 ANTHROPIC_AUTH_TOKEN 占位符——此前这会在热切换、全新安装、以及被旧版本已剥过的 live 配置上破坏 Claude Code 的登录。现在对受管（非 Copilot）的 Codex 供应商无条件注入该占位符，包括只有 URL 的供应商；GitHub Copilot 的行为（仅 API_KEY）不变（#3789、#3784）。

跨配置目录切换的接管残留恢复

在代理接管激活时更改配置目录后重启应用，不再把 Claude / Codex / Gemini 留在指向已失效的本地代理上。现在旧实例会在重启前先还原被接管的 live 文件，首次运行的导入会拒绝把接管占位符当作供应商持久化，SSOT 还原也会在写回前校验当前供应商的配置里不含占位符（#4076）。

格式转换兜底里错标的 SSE 响应聚合

经 Claude / Codex 格式转换的请求，当 MaaS 网关把一个 stream:false 的请求强制流式、并以非 SSE 的 Content-Type 返回 SSE 响应体时，不再以一句晦涩的 422「Failed to parse upstream response」失败。代理现在会在解析失败时嗅探 SSE、把分片聚合成单个 JSON 再跑既有转换器，让客户端仍能拿到有效的非流式响应；剩余的解析失败会附带 content-type、编码和响应体片段等诊断信息，deflate 解码也改为先尝试 zlib 再尝试裸流（#2234）。

Hermes 配置重复 YAML 键

Hermes 配置写入不再累积重复的顶层键（如 mcp_servers），那会导致「Failed to parse Hermes config as YAML: duplicate entry with key」错误。区段替换现在会从剩余文本里清除所有过期副本，而不是退化成追加；去重保护层同时处理 LF 和 CRLF 行尾；修复时保留最后（最新）的那份副本，与 Hermes 自身基于 PyYAML 的「后者胜」语义一致（#3267、#3633、#2973、#2529、#3310、#3762）。

用量查询韧性与错误清晰度

用量卡片不再因为单次瞬时抖动就变红：查询现在会重试一次，并在网络 / 超时 / 5xx 这类瞬时失败下继续展示上次成功的结果最多 10 分钟；而确定性失败（鉴权、空 key、未知供应商、4xx）会立即暴露并清空快照，避免凭据变更后陈旧额度又冒出来。原生余额 / Coding Plan / 订阅查询的超时从 10s 提高到 15s 以适配跨境慢端点，Coding Plan 也会返回明确的「API key is empty」/「Unknown coding plan provider」错误，而不是一句空白的失败。

用量脚本供应商凭据解析

自定义 JS 脚本的用量查询此前只靠猜测 env 字段来解析 {{apiKey}} / {{baseUrl}}，因此凭据存放在别处的应用（如 Codex 的 auth.OPENAI_API_KEY 加 config.toml 里的 base_url）总是拿到空值、即便供应商已完整配置也会失败。脚本查询及其测试 / 预览现在复用与原生余额路径相同的按应用凭据解析器，脚本里显式填写的非空值仍然优先（#1479）。

Claude Code Workflow 子 agent 用量统计

本地（无代理）的会话日志用量统计此前漏掉了 Claude Code Workflow 子 agent 的流量，整体用量被低估约 4.1%（集中在 workflow / subagent 的会话记录里）。扫描器现在会深入更深一层的 subagents/workflows/wf_*/ 记录目录，解析器也不再丢弃那些缺少 stop_reason、但已经产生 input / 缓存 token 成本的 assistant 消息；去重逻辑不变，因此不会重复计数。

Codex /responses 文本模型图像整流

携带图片、且被路由到只支持文本的 OpenAI-chat 模型（如 DeepSeek deepseek-v4-flash）的 Codex /responses 请求，不再以 HTTP 400「unknown variant image_url」失败。媒体整流器现在也覆盖 Codex 适配器，会扫描 responses 的 input 里的 input_image 块，从而既能为已知的纯文本模型主动剥掉图片，也能在上游报「不支持图片」时把图片替换后重试。

智谱 Coding Plan 配额窗口误标

智谱 Coding Plan 视图不再在每个周周期的最后几个小时把 5 小时窗口和周窗口标反。两个窗口现在按显式的 unit 字段分类（3 = 5 小时、6 = 周），而不再靠按重置时间升序排序——后者恰好在用户最常查周额度的时候把两者标反；当字段缺失时仍回退到旧的重置时间启发式（#3036）。

macOS 重复供应商终端窗口

在 macOS 上启动供应商终端时不再在命令会话旁多开一个空窗口；Terminal.app 在冷启动时改用 launch（而非 activate），Ghostty 使用初始命令，从而只打开单个会话，并在 AppleScript 路径失败时保留回退方案（#4156）。

Claude Desktop 模型映射占位符

Claude Desktop 模型映射表单此前在「菜单展示名」和「请求模型」两列用了不一致的示例品牌（DeepSeek vs Kimi），暗示一个展示名会映射到不相关的模型。现在两个占位符都由每行的角色派生，从而保持品牌一致，轻量的 Haiku 档使用 flash 示例。

弹层被全屏面板遮挡

像供应商预设搜索这样的弹层和提示气泡不再渲染到全屏面板后面、看起来点了没反应；它们的 z-index 被提到全屏遮罩之上，同时仍低于模态对话框。

ToggleRow 图标被挤压

开关行的图标在配上长描述时不再被压缩或变形，让图标在多行文字旁保持固定大小。

---

文档

Release Notes 贡献者致谢恢复

恢复了 v3.16.1 与 v3.16.2 release notes 在三种语言里的贡献者致谢。

---

升级提醒

定价库 schema v11 自动迁移

本版给 proxy_request_logs 新增了 pricing_model 列、并按 request_model + pricing_model 重建了 rollup，启动时自动迁移、无需手动操作。历史行的成本在写入时已冻结、不会重算（app_type="claude" 的行混合了原生与转换两类来源）；只有真实但当时未计价的接管行会保持零成本、待定价补齐后再回填。

模型映射新增第四档（Fable 5）

Claude Code 与 Claude Desktop 的模型映射现在是四档（Sonnet / Opus / Fable / Haiku）。老的三档供应商在重新打开并保存后会补上 claude-fable-5 档；该档留空表示继承 Sonnet。注意：在第三方端点上把任意一档留空，会原样透传该档的字面模型名并可能 404，请按需填写。

「Kimi For Coding」预设需要代理接管 + 白名单 UA

恢复的 Codex「Kimi For Coding」预设直接用默认的 codex-cli User-Agent 仍会被 403。要使用它，请开启代理接管，并在供应商高级选项里把自定义 User-Agent 设为白名单 UA（如 claude-cli/*）。

供应商健康检查语义变化

健康检查从「发送真实模型请求」改为「HTTP 可达性探测」。请注意可达 ≠ 可用：一个返回 403 的 host 是可达的，但对真实流量可能是坏的。失败转移的判定仍只由真实代理流量驱动，不受健康检查影响。

---

风险提示

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

Codex OAuth 反向代理：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 v3.13.0 release notes。

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

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

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

---

致谢

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

• #3789：接管时保留 Codex OAuth 凭据，感谢 @codeasier。
• #2774：修复 Completions 转 Anthropic 时不记录实际返回模型、input token 计算错误，感谢 @LaoYueHanNi。
• #4069：修复应用内更新后重启死锁，感谢 @thisTom。
• #4156：修复 macOS 重复供应商终端窗口，感谢 @thisTom。
• #3267：修复 Hermes 配置重复 YAML 键，感谢 @que3sui。
• #1479：修复用量脚本供应商凭据解析，感谢 @pa001024。
• #3975：新增预设供应商搜索与排序，感谢 @Nastem。
• #4183：调整预设供应商按钮外观与搜索框位置，感谢 @WangJiati。
• #4077：新增 claude-mythos-5 模型定价，感谢 @osscv。

也感谢所有在 v3.16.2 发布后反馈用量计费、本地代理稳健性、Codex 升级与平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。

---

下载与安装

访问 Releases 下载对应版本。

系统要求

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

Windows

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

macOS

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

CC Switch v3.16.2

在 v3.16.1 的 Codex 稳定性补丁之后，这一版主要拓宽了数据的可携带性与用量观测能力——新增 S3 兼容云同步、OpenCode 会话用量同步、官方订阅额度模板——并继续加固 Codex 通过 Chat Completions 路由第三方供应商的稳健性，同时修复了一批 Windows / macOS 平台问题，新增 CherryIN、ZenMux 供应商，并全面刷新了三语用户手册。

English → | 日本語版 →

---

使用攻略

这一版新增了云同步的 S3 后端和更多用量统计来源，如果你想用上，可以先看这些文档：

• 设置：在设置页配置云同步（WebDAV / S3 兼容存储），用于在多台设备间备份和恢复供应商、MCP、提示词、技能等配置。
• 用量统计：了解用量看板的数据来源（代理日志、Codex / Gemini / OpenCode 会话同步）与统计口径。

---

[!WARNING]

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

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

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

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

---

概览

CC Switch v3.16.2 是 v3.16.1 之后的一版维护更新。在上一版集中处理 Codex 官方鉴权与本地路由接管的安全问题之后，这一版把重心放在两件事上：一是拓宽数据的可携带性和用量观测——新增 S3 兼容云同步（WebDAV 之外的第二套云备份后端）、OpenCode 会话用量同步，以及面向官方订阅的额度统计模板；二是继续打磨 Codex 通过 Chat Completions 路由第三方供应商时暴露出来的边角问题——流式截断判定、空 tools 下的 tool_choice、自定义工具元数据、推理 token 统计、文件 / 音频附件转换等。

此外，本版还修复了一批本地代理的稳健性问题（临时端口解析、接管占位符还原死循环、Anthropic system 消息归一化、上游 413 文案、Claude Desktop 的 [1m] 模型路由），处理了若干 Windows / macOS 平台体验问题，并新增 CherryIN、ZenMux 两个供应商，同时全面刷新了三语用户手册。

发布日期：2026-06-07

更新规模：41 commits | 132 files changed | +11,116 / -1,636 lines

---

重点内容

• S3 兼容云同步：在 WebDAV 之外新增 S3 兼容对象存储作为第二套云备份后端，内置 AWS S3、MinIO、Cloudflare R2、阿里云 OSS、腾讯云 COS、华为 OBS 等一键预设。
• 更多用量统计来源：新增 OpenCode 会话用量同步，以及面向 Claude / Codex / Gemini 官方订阅的额度统计模板（显式开关、默认关闭）。
• Codex Chat Completions 路由继续加固：修复流式截断误判、空 tools 下 tool_choice 被拒、自定义工具元数据丢失、推理 token 统计缺失，并支持文件 / 音频附件转换与 /v1/models 探活端点。
• 本地代理更稳：修复临时端口（port 0）解析、接管占位符还原死循环、Anthropic system 消息归一化、上游 413 文案，以及 Claude Desktop 1M 上下文模型路由。
• 平台与供应商：修复 Windows 托盘 / 任务栏图标、子目录技能更新、macOS 输入自动大写等问题，并新增 CherryIN、ZenMux 供应商。

---

新功能

S3 兼容云同步

云同步现在支持 S3 兼容对象存储作为 WebDAV 之外的第二套后端，签名采用自实现的 AWS Signature V4，以兼容尽可能多的服务。设置页提供 AWS S3、MinIO、Cloudflare R2、阿里云 OSS、腾讯云 COS、华为 OBS 以及自定义 endpoint 的一键预设，支持连接测试、手动上传 / 下载，以及在配置变更时自动同步（providers、endpoint、MCP、提示词、技能、设置、代理等配置表，不含用量日志这类高频写入数据）。开启 S3 同步会停用正在运行的 WebDAV 同步，反之亦然（#1351）。

OpenCode 会话用量同步

新增 OpenCode 作为用量统计来源，从 OpenCode 本地 SQLite 数据库读取每条消息的 token、成本和模型数据并导入用量记录，并提供独立的「OpenCode」应用筛选页签和「OpenCode Session」数据来源标签。数据库路径会遵循 OPENCODE_DB 和 XDG_DATA_HOME（在所有平台默认 ~/.local/share/opencode），只导入已完成的消息，并在判断新鲜度时把 WAL 文件一并计入，避免刚写入的会话被跳过（#3215）。

官方订阅额度模板

由于部分用户担心发起用量查询的 IP 和发起应用内请求的不一致导致封号风险，因此为 Claude / Codex / Gemini 官方供应商新增一个显式、可选的「官方订阅」用量模板，通过 CLI / OAuth 凭据查询套餐额度，替代此前对官方供应商的隐式自动查询。该模板默认关闭，需要在用量脚本弹窗里开启，并可配置刷新间隔。使用此功能建议开启代理的 TUN 模式。

文本模型图片回退整流器

新增一个代理整流器：当路由到的模型仅支持文本（显式声明，或由内置的模型名启发式判定），或上游拒绝图片输入时，会把 Anthropic 图片块替换为 [Unsupported Image] 占位标记，避免对话被中断。设置页提供该回退功能的开关，并单独提供一个开关控制启发式检测（可关闭以避免误判多模态模型）。

ZenMux Token Plan 供应商

新增 ZenMux 作为 Token Plan 类的 Coding Plan 供应商，可在用量脚本弹窗里手动填写 API key 和 base URL，并以美元口径富展示已用 / 额度（#2709）。

CherryIN 预设

新增 CherryIN 聚合网关作为快捷配置预设，覆盖全部 7 个受管应用——Claude Code / Claude Desktop / OpenClaw / Hermes 使用 Anthropic 格式端点（open.cherryin.net），OpenCode 使用 @ai-sdk/anthropic（/v1），Codex 使用 OpenAI 兼容端点，Gemini CLI 使用 Gemini 兼容端点，附带官方品牌图标，位置紧挨 AiHubMix（#3643）。

Codex CLI 模型探活端点 /v1/models

本地代理现在会响应 Codex CLI 启动时探测的 GET /v1/models，返回 CC Switch 托管的 Codex 模型目录。同时加入了过期目录守卫：解析 live 的 config.toml，仅当 model_catalog_json 仍指向 CC Switch 持有的目录文件时才提供，避免把上一个供应商遗留的目录暴露给 Codex（#3818）。

Codex Chat 文件与音频附件

Codex 的 Responses→Chat 转换现在会把 input_file（携带 file_id 或内联 file_data）和 input_audio 内容部分映射为 Chat Completions 的对应形态，并补发此前会被丢弃的顶层 input_* 项，让文件和音频附件能够送达只支持 Chat 的 Codex 上游。

---

变更

用量看板 Hero 重新设计

把用量看板的 Hero 区与汇总卡片重排为更紧凑的布局，将真实 token 总量、请求数和成本合并到顶部一行展示（#3426）。

SSSAiCode 端点刷新

把 SSSAiCode 预设的官网、注册和 API base URL 更新到 sssaicodeapi.com 域名，并刷新其端点候选节点（默认 node-hk.sssaicodeapi.com，另含 node-hk.sssaiapi.com 和 node-cf.sssaicodeapi.com），覆盖全部 7 个应用预设。

---

修复

Codex Chat 流式截断判定

当 Chat Completions 上游在没有 finish_reason 或 [DONE] 的情况下结束流时，CC Switch 不再把它当作正常完成：只有流真正结束才正常收尾；已产出部分内容时发出 incomplete（max_output_tokens）响应；完全没有产出时发出失败的 stream_truncated 事件。晚到的推理内容也会回填到仍在进行的流式工具调用上。

Codex Chat 空 tools 下的 tool_choice

Responses→Chat 转换现在会在最终 tools 数组缺失或为空（包括所有工具被过滤掉）时一并丢弃 tool_choice 和 parallel_tool_calls，避免严格的 OpenAI 兼容上游（vLLM、企业网关）以"When using tool_choice, tools must be set."报 503/400（#3640）。

Codex 自定义工具元数据保留

自定义 Codex 工具（如自由格式的 apply_patch 工具）现在会把完整的原始定义——包括 format 和 grammar 元数据——以紧凑、顺序稳定的 JSON 块嵌入生成的 Chat 函数描述中，而不是替换成通用占位符，从而在 Chat Completions 上游上仍可正常使用（#3644）。

Codex Chat 用量缺少 reasoning_tokens

Chat→Responses 的用量转换现在总会包含 output_tokens_details.reasoning_tokens（默认 0），即使供应商省略 completion_tokens_details 或返回非对象也是如此，满足 Codex CLI 的严格要求，避免反复的响应解析失败和重试（#3514）。

Codex 自定义工具 / 搜索工具的跨轮推理

Codex Chat 历史里的跨轮推理缓存现在覆盖完整的工具调用集合（function_call、custom_tool_call、tool_search_call）及其输出，而不再仅限普通函数调用，因此 apply_patch 和工具搜索调用在通过 previous_response_id 恢复时能保留各自的 reasoning_content。

临时端口（port 0）解析

当代理被配置为监听 0 端口（由系统分配）时，接管流程现在会先启动代理以拿到真实端口，再写入 live 配置和数据库，避免客户端 URL 指向无效的 :0 地址；若还没解析出具体端口，Claude Desktop 的网关 URL 会被直接拒绝。

代理占位符备份 / 恢复死循环

如果上一次停止代理时未能还原原始 live 配置、把代理占位符遗留在了 live 中，再次接管时不会再用代理配置覆盖掉正常备份，恢复时也不会把占位符写回 live：两条路径都会识别占位符状态并以当前供应商为真相来源重建 live，修复了代理开关变成空操作、客户端被钉死在本地代理地址的问题（#3689）。

代理接管期间误拦截供应商切换

在本地路由接管期间，现在只有显式归类为官方的供应商会被禁止切换，而不会再把端点存在 meta 里、或字段尚未填写的自定义供应商一并禁用。被禁用的「启用」按钮现在以更轻量的提示气泡替代原先的红色「已拦截」标记。

localhost 监听地址归一化

保存代理时如果监听地址填的是 localhost，现在会先归一化为 127.0.0.1 再持久化，避免绑定不一致（#3016）。

Anthropic system 消息归一化

对 Anthropic 格式的供应商，messages 数组里的 system 角色条目现在会被折叠并合并到顶层 system 字段（保留原顺序以及已有的顶层 system），避免严格上游拒绝非首位的 system 消息；OpenAI Chat 路由不受影响（#3775）。

Claude Desktop 1M 上下文模型路由

Claude Desktop 在 1M 上下文 beta 激活时会给模型名追加 [1m] 标记（如 claude-opus-4-8[1m]）。代理现在会在路由匹配前先剥掉该后缀，让精确、别名、旧名和角色关键词匹配都能正确命中，修复了对话中途切换到 1M 模型时的 route_unknown（HTTP 400）失败；诊断用的 route_unknown 错误里仍保留原始模型名。

Codex 413 错误文案

当 Codex 上游网关以 HTTP 413 拒绝过大的请求体时，代理现在返回专门的提示，说明这是供应商服务端的请求体大小限制（而非 CC Switch 本地限制），并给出可操作的恢复步骤（运行 /compact、移除大段日志或内联图片，或请供应商调高限制），不再原样回显上游的 HTML 错误页。

代理面板错误详情

切换代理接管失败时，代理面板的提示现在会带上后端返回的具体错误详情，而不是只显示一句笼统的失败信息（#3656）。

Copilot 无限空白检测阈值

把流式无限空白的中断阈值从 20 调高到 500 个连续空白字符，避免参数里含深层缩进代码（Python、YAML、Rust、Markdown）的正常工具调用被误判中断，同时仍能捕获真正的 Copilot 无限空白 bug（#2647）。

订阅档位托盘渲染

通过统一的档位到标签映射，修复官方订阅档位在托盘和额度展示上的渲染问题：Claude / Codex 不再漏掉 7 天窗口，Gemini Pro / Flash / Flash-Lite 档位不再泄露原始机器名，多窗口套餐（如 Opus + Sonnet）现在按最差利用率展示而非取第一个匹配。

Claude 流式 input_tokens 虚高

部分 Anthropic 兼容的流式供应商（如 Qwen、MiniMax）会在 message_start 里把完整上下文当作 input_tokens 上报，重复计入了已经单独统计的缓存部分，导致显示的缓存命中率被人为拉低。现在解析器会优先采用 message_delta 中更小的正 input_tokens，并采用同一 usage 块里配套的缓存计数；原生 Claude 和 OpenRouter 转换路径不变。

智谱配额查询端点路由

智谱 Coding Plan 的配额查询此前被硬编码到 api.z.ai，导致使用大陆预设（open.bigmodel.cn）的用户在国际端点不可达时查不到用量。现在配额请求会路由到与用户所配 base URL 匹配的主机（#3702）。

MiniMax 余额接口与定价

适配 MiniMax Coding Plan 配额的新余额接口（新接口返回剩余百分比字段，而非旧解析器依赖、会导致档位为空、托盘不再显示用量的用量计数），过滤掉非编程模型（如视频），兼容无周限额的套餐，并为 MiniMax M3 模型补充了默认定价（#3518）。

GLM Coding Plan 端点与模型拉取

把智谱 / Z.AI 的 GLM Coding Plan 预设修正到 /api/coding/paas/v4 端点（覆盖 Codex、OpenCode、OpenClaw、Hermes），并让模型列表探测对已经以 /v{N} 版本段结尾的 base URL 改为先查 {base}/models（保留 /v1/models 作为兜底），让「拉取模型」按钮不再在带版本号的端点上 404（#3524）。

Codex 模型目录路径可移植性

Codex 现在只把相对文件名 cc-switch-model-catalog.json 写入 config.toml，而不是绝对路径（Codex CLI 会从配置目录解析它），修复了在 WSL 和符号链接环境下绝对路径无法转换、导致模型目录失效的问题（#3614）。

APINebula 的 OpenCode SDK

APINebula 的 OpenCode 预设现在加载 @ai-sdk/openai-compatible 而非 @ai-sdk/openai，让请求使用该中转期望的 OpenAI Chat Completions 格式，而不是只支持 chat-completions 的上游会失败的 Responses API。

Windows 退出后托盘图标残留

在 Windows 上退出 CC Switch 可能会留下一个失效的托盘图标，直到鼠标划过才消失。现在应用会在退出前显式移除托盘图标，让它随进程结束干净消失（#3797）。

Windows 任务栏图标

在运行时显式设置 Windows AppUserModelID，并给安装器生成的桌面和开始菜单快捷方式写入相同的 ID 和产品图标，让 CC Switch 在任务栏上显示正确图标并正确归组（#3457）。

Windows 子目录技能的更新检查

在 Windows 上扫描已安装技能时，把反斜杠路径分隔符归一化为正斜杠，让嵌套在子目录里的技能（如 skills/my-skill）能被更新检查匹配到，而不是被静默跳过（#3430）。

macOS 输入自动大写

为共享的文本 Input 组件关闭自动完成、自动纠错、自动大写和拼写检查，让 macOS 不再对配置字段里输入的首字母自动大写或自动纠正（#3626）。

Codex VS Code 会话预览

从 VS Code 发起的 Codex 请求，其会话预览在注入请求前存在 markdown 标题时，可能显示选区或打开文件的内容而非真实提示。现在后端标题和前端预览都会匹配最后一个「## My request for Codex:」标题（IDE 把真实请求作为最后一节注入），让预览反映用户的提示（#3593）。

中文界面 VS Code 文案

把简体和繁体中文里「应用到 Claude Code 插件」的描述改为正确书写「VS Code」而非「Vscode」，与英文、日文文案对齐（#3228）。

---

文档

用户手册刷新

刷新了 README 各语言版本以及 en / zh / ja 用户手册，使其反映全部 7 个受管应用（在介绍和总览文案里补上 Claude Desktop 与 Hermes），把 OpenCode 配置路径修正为 ~/.config/opencode/（opencode.json），补充了 Hermes 配置文件说明，把语言文档更新为四种语言，订正各应用 MCP / 提示词 / 技能的支持情况，说明导出现在会生成带时间戳、含用量日志的 SQL 备份，并补充了定价模型 ID 匹配规则（#3411）。

Codex 官方认证保留指南

新增中 / 英 / 日三语指南，说明如何在把模型流量切到第三方 API 的同时，保留 Codex 官方远程操作和官方插件的可用性，并从 v3.16.1 release notes 链接到该指南。

README 链接与赞助商标记

把各语言 README 里的 Release Notes 链接更新到 v3.16.1，并修复 README_ZH 赞助商区块里损坏的弯引号字符，让其 HTML 属性能正确渲染（#3772）。

---

升级提醒

S3 与 WebDAV 云同步互斥

云同步同一时间只会运行一套后端。开启 S3 自动同步会停用正在运行的 WebDAV 自动同步，反之亦然。如果你之前用的是 WebDAV，切到 S3 前请确认两端数据已对齐，避免误以为旧后端仍在备份。

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

Codex 在启动时读取 model_catalog_json。即使本版已把模型目录改写为相对路径并新增了 /v1/models 探活端点，只要你修改了模型映射表，仍然需要重启 Codex 才能让 /model 菜单刷新。

---

风险提示

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

Codex OAuth 反向代理：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 v3.13.0 release notes。

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

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

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

---

致谢

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

• #1351：新增 S3 兼容云存储同步，感谢 @keithyt06。
• #3215：新增 OpenCode 会话用量同步，感谢 @nothingness0db。
• #2709：新增 ZenMux Token Plan 供应商，感谢 @Eter365。
• #3643：新增 CherryIN 预设供应商，感谢 @zhibisora。
• #3818：新增 Codex CLI 探活用的 GET /v1/models 端点，感谢 @CSberlin。
• #3426：用量看板 Hero 重新设计，感谢 @allenxu09。
• #3640：空 tools 时丢弃 tool_choice，感谢 @Postroggy。
• #3644：Chat 路由保留 Codex 自定义工具元数据，感谢 @LanternCX。
• #3514：Chat→Responses 始终包含 reasoning_tokens，感谢 @yeeyzy。
• #3689：live 已是代理占位符时跳过备份 / 恢复，感谢 @YongmaoLuo。
• #3016：归一化 localhost 监听地址，感谢 @Alexlangl。
• #3775：规范化 Anthropic system 消息，感谢 @Dearli666。
• #3656：改进代理面板错误信息展示，感谢 @lzcndm。
• #2647：调高无限空白检测阈值 20 → 500，感谢 @NiuBlibing。
• #3702：智谱配额查询按所配 base URL 路由，感谢 @YongmaoLuo。
• #3518：适配 MiniMax 余额查询新接口与默认定价，感谢 @LaoYueHanNi。
• #3524：修复智谱 Coding Plan 预设与带版本号端点的模型探测，感谢 @makoMakoGo。
• #3614：模型目录改用相对文件名，感谢 @steponeerror。
• #3797：修复 Windows 退出后托盘图标残留，感谢 @iAJue。
• #3457：修复 Windows 任务栏图标，感谢 @ZhangNanNan1018。
• #3430：归一化 Windows 路径分隔符以匹配子目录技能更新，感谢 @Ninthless。
• #3626：关闭 macOS 输入框自动大写，感谢 @ZHLHZHU。
• #3593：修复 Codex VS Code 会话预览，感谢 @xwil1。
• #3228：对齐中文界面 VS Code 文案，感谢 @Games55k。
• #3411：刷新用户手册以反映当前应用支持，感谢 @makoMakoGo。
• #3772：修复 README release note 链接与赞助商标记，感谢 @null-easy。

也感谢所有在 v3.16.1 发布后反馈 Codex Chat 路由、本地代理接管、用量统计和平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。

---

下载与安装

访问 Releases 下载对应版本。

系统要求

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

Windows

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

macOS

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

CC Switch v3.16.1

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

English → | 日本語版 →

---

使用攻略

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

• 使用第三方 API 时保留 Codex 远程操作和官方插件：说明如何先完成官方登录，再开启 Codex 应用增强，让官方登录态留在 auth.json，同时把模型流量切到第三方 API。
• 在 Codex 中使用 DeepSeek：本地路由实战攻略：从添加 Codex 供应商、开启本地路由，到验证请求转发的完整路径。
• 添加 Codex 供应商：Chat Completions 路由与模型映射：覆盖「需要本地路由映射」、模型映射表与思考能力配置。
• 本地代理服务 与 本地路由：了解代理服务、接管 live 配置、以及相关风险提示。

---

[!WARNING]

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

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

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

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

---

概览

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

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

发布日期：2026-06-01

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

---

重点内容

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

---

新功能

Codex 官方认证保留设置

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

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

Codex DeepSeek 路由指南

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

---

变更

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

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

Codex 切换供应商后提示重启

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

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

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

Codex 热切换刷新显示信息

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

---

修复

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

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

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

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

Codex 模型目录数据丢失

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

同时，供应商切换现在会始终刷新生成的 Codex 模型目录 JSON（#3360，感谢 @Postroggy）。

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

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

Codex 代理错误诊断更完整

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

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

修复原生余额与 Coding Plan 查询时跨 app 错用凭据的问题。现在每个 app 会解析自己的供应商凭据，不再把其他应用面的认证假设带进查询流程（#3355，感谢 @SiskonEmilia）。

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

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

Claude Desktop 官方供应商添加失败

修复添加 Claude Desktop 官方供应商时报错的问题（#3405，感谢 @Eunknight）。

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

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

Windows 工具版本探测

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

---

升级提醒

官方 OAuth 保留需要手动开启

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

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

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

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

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

---

风险提示

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

Codex OAuth 反向代理：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 v3.13.0 release notes。

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

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

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

---

致谢

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

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

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

---

下载与安装

访问 Releases 下载对应版本。

系统要求

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

Windows

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

macOS

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

Homebrew 安装：

brew install --cask cc-switch

更新：

brew upgrade --cask cc-switch

Linux

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

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

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

CC Switch v3.16.0 —— 谨以纪念此版本开发期间死去的5个 Claude Max 订阅

为 Codex 增加 Chat Completions -> Response 格式转换（你可以在 Codex 里使用 DeepSeek, Kimi, GLM 了！）、Codex 供应商身份与历史统一、应用管理面板全方位增强、合作伙伴预设扩张、默认模型 / 定价矩阵升级到 GPT-5.5 与 Claude Opus 4.8、代理与格式转换鲁棒性强化

English → | 日本語版 →

---

[!WARNING]

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

CC Switch 是完全免费、开源的桌面应用，不会向用户收取任何费用。最近发现多个山寨网站冒用 CC Switch 名义诱导用户付费、收集账号信息，部分已造成实际经济损失。请仅通过下列官方渠道获取本软件：

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

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

---

使用攻略

本版本最主打的两块能力是 Codex 第三方供应商 Chat Completions 路由与应用内受管 CLI 工具管理。如果你想让 DeepSeek、Kimi、MiniMax 这类只支持 OpenAI Chat 协议的供应商在 Codex 里直接可用，或者想在应用内一站式安装 / 升级 CLI 工具，建议先读这两篇：

• 在 Codex 中使用 DeepSeek, Kimi, GLM 这种 chat 格式 API 供应商攻略
• 添加 Codex 供应商：Chat Completions 路由与模型映射 —— 覆盖「需要本地路由映射」开关、模型映射表、思考能力（reasoning）自适应识别的完整流程。
• 设置 → 关于：受管 CLI 工具管理 —— 覆盖版本检测、单独升级 / 全部升级、冲突诊断、按安装来源锚定的升级命令。

---

概览

CC Switch v3.16.0 自 v3.15.0 以来的开发核心，是把第三方 Codex 供应商通过 Chat Completions 路由升级为一等公民。Codex 原生只认 OpenAI Responses API 与 GPT 系列模型，本版本让 CC Switch 的本地代理把 Codex 发出的 Responses 请求转换为上游的 Chat Completions，再把 JSON 与 SSE 流式响应重建回 Responses 形态，沿途保留 reasoning_content / 内联 <think> 块 / 流式推理摘要 / 工具调用 / previous_response_id 续接状态，并把错误信封规范化、在 Stream Check 中正确探测 Chat 格式供应商。配套上货 22 个带显式模型目录的 Chat 路由预设（DeepSeek、智谱 GLM、Kimi、MiniMax、StepFun、百度千帆、百炼、ModelScope、Longcat、百灵、小米 MiMo、火山 Agentplan、BytePlus、豆包 Seed、SiliconFlow、Novita AI、Nvidia 等）。

Codex 第三方供应商的身份与历史这一版被统一并加固：所有第三方供应商现在归并到稳定的 custom model-provider 桶，并提供一次性设备迁移来改写历史 JSONL 会话与 state_5.sqlite 线程表（原文件备份在 ~/.cc-switch/backups/ 下），避免因供应商 id 变化导致过往会话"凭空消失"；同时修复了 live 读取 / 切换过程中 OAuth 登录态、用户选中的目录模型、用户自定义 provider id 被覆盖的问题。

本版本还新增了应用内受管 CLI 工具生命周期：设置页的「关于」Tab 升级为 Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes 的工具管理面板，支持静默安装 / 更新、全部升级、冲突诊断、按安装来源锚定的升级，以及对 WSL 的处理和"已安装但跑不起来"状态的可见化。

供应商生态与模型矩阵同步刷新：新增 APIKEY.FUN、APINebula、AtlasCloud、SudoCode、小米 MiMo Token Plan、Claude Desktop 官方预设；跨应用刷新合作伙伴链接与默认模型 / 定价；默认 Claude Opus 模型线升级到 4.8，适用处的 GPT 默认升级到 5.5。此外还在用量可观测性、繁体中文本地化、文档、以及代理 / 格式转换的鲁棒性上做了大量打磨与修复。

发布日期：2026-05-29

更新规模：101 commits | 221 files changed | +27,063 / -3,052 lines

---

重点内容

• Codex Chat Completions 路由：Codex 供应商现在可以由仅支持 OpenAI Chat Completions 的上游提供服务。CC Switch 把 Codex 的 Responses 请求转成 Chat Completions、把 JSON 与 SSE 响应重建回 Responses 形态、保留 reasoning / <think> / 工具调用状态、规范化错误信封，并在 Stream Check 中正确探测 Chat 格式供应商
• Codex 第三方供应商身份与历史统一并更安全：第三方 Codex 供应商现在共用稳定的 custom model-provider 桶，配一次性迁移改写历史 JSONL 会话与 state_5.sqlite 线程，并修复 live 读取 / 切换时 OAuth 登录态、用户选中的目录模型、用户自定义 provider id 的保留
• 受管 CLI 工具管理：「关于」页升级为 Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes 的工具管理面板，含安装 / 更新动作、全部升级、冲突诊断、按来源锚定的升级、WSL 处理，以及"已安装但跑不起来"状态可见化
• 供应商生态与模型矩阵刷新：新增 APIKEY.FUN、APINebula、AtlasCloud、SudoCode、小米 MiMo Token Plan、Claude Desktop 官方预设；跨应用刷新合作伙伴链接与默认模型 / 定价；默认 Claude Opus 升级到 4.8、适用处 GPT 默认升级到 5.5
• 用量与文档打磨：用量看板在日志写入时即时响应更新，修复自定义用量脚本摘要与 subagent 会话日志计费，繁体中文 UI 本地化落地，新增德文 README 与扩充后的 Claude Desktop / Codex Chat / 工具管理手册
• 代理与转换硬化：修复 Codex Chat 推理 / 缓存 / usage 边角情况、DeepSeek Anthropic 工具思考历史、Claude 兼容的空 tool_calls 流、受管账号接管鉴权、MiMo 推理输出、Gemini Native 工具调用重放，以及多条易 panic 的代理路径

---

新功能

Codex Chat Completions 路由

Codex 供应商现在可以由只会说 OpenAI Chat Completions API 的上游提供服务。CC Switch 的本地代理把 Codex 发出的 Responses 请求转换为 Chat Completions，并把 Chat 响应（JSON 与 SSE 两种）重建回 Responses 形态，沿途保留 reasoning_content、内联 <think> 块、流式推理摘要、工具调用，以及 previous_response_id 续接。一个有界的 Codex Chat 历史缓存会在工具输出之前恢复对应的工具调用。

💡 特别感谢 @EldenPdx 的 PR #2804：本功能的 Chat ↔ Responses 格式转换实现参考了他在该 PR 中的实现。

22 个带 Chat 路由的 Codex 第三方供应商预设

为主流中国开源模型启用了 Chat Completions 路由并带显式模型目录——DeepSeek、智谱 GLM（+ 英文站）、Kimi、MiniMax（+ 英文站）、StepFun（+ 英文站）、百度千帆 Coding Plan、百炼（Bailian）、ModelScope、Longcat、百灵（BaiLing）、小米 MiMo（+ Token Plan）、火山 Agentplan、BytePlus、豆包 Seed、SiliconFlow（+ 英文站）、Novita AI、Nvidia。每个预设都声明了自己的上下文窗口，便于 UI 给模型映射行确定尺寸。

Codex 模型映射表

Codex 供应商表单现在提供模型目录（每行：模型 + 显示名 + 上下文窗口），它是上游模型列表的唯一真相来源，并投影到 ~/.codex/cc-switch-model-catalog.json。

Stream Check 支持 Codex Chat 供应商

Stream Check 现在对 Chat 格式的 Codex 供应商改用 Chat 形态的请求体打 /chat/completions，而不是 /v1/responses；并把 URL 回退顺序与生产环境的 CodexAdapter 对齐（仅 origin 的 base URL 先打 /v1/<endpoint>），这样裸路径上的非 404 错误不会再把一个正常工作的供应商误判为不可用。

Codex Chat 思考能力（Reasoning）自适应

当 Codex 供应商走 Chat Completions 路由时，CC Switch 现在会自动识别上游的推理接口——依据是供应商的名称、base URL 和模型名——并注入正确的思考参数（thinking:{type}、enable_thinking、reasoning_split、顶层 reasoning_effort，或 OpenRouter 的原生 reasoning:{effort} 对象），无需手动配置。聚合 / 托管平台（OpenRouter、SiliconFlow）按平台优先匹配，因为同一个模型在不同平台上可能暴露不同的推理控制。只暴露"思考开 / 关"开关的供应商（Kimi、GLM、Qwen、MiniMax、MiMo、SiliconFlow）会丢弃 effort 等级而不是透传一个不支持的字段——因此在 Codex 里调节这类供应商的思考等级不会有任何效果——而有真实 effort 档位的供应商（DeepSeek、OpenRouter，以及 StepFun 仅 step-3.5-flash-2603）则会把等级透传上去。OpenRouter 特别使用原生 reasoning:{effort} 对象，把 max 钳到 xhigh（它的枚举里没有 max），并显式转发 effort:"none" 以便关闭推理。

Codex Goal Mode 与远程压缩控制

Codex 配置编辑现在为第三方供应商暴露一个 Goal Mode 开关和一个远程压缩（Remote Compaction）开关；新建的 Codex 模板默认 disable_response_storage = true，同时仍允许显式开启 goal 支持。

小米 MiMo Token Plan 预设

新增小米 MiMo Token Plan 预设，规格与官方文档对齐（#2803，感谢 @BlueOcean223）。

Claude Desktop 官方预设

新增一个 Claude Desktop 官方预设，用于恢复原生 Claude Desktop 登录，并附带本地化的 Claude Desktop 使用指南（中 / 英 / 日）。

受管 CLI 工具生命周期

为受管 CLI 工具新增静默安装 / 更新命令、最新版本检查、单工具与批量动作、全部升级，以及跨 PATH、Homebrew、npm、pnpm、bun、volta、fnm、nvm、scoop、WinGet、Windows 原生路径和 WSL 的多安装诊断。

按来源感知的工具诊断

设置 / 关于 页面现在可以诊断冲突的工具安装、为每条路径展示具体的安装来源与版本，并生成由后端规划、锚定到真实安装来源的升级命令。

实时用量刷新

后端现在在代理日志、会话日志同步或汇总写入用量数据时发出 usage-log-recorded 事件；用量看板监听该事件并立即让查询失效，而不是等到下一个轮询周期（#3027，感谢 @in30mn1a）。

繁体中文本地化

新增 zh-TW UI 本地化与一个设置语言选项（#3093，感谢 @LaiYueTing）。

德文 README

新增 README_DE.md 并从现有 README 的语言切换器中链接到它（#2994，感谢 @flitzrrr）。

新合作伙伴预设

跨各受支持的应用面新增 APIKEY.FUN、APINebula、AtlasCloud、SudoCode 合作伙伴预设，含合作伙伴文案、图标与 README 条目。

---

变更

Codex 第三方供应商统一进 "custom" 历史桶

Codex 按 model_provider 过滤可恢复历史，因此在供应商专属 id 之间切换会让过去的会话看起来"消失"了。所有第三方供应商现在归并到单一稳定的 custom 桶（保留 openai / ollama 这类预留的内置 id），并配一次性设备迁移：改写历史 JSONL 会话与 state_5.sqlite 线程表，原文件备份到 ~/.cc-switch/backups/codex-history-provider-migration-v1/。

Codex 供应商表单简化

从 Codex 表单中移除了 API Format 选择器（wire_api 永远是 responses，该选择器会误导用户以为能改协议）；模型映射表现在是唯一真相来源，不再有隐藏的默认条目；表单注明改动目录后需要重启 Codex，因为 model_catalog_json 在启动时加载。表单只保留「需要本地路由映射」开关。

Codex 本地路由开关提示重写

把「关 / 开」两段提示从"场景描述"改写为"动作指引"（什么时候该开），并在中 / 英 / 日三语同步。

Codex Live 配置保留

Codex live 配置读取不再强制改写用户的 model_provider 字段；供应商作用域的 experimental_bearer_token 处理现在会在第三方供应商之间切换时保留 OAuth 登录态。

工具安装 / 升级策略

受管工具安装现在优先使用官方原生安装器（在有的情况下），适当时回退到包管理器，对兼容工具先跑 self-update，把升级锚定到检测到的安装来源，并在工作进行中锁定重复的批量动作。

「关于」页升级为工具管理

设置的「关于」页现在呈现已安装 / 最新版本、安装与更新动作、冲突诊断、WSL shell 偏好，以及对损坏或跑不起来工具更清晰的状态。

默认模型与定价刷新

默认 Claude Opus 模型升级到 4.8，适用处把基于 GPT 的预设与模板迁到 GPT-5.5，刷新定价种子，把 Claude Desktop 模型映射与 Claude Code 的三角色档位对齐，并重命名 OpenCode 的 Go 预设以去掉一个陈旧的模型后缀。

合作伙伴链接刷新

更新了胜算云推荐链接、Atlas Cloud 的 UTM 链接，以及跨各 README 语言版本与供应商元数据中的合作伙伴文案。

Homebrew 官方 Cask 安装

由于 CC Switch 已进入 Homebrew 官方仓库，安装简化为 brew install --cask cc-switch；各 README 中移除了对私有 tap 的要求。

共享前端工具

用一个共享的 deepClone helper 替换 JSON stringify / parse 的深拷贝写法，并抽取了一个共享的 useTauriEvent hook（#3140，感谢 @ChongBiaoZhang）。

---

修复

Codex Chat 错误响应转换为 Responses 信封

Codex Chat → Responses 桥接此前会原样透传上游错误体，导致 Codex 客户端无法识别 MiniMax 的 base_resp、裸 OpenAI Chat 错误，或纯文本 / HTML 错误页。现在错误会被规整为标准的 {error: {message, type, code, param}} 信封并保留原始 HTTP 状态码；非 JSON 体会被包裹并在 UTF-8 字符边界截断到 1KB。同时修复了一个既存的 append-vs-insert bug，它会在重写后的 JSON 体上产生重复的 Content-Type 头。

Codex 流中段 system 消息折叠

MiniMax 的 OpenAI 兼容端点会严格拒绝任何非首位的 system 消息（错误 2013）。现在所有 system 片段会被折叠为单条首位消息（按原顺序拼接），对宽松后端也是无损的。

Codex 模型目录重启后被清空

编辑当前激活的 Codex 供应商会触发一次省略了 modelCatalog 的 live 读取，于是随后的保存会静默销毁用户配置的模型映射。Live 读取现在会反向解析磁盘上的目录投影，往返出与保存路径写入的相同形状。

Codex 模型目录无限渲染循环

打断了目录表格与其父状态之间的双向同步环路——它在添加或编辑条目时会导致 UI 严重抖动。

Codex Chat 保留用户选中的目录模型

客户端从目录里选中的模型（例如通过 /model）不再被 config.toml 的默认模型覆盖。

Codex Chat 推理与缓存稳定性

在 Codex 省略或改写 previous_response_id 时恢复一个唯一的 call-id 回退；停止从 previous_response_id 派生缓存身份；并在工具转换中对可解析的 JSON 字符串载荷做规范化，以便前缀缓存稳定复用。

Codex Chat 流式 usage 恢复

Responses → Chat 转换现在会在请求为流式时注入 stream_options.include_usage（并入客户端提供的任何 stream_options），这样 Kimi、MiniMax 这类 OpenAI 兼容上游会重新吐出尾部的 usage 块。此前它们在 Codex Chat 路径上的流式 token / 成本 / 缓存统计都被记成了零。

Codex Chat 工具调用推理回填

Kimi / Moonshot、DeepSeek 这类思考模型会拒绝携带 tool_calls 但 reasoning_content 为空的 assistant 消息。当跨轮历史恢复未命中时（代理重启、call_id 含糊，或某轮上游没有推理），现在会在最后一遍补回一个占位 reasoning_content——真实的尾部推理仍会优先附上——这样请求不再因 reasoning_content is missing in assistant tool call message 而失败。

受管账号 Claude 接管鉴权

受管账号供应商（GitHub Copilot / Codex OAuth）在接管 Claude live 配置时，现在会丢弃 token 环境变量键、只写入 ANTHROPIC_API_KEY 占位符，并带一个出站守卫拒绝把 PROXY_MANAGED 占位符发往上游。

接管期间的 Claude Desktop profile 同步

代理接管时现在会同步 Claude Desktop 的 profile 数据，模型路由与 Claude Code 的三角色档位对齐，并修正了 Cowork egress profile（#3157、#3172，感谢 @MelorTang、@JGSphaela）。

受管账号接管的模型字段

本地路由现在在受管账号上从目标供应商取接管模型字段，而不是携带陈旧的模型值。

DeepSeek Anthropic 工具思考历史

规范化了 DeepSeek Anthropic 兼容的工具思考历史，让后续轮次能够重放推理 / 工具调用上下文而不产生畸形消息（#3203，感谢 @Q3yp）。

Claude 兼容流中的空工具调用

修复了一个 Claude 兼容流式边角情况：空的 tool_calls 数组会重置块状态并破坏流式响应（#2915，感谢 @zhizhuowq）。

Claude Code 代理路径的 MiMo 推理

在 Claude Code 代理路径上新增 MiMo 的 reasoning_content 支持（#2990，感谢 @zhangyapu1）。

Gemini Native 工具调用鲁棒性

修复了长多轮会话中合成工具调用 ID 的 functionResponse.name 解析（422）与 thought_signature 重放（400）问题（#2814，感谢 @Tiancrimson）。

会话日志 subagent token 计费

collect_jsonl_files() 现在会扫描此前被漏掉的 subagent JSONL 日志，使 subagent 的 token 用量被计入会话成本（仅会话日志模式）（#2821，感谢 @LaoYueHanNi）。

用量看板 / 同步稳定性

修复了非 ASCII 模型名导致的 Codex 用量同步 panic、自定义用量脚本摘要，以及用量汇总后缺失实时刷新的问题（#3027、#3129，感谢 @in30mn1a、@hanhan3344）。

智谱 Coding Plan 配额档位排序

当 5 小时桶利用率为 0% 时，智谱 API 会省略 nextResetTime；旧的 i64::MAX 哨兵会把这类条目排到最后，导致周窗口错误地占用五小时槽位。现在档位排序会让缺失的 nextResetTime 映射到五小时桶，使智谱 Coding Plan 的托盘与用量配额显示保持正确。

技能按 key 安装

从 skills.sh 搜索结果安装时现在使用唯一 key 而不是目录名，使共享目录名的技能能安装到正确的那个（#2784，感谢 @zhaomoran）；同时修复了一处技能同步的复制回退（#2791，感谢 @rogerdigital）。

用量价格输入精度

把价格输入步长降到 0.0001，使 DeepSeek 缓存读取这类不足一分的成本也能录入（#2793，关闭 #2503，感谢 @rogerdigital）。

Ghostty 干净窗口启动

Ghostty 现在打开单个干净窗口，而不是克隆已有标签页；其他终端则通过 open -na 打开新窗口（#2801，关闭 #2798，感谢 @luw2007）。

工具版本与更新可靠性

版本探测不再掩盖跑不起来的安装；预发布工具在版本检查中被正确处理；批量更新逐工具执行；安装 / 更新按钮在预检期间保持锁定；锚定升级分支强制使用绝对路径；WSL 安装器路径在需要时使用原生 Unix 安装器。

Codex mise 检测

修复了 Codex 的 mise 环境检测（#2822，感谢 @iambinlin）。

Codex 归档会话

Codex 的归档会话现在会被纳入会话发现（#2861，感谢 @nanmen2）。

Codex Chat 空工具参数

在 Codex Chat 转换中，空的工具调用参数载荷会被强制为 {}，使上游与客户端收到合法 JSON。

Claude 供应商 deeplink 导入

通过 deeplink 导入 Claude 供应商时现在会保留自定义环境字段（#2928，感谢 @doutuifei）。

OMO 推荐模型

把 OMO 推荐模型与上游默认值同步，并改进了「填入推荐」的反馈。

胜算云模型 ID 加前缀以正确路由

胜算云（ShengSuanYun）预设现在带上了上游网关要求的厂商前缀——anthropic/…、google/…、openai/…（如 anthropic/claude-sonnet-4.6、google/gemini-3.1-pro-preview）——覆盖 Claude Code、Claude Desktop、Codex、Gemini、OpenCode、OpenClaw 各预设，含 Claude Code 路由环境变量（ANTHROPIC_MODEL / ANTHROPIC_DEFAULT_{HAIKU,SONNET,OPUS}_MODEL），使它们解析到合法的上游模型而不是路由失败。

ClaudeAPI 重新启用模型测试

把 ClaudeAPI 预设（Claude Code 与 Claude Desktop）从 third_party 重新归类为 aggregator，使其模型测试按钮不再被第三方 Claude 门禁禁用；合作伙伴金星不受影响，因为它由 isPartner 而非 category 驱动。

关于页版本检查

版本检查现在能处理预发布工具版本，不会再误判更新状态。

App 切换器文本裁切

移除了一个会裁切 App 切换器文本的固定宽度约束（#3161，感谢 @loocor）。

useEffect 竞态条件

为 App.tsx 的 effects 加了 active-flag 模式以防卸载时的监听器泄漏，并守卫了把 undefined 语言存进 localStorage 的情况（#2827，感谢 @Zylo206）。

---

移除

LionCC 赞助商与预设

跨各 README、供应商配置与 locale 移除了 LionCC 赞助商条目与 LionCCAPI 预设（图标资源保留）。

AICoding 合作伙伴条目

从 README 赞助商列表、供应商预设与 i18n 元数据中移除了 AICoding 合作伙伴。

Kimi For Coding 的 Codex 预设

从 Codex 预设目录中移除了 Kimi For Coding 预设。

CLI 卸载命令提示

从工具管理 UI 中去掉了生成的 CLI 卸载命令提示，同时保留冲突诊断的可见性。

---

文档

Codex Chat 供应商支持

在 changelog 与用户手册中记录了 Chat Completions 路由、供应商支持、推理自适应识别，以及本地路由指引。

设置手册刷新

更新了设置文档，覆盖新的受管工具生命周期与 Hermes 安装器行为。

Claude Desktop 指南

新增了本地化的 Claude Desktop 指南页与截图，覆盖供应商设置、导入、模型映射，以及本地路由上下文。

安装文档

更新了安装文档与 README，推荐官方 Homebrew cask，并跨各语言刷新了 v3.15.0 发布说明里关于山寨站点的警告措辞。

---

⚠️ 升级提醒

Codex 第三方供应商历史一次性迁移

升级后首次启动会对 Codex 历史执行一次性迁移：把第三方供应商归并到 custom 桶，并改写历史 JSONL 会话与 state_5.sqlite 线程表。原文件会备份到 ~/.cc-switch/backups/codex-history-provider-migration-v1/。这一步是为了修复"切换供应商后过往会话消失"的问题——迁移后历史能正常恢复。

Codex 改动模型目录需重启

Codex 在启动时加载 model_catalog_json，因此在 CC Switch 里改动模型映射表后，需要重启 Codex 才能让新目录生效。

Chat 路由供应商的思考等级可能无效

对只暴露"思考开 / 关"开关的供应商（Kimi、GLM、Qwen、MiniMax、MiMo、SiliconFlow），在 Codex 里调节思考等级（model_reasoning_effort 的 low / medium / high）不会有任何效果——CC Switch 不会把不被支持的 effort 字段透传给它们。只有具备真实 effort 档位的供应商（DeepSeek、OpenRouter，以及 StepFun 仅 step-3.5-flash-2603）调节等级才真正生效。

默认模型升级到 Opus 4.8 / GPT-5.5

默认 Claude Opus 模型线升级到 4.8，适用处的 GPT 默认升级到 5.5。如果你依赖某个固定的旧默认模型，升级后请检查相关预设 / 模板的模型字段是否符合预期。

---

⚠️ 风险提示

本版本在涉及反向代理类功能上沿用 v3.12.3 / v3.13.0 / v3.15.0 提出的风险提示。

GitHub Copilot 反向代理：使用 Copilot 的反代路径可能违反 GitHub / Microsoft 服务条款。详情见 v3.12.3 release notes。

Codex OAuth 反向代理：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 v3.13.0 release notes。

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

Claude Desktop 第三方供应商代理切换：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，第三方供应商对计费、合规与数据留存的约束各不相同，请在使用前阅读目标供应商的服务条款。

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

---

下载与安装

访问 Releases 下载对应版本。

系统要求

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

Windows

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

macOS

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

macOS 版本已通过 Apple 代码签名和公证，可直接安装使用。

Homebrew（macOS）

🎉 CC Switch 现已收录至 Homebrew 官方 cask 仓库，无需添加第三方 tap！

brew install --cask cc-switch

更新：

brew upgrade --cask cc-switch

Linux

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

• CC-Switch-v3.16.0-Linux-x86_64.AppImage / .deb / .rpm
• CC-Switch-v3.16.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

CC Switch v3.15.0

Claude Desktop becomes a first-class managed surface with third-party provider switching via proxy gateway, role-based model mapping, major reverse-proxy hardening, Codex OAuth live model discovery, and a filter-driven usage dashboard Hero card

中文版 → | 日本語版 →

---

[!WARNING]

Only Official Channels (Please Read)

CC Switch is a fully free and open-source desktop app, and we do not charge users any fees. Multiple imposter websites have recently been spotted impersonating CC Switch to solicit payments and harvest account credentials, with some users already reporting financial losses. Please only obtain the software through the official channels listed below:

Channel	Only Official
Website	ccswitch.io
Source	github.com/farion1231/cc-switch
Downloads	GitHub Releases
Author	@farion1231
Report an Imposter	GitHub Issues

Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake. If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues so we can take down the imposter site as quickly as possible.

---

Claude Desktop Guide

The headline feature in this release is the first-class Claude Desktop management panel. If you already have many providers configured for Claude Code, start here:

Use CC Switch to configure, manage, and switch Claude Desktop providers in one place

The guide walks through one-click import from Claude Code, adding Claude Desktop-specific providers, direct mode vs. model-mapping mode, showing the hidden local-routing toggle, and returning to Claude Desktop's official sign-in mode.

---

Overview

CC Switch v3.15.0 is a major release following the v3.14.x line, centered on promoting Claude Desktop to a first-class managed surface. It ships third-party provider switching through the in-app proxy gateway, role-based model mapping (sonnet / opus / haiku) with a supports1m long-context flag, Copilot/Codex OAuth provider reuse, a redesigned Claude Code import flow, app-switcher differentiation between "Claude Code" and "Claude Desktop", and 44 provider presets translated from the Claude Code catalog into the new Claude Desktop surface.

Around proxy reliability, this release performs a systematic hardening pass: P0–P3 patches across routing / lifecycle / retry / failover / rectifier paths; pooled HTTPS connection reuse for non-Anthropic backends to cut per-request latency; cache hit-rate improvements for Codex and OpenAI Responses (emit prompt_cache_key only when a real client-provided session identity exists, canonicalize JSON keys in outgoing request bodies plus tool_call arguments and tool_result content, and thread session_id into the usage logger); correct Anthropic ↔ OpenAI tool_choice mapping; Vertex AI full URLs are no longer truncated; Gemini request models are now extracted from the URI path; takeover detection is tightened; and IPv6 listen addresses are supported. ChatGPT Codex OAuth providers no longer depend on hardcoded model lists — CC Switch now fetches a live model list from the ChatGPT backend on demand.

Claude Code's model mapping is now role-based (sonnet / opus / haiku) with display names and a new supports1m boolean flag, replacing the legacy [1M] suffix and decoupling routing decisions from raw model IDs. The usage dashboard adds a filter-driven Hero card that exposes cache-normalized real total tokens and cache hit rate, updated live as the active date range / provider / model filters change; paired with a fix for cache-cost semantics and the noisy pricing warning storm that fired on every request. Robustness improvements in the OpenAI Responses API usage parsing path mean missing or malformed upstream usage no longer crashes the VSCode Claude Code extension with a null output.

The provider ecosystem expands further: new BytePlus, Volcengine Agentplan, ClaudeAPI, ClaudeCN, RunAPI, RelaxyCode, PatewayAI, and Baidu Qianfan Coding Plan partner presets; DouBao Seed is promoted to partner status; and provider cards now surface a "routing support" badge so users can tell at a glance which providers can be served through Local Routing. This release also fixes a long tail of issues across Codex sessions, OAuth, Claude Desktop forms, Linux segfaults, terminal fallbacks, and ships several GitHub Actions dependency bumps.

Release date: 2026-05-16

Stats: 127 commits | 211 files changed | +17,980 insertions | -2,748 deletions

---

Highlights

• Claude Desktop Becomes a First-Class Managed Surface: Third-party provider switching through the in-app proxy gateway, role-based model mapping (sonnet / opus / haiku) with a supports1m long-context flag, Copilot/Codex OAuth provider reuse, and 44 provider presets translated from the Claude Code catalog. Note: 20 Claude Desktop presets now default to direct mode instead of proxy mode — verify connectivity after upgrade if you previously relied on proxy routing.
• Major Reverse-Proxy Hardening: P0–P3 lifecycle / retry / failover / rectifier patches; pooled HTTPS reuse for non-Anthropic backends; Codex / Responses cache hit-rate improvements; correct Anthropic ↔ OpenAI tool_choice mapping; Vertex AI URL preservation; Gemini path-based model extraction; refined takeover detection; IPv6 listen address support.
• Provider Ecosystem Expansion: New BytePlus, Volcengine Agentplan, ClaudeAPI, ClaudeCN, RunAPI, RelaxyCode, PatewayAI, and Baidu Qianfan Coding Plan partner presets; DouBao Seed promoted to partner status; routing-support badges on provider cards.
• Role-Based Model Mapping with 1M Flag: Role-based sonnet / opus / haiku routing with display names and a supports1m flag replaces the legacy [1M] suffix.
• Codex OAuth Live Model Discovery: ChatGPT Codex providers fetch the live model list from the ChatGPT backend on demand.
• Usage Dashboard Filter-Driven Hero: Surfaces cache-normalized real total tokens and cache hit rate, updated live as date / provider / model filters change.
• DeepSeek Tool Calls + Zero-Usage Final Delta: DeepSeek tool calls now return reasoning_content alongside tool_calls (#2543, thanks @bling-yshs); the final message_delta always includes a usage block (even when zero) so strict Anthropic clients no longer crash on null (#2485, thanks @Myoontyee).
• OpenAI Responses API Usage Parsing Robustness: Missing or malformed upstream usage no longer crashes the VSCode Claude Code extension (#2422, thanks @magucas).

---

Added

Claude Desktop Third-Party Provider Switching via Proxy Gateway

CC Switch now treats Claude Desktop as a first-class managed surface alongside Claude Code / Codex / Gemini / OpenCode / OpenClaw / Hermes.

• New dedicated Claude Desktop panel that brokers third-party providers to Claude Desktop through CC Switch's in-app proxy gateway
• Routing-support badge on cards for providers that need Local Routing
• Role-based model route mapping locked to sonnet / opus / haiku
• Copilot / Codex OAuth providers can be reused in the Claude Desktop panel
• Redesigned Claude Code settings import flow
• App switcher visually distinguishes "Claude Code" from "Claude Desktop", and the app visibility settings use the "Claude Code" label
• 44 Claude Desktop provider presets translated from the Claude Code preset catalog

Routing Support Badges on Provider Cards

Provider cards in both the Claude Code and Codex panels now show a routing-support badge so users can tell at a glance which providers can be served through Local Routing.

Codex OAuth Live Model List

ChatGPT Codex providers no longer rely on a hardcoded model selection — CC Switch fetches a live model list from the ChatGPT backend on demand.

Role-Based Model Mapping with 1M Flag

Claude Code model mapping is now role-based (sonnet / opus / haiku) with display names and a supports1m boolean flag, replacing the legacy [1M] suffix and decoupling routing from raw model IDs.

Filter-Driven Usage Hero

The usage dashboard's Hero summary is now filter-driven, updating live as the active date range / provider / model filters change; it surfaces cache-normalized real total tokens and cache hit rate so the Hero figures line up with the detail list below.

Provider Form "Save Anyway" Prompt

Softened provider form input validation by turning non-blocking input issues into a "save anyway" prompt, so a harmless field issue no longer blocks saving (#2307, thanks @allenxln).

Universal Provider Duplicate Action

Added a "duplicate" button for universal providers from the provider list (#2416, thanks @hubutui).

Persisted Tauri Window State

Window position and size now persist across launches (#2377, thanks @BillSaul).

Tray Icon Tooltip

The system tray icon now surfaces a status tooltip on hover (#2417, thanks @Coconut-Fish).

Warp Terminal Session Launch

Added support for launching Warp and executing a saved session inside it (#2466, thanks @tisonkun).

DeepSeek reasoning_content for Tool Calls

DeepSeek tool-call responses now return reasoning_content and tool_calls together, so callers can render both (#2543, thanks @bling-yshs).

Baidu Qianfan Coding Plan (Claude Code)

Added a Baidu Qianfan Coding Plan preset (#2322, thanks @jimmyzhuu).

Compshare Coding Plan Preset (Cross-App)

The Compshare Coding Plan preset now lands across claude / codex / hermes / openclaw.

Partner Provider Presets

Added BytePlus, Volcengine Agentplan, ClaudeAPI, ClaudeCN, RunAPI, RelaxyCode, and PatewayAI partner presets; promoted DouBao Seed to partner status (refreshed endpoint and links).

44 Claude Desktop Provider Presets

Translated 44 provider presets from the Claude Code preset catalog into the new Claude Desktop panel.

---

Changed

20 Claude Desktop Presets Default to Direct Mode

20 Claude Desktop presets now ship in direct mode instead of routing through the proxy by default, reducing setup friction for users who don't need proxy-specific compatibility shims. If you previously relied on proxy routing for these presets, verify connectivity after upgrading.

Claude Desktop Operational Notes

Switching a Claude Desktop provider writes CC Switch's managed 3P profile and requires restarting Claude Desktop to take effect; proxy-mode providers require CC Switch's Local Routing to stay running while in use.

Failover / Local Routing Guardrails

Failover controls now require the target app's Local Routing takeover to be enabled before they can be turned on; stopping only the proxy service is blocked while any app still depends on takeover state, preventing the "proxy stopped but the app still thinks takeover is running" inconsistency.

Usage Accounting Semantics Changed

Usage summaries now report cache-normalized real total tokens and cache hit rate. Historical token and cost figures may shift after deduplication and pricing recalculation — the new numbers are more accurate but will not equal the values reported in earlier versions.

Provider Preset Rendering Order

Preset lists now render in the author-defined array order, with partners prioritized first, replacing the previous implicit sort.

Model Mapping Hint Copy Simplified

modelMappingOffHint was rewritten as action-oriented copy across zh / en / ja.

CC Switch Brand Surface Unified to ccswitch.io

All in-app and README "official website" references now point at ccswitch.io as the sole official site; the release notes template also surfaces ccswitch.io.

Theme Switch Simplified

Removed the circular reveal animation during theme switches; theme changes are now an instant cross-fade.

Claude Code App Switcher Differentiation

The app switcher visually distinguishes "Claude Code" from "Claude Desktop", and the app visibility settings use the "Claude Code" label.

CI: Claude Review Upgraded to Opus 4.7

The Claude review GitHub Action is upgraded to Opus 4.7; the prompt is tuned to reduce nitpick noise; a new @claude review-only Code Action is added; PR head SHA is pinned for checkout; the --max-turns 5 limit is removed.

GitHub Actions Dependency Bumps

• actions/checkout 4 → 6 (#2517)
• pnpm/action-setup 5 → 6 (#2518)
• softprops/action-gh-release 2 → 3 (#2519)
• actions/stale 9 → 10 (#2520)

DeepSeek Presets Switched to V4

DeepSeek presets now ship V4 (flash / pro) with refreshed pricing seeds.

Codex 1M Context Toggle Hidden in Edit Form

The 1M context-window toggle is no longer surfaced in the Codex provider edit form, reducing the density of knobs that have no effect in current Codex deployments.

OpenClaudeCode Migrated to MicuAPI Domain

The OpenClaudeCode preset is migrated to the MicuAPI domain; Micu API links are refreshed to micuapi.ai.

CrazyRouter Endpoints Switched to cn Subdomain

CrazyRouter preset endpoints now use the cn subdomain.

RelaxyCode Custom Icon

The RelaxyCode preset icon is switched to a custom relaxcode.png asset.

Kimi For Coding Doc URL

The Kimi For Coding website URL is updated to the /code/docs/ path.

SiliconFlow International Site Shows USD

The SiliconFlow international site now correctly shows USD for balance display (it previously displayed CNY incorrectly).

---

Fixed

OpenAI Responses API Usage Parsing Robustness

Hardened build_anthropic_usage_from_responses() and the Responses → Anthropic SSE translator so a missing or malformed upstream usage no longer produces "usage": null in message_delta. This unblocks strict Anthropic clients (notably the VSCode Claude Code extension) that crashed with Cannot read properties of null (reading 'output_tokens') against providers such as Codex OAuth and DashScope's compatible-mode/v1/responses endpoint. Added OpenAI field-name fallbacks (prompt_tokens / completion_tokens), null / empty / partial object handling, and preserved cache token fields even when input/output tokens are missing (#2422, thanks @magucas).

Proxy Reliability Patches (P0–P3)

Multiple rounds of routing / lifecycle / retry / rectifier patches across the request-forwarder paths; extracted a shared handle_rectifier_retry_failure helper and a shared auth_header_value helper.

Proxy: Pooled HTTPS Connection Reuse for Non-Anthropic Backends

Non-Anthropic backends now reuse pooled HTTPS connections instead of opening a fresh TLS session per request, materially reducing per-request latency.

Proxy: Forward Client's Actual HTTP Method

The proxy no longer hard-codes POST — it forwards the client's actual HTTP method, so non-POST upstream endpoints (e.g. GET /v1/models) now work correctly.

Proxy: Per-Attempt Counters and max_retries Wiring

Client-request counters are moved out of the per-attempt loop; AppProxyConfig.max_retries is now correctly wired into the request forwarder.

Proxy: Failover Decision Refinements

Refined retryable vs. unretryable error classification in the request forwarder.

Proxy: Takeover Detection Tightening

Takeover detection is tightened; disabling takeover uses fallback restore, so leftover state no longer strands a provider.

Proxy: Anthropic ↔ OpenAI tool_choice Mapping

During format conversion, Anthropic's tool_choice is now correctly mapped to the OpenAI Chat nested form.

Proxy: Gemini Request Model Extracted from URI Path

Gemini request models are now extracted from the URI path (instead of the body), so transformed traffic reports the right model name.

Proxy: Auth Header Error Handling

get_auth_headers now returns Result instead of panicking on bad credentials.

Proxy: IPv6 Listen Address Validation

The Proxy panel now accepts IPv6 listen addresses.

Proxy: Codex / Responses Cache Hit Rate

Improved cache hit rate for Codex and OpenAI Responses requests by stabilizing cache key derivation: emit prompt_cache_key only when the client actually carries a session identity, so unrelated conversations no longer collapse onto a single key; canonicalize (sort) JSON keys in outgoing request bodies and in tool_call arguments / tool_result content for byte-identical prefix-cache reuse; thread session_id into the usage logger for request correlation.

Proxy: JSON Schema Underscore Fields Preserved

Private-parameter filtering now preserves underscore-prefixed field names inside JSON Schema name maps (properties, patternProperties, definitions, $defs), so user-defined schema keys like _id and _meta pass through the filter intact.

Proxy: Read Tool Empty Pages

Drop empty pages from Read tool inputs so providers no longer reject the request (#2472, thanks @Kwensiu).

Proxy: Per-Request Hot-Path Trim

Trimmed per-request hot-path work and database wait time.

Proxy: Real Provider Model Names Under Takeover

Under takeover, the Claude Code menu now exposes the real provider model names instead of a stale alias.

Proxy: Zero Usage in Final message_delta

The final message_delta event now always includes a usage block (even when zero) so strict Anthropic clients no longer crash on null (#2485, thanks @Myoontyee).

Proxy: Streaming message_delta Deduplication

Deduplicated message_delta events that some upstreams emit twice (#2366, thanks @codeasier).

Proxy: Scoped reasoning_content Preserved for Tool Calls

Tool-call paths now correctly preserve the scoped reasoning_content field during transformation; Kimi / Moonshot's OpenAI Chat compatibility path keeps the field while generic OpenAI-compatible requests stay free of it (#2367, thanks @codeasier).

Proxy: Vertex AI Full URL Preserved

Full Vertex AI URLs are no longer truncated during proxy forwarding (#2415, thanks @xpfo-go).

Proxy: Leading Billing Header Stripped from System Content

Some upstreams prepend a billing-header chunk to the system message; this content is now stripped (#2350).

Proxy: Claude Auth Strategy Derived from ANTHROPIC_* Env Var

The Claude auth strategy is now derived from the actual ANTHROPIC_* env variable name rather than an opaque heuristic.

Third-Party Claude Providers: Disable Model Test

Model probing is disabled for third-party Claude gateways that don't implement /v1/models consistently.

Model-Fetch: /models for Anthropic-Compatible Subpath Providers

/models discovery now works for Anthropic-compatible subpath providers.

Copilot: Claude Model IDs Resolved Against Live /models

Copilot-backed providers now resolve Claude model IDs against the live /models list to avoid stale ID mismatches.

Codex: Session Title No Longer Pulls in environment_context

Codex session title extraction no longer pulls in the environment_context noise (#2439, thanks @eclipsehx).

Codex: Subagent Sessions Hidden

Codex subagent sessions are now hidden from the main session list (#2445, thanks @LanternCX).

Codex Startup Live Import Duplication

Fixed a duplicate-import bug in the Codex startup live-import path (#2590, thanks @DhruvShankpal).

Codex Provider Switch No Longer Disturbs History

Switching the active Codex provider no longer changes existing session history (#2349, thanks @SaladDay).

Codex Usage Log Wording

Corrected a misleading log message for Codex session usage (#2473, thanks @tisonkun).

Claude: Persist max Effort via Env

max effort now correctly persists across restart via the env variable (#2493, thanks @makoMakoGo).

Claude Desktop: Model Route Matching Without [1M] Suffix

Route matching no longer requires the legacy [1M] suffix.

Claude Desktop: Provider Form Input Focus Loss

Fixed an input in the Claude Desktop provider form that lost focus while being edited.

Claude Desktop: Spurious Proxy-Stopped Status Alert

Removed an alert that fired spuriously when the proxy was intentionally stopped.

Claude Desktop: Empty Toolbar Capsule Hidden

The empty toolbar capsule is now hidden when Claude Desktop is the active app.

UI: Monitor Badge Icon Centering

Centered the Monitor badge icon in the app switcher.

Linux: Theme Selection Segfault

Prevented a segfault triggered by selecting a theme on Linux (#2502, thanks @definfo).

Terminal: iTerm Fallback on Cold Launch

Prevented iTerm from being selected as a fallback on cold launch when it isn't actually installed (#2448, thanks @hulkbig).

Config: JSON Keys Sorted Alphabetically

Config writes now sort JSON keys alphabetically for deterministic output (#2469, thanks @fuleinist).

"Import Existing" Made Side-Effect Free

The "import existing" action is now side-effect free (#2429, thanks @xwil1).

Coding Plan: Zhipu Weekly Tier Named by Reset Time

Corrected the Zhipu weekly tier name to match the actual reset time (#2420, thanks @TuYv).

DashScope: Usage Parsing Robustness

Hardened DashScope usage parsing so a malformed payload no longer crashes the VSCode Claude Code extension (#2425, thanks @magucas).

Usage: Deduplicate Proxy and Session-Log Sources

Deduplicated usage records sourced from both the proxy and session logs.

Usage: Cache Cost Semantics + Pricing Warn Storm

Corrected cache-cost semantics and silenced the noisy pricing warning that fired on every request.

CI: Frontend Formatting + Linux Clippy Restored

Restored frontend formatting and Linux clippy checks in CI.

Proxy Test Helper Clippy Warning

Fixed a clippy warning in the proxy test helper.

---

Removed

Hermes Agent Usage Tracking Integration

Removed the Hermes Agent usage tracking integration originally planned for this cycle — upstream behavior changes made the integration impractical to maintain. The integration was never enabled in any released version; the "zero-cost rendering" bug discovered during its development was fixed before the integration was rolled back.

Theme Switch Circular Reveal Animation

Removed the circular reveal animation used during theme switches — it stuttered on slower compositors and added little visible value.

DDSHub Partner Integration

Removed DDSHub as a partner preset and dropped the cross-link blurbs from the READMEs.

---

Docs

README Sponsor Refresh (zh / en / ja)

Added BytePlus, ClaudeCN, RunAPI, and PatewayAI sponsor entries; cross-linked BytePlus and Volcengine entries; refreshed the CrazyRouter $2 credit claim flow, the Compshare blurb, the Right Code blurb, and other sponsor logos and listings; flattened the LionCC logo onto a white background; switched the Chinese README's sponsor logo to the Volcengine artwork; added Hermes Agent to the README subtitles.

Release Notes Template

The release notes template now surfaces ccswitch.io.

Brand Surface

Documented ccswitch.io as the sole official website across READMEs and in-app references.

---

⚠️ Upgrade Notes

20 Claude Desktop Presets Default to Direct Mode

These 20 presets previously routed through the proxy by default and now default to direct mode. If you were using one of these presets pre-upgrade and depended on the proxy path for connectivity (for example because the proxy applies a special rectifier or transformation layer), verify connectivity after upgrading; you can manually switch them back to proxy mode from the CC Switch panel if needed.

Claude Desktop Operational Constraints

Switching a Claude Desktop provider requires restarting Claude Desktop to take effect; proxy-mode providers require CC Switch's Local Routing to stay running while in use — quitting CC Switch or stopping Local Routing will cut off any proxy-mode Claude Desktop providers.

Failover Requires Takeover Enabled

Before enabling Failover, make sure the target app's Local Routing takeover is enabled, otherwise the Failover control will refuse to start; stopping the proxy service while any app still depends on takeover state is blocked, so you need to disable takeover at the app layer first before stopping the proxy.

Usage Figures May Diverge from History

Usage summaries now use cache-normalized real total tokens + cache hit rate. Historical token and cost figures may shift after deduplication and pricing recalculation — the new numbers are more accurate but will not equal what earlier versions reported.

---

⚠️ Risk Notice

This release inherits the risk notices originally introduced in v3.12.3 / v3.13.0 for reverse-proxy-style features.

GitHub Copilot Reverse Proxy: Using Copilot's reverse-proxy path may violate GitHub / Microsoft's terms of service. See the v3.12.3 release notes for details.

Codex OAuth Reverse Proxy: Using the Codex OAuth reverse proxy with a ChatGPT subscription may violate OpenAI's terms of service. See the v3.13.0 release notes for details.

Claude Desktop Third-Party Provider Switching via Proxy Gateway: Routing Claude Desktop traffic through CC Switch's in-app proxy gateway to a third-party provider exposes those requests to that provider's billing, compliance, and data-retention policies — read the target provider's terms of service before using.

By enabling these features, users accept all associated risks. CC Switch is not responsible for any account restrictions, warnings, or service suspensions that result from using these features.

---

Download & Installation

Visit Releases to download the appropriate version.

System Requirements

OS	Minimum Version	Architecture
Windows	Windows 10 or later	x64
macOS	macOS 12 (Monterey) or later	Intel (x64) / Apple Silicon (arm64)
Linux	See table below	x64 / ARM64

Windows

File	Description
CC-Switch-v3.15.0-Windows.msi	Recommended - MSI installer, supports auto-update
CC-Switch-v3.15.0-Windows-Portable.zip	Portable, extract and run, no registry writes

macOS

File	Description
CC-Switch-v3.15.0-macOS.dmg	Recommended - DMG installer, drag into Applications
CC-Switch-v3.15.0-macOS.zip	Extract and drag into Applications, Universal Binary
CC-Switch-v3.15.0-macOS.tar.gz	For Homebrew installation and auto-update

macOS builds are Apple code-signed and notarized — install directly.

Homebrew (macOS)

🎉 CC Switch is now available in the official Homebrew cask repository — no need to add a custom tap!

brew install --cask cc-switch

Update:

brew upgrade --cask cc-switch

Linux

Linux artifacts are published for both x86_64 and ARM64 (aarch64). The architecture is included in the asset filename — pick the one matching your machine's uname -m output:

• CC-Switch-v3.15.0-Linux-x86_64.AppImage / .deb / .rpm
• CC-Switch-v3.15.0-Linux-arm64.AppImage / .deb / .rpm

Distribution	Recommended	Installation
Ubuntu / Debian / Linux Mint / Pop!_OS	.deb	sudo dpkg -i CC-Switch-*.deb or sudo apt install ./CC-Switch-*.deb
Fedora / RHEL / CentOS / Rocky Linux	.rpm	sudo rpm -i CC-Switch-*.rpm or sudo dnf install ./CC-Switch-*.rpm
openSUSE	.rpm	sudo zypper install ./CC-Switch-*.rpm
Arch Linux / Manjaro	.AppImage	Add execute permission and run, or use AUR
Other distros / not sure	.AppImage	chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage

CC Switch v3.14.1

Tray usage visibility, Codex OAuth stability fixes, Skills import/install reliability, and removal of the Hermes config health scanner

中文版 → | 日本語版 →

---

Overview

CC Switch v3.14.1 is a patch release following v3.14.0, focused on Codex OAuth reverse-proxy stability, tray usage visibility, Skills import / install reliability, Gemini session restore paths, and simplifying Hermes configuration health handling.

For the first time, the system tray surfaces cached usage for the current Claude / Codex / Gemini provider directly in its submenus — including subscription summaries and usage-script summaries with color-coded utilization markers. For Chinese coding-plan providers like Kimi / Zhipu / MiniMax, the tray additionally renders a 5-hour + weekly window layout in the 🟢 h12% w80% style (worst utilization drives the emoji), semantically identical to the official subscription badges. Creating a Claude provider whose ANTHROPIC_BASE_URL matches a known coding-plan host now auto-injects meta.usage_script so the tray lights up without opening the Usage Script modal.

Several Codex OAuth reverse-proxy stability issues are addressed this release: client-provided session IDs are now used as both prompt_cache_key and the Codex session header to avoid UUID-driven cache churn; non-streaming Anthropic clients receive proper JSON responses even when the ChatGPT Codex upstream forces OpenAI Responses SSE; and Stream Check now builds probes with the same store: false, encrypted reasoning include, and provider FAST mode setting as production requests, eliminating the "check fails but it actually works" mismatch. Paired with a new explicit FAST mode toggle, users can now opt into service_tier="priority" on Codex OAuth-backed Claude providers, trading latency against ChatGPT quota consumption on their own terms.

Additionally, the in-app Hermes config health scanner and its warning banner are removed (along with the scan_hermes_config_health command, HermesHealthWarning type, and HermesWriteOutcome.warnings payload), refocusing the Hermes surface on active provider display, switching defaults, memory editing, and launching the Hermes Web UI — deep configuration health is now Hermes's own responsibility.

Release Date: 2026-04-23

Update Scale: 13 commits | 48 files changed | +1,883 / -808 lines

---

Highlights

• Tray Usage Visibility: Claude / Codex / Gemini tray submenus show cached usage for the current provider, including subscription and script-based summaries with color markers; refreshes are throttled, limited to visible apps, and synchronized back into React Query (#2184, thanks @TuYv)
• Tray Coding-Plan Usage (Kimi / Zhipu / MiniMax): The tray renders 5-hour + weekly window usage using the 🟢 h12% w80% layout; Claude providers whose base URL matches a known host auto-inject meta.usage_script
• Codex OAuth FAST Mode: New explicit FAST mode toggle for Codex OAuth-backed Claude providers; when enabled, converted Responses requests send service_tier="priority". Off by default (#2210, thanks @JesusDR01)
• Codex OAuth Stability: Fixed reverse-proxy cache routing (#2218, thanks @majiayu000), Responses SSE aggregation (#2235, thanks @xpfo-go), and Stream Check parity with production (#2210, thanks @JesusDR01)
• Hermes Config Health Scanner Removed: Refocuses the Hermes surface on provider management, memory editing, and launching the Web UI — no longer duplicates deep configuration health judgments
• Skills Import / Install Reliability: Import dialog disables actions while pending and deduplicates results by ID (#2211, thanks @TuYv); model quick-set / one-click config applies against the latest form state (#2249, thanks @Coconut-Fish); root-level SKILL.md repo installs are stable (#2231, thanks @santugege)
• Gemini Session Restore Paths: Session scanning reads .project_root metadata and passes the original project directory back into restore flows (#2240, thanks @tisonkun)
• Session / Settings Layout Polish: Hardened the scroll-area viewport with width containment to fix horizontal overflow; tightened app bottom and settings footer spacing (#2201, thanks @Coconut-Fish)

---

Added

Tray Usage Visibility

• System tray submenus now show cached usage for the current Claude / Codex / Gemini provider (#2184, thanks @TuYv)
• Includes subscription quota summaries and usage-script summaries with color-coded utilization markers
• Tray-triggered refreshes are throttled, limited to visible apps, and synchronized back into React Query so the main window and tray share the same usage data

Tray Coding-Plan Usage (Kimi / Zhipu / MiniMax)

• The tray renders 5-hour + weekly window usage for Chinese coding-plan providers
• Uses the same 🟢 h12% w80% two-window layout as official subscription badges (worst utilization drives the emoji color)
• Creating a Claude provider whose ANTHROPIC_BASE_URL matches a known coding-plan host auto-injects meta.usage_script, so the tray lights up without opening the Usage Script modal
• Existing usage_script values are preserved on update, never clobbering user customizations

Codex OAuth FAST Mode

• New explicit FAST mode toggle for Codex OAuth-backed Claude providers (#2210, thanks @JesusDR01)
• When enabled, converted Responses requests send service_tier="priority" for lower latency
• Off by default to avoid unexpectedly increasing ChatGPT quota consumption

---

Changed

Session and Settings Layout Polish

• Hardened the scroll-area viewport with width containment to fix horizontal overflow (#2201, thanks @Coconut-Fish)
• Tightened app bottom and settings footer spacing so long session / settings views fit more cleanly

---

Removed

Hermes Config Health Scanner

• Removed the in-app Hermes config health scanner and its warning banner
• Removed the scan_hermes_config_health command, HermesHealthWarning type, and HermesWriteOutcome.warnings payload
• The CC Switch Hermes surface now focuses on its core job: active provider display, default provider switching, memory editing, and launching the Hermes Web UI for deep configuration

---

Fixed

Codex OAuth Cache Routing

• Use the client-provided session ID as both prompt_cache_key and the Codex session header, preserving explicit cache keys (#2218, thanks @majiayu000)
• Stop generating UUIDs that caused cache-identity churn, stabilizing the ChatGPT Codex reverse-proxy cache identity

Codex OAuth Responses SSE Aggregation

• Non-streaming Anthropic clients now receive proper JSON even when the ChatGPT Codex upstream forces OpenAI Responses SSE (#2235, thanks @xpfo-go)
• CC Switch aggregates the upstream SSE events before running the non-streaming transform

Codex OAuth Stream Check Parity

• Stream Check now builds Codex OAuth probe requests with the same store: false, encrypted reasoning include, and provider FAST mode setting as production proxy traffic (#2210, thanks @JesusDR01)
• Eliminates the "check fails but it actually works" mismatch

Codex Model Extraction

• Reading the model field from Codex config now uses TOML parsing instead of first-line regex matching (#2227, thanks @nmsn)
• Multiline TOML is handled correctly

Model Quick-Set / One-Click Config

• Model quick-set now applies against the latest provider form config (#2249, thanks @Coconut-Fish)
• Fixes stale form state preventing one-click configuration from succeeding

Skills Import Duplicates

• The Skills import dialog disables actions while import is pending (#2211, thanks @TuYv)
• The installed-skills cache deduplicates imported results by ID, preventing double-clicks from adding duplicate installed entries (#2139)

Root-Level Skill Repos

• Skill install and update flows now consistently resolve three source patterns: direct nested paths, install-name recursive search, and repository-root SKILL.md sources (#2231, thanks @santugege)

Gemini Session Restore Paths

• Gemini session scanning now reads .project_root metadata (#2240, thanks @tisonkun)
• Restore flows can pass the original project directory when available

Provider Hover Names

• Provider icons now expose the provider name on hover for inline SVG, image URL, and fallback initials render paths (#2237, thanks @tisonkun)

---

Notes & Caveats

• Hermes Health Scanner Removed: If you were relying on CC Switch to surface deep Hermes YAML configuration issues, switch to the "Launch Hermes Web UI" toolbar button and inspect them in Hermes's own panel. Day-to-day provider management, switching, memory editing, and MCP / Skills sync continue to be handled by CC Switch.
• Codex OAuth FAST Mode Off by Default: Only turn it on if you accept potentially increased ChatGPT quota consumption in exchange for lower latency.
• Tray Cached Usage: Refreshes are throttled and limited to the currently visible app to avoid unnecessary upstream API calls; values are synchronized into React Query so the main window and tray stay in sync.

---

Download & Installation

Visit Releases to download the appropriate version.

System Requirements

OS	Minimum Version	Architecture
Windows	Windows 10 or later	x64
macOS	macOS 12 (Monterey) or later	Intel (x64) / Apple Silicon (arm64)
Linux	See table below	x64

Windows

File	Description
CC-Switch-v3.14.1-Windows.msi	Recommended - MSI installer, supports auto-update
CC-Switch-v3.14.1-Windows-Portable.zip	Portable, extract and run, no registry writes

macOS

File	Description
CC-Switch-v3.14.1-macOS.dmg	Recommended - DMG installer, drag into Applications
CC-Switch-v3.14.1-macOS.zip	Extract and drag into Applications, Universal Binary
CC-Switch-v3.14.1-macOS.tar.gz	For Homebrew installation and auto-update

macOS builds are Apple code-signed and notarized — install directly.

Homebrew (macOS)

brew tap farion1231/ccswitch
brew install --cask cc-switch

Update:

brew upgrade --cask cc-switch

Linux

Distribution	Recommended	Installation
Ubuntu / Debian / Linux Mint / Pop!_OS	.deb	sudo dpkg -i CC-Switch-*.deb or sudo apt install ./CC-Switch-*.deb
Fedora / RHEL / CentOS / Rocky Linux	.rpm	sudo rpm -i CC-Switch-*.rpm or sudo dnf install ./CC-Switch-*.rpm
openSUSE	.rpm	sudo zypper install ./CC-Switch-*.rpm
Arch Linux / Manjaro	.AppImage	Add execute permission and run, or use AUR
Other distros / not sure	.AppImage	chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage