# CC Switch v3.12.2 > Common Config Protection During Proxy Takeover, Snippet Lifecycle Stability, Section-Aware Codex TOML Editing **[中文版 →](v3.12.2-zh.md) | [日本語版 →](v3.12.2-ja.md)** --- ## Overview CC Switch v3.12.2 is a reliability-focused patch release that addresses Common Config loss during proxy takeover and improves Codex TOML editing accuracy. Proxy takeover hot-switches and provider sync now update the restore backup instead of overwriting live config files; the startup sequence has been reordered so snippets are extracted from clean live files before takeover state is restored; and Codex `base_url` editing has been refactored into a section-aware model that no longer appends to the end of the file. **Release Date**: 2026-03-12 **Update Scale**: 5 commits | 22 files changed | +1,716 / -288 lines --- ## Highlights - **Empty state guidance**: Provider list empty state now shows detailed import instructions with a conditional Common Config snippet hint for Claude/Codex/Gemini - **Proxy takeover restore flow rework**: Hot-switches and provider sync now refresh the restore backup instead of overwriting live config files, preserving the full user configuration on rollback - **Snippet lifecycle stability**: Introduced a `cleared` flag to prevent auto-extraction from resurrecting cleared snippets, and reordered startup to extract from clean state - **Section-aware Codex TOML editing**: `base_url` and `model` field reads/writes now target the correct `[model_providers.]` section - **Codex MCP config protection**: Existing `mcp_servers` blocks in restore snapshots survive provider hot-switches via per-server-id merge instead of wholesale replacement, with provider/common-config definitions winning on conflict --- ## New Features ### Empty State Guidance Improved the first-run experience with helpful guidance when the provider list is empty. - Empty state page shows step-by-step import instructions - Conditionally displays a Common Config snippet hint for Claude/Codex/Gemini providers (not shown for OpenCode/OpenClaw) --- ## Changes ### Proxy Takeover Restore Flow The proxy takeover hot-switch and provider sync logic has been reworked to protect Common Config throughout the takeover lifecycle. - Provider sync now updates the restore backup instead of writing directly to live config files when takeover is active - Effective provider settings are rebuilt with Common Config applied before saving restore snapshots, so rollback restores the real user configuration - Legacy providers with inferred common config usage are automatically marked with `commonConfigEnabled=true` ### Codex TOML Editing Engine Codex `config.toml` update logic has been refactored onto shared section-aware TOML helpers. - New Rust module `codex_config.rs` with `update_codex_toml_field` and `remove_codex_toml_base_url_if` - New frontend utilities `getTomlSectionRange` / `getCodexProviderSectionName` for section-aware operations - Inline TOML editing logic scattered across `proxy.rs` now delegates to the new module ### Common Config Initialization Lifecycle The startup sequence has been reordered for more robust snippet extraction and migration. - Startup now auto-extracts Common Config snippets from clean live files before restoring proxy takeover state - Introduced a snippet `cleared` flag to track whether a user intentionally cleared a snippet - Persisted a one-time legacy migration flag to avoid repeated `commonConfigEnabled` backfills --- ## Bug Fixes ### Common Config Loss - Fixed multiple scenarios where Common Config could be dropped during proxy takeover: sync overwriting live files, hot-switches producing incomplete restore snapshots, and provider switches losing config changes ### Codex Restore Snapshot Preservation - Fixed Codex takeover restore backups discarding existing `mcp_servers` blocks during provider hot-switches; changed MCP backup preservation from wholesale table replacement to per-server-id merge so provider/common-config MCP updates win on conflict while backup-only servers are retained ### Cleared Snippet Resurrection - Fixed startup auto-extraction recreating Common Config snippets that users had intentionally cleared ### Codex `base_url` Misplacement - Fixed Codex `base_url` extraction and editing not targeting the correct `[model_providers.]` section, causing it to append to the file tail or confuse `mcp_servers.*.base_url` entries for provider endpoints --- ## Download & Installation Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download the appropriate version. ### System Requirements | System | Minimum Version | Architecture | | ------- | ------------------------------- | ----------------------------------- | | Windows | Windows 10 or later | x64 | | macOS | macOS 10.15 (Catalina) or later | Intel (x64) / Apple Silicon (arm64) | | Linux | See table below | x64 | ### Windows | File | Description | | ------------------------------------------ | ---------------------------------------------------- | | `CC-Switch-v3.12.2-Windows.msi` | **Recommended** - MSI installer with auto-update | | `CC-Switch-v3.12.2-Windows-Portable.zip` | Portable version, extract and run, no registry write | ### macOS | File | Description | | ---------------------------------- | -------------------------------------------------------------------- | | `CC-Switch-v3.12.2-macOS.zip` | **Recommended** - Extract and drag to Applications, Universal Binary | | `CC-Switch-v3.12.2-macOS.tar.gz` | For Homebrew installation and auto-update | > **Note**: Since the author doesn't have an Apple Developer account, you may see an "unidentified developer" warning on first launch. Please close it, then go to "System Settings" -> "Privacy & Security" -> click "Open Anyway", and it will open normally afterwards. ### Homebrew (macOS) ```bash brew tap farion1231/ccswitch brew install --cask cc-switch ``` Update: ```bash brew upgrade --cask cc-switch ``` ### Linux | Distribution | Recommended Format | Installation Method | | --------------------------------------- | ------------------ | ---------------------------------------------------------------------- | | Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb` | `sudo dpkg -i CC-Switch-*.deb` or `sudo apt install ./CC-Switch-*.deb` | | Fedora / RHEL / CentOS / Rocky Linux | `.rpm` | `sudo rpm -i CC-Switch-*.rpm` or `sudo dnf install ./CC-Switch-*.rpm` | | openSUSE | `.rpm` | `sudo zypper install ./CC-Switch-*.rpm` | | Arch Linux / Manjaro | `.AppImage` | Add execute permission and run directly, or use AUR | | Other distributions / Unsure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |