mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-07-24 12:44:18 +08:00
Jason
e50fc0eb28
- Add v3.16.4 release notes in zh/en/ja. - Add a trilingual FAQ explaining why custom models don't show in the Codex desktop model picker (upstream Codex Desktop login-identity gating, not a cc-switch bug) and the keep-official-login mitigation; cross-linked both ways with the official-auth preservation guide. - Align the CHANGELOG 3.16.4 release date to 2026-06-27.
352 lines
33 KiB
Markdown
352 lines
33 KiB
Markdown
# CC Switch v3.16.4
|
||
|
||
> 继 v3.16.3 把「用量计费做准」之后，这一版把重心放在打磨 Codex 代理链路与丰富用量 / 定价工具上——国产供应商原生 Responses 迁移、上游格式选择器与模型映射解耦、zstd 请求 / 错误体解压，以及一批工具调用与 OAuth 走代理的修复；同时新增本地代理请求覆盖、数据库版本过新时的应用内恢复屏、原生 Windows ARM64 构建，并带来一波预设与品牌更新（SubRouter、OpenCode Go、CTok→ETok 改名、Kimi 品牌刷新与 prime-partner 徽标）。
|
||
|
||
**[English →](v3.16.4-en.md) | [日本語版 →](v3.16.4-ja.md)**
|
||
|
||
---
|
||
|
||
## 使用攻略
|
||
|
||
本版以打磨与扩展为主，新增的能力主要落在用量面板与供应商表单的高级选项里，建议结合以下文档了解：
|
||
|
||
- **[Codex 桌面看不到自定义模型？](../guides/codex-desktop-custom-model-visibility-zh.md)**：不少用户反馈在 Codex 桌面应用里看不到配置的第三方 / 自定义模型。这是 Codex 桌面应用**上游自身的门控行为**（按官方登录状态放行模型选择器），并非 CC Switch 的本地配置问题，**本版（v3.16.4）未对此做改动**；文档里说明了原因，以及可用的缓解办法（保留官方登录 + 路由接管）。
|
||
- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源与统计口径。本版新增了从 models.dev 批量导入模型定价、火山方舟 Coding / Agent Plan 的 AK/SK 用量查询，以及自定义日期范围的「实时结束时间」。
|
||
- **[设置](../user-manual/zh/1-getting-started/1.5-settings.md)**：本地代理请求覆盖（自定义请求头 / 请求体）、Codex 上游格式选择器与本地路由开关等都在供应商表单的高级选项里。
|
||
|
||
---
|
||
|
||
> [!WARNING]
|
||
>
|
||
> ## 唯一官方渠道声明（请务必阅读）
|
||
>
|
||
> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
|
||
>
|
||
> | 类别 | 唯一官方 |
|
||
> | -------- | ------------------------------------------------------------------------------ |
|
||
> | 官网 | **[ccswitch.io](https://ccswitch.io)** |
|
||
> | 源码 | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||
> | 下载 | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||
> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||
>
|
||
> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。
|
||
|
||
---
|
||
|
||
## 概览
|
||
|
||
CC Switch v3.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](https://github.com/farion1231/cc-switch/pull/4575)）
|
||
|
||
### 本地代理请求覆盖（自定义请求头与请求体）
|
||
|
||
供应商配置现在可以定义自定义请求头与请求体覆盖，由本地代理在转发时应用，并通过 Claude 与 Codex 供应商表单里的新字段暴露。输入会经过校验，其中包含一份受保护的请求头名单，用于阻止覆盖安全敏感的请求头。（[#4589](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/issues/4017)）。（[#4079](https://github.com/farion1231/cc-switch/pull/4079)）
|
||
|
||
### 原生 Windows ARM64 构建
|
||
|
||
发布产物现在包含原生的 Windows ARM64 制品，ARM 架构的 Windows 设备可以拿到对应的原生构建，不必再依赖 x64 模拟。发布矩阵也改为各平台独立运行（关闭 fail-fast），因此某个任务缺少密钥而失败（例如 fork 里的 macOS 签名）不会再把尚未完成的同级任务一并取消。（[#3950](https://github.com/farion1231/cc-switch/pull/3950)）
|
||
|
||
### 自定义日期范围的实时结束时间
|
||
|
||
自定义日期范围选择器新增了一个「结束时间跟随当前时间」勾选框；开启后结束时间变为只读并自动跟随此刻，因此用量数据始终反映从所选起点到当下的实时消耗。这在 Coding Plan 的 5 小时配额窗口里尤其有用。`liveEndTime` 已纳入 React Query 的缓存键，因此一个实时范围和一个端点相同的固定范围不会再共用同一个陈旧缓存项。（[#4438](https://github.com/farion1231/cc-switch/pull/4438)）
|
||
|
||
### 会话详情头显示源文件名
|
||
|
||
会话详情头现在会在项目目录旁显示会话日志的文件名（悬停看完整路径、可点击复制），方便用户直接从界面定位并打开底层的 JSONL 文件。对于像 ~70 字符的 Codex rollout 这类没有空格的长文件名，会截断到 `max-w-[200px]`，避免在窄窗口里溢出到操作按钮区。（[#4113](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/issues/2016)、[#2931](https://github.com/farion1231/cc-switch/issues/2931)。（[#4583](https://github.com/farion1231/cc-switch/pull/4583)）
|
||
|
||
### 压缩请求体与错误体的解压
|
||
|
||
Codex Desktop 在对 Codex 后端认证时会发送 zstd 压缩的请求体，这会破坏本地代理路由，因为处理器直接用 `serde_json` 解析原始压缩字节。代理现在会在 JSON 解析前对请求体解压（gzip / br / deflate，外加新增的 zstd 支持，包括 `gzip, zstd` 这类堆叠编码），覆盖三个 Codex 处理器，并剥掉过期的 `content-encoding` / `content-length` / `transfer-encoding` 请求头让转发器重新生成。上游非 2xx 的错误体也以同样方式解压，因此压缩过的限流与鉴权细节不再被丢弃、对客户端隐藏。修复 [#3764](https://github.com/farion1231/cc-switch/issues/3764)、[#3696](https://github.com/farion1231/cc-switch/issues/3696)。（[#3817](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/4239)）
|
||
|
||
### 回滚 Anthropic system 消息上提
|
||
|
||
回滚了 [#3775](https://github.com/farion1231/cc-switch/pull/3775) 把 Anthropic 兼容供应商的 `role=system` 消息从 `messages[]` 上提到顶层 `system` 字段的改动。DeepSeek 端点本就原生接受内联的 system 消息，而该重写改变了请求前缀；保持消息原位能保留 prompt 前缀，避免一处疑似的缓存命中率回退（参见 [#4297](https://github.com/farion1231/cc-switch/issues/4297)）。来自 #3775 的、不相关的 Windows 测试修复以及 tool-thinking-history 归一化都保留。
|
||
|
||
### Chat 工具调用缺函数名
|
||
|
||
一些上游会在流式工具调用增量里发送空的或缺失的函数名，过去这会产生无效的 Codex Chat 输出项（或一个 `unknown_tool` 回退）。现在累积的工具调用状态不会再被空增量覆盖，而那些始终没拿到 `call_id` 与有效名字的工具调用会在最终化阶段被跳过，覆盖流式、非流式与旧版 `function_call` 三条路径。（[#4159](https://github.com/farion1231/cc-switch/pull/4159)）
|
||
|
||
### 恢复 Codex 缓存的工具调用字段
|
||
|
||
当 Codex 发起一个引用 `previous_response_id` 的后续 Chat 请求时，它的 `function_call` 项可能只携带 `call_id`。历史增强此前只回填 `reasoning` / `reasoning_content`，留空了函数的 `name`、`arguments`、`status` 等字段；现在它会从历史里恢复全部缓存的工具调用字段，让该调用能为 Chat 上游正确重建。（[#4160](https://github.com/farion1231/cc-switch/pull/4160)）
|
||
|
||
### config.toml 里重复的 Codex base_url 条目
|
||
|
||
把 Codex 的 `base_url` 写入 `config.toml` 时此前每个区段只替换或移除一个匹配的赋值，因此一个已经含多行 `base_url` 的区段会留下多余项、累积重复。`setCodexBaseUrl` 现在会折叠目标区段或顶层的所有匹配（替换第一处、移除其余），TOML 的 `base_url` 正则也处理了转义引号。（[#4316](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/4140)，修复 [#1546](https://github.com/farion1231/cc-switch/issues/1546)）
|
||
|
||
### Claude MCP 路径尊重自定义配置目录
|
||
|
||
当配置了自定义的 Claude 配置目录时，MCP server 的读写现在会解析到该目录下的 MCP 文件、而非默认位置，让 MCP 状态按 profile 隔离。此前对旧文件的「访问即拷贝」迁移被移除，改为直接解析覆盖路径。（[#3431](https://github.com/farion1231/cc-switch/pull/3431)）
|
||
|
||
### 搜索后预设结果可点击
|
||
|
||
在「添加供应商」预设选择器里搜索后，结果一度无法点击或选中。那个与输入打架、会吃掉首字符（如「gateway」→「ateway」）的 `requestAnimationFrame` `select()` 被移除，开箱即点路径的输入自动聚焦被恢复，当搜索框已打开时按 Ctrl/Cmd+F 也接上了重新聚焦。供应商列表的打字守卫也被收窄到 Ctrl/Cmd+F 分支，从而 Escape 仍能关闭搜索面板。（[#4315](https://github.com/farion1231/cc-switch/pull/4315)）
|
||
|
||
### Skills 浏览与供应商卡片显示修复
|
||
|
||
修复了若干显示与交互问题：浏览 skills.sh 时仓库管理操作保持可用，仓库返回空结果时刷新也保持可用；供应商卡片上过长的供应商名与网站 URL 现在会截断而非溢出；OMO 模型变体下拉会截断所选标签并配全文提示；Select 菜单项会在当前选中项上显示对勾。（[#4323](https://github.com/farion1231/cc-switch/pull/4323)）
|
||
|
||
### 切换设置页签时重置滚动
|
||
|
||
在设置对话框里切换页签会保留上一个页签的滚动位置，有时会停在新页签的中途；现在每当激活页签变化时，滚动容器都会重置到顶部。（[#4165](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/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](v3.13.0-zh.md#️-风险提示)。
|
||
|
||
**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
|
||
|
||
**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
|
||
|
||
用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
|
||
|
||
---
|
||
|
||
## 致谢
|
||
|
||
感谢以下贡献者在 v3.16.4 中提交的功能与修复：
|
||
|
||
- [#3817](https://github.com/farion1231/cc-switch/pull/3817)：转发前解压请求体并支持 zstd，感谢 @chenx-dust。
|
||
- [#4583](https://github.com/farion1231/cc-switch/pull/4583)：修复 Copilot / Codex OAuth 模块绕过全局代理导致 Claude 模型 400，感谢 @zymouse。
|
||
- [#4589](https://github.com/farion1231/cc-switch/pull/4589)：新增本地代理请求覆盖（自定义请求头与请求体），感谢 @mfzzf。
|
||
- [#4575](https://github.com/farion1231/cc-switch/pull/4575)：新增数据库版本过新时的应用内恢复屏，感谢 @SaladDay。
|
||
- [#4556](https://github.com/farion1231/cc-switch/pull/4556)：为多处 JsonEditor 接入暗色模式，感谢 @TanKimzeg。
|
||
- [#4438](https://github.com/farion1231/cc-switch/pull/4438)：新增自定义日期范围的实时结束时间，感谢 @arichyx。
|
||
- [#3950](https://github.com/farion1231/cc-switch/pull/3950)：新增 Windows ARM64 发布支持，感谢 @MOON-DREAM-STARS。
|
||
- [#4401](https://github.com/farion1231/cc-switch/pull/4401)：为 Kimi For Coding 预设添加 CLAUDE_CODE_AUTO_COMPACT_WINDOW，感谢 @cyijun。
|
||
- [#4323](https://github.com/farion1231/cc-switch/pull/4323)：修复 Skills 管理与模型配置的交互展示，感谢 @thisTom。
|
||
- [#3431](https://github.com/farion1231/cc-switch/pull/3431)：对齐自定义配置目录的 Claude MCP 路径，感谢 @makoMakoGo。
|
||
- [#4159](https://github.com/farion1231/cc-switch/pull/4159)：跳过缺函数名的 Chat 工具调用，感谢 @hueifeng。
|
||
- [#4385](https://github.com/farion1231/cc-switch/pull/4385)：新增 glm-5.2 定价，感谢 @arichyx。
|
||
- [#4079](https://github.com/farion1231/cc-switch/pull/4079)：支持从 models.dev 导入模型定价，感谢 @kingcanfish。
|
||
- [#4315](https://github.com/farion1231/cc-switch/pull/4315)：修复搜索预设后结果无法点击选中，感谢 @RuixeWolf。
|
||
- [#4316](https://github.com/farion1231/cc-switch/pull/4316)：防止重复的 Codex base_url 条目，感谢 @jeffwcx。
|
||
- [#4140](https://github.com/farion1231/cc-switch/pull/4140)：让供应商终端尊重用户 shell，感谢 @zkforge。
|
||
- [#4113](https://github.com/farion1231/cc-switch/pull/4113)：在会话详情头显示源文件名，感谢 @xu-song。
|
||
- [#4160](https://github.com/farion1231/cc-switch/pull/4160)：恢复 Codex 缓存的工具调用字段，感谢 @chen-985211。
|
||
- [#4239](https://github.com/farion1231/cc-switch/pull/4239)：DeepSeek 端点 thinking:disabled 时剥掉 effort 参数，感谢 @maskshell。
|
||
- [#4165](https://github.com/farion1231/cc-switch/pull/4165)：切换设置页签时重置滚动，感谢 @Muleizhang。
|
||
- [#4319](https://github.com/farion1231/cc-switch/pull/4319)：移除已废弃的 Homebrew tap 步骤，感谢 @tianpeng-dev。
|
||
- [#4522](https://github.com/farion1231/cc-switch/pull/4522)：新增 SubRouter 供应商预设，感谢 @abingyyds。
|
||
|
||
也感谢所有在 v3.16.3 发布后反馈 Codex 代理链路、用量计费、本地代理稳健性与平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。
|
||
|
||
---
|
||
|
||
## 下载与安装
|
||
|
||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
|
||
|
||
### 系统要求
|
||
|
||
| 系统 | 最低版本 | 架构 |
|
||
| ------- | -------------------------- | ----------------------------------- |
|
||
| 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 安装：
|
||
|
||
```bash
|
||
brew install --cask cc-switch
|
||
```
|
||
|
||
更新：
|
||
|
||
```bash
|
||
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` |
|