mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-08-03 11:01:22 +08:00
Jason
499 lines
27 KiB
Markdown
499 lines
27 KiB
Markdown
# 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
|
||
|
||
**[中文版 →](v3.15.0-zh.md) | [日本語版 →](v3.15.0-ja.md)**
|
||
|
||
---
|
||
|
||
## 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](v3.12.3-en.md#️-risk-notice) 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](v3.13.0-en.md#️-risk-notice) 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](https://github.com/farion1231/cc-switch/releases/latest) to download the appropriate version.
|
||
|
||
### System Requirements
|
||
|
||
| 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 |
|
||
|
||
### Windows
|
||
|
||
| 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 |
|
||
|
||
### macOS
|
||
|
||
| 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.
|
||
|
||
### Homebrew (macOS)
|
||
|
||
```bash
|
||
brew tap farion1231/ccswitch
|
||
brew install --cask cc-switch
|
||
```
|
||
|
||
Update:
|
||
|
||
```bash
|
||
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`
|
||
|
||
| 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` |
|