CC Switch v3.16.4 发布解析：Codex 代理链路打磨、本地代理请求重写与用量定价工具升级

本篇基于 CC Switch v3.16.4 官方发布说明（v3.16.4-en.md），系统讲解本次版本在 Codex 代理链路、本地代理请求重写、数据库版本恢复界面、用量/定价工具链上的全部能力变化，并结合仓库 Rust 后端与前端源码印证每项特性的底层实现。读完你可以掌握：如何为 Provider 配置自定义请求头/请求体重写、火山引擎 Ark Coding / Agent Plan 的 AK/SK 用量查询机制、models.dev 模型定价批量导入的匹配规则，以及本次十余项代理修复（zstd 解压缩、OAuth 全局代理、工具调用修复）的实际生效逻辑。

v3.16.4 发布于 2026-06-27，是 v3.16.3（用量计费精确化）之后的一个维护性版本：53 个提交、126 个文件变更、+8,149 / -1,016 行。版本重心从"计费正确"转向"Codex 代理链路打磨 + 用量/定价工具扩展"。

---

一、版本总览：六大主题

1. 中文 Codex 供应商原生 Responses 化：Qwen / DashScope、小米 MiMo、火山 Doubao、美团 LongCat、MiniMax（国内/国际）改为直连原生 Responses 端点，不再走 Responses→Chat 路由接管转换。
2. 本地代理请求重写：Provider 可配置自定义请求头与请求体重写，由本地代理转发时应用，并内置受保护安全头拦截。
3. 数据库过新时的应用内恢复界面：SQLite 版本高于当前应用支持的 SCHEMA_VERSION 时，不再卡死在原生"重试/退出"对话框，而是进入可一键升级的恢复页。
4. 用量/定价工具增强：models.dev 定价批量导入、火山引擎 Ark Coding / Agent Plan 的 AK/SK 用量查询、自定义日期区间"跟随当前时刻"的实时结束时间、GLM-5.2 与 Doubao Seed 2.1 定价。
5. 预设与品牌更新：新增 SubRouter、OpenCode Go 订阅预设；CTok 更名为 ETok；Kimi 品牌标刷新并给官方 Kimi 预设加"顶级伙伴"徽章。
6. 原生 Windows ARM64 构建：发布产物新增 ARM64 原生包，ARM 版 Windows 不再依赖 x64 模拟。

配套阅读（相对文档自身位置的链接已转换为仓库根路径）：

• Codex 桌面端看不到自定义模型？这是 Codex 桌面应用自身的上游门控行为（按官方登录态门控模型选择器），v3.16.4 并不改变这一点，缓解方案是"保持官方登录 + 路由接管"，详见 codex-desktop-custom-model-visibility-en.md；
• 用量仪表盘的数据来源与统计口径见 4.4-usage.md；
• 本地代理请求重写、Codex 上游格式选择器、本地路由开关等位于 Provider 表单高级选项，见 1.5-settings.md。

渠道提示（原文档警告区）：CC Switch 是完全免费开源的桌面应用，不向用户收取任何费用。获取软件只走官网 ccswitch.io、官方源码仓库、官方 Releases 与作者 GitHub 账号；任何要求付费、充值或索要登录凭据的"CC Switch"站点/客户端均为假冒。

---

二、新增能力

2.1 数据库版本过新时的应用内恢复界面

问题场景：当 SQLite 的 user_version 高于当前应用支持的 SCHEMA_VERSION（例如从高版本降级回旧版本，或第三方客户端写入过该文件），旧版启动流程会死在原生"重试/退出"对话框里——"重试"注定再次失败。

v3.16.4 的行为：应用改为路由到一个专门的恢复界面：若存在可用更新，提供一键"升级应用"（下载 + 安装 + 重启，带进度条）；若不存在，则明确告知"即使是最新版也无法读取此数据库"。关键设计点是"过新"检查发生在对数据库的任何写入之前，应用绝不会对它无法理解的数据库执行 DDL；恢复模式下的原生关闭也能干净退出（此时托盘尚未创建）。

源码印证：

• 当前支持的版本号定义在 database/mod.rs：pub(crate) const SCHEMA_VERSION: i32 = 17;；
• 判断逻辑在 stored_user_version_exceeds_supported（database/mod.rs），它只读取 PRAGMA user_version 并返回大于 SCHEMA_VERSION 的存储版本，是纯只读探测，不触发任何迁移写入；
• 启动时的路由分支见 lib.rs：match crate::database::Database::stored_user_version_exceeds_supported(&db_path)，命中后才进入恢复流程。

升级提示：如果你曾用高版本 CC Switch 打开数据库又切回旧版本，旧版本启动后会进入这个"数据库版本过新"恢复页并引导你升级——这是预期行为，升级回最新版即可恢复正常。

2.2 本地代理请求重写（自定义请求头与请求体）

Provider 配置现在可以定义自定义请求头与请求体重写，由本地代理在转发时应用，入口是 Claude 与 Codex Provider 表单中的新字段。输入会经过受保护头列表校验，阻止覆盖安全敏感头。

后端数据结构在 provider.rs：LocalProxyRequestOverrides 挂在 Provider 元数据上，JSON 字段名为 localProxyRequestOverrides，包含 headers（键值对）与 body（JSON 对象）两部分，且 provider.rs 中有 roundtrip 序列化测试保证其持久化/反序列化正确。

转发侧的实际应用逻辑在 forwarder.rs：

• 请求体重写（apply_local_proxy_body_overrides）：补丁必须是 JSON 对象，然后做深度合并（merge_json_override）——对象逐键递归合并、标量直接替换；特别注意顶层 stream 字段被列为受保护字段，重写会被忽略并打 warn 日志（防止用户把流式请求改坏）；
• 请求头重写（apply_local_proxy_header_overrides）：头名统一小写，非法头名/头值直接跳过并记日志；Copilot 链路整体跳过头重写；
• 受保护头拦截（is_protected_local_proxy_override_header，forwarder.rs 起）：host、content-length、transfer-encoding、connection、authorization、x-api-key、x-goog-api-key、content-type、accept-encoding、Cloudflare/Akamai/Fastly/Azure 的客户端 IP 透传头等全部在拦截名单中，命中仅 debug 日志静默忽略——这保证用户重写无法破坏代理自身的鉴权、透传与压缩协商。

2.3 火山引擎 Ark Coding / Agent Plan 用量查询

用量面板新增火山引擎 Ark 的 Coding Plan 与 Agent Plan 配额查询。关键背景：Ark 控制面 OpenAPI（open.volcengineapi.com）要求账户级 AccessKey 签名，而不是推理 API key。因此用量脚本新增了专用 AK/SK 输入区，并提供直达火山 IAM 密钥管理控制台的链接；代理侧实现了火山 Signature V4（AWS SigV4 的变体：固定规范化头顺序、HMAC-SHA256 算法、ark 服务作用域）。

探测策略是双 Plan 自动探测：先调 GetAFPUsage（Agent Plan 的 5 小时/周/月配额），未订阅则回退 GetCodingPlanUsage，并从 Level 字段解析窗口标签（带 ResetTimestamp <= 0 的保护），同时在用量页脚、托盘菜单和全部四种语言中新增 monthly 层级标签。

源码印证（services/coding_plan.rs）：

• 常量 VOLCENGINE_OPENAPI_HOST = "open.volcengineapi.com"，请求形如 POST https://open.volcengineapi.com/?Action=...&Version=2024-01-01&Region=cn-beijing，注释明确区分了控制面网关与数据面推理域名；
• 签名链：volcengine_canonical_query → volcengine_sign（生成 authorization / x-date / x-content-sha256）→ volcengine_openapi_call；
• 探测流程在 query_volcengine：先 GetAFPUsage，Auth 错误直接返回鉴权失败，Transient 错误上抛，Soft 错误收集后继续回退 GetCodingPlanUsage；
• 对非 AK/SK 的输入会直接返回提示："Volcengine usage query needs the account AccessKey ID + Secret (not the inference API key)"。

2.4 从 models.dev 批量导入模型定价

"添加定价"面板新增"从 models.dev 导入"按钮：拉取 https://models.dev/api.json，支持对全量目录做全文搜索，选中的条目通过与手工录入相同的 update_model_pricing 路径入库。

两个值得展开的细节：

1. 模型 ID 归一化：导入的模型 ID 会按后端 clean_model_id_for_pricing 规则清洗——去供应商前缀、转小写、截断 : 后缀、@ 映射为 -、去掉 [1m] 标记——保证落库的行真正能被成本归因查询命中；
2. 零成本回填修复：配套的修复把"区间内回填零成本"从精确 SQL 字符串匹配改为在 Rust 侧按原始模型别名（含路由前缀、:free 变体、日期后缀）匹配，这样新定价的别名行可以立即被定价，而不必等下次启动回填（修复 issue #4017）。

相关后端命令集中在 commands/usage.rs：批量更新模型定价、get_models_dev_sync_config / save_models_dev_sync_config / record_models_dev_sync_result 三个同步状态命令，对应前端的 models.dev 自动同步面板。

2.5 原生 Windows ARM64 构建

发布产物新增 Windows ARM64 原生构建，ARM 版 Windows 设备可直接取对应原生包，不再依赖 x64 模拟；发布矩阵同时改为各平台独立运行（关闭 fail-fast），某个任务因缺少密钥（如 fork 里缺 macOS 签名密钥）而失败时，不再取消仍在运行的兄弟任务。

2.6 自定义日期区间的实时结束时间

自定义日期区间选择器新增"跟随当前时刻作为结束时间"复选框；启用后结束时间变为只读并持续跟踪 now，用量数据始终反映从所选起点到当前时刻的实时消耗——在 Coding Plan 的 5 小时配额窗口内尤其有用。liveEndTime 现在进入 React Query 缓存键，实时区间与同端点的固定区间不再共享同一份过期缓存。

前端印证：

• 复选框与文案在 UsageDateRangePicker.tsx（liveEndTime 状态仅对 preset === "custom" 生效）；
• 展示逻辑在 UsageDashboard.tsx：启用时区间标签渲染为 起点 → 现在。

2.7 其余新增项（简表）

特性	说明
会话详情头部显示源文件名	项目目录旁显示会话日志文件名（悬停看完整路径、点击复制），可直接定位并打开底层 JSONL 文件；对 ~70 字符的 Codex rollout 长文件名按 max-w-[200px] 截断，避免窄窗口溢出到操作按钮
未管理 Skill 导入提示	顶栏"导入 Skill"按钮在磁盘上存在未纳管 Skill 时显示绿点 + tooltip；扫描在挂载时执行一次并在导航间共享（30s staleTime + keepPreviousData），避免重复磁盘 IO
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。四个预设均带推荐链接与应用内推广文案；推广横幅改为仅由 partnerPromotionKey 触发（不再绑定 isPartner），预设可以不带"金色付费伙伴星"单独展示推荐，顺带让既有 MiniMax 推广重新可见
顶级伙伴徽章与排序	一方 Moonshot Kimi 预设（Kimi / Kimi For Coding / Kimi K2.7 Code）标记为顶级伙伴：渲染实心金色心形（无徽章边框）；在默认排序（Original）中浮到官方类别预设之后、其余之前。分组用三路划分并保持组内顺序；既是官方又标顶级伙伴的预设只留在官方组
GLM-5.2 与 Doubao Seed 2.1 定价	种子模型定价纳入 GLM-5.2 与 Doubao Seed 2.1 Pro / Turbo，这些模型的用量不再记零成本。Doubao 价格采用火山官方列表价（约按 7.14 汇率折算）；cache_creation 保持 0，因为 Doubao 的缓存按时间而非按 token 写入计费；既有 2.0 行保留用于历史核算
Kimi For Coding 自动压缩窗口	Kimi For Coding 预设默认 CLAUDE_CODE_AUTO_COMPACT_WINDOW=262144（对齐 Kimi 官方文档），并通过 templateValues 暴露，便于为后续模型或性能调优自定义
SubRouter 伙伴供应商	新增 SubRouter（AI 中转聚合商，一个 key 跨多家供应商触达多个模型）预设，覆盖全部七个受管应用：Claude Code / Claude Desktop / OpenClaw / Hermes 用 Anthropic 格式端点；Codex 与 OpenCode 用 OpenAI 兼容 /v1 端点（gpt-5.5）；Gemini CLI 用 Gemini 兼容 /v1beta 端点（gemini-3.5-flash）；含品牌图标、金色伙伴星、四语言推广文案，推荐注册链接预填 API key 注册页

---

三、行为变更（Changed）

3.1 中文 Codex 供应商切换原生 Responses API

多家中文供应商（Qwen / DashScope、小米 MiMo、火山 Doubao、美团 LongCat、MiniMax 国内/国际）现在提供原生 OpenAI Responses 端点，其 Codex 预设切换到 apiFormat: "openai_responses"，直连上游而不再经过 Responses→Chat 路由接管转换。随之丢弃不再需要的 codexChatReasoning 与 modelCatalog，也使"本地路由映射"开关默认保持关闭。例外：SiliconFlow 托管的 MiniMax 仍留在 openai_chat——那是第三方端点，不是 MiniMax 自有 base_url。其余 Chat 系供应商顺带刷新了过期模型 ID（GLM 5.1→5.2、StepFun 3.5-flash-2603→3.7-flash、Ling 2.5-1T→2.6-1T）。

格式与后端工具档案的绑定可在 codex_config.rs 看到：Some("openai_responses") => CodexCatalogToolProfile::NativeResponses，即 openai_responses 直接映射到原生 Responses 工具档案。

升级注意：已按这些预设配置好的存量 Provider 不受影响，保持原配置；若想切换到原生 Responses（放弃格式转换接管），重新选一次预设并保存即可。

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

此前 Codex Provider 表单把"Chat 格式转换"与"路由接管（模型映射）"绑在同一个开关上，导致提供原生 Responses API 的供应商若想用模型映射，就被迫强制 Chat Completions 转换。现在：

• "上游格式"（Chat Completions / Responses）成为独立的、始终可见的选择器；
• 本地路由开关只控制高级子节（模型映射目录，以及格式为 Chat 时的推理能力项）；
• 初始状态从"是否存在已保存目录"派生，不新增持久化字段；四语言（zh / en / ja / zh-TW）的 codexConfig 文案同步重写。

3.3 预设与品牌变更

• Doubao Seed 2.1 Pro 预设：全六端（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 编辑器深色模式：用量脚本对话框、Provider 表单与通用 Provider 表单中的 CodeMirror JsonEditor 现在经 useDarkMode() 跟随应用主题，切到 oneDark 编辑主题，不再在全应用深色时保持浅色；
• "添加供应商"对话框更紧凑：标题到标签页、标签页到卡片的垂直间距从 24px 收紧到 12px，并新增常驻底部提示引导用户在选完预设后填写下方字段；FullScreenPanel 新增可选 contentClassName 属性，使该 padding 覆盖只作用于本面板，不影响共享该组件的其他面板；
• Kimi 品牌标主题自适应：内联 Kimi 占位标替换为供应商新版标识。K 字形使用 currentColor 跟随主题文字色（浅色模式深色、深色模式白色），品牌强调色固定为新 #1783FF，元数据回退色同步对齐；
• 移除 Fable 5 认证横幅：设置关于页不再显示 3.16.3 为纪念特殊构建添加的 Fable 5 Verified 横幅（图片与标记一并移除），关于面板回到标准版本徽章布局。

---

四、修复清单（Fixed）——含源码级说明

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

CopilotAuthManager 与 CodexOAuthManager 此前在构造时硬编码 Client::new()，其鉴权流程（token 交换、拉取 /models 列表、判定模型厂商、device-code 与 OAuth 刷新请求）会无视已配置的全局代理直连目标服务。Copilot 侧直连导致 /models 返回 0 个 Claude 模型，实时模型解析被打断，上游以 400 model_not_supported 拒绝请求。两个管理器现在每次请求都从共享客户端池取客户端（crate::proxy::http_client::get()），遵守全局代理 URL 并支持运行时热加载。修复 issue #2016 与 #2931。

源码印证：proxy/http_client.rs 维护 GLOBAL_CLIENT: OnceCell<RwLock<Client>> 与 CURRENT_PROXY_URL 两个全局状态，get()（第 188 行）返回的 Client 随代理 URL 变化重建；调用方已全面切换到该入口，例如 providers/codex_oauth_auth.rs 与 providers/copilot_auth.rs 中的鉴权请求均改用 crate::proxy::http_client::get()。

4.2 压缩请求体与错误体解压缩（新增 zstd）

Codex Desktop 在登录态下会发送 zstd 压缩的请求体，而本地代理此前直接用 serde_json 解析原始压缩字节，导致路由解析失败。现在代理在 JSON 解析前先解压请求体（gzip / br / deflate，外加本次新增的 zstd，并支持 gzip, zstd 这类堆叠编码），覆盖三个 Codex handler，同时剥离陈旧的 content-encoding / content-length / transfer-encoding 请求头让转发器重新生成。上游非 2xx 错误体也做同样解压，压缩的限流与鉴权细节不再被丢弃、不再对客户端隐藏。修复 issue #3764 与 #3696。

实现集中在 proxy/content_encoding.rs，工程细节值得参考：

• 文件头注释说明背景：reqwest 的自动解压被禁用（为了透传 accept-encoding），因此请求侧（Codex Desktop 登录态压缩请求）与响应侧（上游压缩响应）共用一套手动解压逻辑；
• split_codings 把 content-encoding 拆成有序编码列表，去掉 identity 与空值，支持堆叠编码与重复头拼接语义；
• is_single_supported 覆盖 gzip / x-gzip / deflate / br / zstd / zst；
• 安全设计：DecompressError 区分"解码失败（数据损坏）"与"输出超预算（TooLarge）"——后者是压缩炸弹的安全拒绝信号，响应侧应据此返回 502 而非静默回退；read_with_output_limit 用 saturating_add + reader.take(budget) 在预算耗尽处立即截停，不是先在内存里完整展开再比大小；
• deflate 的兼容性处理：先按 RFC 9110 的 zlib 包裹格式尝试，失败再回退 raw deflate（TooLarge 也回退，因为 raw 流被误判为 zlib 时可能在预算处截停，真炸弹在 raw 路径同样触发 TooLarge）。

4.3 DeepSeek 端点 thinking: disabled 触发 400

DeepSeek 的 Anthropic 兼容端点会拒绝 thinking.type=disabled 与 effort 参数共存的请求（HTTP 400），这打断了 Claude Code 2.1.166+ 的 sub-agent（Workflow / Dynamic Workflow）——它们硬编码 thinking: disabled。修复策略不是覆盖客户端意图，而是针对官方 DeepSeek 端点剥离冲突的 output_config.effort / reasoning_effort 参数（sub-agent 本就不需要外显推理）。

4.4 回滚 Anthropic system 消息提升

回滚了把 Anthropic 兼容供应商 messages[] 中 role=system 消息提升到顶层 system 字段的改动：DeepSeek 端点原生接受内联 system 消息，而该改写变更了请求前缀，为保持 prompt 前缀稳定、避免疑似缓存命中率回退而整体回退。#3775 中不相关的 Windows 测试修复与 tool-thinking-history 归一化予以保留。

4.5 Codex 工具调用与历史恢复三项修复

• Chat 工具调用缺函数名：部分上游在流式 tool-call delta 中发送空/缺失的函数名，此前会产出非法 Codex Chat 输出项（或 unknown_tool 兜底）。现在累积的工具调用状态不再被空 delta 覆盖，且从未拿到 call_id 与有效名称的工具调用在终结阶段被跳过——覆盖流式、非流式与旧版 function_call 三条路径；
• 恢复缓存的 Codex 工具调用字段：Codex 发起引用 previous_response_id 的后续 Chat 请求时，其 function_call 项可能只带 call_id。历史增强此前只回填 reasoning / reasoning_content，导致 name、arguments、status 等字段为空；现在从历史恢复全部缓存工具调用字段，供 Chat 上游正确重建调用；
• config.toml 重复 base_url：此前向 Codex config.toml 写入 base_url 时，每个 section 只替换/删除一条匹配赋值，已含多条 base_url 的 section 会保留多余项并不断累积重复。setCodexBaseUrl 现在把目标 section 或顶层的所有匹配收敛为一处（替换第一条、删除其余），TOML base_url 正则同时支持转义引号。

4.6 其他修复（简表）

修复	说明
历史迁移探测 CODEX_SQLITE_HOME	Codex 会话历史迁移此前只扫描 ~/.codex/state_5.sqlite 与 config.toml 的 sqlite_home 位置；当 Codex 通过 CODEX_SQLITE_HOME 环境变量迁移状态库时，其线程永远留在旧供应商桶里。第三方与统一会话迁移共用的 codex_state_db_paths 帮助函数现在回退到 CODEX_SQLITE_HOME（config 里的 sqlite_home 仍优先）
Provider 终端尊重用户 Shell	macOS / Linux 上启动 Provider 终端此前硬编码 bash，zsh / fish 用户的 rc 文件不会加载。启动器现在从 $SHELL 检测默认 shell（macOS 回退 /bin/zsh，Linux 回退 /bin/bash）并以 clean-start 标志 exec 进入；启动脚本本身改用 POSIX sh 保证可移植性（如 fish 与 /bin/sh 可能不存在的 NixOS）
Claude MCP 路径尊重自定义配置目录	配置了自定义 Claude 配置目录后，MCP server 读写解析到该目录下的 MCP 文件而不是默认位置，实现 MCP 状态按 profile 隔离；移除了旧文件"访问即复制"迁移，改为直接解析覆盖路径
搜索后预设结果可点击	"添加供应商"预设选择器搜索后结果短暂不可点击/不可选。移除了与输入框竞争、吞掉首字符的 requestAnimationFrame select()（如 "gateway" → "ateway"），恢复了打开+点击路径的输入自动聚焦，搜索框已打开时按 Ctrl/Cmd+F 现在会重新聚焦它；供应商列表的按键守卫收窄到 Ctrl/Cmd+F 分支，Escape 仍可关闭搜索面板
Skills 浏览与 Provider 卡片显示	浏览 skills.sh 时仓库管理操作保持可用；仓库返回空结果时刷新保持可用；过长的 provider 名/网址在卡片上截断而非溢出；OMO 模型变体下拉用 tooltip 展示完整选中项；Select 菜单当前选中项显示对勾
设置标签页切换重置滚动	设置对话框切换标签页时滚动容器回到顶部，不再继承上一个标签页的滚动位置

---

五、文档与仓库资产变更

• Kimi 置顶赞助横幅：四种 README 语言（en / zh / ja / de）顶部置顶赞助横幅更新为 Kimi K2.7 Code（替换 MiniMax M2.7），文案反映 K2.7 Code 发布（面向编码的 agentic 模型，思考 token 用量较 K2.6 降约 30%）；横幅改为从仓库内资产 kimi-banner-en.png 与 kimi-banner-zh.png 提供，不再走 Moonshot CDN，并带指向 Moonshot 控制台（aff=cc-switch）的可点击行动号召；
• Codex 统一会话历史指南：新增三语言（zh / en / ja）指南，解释统一 Codex 会话历史开关"启用时迁移（migration）"与"禁用时账本式恢复（ledger-based restore）"到底做了什么、为什么会话数据从未被真正删除（只是重新打标 + 自动备份）、以及如何验证文件真的在磁盘上而非被归档进别的供应商抽屉；含"我的会话不见了"常见误解的症状表与 macOS / Linux / Windows 的磁盘验证命令，并链接进 v3.16.3 发布说明的"Usage Guides"首位；
• Homebrew 安装步骤简化：安装指南不再要求先执行已废弃的 brew tap farion1231/ccswitch 再 brew install --cask cc-switch，en / ja / zh 用户手册中该步骤已移除，cask 现在直接安装；
• Star-History 全球排名徽章：四种 README 语言的既有 Trendshift 徽章旁新增 star-history 全球排名徽章，含浅色/深色主题变体；
• 火山 Ark Coding Plan 活动链接：ByteDance / 火山 Ark 赞助条目中"中国大陆开发者点我"链接改指火山 ai618 活动页，替换此前的 codingplan 推荐 URL，覆盖四种 README 语言；
• CCSub 赞助横幅矢量资产：低清 ccsub.jpg 替换为矢量 ccsub.svg，从 2046x648 letterbox 到 2046x850（约 2.406:1）以对齐其他赞助表横幅、渲染为同样的 62px 高度。

---

六、风险提示（沿用前版）

本版本延续此前版本对反向代理类功能的风险提示：

• Codex OAuth 反向代理：通过反向代理使用 ChatGPT 订阅的 Codex OAuth 可能违反 OpenAI 服务条款，详情见 v3.13.0 发布说明 的风险提示节；
• Codex 第三方供应商 Chat 路由：本地代理把 Codex 请求转换并转发到第三方供应商时，各家供应商对计费、合规、数据留存的要求可能不同，使用前请阅读目标供应商条款；
• Claude Desktop 第三方供应商代理切换：内置代理网关把 Claude Desktop 请求转发到第三方供应商时，同样必须遵守目标供应商的计费、合规与数据留存条款。

启用上述功能即视为接受相关风险；因使用这些功能导致的账户限制、警告或服务暂停，CC Switch 不承担责任。

---

七、下载与安装

到官方 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	便携版，解压即用

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 安装与自动更新

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

---

八、主要贡献者

v3.16.4 的功能与修复来自以下社区贡献（按 PR 编号）：#3817 请求体解压与 zstd 支持（@chenx-dust）、#4583 Copilot / Codex OAuth 全局代理修复（@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 Provider 终端尊重用户 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 代理链路、用量计费、本地代理健壮性与平台兼容性问题的真实复现线索。