CC Switch v3.15.0

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

中文版 → | 日本語版 →

Claude Desktop Guide

The headline feature in this release is the first-class Claude Desktop management panel. If you already have many providers configured for Claude Code, start here:

Use CC Switch to configure, manage, and switch Claude Desktop providers in one place

The guide walks through one-click import from Claude Code, adding Claude Desktop-specific providers, direct mode vs. model-mapping mode, showing the hidden local-routing toggle, and returning to Claude Desktop's official sign-in mode.

Overview

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

Highlights

• Claude Desktop Becomes a First-Class Managed Surface: 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, 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.
• Major Reverse-Proxy Hardening: P0–P3 lifecycle / retry / failover / rectifier patches; pooled HTTPS reuse for non-Anthropic backends; Codex / Responses cache hit-rate improvements; correct Anthropic ↔ OpenAI tool_choice mapping; Vertex AI URL preservation; Gemini path-based model extraction; refined takeover detection; IPv6 listen address support.
• Provider Ecosystem Expansion: New BytePlus, Volcengine Agentplan, ClaudeAPI, ClaudeCN, RunAPI, RelaxyCode, PatewayAI, and Baidu Qianfan Coding Plan partner presets; DouBao Seed promoted to partner status; routing-support badges on provider cards.
• Role-Based Model Mapping with 1M Flag: Role-based sonnet / opus / haiku routing with display names and a supports1m flag replaces the legacy [1M] suffix.
• Codex OAuth Live Model Discovery: ChatGPT Codex providers fetch the live model list from the ChatGPT backend on demand.
• Usage Dashboard Filter-Driven Hero: Surfaces cache-normalized real total tokens and cache hit rate, updated live as date / provider / model filters change.
• DeepSeek Tool Calls + Zero-Usage Final Delta: DeepSeek tool calls now return 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).
• OpenAI Responses API Usage Parsing Robustness: Missing or malformed upstream usage no longer crashes the VSCode Claude Code extension (#2422, thanks @magucas).

Added

Claude Desktop Third-Party Provider Switching via Proxy Gateway

CC Switch now treats Claude Desktop as a first-class managed surface alongside Claude Code / Codex / Gemini / OpenCode / OpenClaw / Hermes.

• New dedicated Claude Desktop panel that brokers third-party providers to Claude Desktop through CC Switch's in-app proxy gateway
• Routing-support badge on cards for providers that need Local Routing
• Role-based model route mapping locked to sonnet / opus / haiku
• Copilot / Codex OAuth providers can be reused in the Claude Desktop panel
• Redesigned Claude Code settings import flow
• App switcher visually distinguishes "Claude Code" from "Claude Desktop", and the app visibility settings use the "Claude Code" label
• 44 Claude Desktop provider presets translated from the Claude Code preset catalog

Routing Support Badges on Provider Cards

Provider 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.

Codex OAuth Live Model List

ChatGPT Codex providers no longer rely on a hardcoded model selection — CC Switch fetches a live model list from the ChatGPT backend on demand.

Role-Based Model Mapping with 1M Flag

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.

Filter-Driven Usage Hero

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.

Provider Form "Save Anyway" Prompt

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).

Universal Provider Duplicate Action

Added a "duplicate" button for universal providers from the provider list (#2416, thanks @hubutui).

Persisted Tauri Window State

Window position and size now persist across launches (#2377, thanks @BillSaul).

Tray Icon Tooltip

The system tray icon now surfaces a status tooltip on hover (#2417, thanks @Coconut-Fish).

Warp Terminal Session Launch

Added support for launching Warp and executing a saved session inside it (#2466, thanks @tisonkun).

DeepSeek reasoning_content for Tool Calls

DeepSeek tool-call responses now return reasoning_content and tool_calls together, so callers can render both (#2543, thanks @bling-yshs).

Baidu Qianfan Coding Plan (Claude Code)

Added a Baidu Qianfan Coding Plan preset (#2322, thanks @jimmyzhuu).

Compshare Coding Plan Preset (Cross-App)

The Compshare Coding Plan preset now lands across claude / codex / hermes / openclaw.

Partner Provider Presets

Added BytePlus, Volcengine Agentplan, ClaudeAPI, ClaudeCN, RunAPI, RelaxyCode, and PatewayAI partner presets; promoted DouBao Seed to partner status (refreshed endpoint and links).

44 Claude Desktop Provider Presets

Translated 44 provider presets from the Claude Code preset catalog into the new Claude Desktop panel.

Changed

20 Claude Desktop Presets Default to Direct Mode

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.

Claude Desktop Operational Notes

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 / Local Routing Guardrails

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 Accounting Semantics Changed

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.

Provider Preset Rendering Order

Preset lists now render in the author-defined array order, with partners prioritized first, replacing the previous implicit sort.

Model Mapping Hint Copy Simplified

modelMappingOffHint was rewritten as action-oriented copy across zh / en / ja.

CC Switch Brand Surface Unified to ccswitch.io

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.

Theme Switch Simplified

Removed the circular reveal animation during theme switches; theme changes are now an instant cross-fade.

Claude Code App Switcher Differentiation

The app switcher visually distinguishes "Claude Code" from "Claude Desktop", and the app visibility settings use the "Claude Code" label.

CI: Claude Review Upgraded to Opus 4.7

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.

GitHub Actions Dependency Bumps

• 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 Switched to V4

DeepSeek presets now ship V4 (flash / pro) with refreshed pricing seeds.

Codex 1M Context Toggle Hidden in Edit Form

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.

OpenClaudeCode Migrated to MicuAPI Domain

The OpenClaudeCode preset is migrated to the MicuAPI domain; Micu API links are refreshed to micuapi.ai.

CrazyRouter Endpoints Switched to cn Subdomain

CrazyRouter preset endpoints now use the cn subdomain.

RelaxyCode Custom Icon

The RelaxyCode preset icon is switched to a custom relaxcode.png asset.

Kimi For Coding Doc URL

The Kimi For Coding website URL is updated to the /code/docs/ path.

SiliconFlow International Site Shows USD

The SiliconFlow international site now correctly shows USD for balance display (it previously displayed CNY incorrectly).

Fixed

OpenAI Responses API Usage Parsing Robustness

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).

Proxy Reliability Patches (P0–P3)

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.

Proxy: Pooled HTTPS Connection Reuse for Non-Anthropic Backends

Non-Anthropic backends now reuse pooled HTTPS connections instead of opening a fresh TLS session per request, materially reducing per-request latency.

Proxy: Forward Client's Actual HTTP Method

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.

Proxy: Per-Attempt Counters and max_retries Wiring

Client-request counters are moved out of the per-attempt loop; AppProxyConfig.max_retries is now correctly wired into the request forwarder.

Proxy: Failover Decision Refinements

Refined retryable vs. unretryable error classification in the request forwarder.

Proxy: Takeover Detection Tightening

Takeover detection is tightened; disabling takeover uses fallback restore, so leftover state no longer strands a provider.

Proxy: Anthropic ↔ OpenAI tool_choice Mapping

During format conversion, Anthropic's tool_choice is now correctly mapped to the OpenAI Chat nested form.

Proxy: Gemini Request Model Extracted from URI Path

Gemini request models are now extracted from the URI path (instead of the body), so transformed traffic reports the right model name.

Proxy: Auth Header Error Handling

get_auth_headers now returns Result instead of panicking on bad credentials.

Proxy: IPv6 Listen Address Validation

The Proxy panel now accepts IPv6 listen addresses.

Proxy: Codex / Responses Cache Hit Rate

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.

Proxy: JSON Schema Underscore Fields Preserved

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.

Proxy: Read Tool Empty Pages

Drop empty pages from Read tool inputs so providers no longer reject the request (#2472, thanks @Kwensiu).

Proxy: Per-Request Hot-Path Trim

Trimmed per-request hot-path work and database wait time.

Proxy: Real Provider Model Names Under Takeover

Under takeover, the Claude Code menu now exposes the real provider model names instead of a stale alias.

Proxy: Zero Usage in Final message_delta

The 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).

Proxy: Streaming message_delta Deduplication

Deduplicated message_delta events that some upstreams emit twice (#2366, thanks @codeasier).

Proxy: Scoped reasoning_content Preserved for Tool Calls

Tool-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).

Proxy: Vertex AI Full URL Preserved

Full Vertex AI URLs are no longer truncated during proxy forwarding (#2415, thanks @xpfo-go).

Proxy: Leading Billing Header Stripped from System Content

Some upstreams prepend a billing-header chunk to the system message; this content is now stripped (#2350).

Proxy: Claude Auth Strategy Derived from ANTHROPIC_* Env Var

The Claude auth strategy is now derived from the actual ANTHROPIC_* env variable name rather than an opaque heuristic.

Third-Party Claude Providers: Disable Model Test

Model probing is disabled for third-party Claude gateways that don't implement /v1/models consistently.

Model-Fetch: /models for Anthropic-Compatible Subpath Providers

/models discovery now works for Anthropic-compatible subpath providers.

Copilot: Claude Model IDs Resolved Against Live /models

Copilot-backed providers now resolve Claude model IDs against the live /models list to avoid stale ID mismatches.

Codex: Session Title No Longer Pulls in environment_context

Codex session title extraction no longer pulls in the environment_context noise (#2439, thanks @eclipsehx).

Codex: Subagent Sessions Hidden

Codex subagent sessions are now hidden from the main session list (#2445, thanks @LanternCX).

Codex Startup Live Import Duplication

Fixed a duplicate-import bug in the Codex startup live-import path (#2590, thanks @DhruvShankpal).

Codex Provider Switch No Longer Disturbs History

Switching the active Codex provider no longer changes existing session history (#2349, thanks @SaladDay).

Codex Usage Log Wording

Corrected a misleading log message for Codex session usage (#2473, thanks @tisonkun).

Claude: Persist max Effort via Env

max effort now correctly persists across restart via the env variable (#2493, thanks @makoMakoGo).

Claude Desktop: Model Route Matching Without [1M] Suffix

Route matching no longer requires the legacy [1M] suffix.

Claude Desktop: Provider Form Input Focus Loss

Fixed an input in the Claude Desktop provider form that lost focus while being edited.

Claude Desktop: Spurious Proxy-Stopped Status Alert

Removed an alert that fired spuriously when the proxy was intentionally stopped.

Claude Desktop: Empty Toolbar Capsule Hidden

The empty toolbar capsule is now hidden when Claude Desktop is the active app.

UI: Monitor Badge Icon Centering

Centered the Monitor badge icon in the app switcher.

Linux: Theme Selection Segfault

Prevented a segfault triggered by selecting a theme on Linux (#2502, thanks @definfo).

Terminal: iTerm Fallback on Cold Launch

Prevented iTerm from being selected as a fallback on cold launch when it isn't actually installed (#2448, thanks @hulkbig).

Config: JSON Keys Sorted Alphabetically

Config writes now sort JSON keys alphabetically for deterministic output (#2469, thanks @fuleinist).

"Import Existing" Made Side-Effect Free

The "import existing" action is now side-effect free (#2429, thanks @xwil1).

Coding Plan: Zhipu Weekly Tier Named by Reset Time

Corrected the Zhipu weekly tier name to match the actual reset time (#2420, thanks @TuYv).

DashScope: Usage Parsing Robustness

Hardened DashScope usage parsing so a malformed payload no longer crashes the VSCode Claude Code extension (#2425, thanks @magucas).

Usage: Deduplicate Proxy and Session-Log Sources

Deduplicated usage records sourced from both the proxy and session logs.

Usage: Cache Cost Semantics + Pricing Warn Storm

Corrected cache-cost semantics and silenced the noisy pricing warning that fired on every request.

CI: Frontend Formatting + Linux Clippy Restored

Restored frontend formatting and Linux clippy checks in CI.

Proxy Test Helper Clippy Warning

Fixed a clippy warning in the proxy test helper.

Removed

Hermes Agent Usage Tracking Integration

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.

Theme Switch Circular Reveal Animation

Removed the circular reveal animation used during theme switches — it stuttered on slower compositors and added little visible value.

DDSHub Partner Integration

Removed DDSHub as a partner preset and dropped the cross-link blurbs from the READMEs.

Docs

README Sponsor Refresh (zh / en / ja)

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.

Release Notes Template

The release notes template now surfaces ccswitch.io.

Brand Surface

Documented ccswitch.io as the sole official website across READMEs and in-app references.

⚠️ Upgrade Notes

20 Claude Desktop Presets Default to Direct Mode

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.

Claude Desktop Operational Constraints

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.

Failover Requires Takeover Enabled

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 Figures May Diverge from History

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.

⚠️ Risk Notice

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.

Download & Installation

Visit Releases to download the appropriate version.

System Requirements

Windows

macOS

macOS builds are Apple code-signed and notarized — install directly.

Homebrew (macOS)

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

Update:

brew upgrade --cask cc-switch

Linux

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's uname -m output:

• CC-Switch-v3.15.0-Linux-x86_64.AppImage / .deb / .rpm
• CC-Switch-v3.15.0-Linux-arm64.AppImage / .deb / .rpm