mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-07-24 12:44:18 +08:00
Jason
279 lines
28 KiB
Markdown
279 lines
28 KiB
Markdown
# CC Switch v3.16.5
|
||
|
||
> 这一版的重头戏是**让原生 Responses 格式的国产模型供应商真正适配到位**——为小米 MiMo、火山豆包、千问 Qwen3-Coder、美团 LongCat、MiniMax 等具备原生 Responses 端点的供应商生成 Codex 模型目录，让 Codex 桌面能看到这些模型、内置工具也能正常工作，并对少数拒收 `web_search` 的国产网关自动禁用该工具、避免请求被硬性拒绝。另有两处重要改进：切换供应商时，你在应用内新增的插件、环境变量等会**自动回写到通用配置并带给下一个供应商**；Linux（Wayland + NVIDIA）上「标题栏能点、页面点不动、缩放黑屏」的问题，现在也能用一个环境变量开关自救。本版还带来 Claude Sonnet 5 定价与默认档升级、两级分组的会话视图，以及一批凭据安全与平台兼容修复。
|
||
|
||
**[English →](v3.16.5-en.md) | [日本語版 →](v3.16.5-ja.md)**
|
||
|
||
---
|
||
|
||
## 使用攻略
|
||
|
||
本版的新能力主要落在 Codex 供应商表单、会话面板与用量 / 通用配置里，建议结合以下文档了解：
|
||
|
||
- **[Codex 桌面看不到自定义模型？](../guides/codex-desktop-custom-model-visibility-zh.md)**：本版重做了**原生直连时的模型目录生成**——当 Codex 供应商使用原生 Responses（`openai_responses`）直连时，CC Switch 会生成 `~/.codex/cc-switch-model-catalog.json`，让 Codex 桌面能显示配置的自定义模型、工具也可用。若你此前配过原生 Codex 供应商，请**重新保存一次**以生成新目录（详见下方「升级提醒」）。
|
||
- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源与统计口径。本版新增了 Claude Sonnet 5 定价，并修复了用量脚本凭据被当作「显式覆盖」持久化的问题。
|
||
- **[设置](../user-manual/zh/1-getting-started/1.5-settings.md)**：Codex 上游格式选择器与本地路由开关、Claude 通用配置（现更名为「应用通用配置」并支持切换时自动同步）都在供应商表单的高级选项里。
|
||
|
||
---
|
||
|
||
> [!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.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](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/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 启动即可：
|
||
|
||
```bash
|
||
CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
|
||
```
|
||
|
||
该覆盖是通用的——若你在平铺式 Wayland 合成器上遇到的是反向的输入问题，则改设为 `CC_SWITCH_GDK_BACKEND=x11`。（[#4351](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/4782)）
|
||
|
||
### 长下拉列表的滚动边界
|
||
|
||
`SelectContent` 弹层此前用 `overflow-hidden` 且没有高度上限，因此选项很多的下拉（如长模型 / 供应商列表）会渲染得比视口还高、把溢出项裁掉且无法触及。现在它设了 `max-h-[min(24rem,var(--radix-select-content-available-height))]` 与 `overflow-y-auto`，把内容限制在 24rem 或 Radix 计算出的可用高度内并允许纵向滚动。（[#4798](https://github.com/farion1231/cc-switch/pull/4798)）
|
||
|
||
### 日期范围选择器的日历在窄弹层里保持可见
|
||
|
||
自定义日期范围选择器此前按**视口宽度**（Tailwind `sm:` 640px 断点）切换两列布局（日期字段 | 日历），但弹层被夹在 `100vw - 2rem` 且锚定到触发器，实际可用宽度比视口窄。在窄窗口上，两列布局可能在弹层只放得下一列时被激活，把日历列挤出右边界裁掉（月份头与 7 列里的 4 列被切掉且无法触及）。现在布局改用 **CSS 容器查询**按弹层自身的行内尺寸切换，因此只有当弹层本身窄时才收成一列，让日历在任意窗口宽度下都完整可见。（[#4860](https://github.com/farion1231/cc-switch/pull/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](v3.13.0-zh.md#️-风险提示)。
|
||
|
||
**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
|
||
|
||
**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
|
||
|
||
用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
|
||
|
||
---
|
||
|
||
## 致谢
|
||
|
||
感谢以下贡献者在 v3.16.5 中提交的功能与修复：
|
||
|
||
- [#4776](https://github.com/farion1231/cc-switch/pull/4776)：新增会话分类视图与分组管理，感谢 @alkaid616。
|
||
- [#4829](https://github.com/farion1231/cc-switch/pull/4829)：把「写入通用配置」更名为「应用通用配置」，感谢 @arichyx。
|
||
- [#4654](https://github.com/farion1231/cc-switch/pull/4654)：让用量脚本凭据仅作显式覆盖持久化，感谢 @yyhhyyyyyy。
|
||
- [#4680](https://github.com/farion1231/cc-switch/pull/4680)：修复 Windows 上 Hermes 供应商配置不生效，感谢 @thisTom。
|
||
- [#4782](https://github.com/farion1231/cc-switch/pull/4782)：去重 Windows 上的 Codex npm 影子命令，感谢 @justjavac。
|
||
- [#4798](https://github.com/farion1231/cc-switch/pull/4798)：修复长下拉列表无法滚动，感谢 @xwil1。
|
||
- [#4351](https://github.com/farion1231/cc-switch/pull/4351)：允许通过 `CC_SWITCH_GDK_BACKEND` 覆盖 AppImage 强制的 `GDK_BACKEND=x11`，感谢 @BoneLiu。
|
||
- [#4860](https://github.com/farion1231/cc-switch/pull/4860)：让日期范围选择器的日历在窄弹层里保持可见，感谢 @SaladDay。
|
||
|
||
也感谢所有在 v3.16.4 发布后反馈 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.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 安装：
|
||
|
||
```bash
|
||
brew install --cask cc-switch
|
||
```
|
||
|
||
更新：
|
||
|
||
```bash
|
||
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` |
|