docs/release-notes/v3.15.0-en.md
Claude Desktop becomes a first-class managed surface with third-party provider switching via proxy gateway, role-based model mapping, major reverse-proxy hardening, Codex OAuth live model discovery, and a filter-driven usage dashboard Hero card
CC Switch v3.15.0 is a major release following the v3.14.x line, centered on promoting Claude Desktop to a first-class managed surface. It ships third-party provider switching through the in-app proxy gateway, role-based model mapping (sonnet / opus / haiku) with a supports1m long-context flag, Copilot/Codex OAuth provider reuse, a redesigned Claude Code import flow, app-switcher differentiation between "Claude Code" and "Claude Desktop", and 44 provider presets translated from the Claude Code catalog into the new Claude Desktop surface.
Around proxy reliability, this release performs a systematic hardening pass: P0–P3 patches across routing / lifecycle / retry / failover / rectifier paths; pooled HTTPS connection reuse for non-Anthropic backends to cut per-request latency; cache hit-rate improvements for Codex and OpenAI Responses (emit prompt_cache_key only when a real client-provided session identity exists, canonicalize JSON keys in outgoing request bodies plus tool_call arguments and tool_result content, and thread session_id into the usage logger); correct Anthropic ↔ OpenAI tool_choice mapping; Vertex AI full URLs are no longer truncated; Gemini request models are now extracted from the URI path; takeover detection is tightened; and IPv6 listen addresses are supported. ChatGPT Codex OAuth providers no longer depend on hardcoded model lists — CC Switch now fetches a live model list from the ChatGPT backend on demand.
Claude Code's model mapping is now role-based (sonnet / opus / haiku) with display names and a new supports1m boolean flag, replacing the legacy [1M] suffix and decoupling routing decisions from raw model IDs. The usage dashboard adds a filter-driven Hero card that exposes cache-normalized real total tokens and cache hit rate, updated live as the active date range / provider / model filters change; paired with a fix for cache-cost semantics and the noisy pricing warning storm that fired on every request. Robustness improvements in the OpenAI Responses API usage parsing path mean missing or malformed upstream usage no longer crashes the VSCode Claude Code extension with a null output.
The provider ecosystem expands further: new BytePlus, Volcengine Agentplan, ClaudeAPI, ClaudeCN, RunAPI, RelaxyCode, PatewayAI, and Baidu Qianfan Coding Plan partner presets; DouBao Seed is promoted to partner status; and provider cards now surface a "routing support" badge so users can tell at a glance which providers can be served through Local Routing. This release also fixes a long tail of issues across Codex sessions, OAuth, Claude Desktop forms, Linux segfaults, terminal fallbacks, and ships several GitHub Actions dependency bumps.
Release date: 2026-05-16
Stats: 127 commits | 211 files changed | +17,980 insertions | -2,748 deletions
sonnet / opus / haiku) with a supports1m long-context flag, Copilot/Codex OAuth provider reuse, and 44 provider presets translated from the Claude Code catalog. Note: 20 Claude Desktop presets now default to direct mode instead of proxy mode — verify connectivity after upgrade if you previously relied on proxy routing.tool_choice mapping; Vertex AI URL preservation; Gemini path-based model extraction; refined takeover detection; IPv6 listen address support.sonnet / opus / haiku routing with display names and a supports1m flag replaces the legacy [1M] suffix.reasoning_content alongside tool_calls (#2543, thanks @bling-yshs); the final message_delta always includes a usage block (even when zero) so strict Anthropic clients no longer crash on null (#2485, thanks @Myoontyee).usage no longer crashes the VSCode Claude Code extension (#2422, thanks @magucas).CC Switch now treats Claude Desktop as a first-class managed surface alongside Claude Code / Codex / Gemini / OpenCode / OpenClaw / Hermes.
sonnet / opus / haikuProvider cards in both the Claude Code and Codex panels now show a routing-support badge so users can tell at a glance which providers can be served through Local Routing.
ChatGPT Codex providers no longer rely on a hardcoded model selection — CC Switch fetches a live model list from the ChatGPT backend on demand.
Claude Code model mapping is now role-based (sonnet / opus / haiku) with display names and a supports1m boolean flag, replacing the legacy [1M] suffix and decoupling routing from raw model IDs.
The usage dashboard's Hero summary is now filter-driven, updating live as the active date range / provider / model filters change; it surfaces cache-normalized real total tokens and cache hit rate so the Hero figures line up with the detail list below.
Softened provider form input validation by turning non-blocking input issues into a "save anyway" prompt, so a harmless field issue no longer blocks saving (#2307, thanks @allenxln).
Added a "duplicate" button for universal providers from the provider list (#2416, thanks @hubutui).
Window position and size now persist across launches (#2377, thanks @BillSaul).
The system tray icon now surfaces a status tooltip on hover (#2417, thanks @Coconut-Fish).
Added support for launching Warp and executing a saved session inside it (#2466, thanks @tisonkun).
reasoning_content for Tool CallsDeepSeek tool-call responses now return reasoning_content and tool_calls together, so callers can render both (#2543, thanks @bling-yshs).
Added a Baidu Qianfan Coding Plan preset (#2322, thanks @jimmyzhuu).
The Compshare Coding Plan preset now lands across claude / codex / hermes / openclaw.
Added BytePlus, Volcengine Agentplan, ClaudeAPI, ClaudeCN, RunAPI, RelaxyCode, and PatewayAI partner presets; promoted DouBao Seed to partner status (refreshed endpoint and links).
Translated 44 provider presets from the Claude Code preset catalog into the new Claude Desktop panel.
20 Claude Desktop presets now ship in direct mode instead of routing through the proxy by default, reducing setup friction for users who don't need proxy-specific compatibility shims. If you previously relied on proxy routing for these presets, verify connectivity after upgrading.
Switching a Claude Desktop provider writes CC Switch's managed 3P profile and requires restarting Claude Desktop to take effect; proxy-mode providers require CC Switch's Local Routing to stay running while in use.
Failover controls now require the target app's Local Routing takeover to be enabled before they can be turned on; stopping only the proxy service is blocked while any app still depends on takeover state, preventing the "proxy stopped but the app still thinks takeover is running" inconsistency.
Usage summaries now report cache-normalized real total tokens and cache hit rate. Historical token and cost figures may shift after deduplication and pricing recalculation — the new numbers are more accurate but will not equal the values reported in earlier versions.
Preset lists now render in the author-defined array order, with partners prioritized first, replacing the previous implicit sort.
modelMappingOffHint was rewritten as action-oriented copy across zh / en / ja.
All in-app and README "official website" references now point at ccswitch.io as the sole official site; the release notes template also surfaces ccswitch.io.
Removed the circular reveal animation during theme switches; theme changes are now an instant cross-fade.
The app switcher visually distinguishes "Claude Code" from "Claude Desktop", and the app visibility settings use the "Claude Code" label.
The Claude review GitHub Action is upgraded to Opus 4.7; the prompt is tuned to reduce nitpick noise; a new @claude review-only Code Action is added; PR head SHA is pinned for checkout; the --max-turns 5 limit is removed.
actions/checkout 4 → 6 (#2517)pnpm/action-setup 5 → 6 (#2518)softprops/action-gh-release 2 → 3 (#2519)actions/stale 9 → 10 (#2520)DeepSeek presets now ship V4 (flash / pro) with refreshed pricing seeds.
The 1M context-window toggle is no longer surfaced in the Codex provider edit form, reducing the density of knobs that have no effect in current Codex deployments.
The OpenClaudeCode preset is migrated to the MicuAPI domain; Micu API links are refreshed to micuapi.ai.
cn SubdomainCrazyRouter preset endpoints now use the cn subdomain.
The RelaxyCode preset icon is switched to a custom relaxcode.png asset.
The Kimi For Coding website URL is updated to the /code/docs/ path.
The SiliconFlow international site now correctly shows USD for balance display (it previously displayed CNY incorrectly).
Hardened build_anthropic_usage_from_responses() and the Responses → Anthropic SSE translator so a missing or malformed upstream usage no longer produces "usage": null in message_delta. This unblocks strict Anthropic clients (notably the VSCode Claude Code extension) that crashed with Cannot read properties of null (reading 'output_tokens') against providers such as Codex OAuth and DashScope's compatible-mode/v1/responses endpoint. Added OpenAI field-name fallbacks (prompt_tokens / completion_tokens), null / empty / partial object handling, and preserved cache token fields even when input/output tokens are missing (#2422, thanks @magucas).
Multiple rounds of routing / lifecycle / retry / rectifier patches across the request-forwarder paths; extracted a shared handle_rectifier_retry_failure helper and a shared auth_header_value helper.
Non-Anthropic backends now reuse pooled HTTPS connections instead of opening a fresh TLS session per request, materially reducing per-request latency.
The proxy no longer hard-codes POST — it forwards the client's actual HTTP method, so non-POST upstream endpoints (e.g. GET /v1/models) now work correctly.
max_retries WiringClient-request counters are moved out of the per-attempt loop; AppProxyConfig.max_retries is now correctly wired into the request forwarder.
Refined retryable vs. unretryable error classification in the request forwarder.
Takeover detection is tightened; disabling takeover uses fallback restore, so leftover state no longer strands a provider.
tool_choice MappingDuring format conversion, Anthropic's tool_choice is now correctly mapped to the OpenAI Chat nested form.
Gemini request models are now extracted from the URI path (instead of the body), so transformed traffic reports the right model name.
get_auth_headers now returns Result instead of panicking on bad credentials.
The Proxy panel now accepts IPv6 listen addresses.
Improved cache hit rate for Codex and OpenAI Responses requests by stabilizing cache key derivation: emit prompt_cache_key only when the client actually carries a session identity, so unrelated conversations no longer collapse onto a single key; canonicalize (sort) JSON keys in outgoing request bodies and in tool_call arguments / tool_result content for byte-identical prefix-cache reuse; thread session_id into the usage logger for request correlation.
Private-parameter filtering now preserves underscore-prefixed field names inside JSON Schema name maps (properties, patternProperties, definitions, $defs), so user-defined schema keys like _id and _meta pass through the filter intact.
Drop empty pages from Read tool inputs so providers no longer reject the request (#2472, thanks @Kwensiu).
Trimmed per-request hot-path work and database wait time.
Under takeover, the Claude Code menu now exposes the real provider model names instead of a stale alias.
message_deltaThe final message_delta event now always includes a usage block (even when zero) so strict Anthropic clients no longer crash on null (#2485, thanks @Myoontyee).
message_delta DeduplicationDeduplicated message_delta events that some upstreams emit twice (#2366, thanks @codeasier).
reasoning_content Preserved for Tool CallsTool-call paths now correctly preserve the scoped reasoning_content field during transformation; Kimi / Moonshot's OpenAI Chat compatibility path keeps the field while generic OpenAI-compatible requests stay free of it (#2367, thanks @codeasier).
Full Vertex AI URLs are no longer truncated during proxy forwarding (#2415, thanks @xpfo-go).
Some upstreams prepend a billing-header chunk to the system message; this content is now stripped (#2350).
ANTHROPIC_* Env VarThe Claude auth strategy is now derived from the actual ANTHROPIC_* env variable name rather than an opaque heuristic.
Model probing is disabled for third-party Claude gateways that don't implement /v1/models consistently.
/models for Anthropic-Compatible Subpath Providers/models discovery now works for Anthropic-compatible subpath providers.
/modelsCopilot-backed providers now resolve Claude model IDs against the live /models list to avoid stale ID mismatches.
environment_contextCodex session title extraction no longer pulls in the environment_context noise (#2439, thanks @eclipsehx).
Codex subagent sessions are now hidden from the main session list (#2445, thanks @LanternCX).
Fixed a duplicate-import bug in the Codex startup live-import path (#2590, thanks @DhruvShankpal).
Switching the active Codex provider no longer changes existing session history (#2349, thanks @SaladDay).
Corrected a misleading log message for Codex session usage (#2473, thanks @tisonkun).
max Effort via Envmax effort now correctly persists across restart via the env variable (#2493, thanks @makoMakoGo).
[1M] SuffixRoute matching no longer requires the legacy [1M] suffix.
Fixed an input in the Claude Desktop provider form that lost focus while being edited.
Removed an alert that fired spuriously when the proxy was intentionally stopped.
The empty toolbar capsule is now hidden when Claude Desktop is the active app.
Centered the Monitor badge icon in the app switcher.
Prevented a segfault triggered by selecting a theme on Linux (#2502, thanks @definfo).
Prevented iTerm from being selected as a fallback on cold launch when it isn't actually installed (#2448, thanks @hulkbig).
Config writes now sort JSON keys alphabetically for deterministic output (#2469, thanks @fuleinist).
The "import existing" action is now side-effect free (#2429, thanks @xwil1).
Corrected the Zhipu weekly tier name to match the actual reset time (#2420, thanks @TuYv).
Hardened DashScope usage parsing so a malformed payload no longer crashes the VSCode Claude Code extension (#2425, thanks @magucas).
Deduplicated usage records sourced from both the proxy and session logs.
Corrected cache-cost semantics and silenced the noisy pricing warning that fired on every request.
Restored frontend formatting and Linux clippy checks in CI.
Fixed a clippy warning in the proxy test helper.
Removed the Hermes Agent usage tracking integration originally planned for this cycle — upstream behavior changes made the integration impractical to maintain. The integration was never enabled in any released version; the "zero-cost rendering" bug discovered during its development was fixed before the integration was rolled back.
Removed the circular reveal animation used during theme switches — it stuttered on slower compositors and added little visible value.
Removed DDSHub as a partner preset and dropped the cross-link blurbs from the READMEs.
Added BytePlus, ClaudeCN, RunAPI, and PatewayAI sponsor entries; cross-linked BytePlus and Volcengine entries; refreshed the CrazyRouter $2 credit claim flow, the Compshare blurb, the Right Code blurb, and other sponsor logos and listings; flattened the LionCC logo onto a white background; switched the Chinese README's sponsor logo to the Volcengine artwork; added Hermes Agent to the README subtitles.
The release notes template now surfaces ccswitch.io.
Documented ccswitch.io as the sole official website across READMEs and in-app references.
These 20 presets previously routed through the proxy by default and now default to direct mode. If you were using one of these presets pre-upgrade and depended on the proxy path for connectivity (for example because the proxy applies a special rectifier or transformation layer), verify connectivity after upgrading; you can manually switch them back to proxy mode from the CC Switch panel if needed.
Switching a Claude Desktop provider requires restarting Claude Desktop to take effect; proxy-mode providers require CC Switch's Local Routing to stay running while in use — quitting CC Switch or stopping Local Routing will cut off any proxy-mode Claude Desktop providers.
Before enabling Failover, make sure the target app's Local Routing takeover is enabled, otherwise the Failover control will refuse to start; stopping the proxy service while any app still depends on takeover state is blocked, so you need to disable takeover at the app layer first before stopping the proxy.
Usage summaries now use cache-normalized real total tokens + cache hit rate. Historical token and cost figures may shift after deduplication and pricing recalculation — the new numbers are more accurate but will not equal what earlier versions reported.
This release inherits the risk notices originally introduced in v3.12.3 / v3.13.0 for reverse-proxy-style features.
GitHub Copilot Reverse Proxy: Using Copilot's reverse-proxy path may violate GitHub / Microsoft's terms of service. See the v3.12.3 release notes for details.
Codex OAuth Reverse Proxy: Using the Codex OAuth reverse proxy with a ChatGPT subscription may violate OpenAI's terms of service. See the v3.13.0 release notes for details.
Claude Desktop Third-Party Provider Switching via Proxy Gateway: Routing Claude Desktop traffic through CC Switch's in-app proxy gateway to a third-party provider exposes those requests to that provider's billing, compliance, and data-retention policies — read the target provider's terms of service before using.
By enabling these features, users accept all associated risks. CC Switch is not responsible for any account restrictions, warnings, or service suspensions that result from using these features.
Visit Releases to download the appropriate version.
| OS | Minimum Version | Architecture |
|---|---|---|
| Windows | Windows 10 or later | x64 |
| macOS | macOS 12 (Monterey) or later | Intel (x64) / Apple Silicon (arm64) |
| Linux | See table below | x64 / ARM64 |
| File | Description |
|---|---|
CC-Switch-v3.15.0-Windows.msi | Recommended - MSI installer, supports auto-update |
CC-Switch-v3.15.0-Windows-Portable.zip | Portable, extract and run, no registry writes |
| File | Description |
|---|---|
CC-Switch-v3.15.0-macOS.dmg | Recommended - DMG installer, drag into Applications |
CC-Switch-v3.15.0-macOS.zip | Extract and drag into Applications, Universal Binary |
CC-Switch-v3.15.0-macOS.tar.gz | For Homebrew installation and auto-update |
macOS builds are Apple code-signed and notarized — install directly.
brew tap farion1231/ccswitch
brew install --cask cc-switch
Update:
brew upgrade --cask cc-switch
Linux artifacts are published for both x86_64 and ARM64 (
aarch64). The architecture is included in the asset filename — pick the one matching your machine'suname -moutput:
CC-Switch-v3.15.0-Linux-x86_64.AppImage/.deb/.rpmCC-Switch-v3.15.0-Linux-arm64.AppImage/.deb/.rpm
| Distribution | Recommended | Installation |
|---|---|---|
| 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, or use AUR |
| Other distros / not sure | .AppImage | chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage |