docs/release-notes/v3.16.5-en.md
The centerpiece of this release is getting native-Responses direct-connect properly adapted for domestic (Chinese) model providers — generating Codex model catalogs for providers with native Responses endpoints (Xiaomi MiMo, Volcengine Doubao, Qwen3-Coder, Meituan LongCat, MiniMax) so the Codex desktop app can actually see these models and their built-in tools work, and automatically disabling
web_searchfor the few domestic gateways that reject it so requests are no longer hard-rejected. Two other important improvements: when you switch providers, the plugins, environment variables, etc. you added inside the app are automatically written back to the common config and carried over to the next provider; and Linux (Wayland + NVIDIA) users hitting the "title bar clicks, page is dead, black screen on resize" problem now have an environment-variable escape hatch. This release also brings Claude Sonnet 5 pricing and a default-tier bump, a two-level grouped session view, and a batch of credential-safety and platform-compatibility fixes.
The new capabilities in this release land mainly in the Codex provider form, the session panel, and usage / common config. The following docs are worth reading alongside it:
openai_responses), CC Switch generates ~/.codex/cc-switch-model-catalog.json so the Codex desktop app can display the configured custom models and their tools work. If you previously configured a native Codex provider, re-save it once to regenerate the catalog (see "Upgrade Notes" below).[!WARNING]
Only Official Channels (Please Read)
CC Switch is a fully free and open-source desktop app, and we do not charge users any fees. Please only obtain the software through the official channels listed below:
Channel Only Official Website ccswitch.io Source github.com/farion1231/cc-switch Downloads GitHub Releases Author @farion1231 Report an Imposter GitHub Issues Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake. If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues.
CC Switch v3.16.5 is a maintenance update following v3.16.4, centered on making native Codex direct-connect work end-to-end for domestic model providers. v3.16.4 already switched Qwen / DashScope, Xiaomi MiMo, Volcengine Doubao, Meituan LongCat, and MiniMax to native Responses endpoints; this release goes a step further and generates the model catalog Codex needs (~/.codex/cc-switch-model-catalog.json), so the Codex desktop app can really see these custom models and invoke their built-in tools, and it fully decouples model mapping from the "local routing" toggle. For the few domestic gateways whose first-party models don't support OpenAI's built-in web_search (MiMo, LongCat, MiniMax, Qwen3-Coder), this release also disables that tool automatically, so Codex's default doesn't trigger a hard 400.
For everyday use, this release makes Claude's common config auto-sync and carry over when you switch providers — the plugins, environment variables, theme, etc. you added inside the running app are first written back to the common config and then handed to the next provider, so they're not lost on switch; it adds an escape-hatch environment variable for Linux (Wayland + NVIDIA) users hitting click-dead / black-screen issues; it adds Claude Sonnet 5 pricing and bumps the default Sonnet tier to it; it brings a two-level "provider → project directory" grouped session view; and it fixes a string of credential-safety (the common-config snippet now strips all secrets, usage-script credentials are only kept as explicit overrides), platform-compatibility (Hermes Windows config directory, Windows Codex npm shims), and UI (long dropdown scrolling, narrow-window date-range picker) issues. It also adds several new provider presets, ready to pick out of the box.
Release date: 2026-07-01
Stats: 36 commits | 93 files changed | +5,678 / -2,804 lines
~/.codex/cc-switch-model-catalog.json) for domestic providers like Xiaomi MiMo, Volcengine Doubao, Qwen3-Coder, Meituan LongCat, and MiniMax, so the Codex desktop app can see these models and their built-in tools work; and it auto-disables web_search for the domestic gateways that reject it (MiMo, LongCat, MiniMax, Qwen3-Coder) to avoid hard 400s. Existing native providers need a one-time re-save to regenerate the catalog.CC_SWITCH_GDK_BACKEND=wayland to switch back to native Wayland (set it to x11 for the inverse problem on tiling compositors).claude-sonnet-5.This release makes native Codex direct-connect work for domestic providers. After v3.16.4 switched Xiaomi MiMo, Volcengine Doubao, Qwen3-Coder, Meituan LongCat, and MiniMax to native Responses (apiFormat: "openai_responses"), this release reverses the then-current "drop the model catalog on native direct-connect" approach: when these providers connect directly without the local proxy, CC Switch generates ~/.codex/cc-switch-model-catalog.json for them, so the Codex desktop app really shows these custom models and their built-in tools work — without triggering the freeform apply_patch (type=custom) tool that native gateways like MiMo reject (editing falls back to shell_command). Catalog generation is keyed on apiFormat and decoupled from the "local routing" toggle, so a native provider persists a catalog without turning on local route mapping, while openai_chat keeps the existing Responses↔Chat proxy conversion unchanged. Because Codex's parser requires base_instructions on every entry, the native template carries a neutral default that each vendor's official copy overrides (MiMo, MiniMax). Existing native providers need a one-time re-save to generate a valid catalog (no database migration).
Alongside that, for the few domestic gateways whose first-party models don't support OpenAI's built-in web_search tool (MiMo, LongCat, MiniMax, Qwen3-Coder), this release auto-disables the tool on switch, so Codex's default doesn't include it and get hard-rejected with a 400 (see "Fixed" below).
The Session Manager panel gains a grouped view alongside the existing flat list, toggled via a List / ListTree selector in the toolbar, with view mode and expansion state persisted to localStorage. Grouping builds a two-level "provider → project directory" hierarchy: sessions are grouped by project directory name, and sessions with no project directory fall into an "unknown directory" bucket. Both levels are collapsible sections, with a "collapse all" button; in batch mode, each group header shows a tri-state checkbox that selects / deselects every selectable session in that group at once, along with a selected / selectable count badge. Copy across all four locales (zh / en / ja / zh-TW) is in sync. The change is entirely front-end, with no backend commands or data-access changes. (#4776)
Added a claude-sonnet-5 pricing row in schema.rs at Anthropic list pricing — $3 / $15 per million input / output tokens and $0.30 / $3.75 cache read / write, matching Sonnet 4.6. The introductory $2 / $10 promotion (valid through 2026-08-31) is deliberately not seeded, so accounting reflects steady-state list pricing rather than a temporary discount. The row is applied on the app's next start via ensure_model_pricing_seeded, with no SCHEMA_VERSION bump.
This release adds a batch of provider presets; pick one and fill in your own API key to use it:
Each preset's endpoints and default models are configured for the corresponding app — the Claude family connects directly to an Anthropic-compatible host, Codex uses native Responses, and the rest use the OpenAI-compatible /v1.
This is a very practical change in this release: when you switch away from a Claude provider that has the common config enabled, the service first re-extracts the shareable portion from its live settings.json and updates the common config, then hands it to the next provider, instead of only writing one way. As a result, the plugins (enabledPlugins), hooks, environment variables (env), theme (theme), and other shared config you added directly in the running app are not silently lost on switch, but automatically follow along to the next provider; deletions sync too (a removed key is not re-injected). This sync is strictly scoped to Claude providers that have the common config enabled, is skipped when it was explicitly cleared, and all failures are non-fatal (warn only) and never block the switch.
The Codex provider form aligns with Claude Code — the model-mapping catalog is now independent of route takeover, because native Responses providers (MiMo, Doubao, MiniMax) need it for proxy-less direct-connect, while Chat providers go through the proxy regardless. The "needs local routing" toggle is removed (it had no backend field and only gated catalog / reasoning persistence, which is equivalent to whether the mapping is filled in). Model mapping is now always shown for non-official providers and persisted whenever it's non-empty, while reasoning visibility / persistence is gated on the Chat format instead. Copy across all four locales (zh / en / ja / zh-TW) was rewritten accordingly. As a side fix, useCodexConfigState no longer drops supportsParallelToolCalls / inputModalities / baseInstructions when loading a saved provider (which used to silently lose parallel tools, image input, and the official base instructions on edit).
Bumped the default Sonnet tier in each provider preset from claude-sonnet-4-6 to claude-sonnet-5 (across the claude / claude-desktop / hermes / openclaw / opencode presets and the universal NEWAPI_DEFAULT_MODELS), covering keys like ANTHROPIC_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL / ANTHROPIC_DEFAULT_OPUS_MODEL and their prefixed variants. Claude Desktop's default-route sonnet route_id also migrates to claude-sonnet-5. Non-Anthropic pins (gpt / gemini / glm / sonnet-4-5) are left unchanged.
The Doubao (DouBaoSeed) preset's model id switches to the dated form doubao-seed-2-1-pro-260628 (across all apps), because Volcengine Ark rejects the bare doubao-seed-2-1-pro with a 404 and only accepts the full dated id. Since real usage now carries a date suffix, strip_model_date_suffix was extended to also strip Volcengine's 6-digit YYMMDD form (validating month 01-12 and day 01-31 to avoid eating non-date version suffixes like -123456), so it normalizes back to hit the bare-name seed row in the pricing table, fixing the $0-cost display for Doubao models.
The original label "Write Common Config" was ambiguous about data-flow direction (it read like "write the current config into the common config"), whereas the actual behavior is the reverse — it merges the saved common-config snippet into this provider's config. The checkbox is renamed to "Apply Common Config" across all four locales (zh / en / ja / zh-TW), including every hint / guide / notice reference, with the Japanese user manual and README_JA.md synced too. (#4829)
dds.svg orphan was removed.Some native /responses gateways whose first-party models lack OpenAI's hosted web_search tool reject it with "tool type 'web_search' is not supported", and Codex sends the tool by default, producing a hard 400. CC Switch now writes the top-level TOML line web_search = "disabled" for those vendors on switch. The scope is a blacklist (default-on): only providers matched by base_url host (xiaomimimo.com, longcat.chat, minimax.io, minimaxi.com) or by model brand prefix (mimo, longcat, minimax, qwen3-coder) are disabled, so relays serving real GPT, Doubao, general Qwen, and any unknown provider keep Codex's default. The qwen3-coder prefix only suppresses native qwen3-coder-plus (Bailian / DashScope marks built-in tools unsupported for the coder series), while general Qwen sharing the same host stays enabled; matching is on the model axis (stripping any aggregator vendor/ path segment), so it also catches cases like SiliconFlow fronting a reject vendor's model. A blacklist was chosen over a fuzzy "is this GPT?" whitelist because wrongly keeping web_search on fails with a hard 400; an ownership sentinel ensures CC Switch only ever removes a disabled value it wrote itself, so existing providers need no re-save and switching back re-enables it. As a side fix, the LongCat-2.0-Preview preset's context window is corrected from 131072 (128K) to the real 1048576 (1M).
extract_claude_common_config previously only redacted ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN, but Claude providers legitimately carry other credentials (OPENROUTER_API_KEY, GOOGLE_API_KEY, and possibly OpenAI / Gemini / AWS Bedrock / Vertex secrets), which could leak into the shared snippet and then be injected into other providers. Extraction now pattern-matches and strips any credential-shaped env key (*_API_KEY / *_AUTH_TOKEN / *secret* / *token*, etc.), while preserving legitimately shareable plural *_TOKENS values like MAX_OUTPUT_TOKENS. This also closes the same leak on the manual "Extract" and one-time auto-extract paths.
Provider usage scripts store optional api_key / base_url fields that override the live credentials when querying quota, but they used to silently mirror the provider's own credentials — so copying a provider or editing its main API key / base URL left the usage script pinned to the old endpoint and key, and quota queries kept hitting a stale target. ProviderService now normalizes before persisting: if the script's api_key or base_url matches the provider's resolved usage credentials (or is blank), it is cleared to None so queries fall back to the live config; genuinely different overrides are kept (token_plan scripts are left alone). The deeplink import path gets matching normalization too, and the front-end invalidates the relevant cache keys on update so the home page re-queries with the corrected config. (#4654)
CC Switch hardcoded ~/.hermes as the Hermes config directory, but Hermes itself resolves it via the HERMES_HOME environment variable, then a platform default (%LOCALAPPDATA%\hermes on Windows). On Windows this meant CC Switch wrote provider configs to a path Hermes never reads, so provider switches had no effect. get_hermes_dir() now mirrors Hermes' own resolution order — explicit override, then HERMES_HOME (taken verbatim, no ~ expansion), then the platform default — re-honoring the HERMES_HOME that #3470 had dropped (Hermes' Windows installer sets it as the first-class mechanism for relocated installs). (#4680, see #3178, #3470)
GDK_BACKEND=x11The AppImage's GTK launch hook unconditionally exports GDK_BACKEND=x11 to dodge a historical native-Wayland crash. On newer Wayland + NVIDIA setups, this forced XWayland leaves the WebKitGTK web content unable to receive pointer events (the title bar clicks, the page is dead) and black-screens on resize, and the existing WEBKIT_DISABLE_* mitigations don't help because the root cause is the forced window backend, not rendering. main.rs now reads an optional CC_SWITCH_GDK_BACKEND escape hatch before GTK init (the AppImage's launch hook never touches it): leaving it unset keeps current behavior (zero regression). When you hit the problem above, launch with it set to switch back to native Wayland:
CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
The override is generic — if you're on a tiling Wayland compositor hitting the inverse input problem, set CC_SWITCH_GDK_BACKEND=x11 instead. (#4351, fixes #4350)
The "Get API Key" link and partner-promotion block below the API key input was only wired for claude / codex / gemini / opencode. Claude Desktop rendered a bare input that never showed it, and OpenClaw / Hermes were blocked by two gaps (the whitelist only listed those four appIds, and category parsing only recognized those four preset-id patterns). Claude Desktop now uses the shared ApiKeySection, and both the whitelist and category parsing were extended to claude-desktop / openclaw / hermes; additionally, the Hermes / OpenClaw forms no longer let an "official" category disable the key input (these apps have no OAuth-only official providers — e.g. Hermes' Nous Research is official but still needs a user-supplied key).
On Windows, npm installs a tool as three sibling files — codex.cmd, codex.exe, and an extensionless Unix shim codex — and CC Switch previously listed all three as candidates, so the non-executable extensionless shim was probed as a redundant / failing candidate. It now appends the extensionless path only when there's no runnable .cmd / .exe sibling adjacent, and path resolution prefers the runnable .cmd / .exe, anchoring version detection and launch to the actually-runnable Windows shim. (#4782)
SelectContent previously used overflow-hidden with no height cap, so dropdowns with many options (e.g. long model / provider lists) rendered taller than the viewport and clipped their overflow with no way to reach it. It now sets max-h-[min(24rem,var(--radix-select-content-available-height))] and overflow-y-auto, bounding the content to 24rem or the Radix-computed available height and allowing vertical scrolling. (#4798)
The custom date-range picker previously switched to its two-column layout (date fields | calendar) based on the viewport width (Tailwind's sm: 640px breakpoint), but the popover is clamped to 100vw - 2rem and anchored to its trigger, so its real available width is narrower than the viewport. On narrow windows the two-column layout could activate while the popover only had room for one column, pushing the calendar column off the right edge where it was clipped (the month header and 4 of 7 weekday columns cut off and unreachable). The layout now keys off the popover's own inline size via a CSS container query, so it collapses to one column exactly when the popover itself is narrow, keeping the calendar fully visible at any window width. (#4860)
CC_SWITCH_GDK_BACKEND Escape Hatch DocumentedAdded an FAQ entry for the optional CC_SWITCH_GDK_BACKEND environment variable across all four README languages and the zh / en / ja user-manual troubleshooting pages, explaining how Wayland + NVIDIA users can switch back to native Wayland when the web content goes "click-dead + black screen on resize", and how tiling-Wayland users can set it to x11 for the inverse input problem.
The Kimi K2.7 Code partner section in the English, German, and Japanese READMEs now points its banner and inline calls to action at https://platform.kimi.ai?aff=cc-switch (keeping the referral tag), and all four READMEs gained a line promoting the Kimi For Coding subscription linked to https://www.kimi.com/code/?aff=cc-switch.
This release reworks model-catalog generation for native Responses direct-connect. If you previously configured a Codex provider using native Responses (openai_responses), re-pick the preset or open the provider and save it once to generate the new ~/.codex/cc-switch-model-catalog.json — that's what lets the Codex desktop app show the custom models and makes the tools work. This requires no database migration and does not affect providers on the openai_chat format.
For known-to-reject-web_search domestic native gateways (Xiaomi MiMo, Meituan LongCat, MiniMax, Qwen3-Coder), this release automatically writes web_search = "disabled" on switch. Relays serving real GPT, Doubao, general Qwen, and unknown providers are unaffected and keep Codex's default. The switch is managed by CC Switch with an ownership sentinel, so switching back to a provider not on the blacklist restores it automatically, with no manual intervention.
Claude-family providers newly created from a preset now have their default Sonnet tier pointing to claude-sonnet-5. Existing configured providers are unaffected and keep their configuration as-is; to switch to Sonnet 5, re-pick the preset and save.
This release continues the risk notices from previous versions for reverse-proxy-style features.
Codex OAuth reverse proxy: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the v3.13.0 release notes for details.
Codex third-party provider Chat routing: when CC Switch local proxy converts and forwards Codex requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
Claude Desktop third-party provider proxy switching: when CC Switch's built-in proxy gateway forwards Claude Desktop requests to third-party providers, you must also follow the target provider's billing, compliance, and data-retention terms.
By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
Thanks to the following contributors for the features and fixes in v3.16.5:
GDK_BACKEND=x11 via CC_SWITCH_GDK_BACKEND, thanks @BoneLiu.Thanks also to everyone who reported native Codex direct-connect, common config, credential reuse, and platform compatibility issues after the v3.16.4 release. Many of these patches came directly from real-world reproduction clues.
Visit Releases and download the build for your system.
| System | Minimum Version | Architecture |
|---|---|---|
| Windows | Windows 10 and later | x64 / ARM64 |
| macOS | macOS 12 (Monterey)+ | Intel (x64) / Apple Silicon (arm64) |
| Linux | See table below | x64 / ARM64 |
| File | Description |
|---|---|
CC-Switch-v3.16.5-Windows.msi | Recommended - MSI installer with auto-update |
CC-Switch-v3.16.5-Windows-Portable.zip | Portable build, unzip and run |
Windows ARM64 devices should pick the artifact whose file name carries the arm64 tag.
| File | Description |
|---|---|
CC-Switch-v3.16.5-macOS.dmg | Recommended - DMG installer, drag to Applications |
CC-Switch-v3.16.5-macOS.zip | Unzip and drag to Applications, Universal Binary |
CC-Switch-v3.16.5-macOS.tar.gz | For Homebrew install and auto-update |
Homebrew install:
brew install --cask cc-switch
Upgrade:
brew upgrade --cask cc-switch
Linux assets are available for both x86_64 and ARM64 (aarch64). Choose the file whose architecture tag matches your machine's uname -m output:
CC-Switch-v3.16.5-Linux-x86_64.AppImage / .deb / .rpmCC-Switch-v3.16.5-Linux-arm64.AppImage / .deb / .rpm| Distribution | Recommended Format | Install Command |
|---|---|---|
| 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 | Make executable and run directly, or use AUR |
| Other distributions / unsure | .AppImage | chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage |