CC Switch v3.12.3 发版解析：Copilot 反向代理、Reasoning Effort 映射与 SQLite 双后端实现

本文基于 CC Switch v3.12.3 的官方发布说明（v3.12.3-ja.md，同系列还有 中文版 与 英文版），系统梳理该版本的核心变更：GitHub Copilot 反向代理与认证中心、Reasoning Effort 自动映射、Tool Search 环境变量化、Skill 备份/恢复生命周期、OpenCode SQLite 后端等，并结合开源仓库中的 Rust 前端源码与单元测试，逐项说明这些功能在实现层的真实行为与边界条件，帮助你在启用这些能力前准确理解其原理与风险。

版本概览

CC Switch v3.12.3 发布于 2026-03-24，更新规模为 36 个 commits、107 个文件变更、+9,124 / -802 行代码。该版本的核心目标包括：

• 新增 GitHub Copilot 反向代理与 Copilot Auth Center，使 Copilot 令牌可以访问 Claude/OpenAI API；
• macOS 构建引入 Apple 代码签名与公证，消除「开发元を確認できません」警告，并提供 DMG 安装包；
• 代理层自动将 Claude 的 thinking budget 映射为 OpenAI 兼容的 reasoning_effort 参数；
• Tool Search 从二进制补丁方式迁移到 Claude 2.1.76+ 原生 ENABLE_TOOL_SEARCH 环境变量；
• OpenCode 会话存储从 JSON 扩展为 SQLite 双后端；
• 同时包含 Skill 备份/恢复、代理 gzip 压缩、o 系列模型兼容性修复等一批工程改进。

---

GitHub Copilot 反向代理与 Copilot Auth Center

本版本最大的功能是 GitHub Copilot 反向代理：使用 Copilot 访问令牌，从 Claude Code、Codex 等客户端经由 CC Switch 代理转发 API 请求，访问 Claude API 与 OpenAI API。

实现层面，仓库 src-tauri/src/proxy/providers/ 下可以看到对应的模块化拆分：

• copilot_auth.rs：负责令牌获取与管理，支持 GitHub 设备流程（device flow）取令牌、令牌有效期管理与自动刷新；
• copilot_model_map.rs：负责 Copilot 侧模型名的映射；
• copilot_optimizer.rs：针对 Copilot 服务端的请求优化处理。

从源码结构看，Copilot 请求需要处理「请求指纹」（fingerprint）与特定头部，本版本的 Bug 修复章节也专门提到修复了「Copilot 反向代理的请求指纹生成缺陷导致的认证错误」，说明指纹构造是这一链路中认证成败的关键环节。前端则新增 Copilot Auth Center，可直接查看令牌状态并触发重新认证，无需进入代理面板配置。

⚠️ 风险免责（原文档明确声明）：Copilot 反向代理通过逆向工程方式访问非官方 API，可能违反 GitHub 服务条款与附加产品条款；已有用户报告收到「脚本化交互/异常过度使用」警告邮件，继续使用者可能被临时或永久停用 Copilot 访问。启用此功能即视为用户自行承担全部风险，CC Switch 对由此导致的账户限制、警告或服务停用不承担责任。生产环境启用前请务必自行评估合规风险。

---

Reasoning Effort 自动映射：Claude thinking 预算 → OpenAI effort

当 Claude Code 这类客户端通过 CC Switch 代理访问 OpenAI o 系列或 GPT-5+ 模型时，Anthropic 请求体里的 thinking 配置无法被 OpenAI 直接理解。本版本在代理转换层实现了自动映射，核心实现位于 transform.rs 中的 resolve_reasoning_effort 函数（约 L83-L124），采用两级解析策略：

优先级 1：显式 output_config.effort

若请求体带有 output_config.effort，直接映射并尊重用户意图：

请求值	映射结果	说明
low / medium / high	同名透传	1:1 映射
max	xhigh	OpenAI 的 xhigh 即最大推理强度
其他未知值	不注入	保守处理，避免向严格后端发送未知字段

优先级 2：thinking.type + budget_tokens 回退阈值

thinking 配置	映射结果
type: "adaptive"	xhigh（adaptive 即最大推理强度）
type: "enabled"，budget < 4000	low
type: "enabled"，4000 ≤ budget < 16000	medium
type: "enabled"，budget ≥ 16000	high
type: "enabled" 但无 budget	high（保守默认）
disabled 或缺失 thinking 字段	不注入

模型白名单由 supports_reasoning_effort（同文件 L71-L81）判定：o 系列（o1、o3、o4-mini 等）、GPT-5+（gpt-5、gpt-5.x、gpt-5-codex 等）、以及 xAI Grok Build 模型（grok-4.5、grok-build-*）；gpt-4o、claude-sonnet-4-6 等不支持的模型不会注入该字段。

这一能力覆盖 Chat Completions 与 Responses API 两条路径，并配有完整的单元测试（如 test_output_config_max_maps_to_reasoning_effort_xhigh、test_thinking_budget_fallback_* 等，位于 transform.rs 的测试模块）。

---

Tool Search：从二进制补丁迁移到环境变量

本版本将 Claude CLI 的 Tool Search 开关机制整体迁移：废弃以往对 CLI 二进制的补丁方式，改用 Claude 2.1.76+ 原生支持的环境变量 ENABLE_TOOL_SEARCH。迁移后不再需要在每次 CLI 升级后重新打补丁。

该开关在 UI 上暴露于通用配置（Common Config）编辑器，与 Teammates 模式、高强度思考等开关位于同一行，实现见 CommonConfigEditor.tsx（前端表单）与 claudeProviderPresets.ts（预设定义），持久化与写入逻辑位于后端 services/provider/mod.rs。相关测试见 CommonConfigEditor.test.tsx。

Skill 备份 / 恢复生命周期

本版本为 Skill（技能文件）补齐了完整的备份/恢复闭环，防止卸载导致数据丢失：

• 自动备份：卸载 Skill 前，先将全部 skill 文件与元数据备份至 ~/.cc-switch/skill-backups/，每个备份包含 meta.json；旧备份自动剪枝，最多保留 20 份；备份路径会返回前端并在成功提示中展示。
• 列表/恢复/删除：新增管理命令，可列出所有可用备份（含元数据）、恢复备份（将文件复制回 SSOT、保存 DB 记录、同步到当前应用，失败时自动回滚）、删除备份（需确认对话框）。
• 安全加固：从源码 skill.rs 可见，meta.json 中的 directory 字段被视为不可信输入——备份可能来自手工放置或不可信来源，代码对 join 进文件系统路径的字段做了校验，并有专门测试（如 restore must reject a traversal directory from meta.json）拒绝目录穿越（traversal）路径，防止备份恢复成为任意文件读写面。

前端配套为 ConfirmDialog 增加了可配置的 zIndex 属性以支持嵌套对话框堆叠，保证恢复/删除确认层能正确压在备份列表对话框之上。

OpenCode SQLite 双后端

OpenCode 的会话存储由单一 JSON 扩展为 JSON + SQLite 双后端：

• 双后端扫描：同时扫描两种存储，会话 ID 冲突时以 SQLite 为准；
• 原子删除与路径校验：SQLite 侧的会话删除为原子操作，并校验会话文件路径；
• 向后兼容：JSON 后端继续保留，存量数据不受影响。

这一设计允许使用 OpenCode 新版 SQLite 会话存储的用户与旧版 JSON 用户在同一应用中混合管理会话。

---

Codex 1M 上下文窗口开关

设置编辑器新增一键开关，直接改写 Codex 的 config.toml：

• 勾选后写入 model_context_window = 1000000；
• 同时自动设置 model_auto_compact_token_limit = 900000（自动压缩阈值略低于窗口上限）；
• 取消勾选时两个字段均被干净移除，不残留空值。

后端读取逻辑见 codex_config.rs：当 config.toml 未显式设置 model_context_window 时，目录构建回退到 128,000；显式设置 1,000,000 后，模型目录的上下文窗口默认值会跟随该值（该文件内含 build_simplified_catalog_respects_explicit_model_context_window 等测试用例）。

自动升级禁用开关

Claude 通用配置编辑器新增 DISABLE_AUTOUPDATER 环境变量复选框（实现同样位于 CommonConfigEditor.tsx）：启用后写入 DISABLE_AUTOUPDATER=1，阻止 Claude Code 自动升级，便于锁定 CLI 版本以匹配已调好的补丁/配置环境；与 Teammates、Tool Search、高强度思考开关同排展示。

macOS 代码签名与公证

v3.12.3 的 macOS 构建完成 Apple Developer ID 签名 + Apple 公证服务公证，CI/CD 流水线集成了签名/公证步骤：

• 首次启动不再出现「开发元を確認できません」警告，可直接安装使用；
• 新增 DMG 安装包，支持拖拽安装；
• 文档层面同步更新：README（含日文/中文版本）、安装指南（EN/ZH/JA）、FAQ 页面中的 xattr 规避方法与旧警告说明全部移除，替换为「已完成 Apple 代码签名与公证」的统一表述。

代理 Gzip 压缩

非流式代理请求现自动协商 gzip 压缩以降低带宽消耗。实现细节见 content_encoding.rs：

• 非流式路径：reqwest 自动协商 gzip，响应透传解压；
• 流式路径：为避免 SSE 流被截断时产生解压错误，保守保持 Accept-Encoding: identity，不做压缩；
• 堆叠编码支持：解压模块支持 HTTP 规范允许的多编码堆叠（如 gzip, zstd，需按反向顺序逐层解压），并有对应测试 decompress_body_stacked_gzip_then_zstd_decodes_in_reverse；
• 解压炸弹防护：decompress_body_with_limit 在流式解压过程中强制执行体积上限（测试 decompress_body_with_limit_aborts_gzip_bomb_mid_stream 验证了伪随机数据被截断流触发中途中止），防止恶意压缩 payload 耗尽内存。

o 系列模型兼容性修复

代理转发对 OpenAI o 系列模型的 token 参数处理被修正：

• Chat Completions 路径：o1/o3/o4-mini 模型改用 max_completion_tokens 替代 max_tokens。对应源码在 transform.rs 的 anthropic_to_openai_with_reasoning_content（L186-L194）：is_openai_o_series(model) 为真时改写字段名，其余模型保持 max_tokens；
• Responses API 路径：保持正确的 max_output_tokens 字段，防止错误注入 max_completion_tokens（此前会导致 o 系列在 Responses 协议下报参数错误）。

---

其他变更与 Bug 修复

变更（摘选）

• Skills 缓存策略优化：改进缓存过期管理与失效策略，减少不必要的缓存重建，缩短启动时间；
• 模型预设更新：Claude 4.6 上下文窗口尺寸更新、MiniMax 预设升级至 M2.7、小米 MiMo 预设模型 ID 与参数更新；
• AddProviderDialog 简化：移除冗余 OAuth 标签页，对话框从 3 标签精简为 2 标签（应用专属 + 通用）；
• 提供商表单高级选项折叠：Claude 表单的模型映射、API 格式等高级字段在未填写时默认折叠，预设写入后自动展开，手动清空则不自动折叠；
• OpenCode 模型变体位置调整：变体从 options 内部移至预设顶层，提升可发现性（#1317）；
• Skills 导入流程重构：以显式 ImportSkillSelection 取代基于文件系统的隐式应用推断，防止同一 skill 目录位于多个应用路径时误启用多个应用；sync_to_app 新增调整逻辑清理失效/孤立符号链接；MCP sync_all_enabled 可从实时配置移除已禁用服务器；模式迁移保留遗留应用映射快照，避免有损重建。

Bug 修复（完整清单）

修复项	说明
WebDAV 密码丢失	修复保存无关配置时 WebDAV 密码被静默清空的问题
工具消息解析	修复代理工具消息解析缺陷，消除特定工具调用模式下的报错
暗色模式显示	修复暗色模式下部分 UI 组件显示异常
Copilot 请求指纹	修复 Copilot 反向代理指纹生成缺陷导致的认证错误
提供商表单重复提交	防止快速连续点击导致的重复提交（#1352）
Ghostty 会话恢复	修复 Ghostty 终端中 Claude 会话恢复失败（#1506）
Skill ZIP 导入扩展名	ZIP 导入对话框支持 .skill 文件扩展名（#1240、#1455）
Skill ZIP 目标应用	ZIP 安装的 skill 不再固定默认 Claude，改为使用当前激活应用
OpenClaw 卡片高亮	修复 OpenClaw 当前激活的提供商卡片不高亮（#1419）
响应式布局	存在 TOC 标题时的响应式设计改进（#1491）
Skills 导入白屏	ImportSkillsDialog 补充缺失的 TooltipProvider，防止打开时运行时崩溃
面板底部空白	各内容面板硬编码的 h-[calc(100vh-8rem)] 统一替换为 flex-1 min-h-0，消除跨平台底部间隙

文档：中英日三语用户手册新增模型 ID 规范化规则说明（前缀移除、后缀截断、@→- 替换，#1591）。

---

下载与安装

系统要求

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

Windows

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

macOS

文件	说明
CC-Switch-v3.12.3-macOS.dmg	推荐 — DMG 安装器，拖拽安装
CC-Switch-v3.12.3-macOS.zip	解压后拖入 Applications，Universal Binary
CC-Switch-v3.12.3-macOS.tar.gz	Homebrew 安装与自动更新用

macOS 版本已完成 Apple 代码签名与公证，可直接安装使用。

Homebrew（macOS）

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

升级：

brew upgrade --cask cc-switch

Linux

发行版	推荐格式	安装方式
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.12.3 是 CC Switch 能力面显著扩大的一个版本：Copilot 反向代理把「一个令牌访问多家 API」的玩法落地到产品（并明确标注了合规风险）；Reasoning Effort 映射与 o 系列 token 参数修复显著提升了 Claude 客户端经代理访问 OpenAI 推理模型时的参数保真度；Skill 备份生命周期与 OpenCode SQLite 双后端则补齐了数据管理与存储演进两块短板。如果你依赖代理转发到 OpenAI 系模型，建议重点阅读上文关于 reasoning_effort 阈值映射与 max_completion_tokens 字段选择的说明，以便在调试模型行为差异时准确定位参数链路。