mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-07-24 12:44:18 +08:00
Jason
c548e7fcba
New zh/en/ja guide for the unified Codex session-history toggle: what opt-in migration (on enable) and ledger-based restore (on disable) actually do, why session data is never truly deleted (tag-only rewrite + automatic backups), and how to verify files on disk versus just being filed under another provider drawer. Includes a symptom reference table for the common "my sessions are gone" misunderstanding and on-disk verification commands for macOS/Linux/Windows. Link the guide as the lead item in the "Usage Guides" section of the v3.16.3 release notes (zh/en/ja).
341 lines
30 KiB
Markdown
341 lines
30 KiB
Markdown
# CC Switch v3.16.3
|
||
|
||
> 🎉 **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 →](v3.16.3-en.md) | [日本語版 →](v3.16.3-ja.md)**
|
||
|
||
---
|
||
|
||
## 使用攻略
|
||
|
||
本版新增了 **Codex 统一会话历史** 开关——它涉及会话的迁移 / 还原，操作不当时容易让人误以为"会话丢了"，强烈建议先读这篇攻略；用量统计的口径和看板这一版也做了较多调整，一并附上：
|
||
|
||
- **[Codex 统一会话历史：功能介绍与使用攻略](../guides/codex-unified-session-history-guide-zh.md)**：讲清"统一 / 迁移 / 还原"到底改了什么、为什么数据不会真正丢失，以及看不到会话时如何自查与精确还原。**用过这个开关、或担心会话丢失，请务必先读。**
|
||
- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源（代理日志、会话同步）与统计口径，本版新增了全局的供应商 / 模型筛选，并把路由接管的真实计价模型展示了出来。
|
||
- **[设置](../user-manual/zh/1-getting-started/1.5-settings.md)**：自定义 User-Agent 覆盖、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.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](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/issues/3980)、[#4026](https://github.com/farion1231/cc-switch/issues/4026)、[#4049](https://github.com/farion1231/cc-switch/issues/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](https://github.com/farion1231/cc-switch/pull/3975)、[#4183](https://github.com/farion1231/cc-switch/pull/4183)）。
|
||
|
||
### Claude Mythos 5 定价
|
||
|
||
在内置模型 / 定价表里登记 `claude-mythos-5` 模型（输入 $10 / 输出 $50，每百万 token；缓存读取 $1.00、缓存写入 $12.50），让用量统计能正确计价并展示（[#4077](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/2774)）。
|
||
|
||
### 应用内更新不再卡死
|
||
|
||
从应用内安装更新时不再卡在「重启中」界面——过去会出现新版已装好、却必须手动强制退出的情况。下载—安装—重启整条链路现在完全在后端执行（新增 `install_update_and_restart` 命令），按平台决定安装顺序，并在重新执行前先销毁单实例锁，而不再依赖旧 WebView 在应用包已被替换之后继续跑 JS；退出请求也做了分类，让重启请求落到 Tauri 默认流程，而不是在窗口状态插件的互斥锁上死锁（[#4069](https://github.com/farion1231/cc-switch/pull/4069)、[#4074](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/3789)、[#3784](https://github.com/farion1231/cc-switch/issues/3784)）。
|
||
|
||
### 跨配置目录切换的接管残留恢复
|
||
|
||
在代理接管激活时更改配置目录后重启应用，不再把 Claude / Codex / Gemini 留在指向已失效的本地代理上。现在旧实例会在重启前先还原被接管的 live 文件，首次运行的导入会拒绝把接管占位符当作供应商持久化，SSOT 还原也会在写回前校验当前供应商的配置里不含占位符（[#4076](https://github.com/farion1231/cc-switch/pull/4076)）。
|
||
|
||
### 格式转换兜底里错标的 SSE 响应聚合
|
||
|
||
经 Claude / Codex 格式转换的请求，当 MaaS 网关把一个 `stream:false` 的请求强制流式、并以非 SSE 的 Content-Type 返回 SSE 响应体时，不再以一句晦涩的 422「Failed to parse upstream response」失败。代理现在会在解析失败时嗅探 SSE、把分片聚合成单个 JSON 再跑既有转换器，让客户端仍能拿到有效的非流式响应；剩余的解析失败会附带 content-type、编码和响应体片段等诊断信息，deflate 解码也改为先尝试 zlib 再尝试裸流（[#2234](https://github.com/farion1231/cc-switch/pull/2234)）。
|
||
|
||
### Hermes 配置重复 YAML 键
|
||
|
||
Hermes 配置写入不再累积重复的顶层键（如 `mcp_servers`），那会导致「Failed to parse Hermes config as YAML: duplicate entry with key」错误。区段替换现在会从剩余文本里清除所有过期副本，而不是退化成追加；去重保护层同时处理 LF 和 CRLF 行尾；修复时保留最后（最新）的那份副本，与 Hermes 自身基于 PyYAML 的「后者胜」语义一致（[#3267](https://github.com/farion1231/cc-switch/pull/3267)、[#3633](https://github.com/farion1231/cc-switch/issues/3633)、[#2973](https://github.com/farion1231/cc-switch/issues/2973)、[#2529](https://github.com/farion1231/cc-switch/issues/2529)、[#3310](https://github.com/farion1231/cc-switch/issues/3310)、[#3762](https://github.com/farion1231/cc-switch/issues/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](https://github.com/farion1231/cc-switch/pull/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](https://github.com/farion1231/cc-switch/pull/3036)）。
|
||
|
||
### macOS 重复供应商终端窗口
|
||
|
||
在 macOS 上启动供应商终端时不再在命令会话旁多开一个空窗口；Terminal.app 在冷启动时改用 `launch`（而非 `activate`），Ghostty 使用初始命令，从而只打开单个会话，并在 AppleScript 路径失败时保留回退方案（[#4156](https://github.com/farion1231/cc-switch/pull/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](v3.13.0-zh.md#️-风险提示)。
|
||
|
||
**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
|
||
|
||
**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
|
||
|
||
用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
|
||
|
||
---
|
||
|
||
## 致谢
|
||
|
||
感谢以下贡献者在 v3.16.3 中提交的功能与修复：
|
||
|
||
- [#3789](https://github.com/farion1231/cc-switch/pull/3789)：接管时保留 Codex OAuth 凭据，感谢 @codeasier。
|
||
- [#2774](https://github.com/farion1231/cc-switch/pull/2774)：修复 Completions 转 Anthropic 时不记录实际返回模型、input token 计算错误，感谢 @LaoYueHanNi。
|
||
- [#4069](https://github.com/farion1231/cc-switch/pull/4069)：修复应用内更新后重启死锁，感谢 @thisTom。
|
||
- [#4156](https://github.com/farion1231/cc-switch/pull/4156)：修复 macOS 重复供应商终端窗口，感谢 @thisTom。
|
||
- [#3267](https://github.com/farion1231/cc-switch/pull/3267)：修复 Hermes 配置重复 YAML 键，感谢 @que3sui。
|
||
- [#1479](https://github.com/farion1231/cc-switch/pull/1479)：修复用量脚本供应商凭据解析，感谢 @pa001024。
|
||
- [#3975](https://github.com/farion1231/cc-switch/pull/3975)：新增预设供应商搜索与排序，感谢 @Nastem。
|
||
- [#4183](https://github.com/farion1231/cc-switch/pull/4183)：调整预设供应商按钮外观与搜索框位置，感谢 @WangJiati。
|
||
- [#4077](https://github.com/farion1231/cc-switch/pull/4077)：新增 claude-mythos-5 模型定价，感谢 @osscv。
|
||
|
||
也感谢所有在 v3.16.2 发布后反馈用量计费、本地代理稳健性、Codex 升级与平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。
|
||
|
||
---
|
||
|
||
## 下载与安装
|
||
|
||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
|
||
|
||
### 系统要求
|
||
|
||
| 系统 | 最低版本 | 架构 |
|
||
| ------- | -------------------------- | ----------------------------------- |
|
||
| 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 安装：
|
||
|
||
```bash
|
||
brew install --cask cc-switch
|
||
```
|
||
|
||
更新：
|
||
|
||
```bash
|
||
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` |
|