# CC Switch v3.12.2 > 代理接管期间通用配置保护、Snippet 生命周期稳定性、Codex TOML Section 感知编辑 **[English →](v3.12.2-en.md) | [日本語版 →](v3.12.2-ja.md)** --- ## 概览 CC Switch v3.12.2 是一个以可靠性为核心的补丁版本，重点解决代理（Proxy）接管模式下通用配置（Common Config）丢失的问题，并改进了 Codex TOML 配置的编辑准确性。代理接管的热切换和供应商同步现在会更新恢复备份而非直接覆盖 live 文件；启动流程重新排序，确保先从干净的 live 文件提取 Snippet 再恢复接管状态；Codex 的 `base_url` 编辑重构为 Section 感知模式，不再错误追加到文件末尾。 **发布日期**：2026-03-12 **更新规模**：5 commits | 22 files changed | +1,716 / -288 lines --- ## 重点内容 - **首次使用引导优化**：供应商列表空状态显示详细的导入说明，Claude/Codex/Gemini 还会提示通用配置 Snippet 功能 - **代理接管恢复流程重构**：热切换和供应商同步现在刷新恢复备份，而非覆盖 live 配置文件，回滚时保留完整的用户配置 - **Snippet 生命周期稳定**：引入 `cleared` 标志防止已清除的 Snippet 被自动重新提取，启动顺序调整确保从干净状态提取 - **Codex TOML Section 感知编辑**：`base_url` 和 `model` 字段的读写现在定位到正确的 `[model_providers.]` Section - **Codex MCP 配置保护**：热切换供应商时保留恢复快照中已有的 `mcp_servers` 配置块，按 server id 合并而非整表替换，供应商/通用配置的 MCP 定义优先 --- ## 新功能 ### 空状态引导优化 改善首次使用体验，当供应商列表为空时显示详细的导入说明。 - 空状态页面展示导入供应商的操作指引 - 对 Claude/Codex/Gemini 应用有条件地显示通用配置 Snippet 提示（OpenCode/OpenClaw 不显示） --- ## 变更 ### 代理接管恢复流程 代理接管的热切换和供应商同步逻辑经过重构，确保通用配置在整个接管生命周期中得到保护。 - 接管活跃时，供应商同步更新恢复备份而非直接写入 live 配置文件 - 保存恢复快照前先应用通用配置，使回滚能还原真实的用户配置 - 遗留供应商中推断使用了通用配置的条目自动标记 `commonConfigEnabled=true` ### Codex TOML 编辑引擎 将 Codex `config.toml` 的更新逻辑重构到共享的 Section 感知 TOML 辅助函数上。 - Rust 端新增 `codex_config.rs` 模块，包含 `update_codex_toml_field` 和 `remove_codex_toml_base_url_if` - 前端新增 `getTomlSectionRange` / `getCodexProviderSectionName` 等 Section 感知工具函数 - `proxy.rs` 中散落的 TOML 内联编辑逻辑统一委托给新模块 ### 通用配置初始化生命周期 启动流程重新排序，通用配置 Snippet 的提取和迁移逻辑更加健壮。 - 启动时先从干净的 live 文件自动提取通用配置 Snippet，再恢复代理接管状态 - 引入 Snippet `cleared` 标志，追踪用户是否主动清除了某个 Snippet - 持久化一次性遗留迁移标志，避免重复执行旧版 `commonConfigEnabled` 回填 --- ## Bug 修复 ### 通用配置丢失 - 修复代理接管期间通用配置可能被丢弃的多种场景：同步覆盖 live 文件、热切换产生不完整的恢复快照、供应商切换丢失配置变更 ### Codex 恢复快照保护 - 修复 Codex 接管恢复备份在供应商热切换时丢弃已有 `mcp_servers` 配置块的问题；将 MCP 备份保留策略从整表替换改为按 server id 合并，供应商/通用配置的 MCP 定义在冲突时优先，备份中独有的服务器仍被保留 ### 已清除 Snippet 复活 - 修复启动时自动提取机制重新创建用户已主动清除的通用配置 Snippet 的问题 ### Codex `base_url` 位置错误 - 修复 Codex `base_url` 提取和编辑未定位到正确的 `[model_providers.]` Section，导致追加到文件末尾或误将 `mcp_servers.*.base_url` 识别为供应商端点的问题 --- ## 下载与安装 访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。 ### 系统要求 | 系统 | 最低版本 | 架构 | | ------- | ----------------------------- | ----------------------------------- | | Windows | Windows 10 及以上 | x64 | | macOS | macOS 10.15 (Catalina) 及以上 | Intel (x64) / Apple Silicon (arm64) | | Linux | 见下表 | x64 | ### Windows | 文件 | 说明 | | ------------------------------------------ | ----------------------------------- | | `CC-Switch-v3.12.2-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 | | `CC-Switch-v3.12.2-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 | ### macOS | 文件 | 说明 | | ---------------------------------- | --------------------------------------------------------- | | `CC-Switch-v3.12.2-macOS.zip` | **推荐** - 解压后拖入 Applications 即可，Universal Binary | | `CC-Switch-v3.12.2-macOS.tar.gz` | 用于 Homebrew 安装和自动更新 | > **注意**：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告，请先关闭，然后前往"系统设置" → "隐私与安全性" → 点击"仍要打开"，之后便可以正常打开 ### Homebrew（macOS） ```bash brew tap farion1231/ccswitch brew install --cask cc-switch ``` 更新： ```bash 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` |