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)

🎉 CC Switch is now available in the official Homebrew cask repository — no need to add a custom tap!

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

CC Switch v3.14.1

Tray usage visibility, Codex OAuth stability fixes, Skills import/install reliability, and removal of the Hermes config health scanner

中文版 → | 日本語版 →

Overview

CC Switch v3.14.1 is a patch release following v3.14.0, focused on Codex OAuth reverse-proxy stability, tray usage visibility, Skills import / install reliability, Gemini session restore paths, and simplifying Hermes configuration health handling.

For the first time, the system tray surfaces cached usage for the current Claude / Codex / Gemini provider directly in its submenus — including subscription summaries and usage-script summaries with color-coded utilization markers. For Chinese coding-plan providers like Kimi / Zhipu / MiniMax, the tray additionally renders a 5-hour + weekly window layout in the 🟢 h12% w80% style (worst utilization drives the emoji), semantically identical to the official subscription badges. Creating a Claude provider whose ANTHROPIC_BASE_URL matches a known coding-plan host now auto-injects meta.usage_script so the tray lights up without opening the Usage Script modal.

Several Codex OAuth reverse-proxy stability issues are addressed this release: client-provided session IDs are now used as both prompt_cache_key and the Codex session header to avoid UUID-driven cache churn; non-streaming Anthropic clients receive proper JSON responses even when the ChatGPT Codex upstream forces OpenAI Responses SSE; and Stream Check now builds probes with the same store: false, encrypted reasoning include, and provider FAST mode setting as production requests, eliminating the "check fails but it actually works" mismatch. Paired with a new explicit FAST mode toggle, users can now opt into service_tier="priority" on Codex OAuth-backed Claude providers, trading latency against ChatGPT quota consumption on their own terms.

Additionally, the in-app Hermes config health scanner and its warning banner are removed (along with the scan_hermes_config_health command, HermesHealthWarning type, and HermesWriteOutcome.warnings payload), refocusing the Hermes surface on active provider display, switching defaults, memory editing, and launching the Hermes Web UI — deep configuration health is now Hermes's own responsibility.

Release Date: 2026-04-23

Update Scale: 13 commits | 48 files changed | +1,883 / -808 lines

Highlights

• Tray Usage Visibility: Claude / Codex / Gemini tray submenus show cached usage for the current provider, including subscription and script-based summaries with color markers; refreshes are throttled, limited to visible apps, and synchronized back into React Query (#2184, thanks @TuYv)
• Tray Coding-Plan Usage (Kimi / Zhipu / MiniMax): The tray renders 5-hour + weekly window usage using the 🟢 h12% w80% layout; Claude providers whose base URL matches a known host auto-inject meta.usage_script
• Codex OAuth FAST Mode: New explicit FAST mode toggle for Codex OAuth-backed Claude providers; when enabled, converted Responses requests send service_tier="priority". Off by default (#2210, thanks @JesusDR01)
• Codex OAuth Stability: Fixed reverse-proxy cache routing (#2218, thanks @majiayu000), Responses SSE aggregation (#2235, thanks @xpfo-go), and Stream Check parity with production (#2210, thanks @JesusDR01)
• Hermes Config Health Scanner Removed: Refocuses the Hermes surface on provider management, memory editing, and launching the Web UI — no longer duplicates deep configuration health judgments
• Skills Import / Install Reliability: Import dialog disables actions while pending and deduplicates results by ID (#2211, thanks @TuYv); model quick-set / one-click config applies against the latest form state (#2249, thanks @Coconut-Fish); root-level SKILL.md repo installs are stable (#2231, thanks @santugege)
• Gemini Session Restore Paths: Session scanning reads .project_root metadata and passes the original project directory back into restore flows (#2240, thanks @tisonkun)
• Session / Settings Layout Polish: Hardened the scroll-area viewport with width containment to fix horizontal overflow; tightened app bottom and settings footer spacing (#2201, thanks @Coconut-Fish)

Added

Tray Usage Visibility

• System tray submenus now show cached usage for the current Claude / Codex / Gemini provider (#2184, thanks @TuYv)
• Includes subscription quota summaries and usage-script summaries with color-coded utilization markers
• Tray-triggered refreshes are throttled, limited to visible apps, and synchronized back into React Query so the main window and tray share the same usage data

Tray Coding-Plan Usage (Kimi / Zhipu / MiniMax)

• The tray renders 5-hour + weekly window usage for Chinese coding-plan providers
• Uses the same 🟢 h12% w80% two-window layout as official subscription badges (worst utilization drives the emoji color)
• Creating a Claude provider whose ANTHROPIC_BASE_URL matches a known coding-plan host auto-injects meta.usage_script, so the tray lights up without opening the Usage Script modal
• Existing usage_script values are preserved on update, never clobbering user customizations

Codex OAuth FAST Mode

• New explicit FAST mode toggle for Codex OAuth-backed Claude providers (#2210, thanks @JesusDR01)
• When enabled, converted Responses requests send service_tier="priority" for lower latency
• Off by default to avoid unexpectedly increasing ChatGPT quota consumption

Changed

Session and Settings Layout Polish

• Hardened the scroll-area viewport with width containment to fix horizontal overflow (#2201, thanks @Coconut-Fish)
• Tightened app bottom and settings footer spacing so long session / settings views fit more cleanly

Removed

Hermes Config Health Scanner

• Removed the in-app Hermes config health scanner and its warning banner
• Removed the scan_hermes_config_health command, HermesHealthWarning type, and HermesWriteOutcome.warnings payload
• The CC Switch Hermes surface now focuses on its core job: active provider display, default provider switching, memory editing, and launching the Hermes Web UI for deep configuration

Fixed

Codex OAuth Cache Routing

• Use the client-provided session ID as both prompt_cache_key and the Codex session header, preserving explicit cache keys (#2218, thanks @majiayu000)
• Stop generating UUIDs that caused cache-identity churn, stabilizing the ChatGPT Codex reverse-proxy cache identity

Codex OAuth Responses SSE Aggregation

• Non-streaming Anthropic clients now receive proper JSON even when the ChatGPT Codex upstream forces OpenAI Responses SSE (#2235, thanks @xpfo-go)
• CC Switch aggregates the upstream SSE events before running the non-streaming transform

Codex OAuth Stream Check Parity

• Stream Check now builds Codex OAuth probe requests with the same store: false, encrypted reasoning include, and provider FAST mode setting as production proxy traffic (#2210, thanks @JesusDR01)
• Eliminates the "check fails but it actually works" mismatch

Codex Model Extraction

• Reading the model field from Codex config now uses TOML parsing instead of first-line regex matching (#2227, thanks @nmsn)
• Multiline TOML is handled correctly

Model Quick-Set / One-Click Config

• Model quick-set now applies against the latest provider form config (#2249, thanks @Coconut-Fish)
• Fixes stale form state preventing one-click configuration from succeeding

Skills Import Duplicates

• The Skills import dialog disables actions while import is pending (#2211, thanks @TuYv)
• The installed-skills cache deduplicates imported results by ID, preventing double-clicks from adding duplicate installed entries (#2139)

Root-Level Skill Repos

• Skill install and update flows now consistently resolve three source patterns: direct nested paths, install-name recursive search, and repository-root SKILL.md sources (#2231, thanks @santugege)

Gemini Session Restore Paths

• Gemini session scanning now reads .project_root metadata (#2240, thanks @tisonkun)
• Restore flows can pass the original project directory when available

Provider Hover Names

• Provider icons now expose the provider name on hover for inline SVG, image URL, and fallback initials render paths (#2237, thanks @tisonkun)

Notes & Caveats

• Hermes Health Scanner Removed: If you were relying on CC Switch to surface deep Hermes YAML configuration issues, switch to the "Launch Hermes Web UI" toolbar button and inspect them in Hermes's own panel. Day-to-day provider management, switching, memory editing, and MCP / Skills sync continue to be handled by CC Switch.
• Codex OAuth FAST Mode Off by Default: Only turn it on if you accept potentially increased ChatGPT quota consumption in exchange for lower latency.
• Tray Cached Usage: Refreshes are throttled and limited to the currently visible app to avoid unnecessary upstream API calls; values are synchronized into React Query so the main window and tray stay in sync.

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

CC Switch v3.14.0

Hermes Agent becomes the 6th managed app, Claude Opus 4.7 rolls out across the preset matrix, Gemini Native API proxy, "Local Routing" rename, and application-level window controls

中文版 → | 日本語版 →

Overview

CC Switch v3.14.0 is a major release centered on onboarding Hermes Agent as the 6th first-class managed app and rolling out Claude Opus 4.7 across the full aggregator and Bedrock preset matrix. Hermes support covers a database v9 → v10 migration, a complete Rust command surface, YAML-backed ~/.hermes/config.yaml read/write with atomic backups, MCP sync, Skills sync, SQLite + JSONL session management, and dedicated frontend panels including a Memory editor. All four API protocols aligned with Hermes Agent 0.10.0 (chat_completions, anthropic_messages, codex_responses, bedrock_converse) are selectable. Providers owned by the user-authored providers: dict are rendered as read-only cards, and deep YAML configuration is delegated directly to the Hermes Web UI.

Beyond Hermes, this release adds a Gemini Native API proxy (api_format = "gemini_native") so the proxy can forward directly to Google's generateContent endpoint with full streaming, schema conversion, and shadow request support; renames the legacy "Local Proxy Takeover" to Local Routing across UI copy, README, and docs in all three locales; introduces application-level window controls, an opt-in setting that materially improves the experience on Linux Wayland where compositor-drawn buttons can become inert; and bundles late additions for launching hermes dashboard from the toolbar, a LemonData preset across all six apps, a DDSHub Codex endpoint, plus several Hermes health-check and Usage modal fixes.

On the session side, the message list is virtualized via @tanstack/react-virtual so conversations with thousands of records scroll smoothly and long messages collapse by default; the Usage dashboard adds a date range picker (Today / 1d / 7d / 14d / 30d + custom date-time calendar) and a page-jump input; Stream Check error classification now surfaces color-coded toasts with refreshed default probe models and an explicit "model not found" branch; and switching to official providers is blocked while Local Routing is active to avoid account-suspension risk. The pricing database is reseeded from v8 → v9 with ~50 new model entries (Claude 4.7, Opus 4.7 Adaptive Thinking, Grok 4, Qwen 3.5/3.6, MiniMax M2.5/M2.7, Doubao Seed 2.0 series, GLM-5/5.1 and others) and corrected stale prices.

Release Date: 2026-04-21

Update Scale: 100 commits | 219 files changed | +20,548 / -3,569 lines

Highlights

• Hermes Agent Support (6th Managed App): Database v9 → v10 migration, full Rust command surface, YAML read/write with atomic backups, MCP sync, Skills sync, SQLite + JSONL session management, dedicated frontend panels, and four API protocols (chat_completions / anthropic_messages / codex_responses / bedrock_converse)
• Claude Opus 4.7 Rollout: Adaptive thinking whitelisting, per-million pricing seed, Bedrock SKU (anthropic.claude-opus-4-7 / global.anthropic.claude-opus-4-7, dropping the legacy -v1 suffix); all aggregator and Bedrock presets migrated to Opus 4.7 as the default Opus model
• Claude max Effort Tier: Effort dropdown upgraded from high to max
• Gemini Native API Proxy: New api_format = "gemini_native" forwards directly to Google's generateContent with full streaming / schema conversion / shadow request support
• GitHub Copilot Enterprise Server: GHES authentication and endpoint configuration for Copilot-backed Claude providers
• Copilot Premium Consumption Deep Optimization: Proactive thinking-block stripping before forwarding, tool_result classification fix, subagent detection, x-interaction-id billing merge, orphan tool_result sanitization, and default warmup downgrade — a systematic reduction in premium interaction consumption
• Session List Virtualization: Long conversations scroll smoothly and long messages collapse by default to reduce text layout cost
• Codex / OpenClaw Session Title Extraction: Meaningful title extraction with 2-line display; strips OpenClaw message_id suffix noise
• Usage Date Range Picker: Today / 1d / 7d / 14d / 30d preset tabs + custom date-time calendar; page-jump input on paginated lists
• Stream Check Error Classification: Color-coded error toasts; refreshed default probe models; explicit "model not found" detection
• Block Official Provider Switching During Local Routing: Routing official API traffic through the local proxy carries account-suspension risk — switches are blocked with a warning toast
• Pricing Database Refresh (v8 → v9): ~50 new model entries and corrected stale prices
• Application-Level Window Controls: Opt-in setting to render CC Switch's own min/max/close buttons, materially improving Linux Wayland experience
• Hermes in Unified Skills Management: Skill install, enable, and filter now cover Hermes
• Hermes / OpenClaw Config Directory Override: Point CC Switch at a custom ~/.hermes/config.yaml or openclaw.json location
• Launch Hermes Dashboard from Toolbar: When the Hermes Web UI probe fails, the toolbar entry offers to run hermes dashboard in the user's preferred terminal
• New Partner Presets: LemonData across all six apps; DDSHub Codex endpoint; StepFun Step Plan

Added

Hermes Agent Support (6th Managed App)

CC Switch now treats Hermes Agent as a first-class managed app alongside Claude / Codex / Gemini / OpenCode / OpenClaw.

• Database Migration v9 → v10: Adds enabled_hermes columns to mcp_servers and skills tables (DEFAULT 0, auto-migrated, no data loss)
• YAML Configuration Read/Write: ~/.hermes/config.yaml read/write with atomic backups; tests/hermes_roundtrip.rs guards against dropped OAuth MCP auth blocks or pollution of unrelated YAML keys
• Four API Protocols: Aligned with Hermes Agent 0.10.0 — chat_completions / anthropic_messages / codex_responses / bedrock_converse; new deeplinks default to chat_completions
• User providers: Dict Read-Only Rendering: User-authored providers in the YAML appear as read-only cards in CC Switch; deep configuration delegates to the Hermes Web UI
• Additive Switching: Unlike Claude / Codex's "override" style, all Hermes providers coexist in the same YAML

Hermes Memory Panel

• New Memory panel for editing MEMORY.md / USER.md directly, with an enable switch, character-count limits, and a live save flow
• Replaces the Prompts entry for Hermes

Hermes Provider Presets (~50)

• Covers Nous Research, Shengsuanyun, OpenRouter, DeepSeek, Together AI, StepFun, Zhipu GLM, Bailian, Kimi, MiniMax, DouBao, BaiLing, ModelScope, KAT-Coder, PackyCode, Cubence, AIGoCode, RightCode, AICodeMirror, AICoding, CrazyRouter, SSSAiCode, Micu, CTok.ai, DDSHub, E-FlowCode, LionCCAPI, PIPELLM, Compshare, SiliconFlow, AiHubMix, DMXAPI, TheRouter, Novita, Nvidia, and Xiaomi MiMo

Launch Hermes Dashboard from Toolbar

• When the Hermes Web UI probe fails, the toolbar entry opens a confirm dialog offering to run hermes dashboard in the user's preferred terminal
• Spawned via a temp bash / batch script; hermes dashboard opens the browser itself once ready, so no polling is required
• The Memory panel and Health banner keep the existing toast behavior
• Also corrects the stale hermes web hint in the offline toast (the real command is hermes dashboard)
• Linux terminal detection reordered to try which before stat'ing /usr/bin, /bin, /usr/local/bin

Claude Opus 4.7 Support

• New Claude Opus 4.7 with adaptive thinking whitelisting, per-million pricing seed, and Bedrock SKU (anthropic.claude-opus-4-7 / global.anthropic.claude-opus-4-7, dropping the legacy -v1 suffix)
• All aggregator and Bedrock presets migrated to Opus 4.7 as the default Opus model

Claude max Effort Tier

• Claude effort dropdown upgraded from high to max for extended reasoning capacity

Gemini Native API Proxy

• New api_format = "gemini_native" so the proxy can forward directly to Google's generateContent API (#1918, thanks @yovinchen)
• Full streaming, schema conversion, and shadow request support
• Adds gemini_url.rs, gemini_schema.rs, gemini_shadow.rs, streaming_gemini.rs, and transform_gemini.rs under the proxy providers module

GitHub Copilot Enterprise Server (GHES)

• GHES authentication and endpoint configuration for Copilot-backed Claude providers (#2175, thanks @hotelbe)

Session List Virtualization

• Virtualized the session list via @tanstack/react-virtual so long conversations (thousands of records) scroll smoothly
• Long session messages are collapsed by default to reduce text layout cost

Codex / OpenClaw Session Title Extraction

• Meaningful title auto-extraction for Codex and OpenClaw sessions with 2-line display
• Strips OpenClaw message_id suffix noise

Usage Date Range Picker

• New date range selector on the usage dashboard with preset tabs (Today / 1d / 7d / 14d / 30d) + custom date + time calendar (#2002, thanks @yovinchen)
• Page-jump input added on paginated lists

Model Mapping Quick-Set

• New quick-set button next to model mapping fields in provider forms for faster edits (#2179, thanks @lispking)

Stream Check Error Classification

• Stream Check errors are classified and surfaced as color-coded toasts
• Refreshed default probe models to match each vendor's current lineup
• Explicit detection for "model not found" responses

Block Official Provider Switching During Local Routing

• Switching to official providers is blocked while Local Routing is active, with a warning toast
• Reason: routing official API traffic through the local proxy carries account-suspension risk

Pricing Database Refresh (v8 → v9)

• Reseed-on-migration pricing table
• ~50 new model pricing entries including Claude 4.7, Opus 4.7 Adaptive Thinking, Grok 4, Qwen 3.5/3.6, MiniMax M2.5/M2.7, Doubao Seed 2.0 series, GLM-5/5.1
• Corrected stale prices for DeepSeek, Kimi K2.5, and others

Application-Level Window Controls

• Opt-in setting to render CC Switch's own minimize / toggle-maximize / close buttons instead of system decorations (#1119, thanks @git1677967754)
• Materially improves the experience on Linux Wayland where compositor-drawn buttons can become inert

Hermes in Unified Skills Management

• Hermes is added to the unified Skills surface
• Skill install, enable, and filter now cover the Hermes app alongside Claude / Codex / Gemini / OpenCode / OpenClaw

OpenClaw Config Directory Override

• New settings option to point CC Switch at a custom openclaw.json location (#1518, thanks @mrFranklin)

Hermes Config Directory Override

• New settings option to point CC Switch at a custom ~/.hermes/config.yaml location, backed by data-driven dispatch

StepFun Step Plan Preset

• StepFun Step Plan (EN / ZH) provider presets (#2155, thanks @hengm3467)

New API Usage Script Template

• Added a User-Agent header to the New API usage script template for better upstream compatibility

LemonData Provider Preset (All Six Apps)

• LemonData registered as a third-party partner preset across Claude, Codex, Gemini, OpenCode, OpenClaw, and Hermes
• Icon assets and zh / en / ja partner-promotion copy
• Claude preset uses ANTHROPIC_API_KEY auth; OpenAI-compatible apps target gpt-5.4

DDSHub Codex Preset

• Added a Codex-compatible endpoint for DDSHub at the same host as its Claude service
• Base URL omits the /v1 suffix because the gateway auto-routes OpenAI SDK paths

Changed

"Local Proxy Takeover" → "Local Routing"

• Unified the terminology across UI copy, README, and docs in all three locales
• Functional behavior is unchanged

Hermes Auto api_mode Removed

• Users must pick an explicit protocol; new deeplinks default to chat_completions
• Eliminates URL-based heuristic surprises

Hermes Provider Form

• Added an API mode dropdown and per-provider model editor
• Binds per-provider models to the top-level model: when switching active providers

Hermes Deep Config Delegation

• Deep YAML knobs are no longer duplicated in the CC Switch form — they are delegated to the Hermes Web UI via a direct launch action

Hermes Toolbar Layout

• Swapped the Hermes Web UI button from ExternalLink to LayoutDashboard (clicking may spawn hermes dashboard rather than just opening a URL)
• Moved MCP to the final toolbar slot so Hermes matches the Claude / Codex / Gemini / OpenCode layout

ANTHROPIC_REASONING_MODEL Removed from Claude Quick-Set

• Decoupled the reasoning capability from model selection; the legacy field is no longer surfaced in the quick-set form

Per-Provider Proxy Config Removed

• Consolidated into global Local Routing
• Provider-level proxy toggle and associated storage are gone

Unified Toolbar Icon Button Width

• Normalized icon-button widths across Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes panels for a consistent header look

Rust Toolchain Pinned to 1.95

• Adopted clippy 1.95 suggestions across the workspace and pinned the toolchain to prevent nightly drift

Tray Menu ID Constant

• The tray identifier moved from the hardcoded string "main" to a TRAY_ID constant ("cc-switch") across all call sites (#1978, thanks @lidaxian121)

Copilot Premium Consumption Deep Optimization

A systematic overhaul to reduce Copilot reverse-proxy premium interaction consumption across multiple dimensions:

• Proactive Thinking Block Stripping Before Forwarding: Anthropic's thinking / redacted_thinking blocks are rejected by OpenAI-compatible endpoints. Previously, the request failed upstream, burning one premium interaction before the thinking_rectifier could retry. A new proactive strip step (Copilot optimization pipeline step 3.5, after tool_result merging) eliminates that wasted interaction
• Request Classification Fix: Messages containing tool_result are now classified as agent continuation instead of user-initiated, preventing every tool call from being falsely counted as a premium interaction
• Subagent Detection: Identifies subagents via __SUBAGENT_MARKER__ with metadata._agent_ fallback, setting x-interaction-type=conversation-subagent
• Deterministic x-interaction-id Billing Merge: Derives x-interaction-id from the session ID so multiple requests within the same session collapse into a single billing interaction
• Orphan tool_result Sanitization: Cleans up orphan tool_result entries to prevent upstream errors that would trigger retries and duplicate billing
• Warmup Downgrade Enabled by Default: Uses gpt-5-mini as the default downgrade model
• Optimization Pipeline Reorder: classify → sanitize → merge → warmup, so classification sees raw tool_result semantics
• Fixed a CopilotOptimizerConfig default-value inconsistency (unified to gpt-5-mini)

Usage Script Intranet Support

• Removed private-IP / suspicious-hostname blocking from usage scripts, unblocking enterprise intranet, Docker, and self-hosted API endpoints
• Built-in templates still enforce HTTPS (except localhost) and same-origin checks; custom templates remain user-controlled with those request-URL checks skipped

Failover Queue Notes

• Provider notes now appear in failover queue selectors and queue rows for easier identification across multi-provider queues (#2138, thanks @Coconut-Fish)

Fixed

Header Auto-Compact Latching After Maximize

• The toolbar no longer stays compacted after maximize/restore; compaction now reevaluates on size changes

Hermes YAML Pollution & OAuth MCP auth Drop

• Round-tripping through CC Switch no longer drops OAuth MCP auth blocks or pollutes unrelated YAML keys
• Guard tests added via tests/hermes_roundtrip.rs

Hermes Active Provider Display

• Hermes UI now correctly surfaces the active provider and wires add / enable / remove actions

Hermes Provider Persistence

• Providers persist under custom_providers: so api_mode and model survive restarts and config reloads

Hermes Health Check Borrowing OpenClaw Schema

• Hermes providers were routed through check_additive_app_stream (the OpenClaw dispatcher), which reads camelCase baseUrl / apiKey / api and surfaced "OpenClaw provider is missing baseUrl" even when every Hermes field was filled
• Introduced check_hermes_stream with Hermes-specific extractors that map api_mode (chat_completions / anthropic_messages / codex_responses) to the matching check_claude_stream api_format; bedrock_converse returns as unsupported
• api_mode is now resolved before URL / API key extraction, so bedrock_converse users see the real cause rather than a misleading "missing base_url"

Usage Query Modal for Hermes & OpenClaw

• getProviderCredentials now reads flat settingsConfig fields for Hermes (snake_case base_url / api_key) and OpenClaw (camelCase baseUrl / apiKey), so the "official balance" template auto-selects for matching providers like SiliconFlow
• Refactored the BALANCE and TOKEN_PLAN test paths to reuse the precomputed providerCredentials instead of re-reading env.ANTHROPIC_* directly, fixing the "empty key" error for non-Claude apps even when the key was configured

Codex cache_control Preservation

• Preserve cache_control when merging system prompts during Codex format conversion (#1946, thanks @yovinchen)

Claude Prompt Cache Key Leak

• Stopped sending prompt cache keys during Claude chat conversions (#2003, thanks @yovinchen)

Proxy Hop-by-Hop Header Stripping

• Strip hop-by-hop response headers (Connection, Keep-Alive, Transfer-Encoding, etc.) per RFC 7230 (#2060, thanks @yovinchen)

Permissive Proxy CORS Removed

• Removed the permissive CORS layer from the proxy (#1915, thanks @zerone0x)

Backend Error Details in Proxy Toast

• Surface backend error payload details in proxy-related toast messages instead of a generic failure string

Usage Log Deduplication

• Deduplicated proxy and session-log usage records so the same request is no longer double-counted
• Synced the request log time range with the dashboard's 1d / 7d / 30d selector

Common Config Checkbox Persistence

• Checkbox state for Claude / Codex / Gemini common-config toggles now persists correctly across reopens (#2191, thanks @zxZeng)

Claude Plugin settings.json Sync

• Editing the current provider now syncs back to settings.json for the Claude plugin path (#1905, thanks @chengww5217)

Google Official Gemini Env Preservation

• Saving the Google Official Gemini provider no longer clobbers the env block

OpenCode JSON5 Parser for Trailing Commas

• OpenCode config reads now tolerate trailing commas via a JSON5 parser (#2023, thanks @wwminger)

Preset Refreshes

• Refreshed stale context windows for DeepSeek and Claude 1M
• Refreshed stale model IDs; backfilled Hermes model lists
• Fixed the Nous endpoint and replaced the Hermes placeholder icon with Nous brand artwork
• Pruned unused official Hermes presets

Auto-Expand Collapsed Messages on Search Hit

• Collapsed messages now auto-expand when a search match lands inside hidden content

Unknown Subscription Quota Tiers Hidden

• Provider cards no longer render unknown subscription quota tiers

Weekly Limit Label Unified

• Aligned the weekly_limit tier label with the official 7-day naming across locales

Root-Level Skill Repo Install

• Fixed skill installation when the repository root itself is a skill

Session ID Parsing Clippy

• Removed a redundant closure in session ID parsing (clippy warning)

Stream Check Default Models Refresh

• Updated stream-check default probe models to match each vendor's current lineup

Skills Import Sync

• Imported Skills are now immediately synced into enabled app directories instead of only being recorded in the database (#2101, thanks @yaoguohh)
• The UI no longer shows "installed" while the target app directory is missing the skill

Ghostty Session Restore

• Fixed Ghostty session restore launch by using shell execution with --working-directory (#1976, thanks @Suda202)
• Avoids cwd escaping issues when the path contains spaces or special characters

Docs

README Sponsor Updates

• Updated SiliconFlow signup bonus to ¥16
• Trimmed the SSSAiCode sponsor blurb
• Updated partner logos
• Added LemonData as a new sponsor

Global Proxy Hint Clarified

• Clarified the global proxy hint about local routing across all three locales

Takeover → Routing Rename

• Renamed takeover docs to routing and updated anchors across all languages

PIPELLM Website URL

• Updated the PIPELLM sponsor website URL to code.pipellm.ai

⚠️ Breaking Changes

Hermes requires explicit api_mode

• The Auto mode is gone; imported or deeplinked providers default to chat_completions
• Users with prior Auto configs will be prompted to pick a protocol

ANTHROPIC_REASONING_MODEL removed from Claude quick-set

• The legacy field is no longer exposed; existing settings are cleaned up automatically

Per-provider proxy configuration removed

• Migrate to the global Local Routing setting
• Existing per-provider proxy values are ignored

Database schema v9 → v10

• Adds enabled_hermes columns to mcp_servers and skills
• Auto-migrated with DEFAULT 0; no data loss

Pricing table reseeded (v8 → v9)

• The model_pricing table is cleared and reseeded on first launch to pick up new models and corrected prices

XCodeAPI preset removed

• Users of the XCodeAPI preset should switch to another provider

⚠️ 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 v3.12.3 release notes.

Codex OAuth Reverse Proxy: Using the Codex OAuth reverse proxy with a ChatGPT subscription may violate OpenAI's terms of service. See v3.13.0 release notes.

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

CC Switch v3.13.0

Lightweight Mode, Quota & Balance Visibility, Provider Model Auto-Fetch, Codex OAuth Reverse Proxy, and Tray Per-App Submenus

中文版 → | 日本語版 →

Overview

CC Switch v3.13.0 is a major feature release centered on observability, provider workflow ergonomics, and proxy compatibility. It adds inline quota and balance displays across official Claude / Codex / Gemini providers plus Token Plan, Copilot, and third-party balance APIs; introduces a Lightweight Mode that keeps CC Switch running from the system tray without a main window; delivers automatic model discovery via OpenAI-compatible /v1/models across all five supported applications; ships a Codex OAuth reverse proxy for ChatGPT subscribers; reorganizes the tray menu into per-app submenus; rebuilds the proxy forwarding stack on a Hyper-based client; and overhauls the Skills workflow with discovery, batch updates, storage-location toggling, and built-in skills.sh search and install. Additional improvements include full URL endpoint mode, enhanced token usage tracking, the Copilot interaction optimizer, a UTF-8 streaming chunk boundary fix for multi-byte output, a Linux startup UI responsiveness fix, and a friendlier new-user onboarding experience.

Release Date: 2026-04-10

Update Scale: 139 commits | 280 files changed | +31,627 / -3,042 lines

Highlights

• Lightweight Mode: Tray-only operating mode that destroys the main window on exit to tray and recreates it on demand, reducing CC Switch's desktop footprint to near zero when idle
• Quota & Balance Visibility: Inline quota or balance readout across provider cards — official Claude / Codex / Gemini subscriptions, GitHub Copilot premium interactions, Codex OAuth, Token Plan providers (Kimi / Zhipu GLM / MiniMax), plus official balance queries for DeepSeek, StepFun, SiliconFlow, OpenRouter, and Novita AI
• Provider Model Auto-Fetch: OpenAI-compatible /v1/models discovery across Claude, Codex, Gemini, OpenCode, and OpenClaw provider forms, with grouped dropdown selection and failure-specific error messages
• Codex OAuth Reverse Proxy: ChatGPT Codex reverse proxy exposed as a new Claude provider card type, allowing users to use their ChatGPT subscription in Claude Code. Includes managed OAuth login and inline subscription quota display (⚠️ Risk Notice)
• Tray Per-App Submenus: Reworked the tray menu into per-application submenus so it never overflows the screen and background provider switching scales to dozens of providers per app
• Skills Discovery & Batch Updates: SHA-256-based skill update detection, per-skill and "Update All" batch actions, skills.sh search integration, and a storage-location toggle between CC Switch storage and ~/.agents/skills
• Session Workflow Upgrades: Batch session deletion, a directory picker before launching Claude terminal restore, usage import from Claude / Codex / Gemini session logs without proxy interception, precise Codex JSONL parsing, and per-app usage filtering
• OpenCode / OpenClaw Stream Check Coverage: OpenCode detection via npm package mapping, OpenClaw openai-completions support, and the remaining OpenClaw protocol variants — with custom-header passthrough and auth-header detection fixes
• Full URL Endpoint Mode: Provider option that treats base_url as a complete upstream endpoint, unblocking vendors that require nonstandard URL layouts
• Hyper-based Proxy Forwarding Stack: Refactored proxy forwarding onto a Hyper-based client with transparent header forwarding, improved endpoint rewriting, and better support for dynamic upstream endpoints
• Copilot Interaction Optimizer: Request classification and routing logic that reduces unnecessary GitHub Copilot premium interaction consumption
• UTF-8 Stream Chunk Boundary Fix: All four SSE streaming paths now preserve incomplete multi-byte UTF-8 sequences across TCP chunks, eliminating intermittent U+FFFD garbled output via the Copilot reverse proxy
• Linux Startup UI Fix: Fixed the long-standing issue where the window UI couldn't receive clicks on Linux until the user manually maximized and restored the window
• First-Run Onboarding: One-time welcome dialog on fresh installs, automatic seeding of Claude / OpenAI / Google official presets, and auto-import of OpenCode / OpenClaw live configurations on startup
• Claude Session Titles & Search Highlighting: Meaningful title extraction for Claude sessions using a priority chain (custom-title metadata → first user message → directory basename), plus keyword highlighting in Session Manager search results
• URL-Based Provider Icons: Dual rendering mode supporting Vite URL imports for large SVGs and raster images (PNG, JPG, WebP), keeping small SVGs inlined
• New Provider Presets: TheRouter, DDSHub, LionCCAPI, Shengsuanyun (胜算云), PIPELLM, and E-FlowCode across supported applications

New Features

Lightweight Mode

A tray-only operating mode that dramatically reduces CC Switch's desktop footprint when idle.

• Destroys the main window on exit-to-tray instead of hiding it, freeing UI resources and memory
• Recreates the window on demand when the user reopens CC Switch from the tray, a deeplink, or single-instance activation
• Integrated into every window-re-show path: normal startup, deeplink, single_instance, tray show_main, and the lightweight-exit round-trip

Quota & Balance Visibility

Added inline quota and balance readouts to provider cards so users can see remaining capacity without leaving the card.

• Official subscriptions: Inline quota display for Claude, Codex, and Gemini official providers
• GitHub Copilot: Premium interactions quota display on the Copilot provider card
• Codex OAuth: ChatGPT subscription quota inline with the Codex OAuth provider card
• Token Plan providers: Kimi, Zhipu GLM, and MiniMax usage progression display (requires manual activation to avoid confusion)
• Third-party balances: Official balance queries for DeepSeek, StepFun, SiliconFlow, OpenRouter, and Novita AI (requires manual activation to avoid confusion)
• Health-check and usage-config buttons are hidden for official providers to keep the card clean

Provider Model Auto-Fetch

Added OpenAI-compatible model discovery to every provider form, removing the manual copy-paste loop for model IDs.

• Queries the configured provider endpoint's /v1/models
• Groups models in the dropdown by category for easier selection
• Failure-specific error messages distinguish network / authentication / endpoint issues
• Supported across all five applications: Claude, Codex, Gemini, OpenCode, and OpenClaw

Codex OAuth Reverse Proxy

Added a reverse proxy path for ChatGPT subscribers who want to use their ChatGPT subscription in Claude Code.

• Managed OAuth login flow with ChatGPT authentication
• Surfaces as a new Claude provider card type alongside API-key providers
• Inline subscription quota display
• Integrated into the Auth Center for unified token management
• See the ⚠️ Risk Notice below before enabling

Tray Per-App Submenus

Reorganized the tray menu so providers are grouped under each application instead of living in a flat list.

• Per-application submenus for Claude, Codex, Gemini, OpenCode, and OpenClaw
• Prevents the tray menu from overflowing the screen when users have many providers
• Background provider switching scales cleanly to long provider lists

Skills Discovery & Batch Updates

Upgraded the Skills management panel into a complete discovery plus maintenance workflow.

• SHA-256 update detection: Skills are content-hashed so the UI knows exactly which ones have upstream changes
• Per-skill and batch updates: Individual "Update" buttons plus an animated "Update All" batch action
• Storage-location toggle: Switch between CC Switch storage and ~/.agents/skills without losing skill state
• Public registry search: skills.sh search integrated directly into the dialog for discovering community skills

Session Workflow Upgrades

Multiple session management improvements that reduce friction when working with Claude / Codex / Gemini sessions.

• Batch session deletion: Select and delete multiple sessions at once from Session Manager (#1693, thanks @Alexlangl)
• Directory picker before restore: Claude terminal restore now prompts for the working directory up front (#1752, thanks @yovinchen)
• Usage from session logs without proxy: Usage data imported directly from Claude / Codex / Gemini session logs — no proxy interception required
• Precise Codex JSONL parsing: Replaced estimated Codex usage with precise JSONL session-log parsing plus Codex model name normalization for consistent pricing lookup
• Gemini CLI session log integration: Gemini usage now syncs accurately from Gemini CLI session logs
• Per-app usage filtering: Filter the usage dashboard by Claude, Codex, or Gemini independently

OpenCode / OpenClaw Stream Check Coverage

Extended the Stream Check panel to cover the full OpenCode and OpenClaw surface area.

• OpenCode detection via npm package mapping
• Support for the OpenClaw openai-completions protocol
• Support for the remaining three OpenClaw protocol variants
• Edge-case handling for custom-header passthrough, OpenClaw custom auth-header detection, Bedrock error messaging, and OpenCode default baseURL fallback

Full URL Endpoint Mode

Added a provider option that treats base_url as a complete upstream endpoint instead of a base URL with path appending (#1561, thanks @yovinchen).

• Proxy forwarding and Stream Check both honor the full-URL mode
• Unblocks vendors that require nonstandard URL layouts
• Configurable per-provider on the provider form

OpenCode StepFun Step Plan Preset

• Added a StepFun Step Plan provider preset for OpenCode with sensible defaults (#1668, thanks @sky-wang-salvation)

Copilot Interaction Optimizer

Added request classification and routing logic that reduces unnecessary GitHub Copilot premium interaction consumption.

• Classifies incoming requests by intent and weight
• Routes low-value requests away from premium interaction consumption paths
• Designed to extend the usable lifetime of a Copilot subscription
• Note: Even with optimized consumption, using the Copilot API outside of Copilot still consumes more than using it within Copilot.

First-Run Welcome Dialog

Added a one-time welcome dialog on fresh installs to guide new users through the CC Switch workflow.

• Explains how existing live configuration is preserved as a default provider
• Introduces the bundled official preset that enables one-click revert to official endpoints
• Upgrade users are automatically excluded via empty provider check

Official Provider Seeding

• Added automatic seeding of Claude Official, OpenAI Official, and Google Official provider entries on startup, giving every user a one-click path back to the official endpoint

OpenCode / OpenClaw Auto-Import

• Added automatic startup import of live OpenCode and OpenClaw provider configurations, matching the auto-import behavior already present for Claude, Codex, and Gemini

Common Config Editor Guidance

• Added an informational guide and empty-state prompt to the Common Config snippet editor modal for Claude, Codex, and Gemini
• Added a one-time informational dialog explaining Common Config Snippets when users first open the provider add/edit form

Claude Session Titles & Search Highlighting

• Added meaningful title extraction for Claude sessions using a priority chain: custom-title metadata, first real user message, then directory basename fallback
• Added keyword highlighting in session titles and messages during Session Manager search

URL-Based Provider Icons

• Added a dual rendering mode to the icon system: small SVGs are inlined as React components, while large SVGs and raster images (PNG, JPG, WebP) are loaded via Vite URL imports as <img> tags

Kaku Terminal Support

• Added Kaku as a selectable terminal for session launch on macOS, reusing the WezTerm-compatible launch path (#1983, thanks @yovinchen)

OMO Slim Council Support

• Restored first-class council support as a built-in oh-my-opencode-slim agent with updated metadata and UI copy (#1982, thanks @yovinchen)

New Provider Presets

• TheRouter: Added across Claude, Codex, Gemini, OpenCode, and OpenClaw (#1891, #1892, thanks @cmzz)
• DDSHub: Added as a third-party partner provider for Claude with icon and partner promotion text
• LionCCAPI: Added across all five apps with anthropic-messages protocol for OpenCode and OpenClaw
• Shengsuanyun (胜算云): Added as an aggregator partner provider across all five apps with URL-based icon and localized display name
• PIPELLM: Added across Claude, Codex, OpenCode, and OpenClaw with full model definitions and icon
• E-FlowCode: Added across all five apps with per-app protocol configuration

Changes

Tray Menu Organization

• Reworked the tray menu into per-application submenus (Claude / Codex / Gemini / OpenCode / OpenClaw)
• Prevents overflow and scales to long provider lists

Proxy Forwarding Stack

Rebuilt the proxy forwarding layer on a Hyper-based HTTP client (#1714, thanks @yovinchen).

• Transparent header forwarding: headers are forwarded without aggressive filtering
• Improved endpoint rewriting logic
• Better support for dynamic upstream endpoints
• Paired with the new Full URL Endpoint Mode to unblock vendors with nonstandard URL layouts

OAuth Auth Center UI Polish

• Tightened the Auth Center copy, layout, and icon presentation so the Codex OAuth login flow feels cleaner and less cluttered

Provider Key Lifecycle & Live Sync

Reworked the additive provider create / rename / duplicate flows so live config writes, cleanup, and rollback stay consistent across OpenCode / OpenClaw and takeover scenarios (#1724, thanks @yovinchen).

• Additive-mode highlight behavior made persistent across refreshes (#1747, thanks @yovinchen)
• Consistent live config writes across OpenCode / OpenClaw
• Rollback behavior preserved when operations fail

Codex OAuth Defaults

• Updated the Codex OAuth preset to the GPT-5.4 model family

Bug Fixes

Copilot Authentication & Proxy Compatibility

• Fixed GitHub Copilot authentication regressions (#1854, thanks @Mason-mengze)
• Corrected enterprise and dynamic endpoint handling
• Repaired clipboard verification-code copying on macOS and Linux
• Fixed Responses routing when Copilot-backed Claude providers target OpenAI models (#1735, thanks @Mason-mengze)

UTF-8 Stream Chunk Boundaries

Fixed intermittent garbled output (U+FFFD replacement characters) in Claude Code when multi-byte UTF-8 sequences such as Chinese characters and emoji were split across TCP stream chunks via the Copilot reverse proxy (#1923, thanks @Cod1ng).

• Replaced String::from_utf8_lossy with a new append_utf8_safe helper across all four SSE streaming paths
• Preserves incomplete trailing bytes in a remainder buffer and merges them with the next chunk before decoding
• Not reproducible with direct Copilot connections that pass through raw bytes without format conversion

Fragmented System Prompt Normalization

Fixed strict OpenAI-compatible chat backends (Nvidia, Qwen-style) rejecting requests when converted Claude payloads contained multiple system messages (#1942, thanks @yovinchen).

• Normalized system content into a single leading system message during the Anthropic → OpenAI chat transformation
• Leaves the rest of the message stream unchanged

Streaming Parser Compatibility

• Fixed SSE parsing to accept fields with optional spaces, improving compatibility with non-strict streaming implementations (#1664, thanks @Alexlangl)

Provider Switch State Corruption

• Serialized per-app provider switches to prevent concurrent failover or hot-switch operations from leaving is_current, settings state, and live backup state out of sync

Claude Takeover Live Config Drift

• Fixed provider edits while Claude takeover is active so live settings remain aligned with the latest provider state without breaking takeover restore behavior (#1828, thanks @geekdada)

WebDAV Password Retention & Validation

• Fixed the WebDAV password field so saved credentials remain visible after refresh
• Treated MKCOL 405 responses correctly during connection validation (#1685, thanks @Alexlangl)

Provider Card Action States

• Fixed additive-mode highlight behavior (#1747, thanks @yovinchen)
• Aligned usage display layout across provider cards by always rendering action buttons
• Replaced hard proxy-switch blocking with a warning path
• Disabled unsupported test and usage actions for Copilot and Codex OAuth cards
• Hid usage-config and health-check buttons for official providers
• Removed the hover-push animation from provider cards

Usage Accuracy & Pricing

• Fixed MiniMax quota math and 0% → 100% progression
• Corrected CNY → USD pricing plus missing model definitions
• Improved Gemini session-log syncing accuracy
• Resolved session-based usage entries being shown as unknown providers

Usage Editor & Skills UI Regressions

• Fixed usage query fields being reset while editing extractor code (#1771, thanks @if-nil)
• Corrected broken skills.sh links and empty descriptions
• Fixed auto-query default interval (5 min) and number-input clearing in usage configuration

Chinese Skills Terminology

• Unified Skills-related labels across settings panels in the zh locale so storage and sync options use consistent wording

Environment & Preset Compatibility

• Added Bun global bin detection in CLI scan (#1742, thanks @makoMakoGo)
• Adapted to the oh-my-openagent rename with backward compatibility (#1746, thanks @yovinchen)
• Corrected the OpenCode kimi-for-coding preset (#1738, thanks @makoMakoGo)
• Gated Gemini keychain parsing to macOS only
• Fixed an OpenClaw serializer panic on empty collections (#1724, thanks @yovinchen)

Linux UI Unresponsive on Startup

Fixed a long-standing Linux bug where the window UI (including native title bar buttons) couldn't receive clicks until the user manually maximized and restored the window.

• Root causes: (1) Tauri webview did not acquire keyboard focus after show() on Linux, so the first click was consumed by X11/Wayland click-to-activate (Tauri #10746, wry #637); (2) GTK surface's input region failed to renegotiate on the visible:false → show() path under some WebKitGTK/compositor combinations, leaving the entire window unresponsive
• Mitigations: Set WEBKIT_DISABLE_COMPOSITING_MODE=1 at startup, and added a new linux_fix::nudge_main_window helper that performs set_focus + a ±1px no-op resize ~200ms after show, equivalent to a visually invisible "maximize-and-restore"
• Coverage: Wired into all window-re-show paths — normal startup, deeplink, single_instance, tray show_main, and lightweight-mode exit

Linux Drag Region on Header

• Removed data-tauri-drag-region from the top header bar on Linux to avoid triggering gtk_window_begin_move_drag paths affected by Tauri #13440 under Wayland
• macOS drag behavior is preserved

OpenCode / OpenClaw Stream Check Edge Cases

• Fixed custom-header passthrough
• OpenClaw custom auth-header detection
• Bedrock error messaging
• OpenCode default baseURL fallback handling

Duplicate Toast on Provider Switch

• Fixed double toast notifications (proxy-required warning followed by switch-success) when switching to Copilot, ChatGPT, or OpenAI-format providers with the proxy not running

Session Search Accuracy & Chinese Support

• Fixed session search result truncation across providers
• Switched FlexSearch tokenizer to full mode for proper Chinese substring matching

Adaptive Thinking Reasoning Effort

• Fixed resolve_reasoning_effort() mapping adaptive thinking to xhigh instead of incorrectly using high in OpenAI format conversions

Thinking Model Fallback Display

• Fixed the Claude provider form showing an empty Thinking model field after saving only a main model by applying read-only fallback to ANTHROPIC_MODEL (#1984, thanks @yovinchen)

Auth Tab Localization

• Fixed missing i18n translation keys for the settings auth tab label across all locale bundles (#1985, thanks @yovinchen)

Schema Migration Guard

• Fixed database migrations failing when skills or model_pricing tables did not exist by adding table-existence checks before ALTER and UPDATE operations

Documentation

User Manual Refresh

• Updated the EN / ZH / JA user manuals to cover tray submenus, lightweight mode, provider model fetching, session management, workspace files, WebDAV v2 behavior, OpenCode / OpenClaw activation, and other provider workflow improvements

Community & Contribution Docs

• Added CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md
• Added bilingual GitHub issue and PR templates
• Added Dependabot configuration (#1829, thanks @bengbengbalabalabeng) and a stale-bot workflow for inactive issues
• Added a PR / push quality-checks CI workflow

Release Notes Risk Notice Backport

• Added a Copilot reverse proxy risk notice and anchored highlight links in the v3.12.3 release notes across all three languages

Sponsor Partners

• Added Shengsuanyun, LionCC, and DDS as sponsor partners in README across all languages

⚠️ Risk Notice

Codex OAuth Reverse Proxy Disclaimer

The Codex OAuth reverse proxy introduced in this release accesses ChatGPT Codex services through reverse-engineered OAuth flows. Please be aware of the following risks before enabling this feature:

1. Terms of Service: Using reverse-engineered OAuth flows to access OpenAI services may violate OpenAI's terms of service, which prohibit unauthorized automated access, service reproduction, and circumventing intended access paths.
2. Account Risk: OpenAI may flag unusual usage patterns as suspicious automated activity, potentially resulting in temporary or permanent restrictions on ChatGPT access.
3. No Guarantee: OpenAI may update its authentication and detection mechanisms at any time, and usage patterns that work today may be flagged in the future.

The GitHub Copilot reverse proxy introduced in v3.12.3 also remains subject to its existing risk notice — see the v3.12.3 release notes for the full disclosure.

Users enable these features at their own risk. CC Switch is not responsible for any account restrictions, warnings, or service suspensions resulting from the use of these features.

Download & Installation

Visit Releases to download the appropriate version.

System Requirements

Windows

macOS

macOS builds are code-signed and notarized by Apple for a seamless install experience.

Homebrew (macOS)

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

Update:

brew upgrade --cask cc-switch

Linux

CC Switch v3.12.3

GitHub Copilot Reverse Proxy, macOS Code Signing & Notarization, Reasoning Effort Mapping, OpenCode SQLite Backend

中文版 → | 日本語版 →

Overview

CC Switch v3.12.3 is a major feature release that adds GitHub Copilot reverse proxy support with a dedicated Auth Center, introduces macOS code signing and Apple notarization for a seamless install experience, maps reasoning effort levels across providers, migrates OpenCode to a SQLite backend, enables Tool Search via the native ENABLE_TOOL_SEARCH environment variable toggle, and delivers a full skill backup/restore lifecycle. Additional improvements include proxy gzip compression, o-series model compatibility, Skills import rework, Ghostty terminal fix, Skills cache strategy optimization, Claude 4.6 context window update, and multiple bug fixes.

Release Date: 2026-03-24

Update Scale: 36 commits | 107 files changed | +9,124 / -802 lines

Highlights

• GitHub Copilot reverse proxy: Full Copilot proxy support with OAuth device flow authentication, token refresh, and request fingerprint emulation
• Copilot Auth Center: Dedicated authentication management UI for GitHub Copilot OAuth flow with token status display and one-click refresh
• macOS code signing & notarization: macOS builds are now code-signed and notarized by Apple, eliminating the "unidentified developer" warning entirely
• Reasoning Effort mapping: Proxy-layer auto-mapping — explicit output_config.effort takes priority, falling back to budget_tokens thresholds (<4 000→low, 4 000–16 000→medium, ≥16 000→high) for o-series and GPT-5+ models
• OpenCode SQLite backend: Added SQLite session storage for OpenCode alongside existing JSON backend; dual-backend scan with SQLite priority on ID conflicts
• Codex 1M context window toggle: One-click checkbox to set model_context_window = 1000000 with auto-populated model_auto_compact_token_limit
• Disable Auto-Upgrade toggle: Added DISABLE_AUTOUPDATER env var checkbox in the Claude Common Config editor to prevent Claude Code from auto-upgrading
• Tool Search env var toggle: Tool Search enabled via Claude 2.1.76+ native ENABLE_TOOL_SEARCH environment variable in the Common Config editor — no binary patching required
• Skill backup/restore lifecycle: Skills are automatically backed up before uninstall; backup list with restore and delete management added
• Proxy gzip compression: Non-streaming proxy requests now auto-negotiate gzip compression, reducing bandwidth usage
• o-series model compatibility: Chat Completions proxy correctly uses max_completion_tokens for o1/o3/o4-mini models; Responses API kept on the correct max_output_tokens field
• Skills import rework: Replaced implicit filesystem-based app inference with explicit ImportSkillSelection to prevent incorrect multi-app activation
• Ghostty terminal support: Fixed Claude session restore in Ghostty terminal

New Features

GitHub Copilot Reverse Proxy

Added full reverse proxy support for GitHub Copilot, enabling Copilot-authenticated requests to be forwarded through CC Switch.

• Implements OAuth device flow authentication for GitHub Copilot
• Automatic token refresh and session management
• Request fingerprint emulation for seamless compatibility
• Integrated into the existing proxy infrastructure alongside Claude, Codex, and Gemini handlers

Copilot Auth Center

A dedicated authentication management UI for GitHub Copilot.

• OAuth device flow with code display and browser-based authorization
• Token status display showing expiration and validity
• One-click token refresh without re-authentication
• Integrated into the settings panel for easy access

Reasoning Effort Mapping

Proxy-layer auto-mapping of reasoning effort for OpenAI o-series and GPT-5+ models.

• Two-tier resolution: explicit output_config.effort takes priority, falling back to thinking budget_tokens thresholds (<4 000→low, 4 000–16 000→medium, ≥16 000→high)
• Covers both Chat Completions and Responses API paths with 17 unit tests

OpenCode SQLite Backend

Added SQLite session storage support for OpenCode alongside the existing JSON backend.

• Dual-backend scan with SQLite priority on ID conflicts
• Atomic session deletion and path validation
• JSON backend remains functional for backwards compatibility

Codex 1M Context Window Toggle

Added a one-click toggle for Codex 1M context window in the config editor.

• Checkbox sets model_context_window = 1000000 in config.toml
• Auto-populates model_auto_compact_token_limit = 900000 when enabled
• Unchecking removes both fields cleanly

Disable Auto-Upgrade Toggle

Added a checkbox in the Claude Common Config editor to disable Claude Code auto-upgrades.

• Sets DISABLE_AUTOUPDATER=1 in the environment configuration when enabled
• Displayed alongside Teammates mode, Tool Search, and High Effort toggles

Tool Search Environment Variable Toggle

Tool Search is now enabled via the native ENABLE_TOOL_SEARCH environment variable introduced in Claude 2.1.76+.

• Toggle available in the Common Config editor under environment variables
• Sets ENABLE_TOOL_SEARCH=1 in the Claude environment configuration
• No binary patching required — uses Claude's built-in support

macOS Code Signing & Notarization

macOS builds are now code-signed and notarized by Apple.

• Application signed with a valid Apple Developer certificate
• Notarized through Apple's notarization service for Gatekeeper approval
• DMG installer also signed and notarized
• Eliminates the "unidentified developer" warning on first launch

Skill Auto-Backup on Uninstall

Skill files are now automatically backed up before uninstall to prevent accidental data loss.

• Backups stored in ~/.cc-switch/skill-backups/ with all skill files and a meta.json containing original metadata
• Old backups are automatically pruned to keep at most 20
• Backup path is returned to the frontend and shown in the success toast

Skill Backup Restore & Delete

Added management commands for skill backups created during uninstall.

• List all available skill backups with metadata
• Restore copies files back to SSOT, saves the DB record, and syncs to the current app with rollback on failure
• Delete removes the backup directory after a confirmation dialog
• ConfirmDialog gains a configurable zIndex prop to support nested dialog stacking

Changes

Skills Cache Strategy Optimization

Optimized the Skills cache invalidation strategy for better performance.

• Reduced unnecessary cache refreshes during skill operations
• Improved cache coherence between skill install/uninstall and list queries

Claude 4.6 Context Window Update

Updated Claude 4.6 model preset with the latest context window size.

• Reflects the expanded context window for Claude 4.6 models
• Updated in provider presets for accurate model information display

MiniMax M2.7 Upgrade

• Updated MiniMax provider preset to M2.7 model variant

Xiaomi MiMo Upgrade

• Updated Xiaomi MiMo provider preset to the latest model version

AddProviderDialog Simplification

• Removed redundant OAuth tab, reducing dialog from 3 tabs to 2 (app-specific + universal)

Provider Form Advanced Options Collapse

• Model mapping, API format, and other advanced fields in the Claude provider form now auto-collapse when empty
• Auto-expands when any value is set or when a preset fills them in; does not auto-collapse when manually cleared

Proxy Gzip Compression

Non-streaming proxy requests now support gzip compression for reduced bandwidth usage.

• Non-streaming requests let reqwest auto-negotiate gzip and transparently decompress responses
• Streaming requests conservatively keep Accept-Encoding: identity to avoid decompression errors on interrupted SSE streams

o1/o3 Model Compatibility

Proxy forwarding now handles OpenAI o-series model token parameters correctly.

• Chat Completions path uses max_completion_tokens instead of max_tokens for o1/o3/o4-mini models (#1451, thanks @Hemilt0n)
• Responses API path kept on the correct max_output_tokens field instead of incorrectly injecting max_completion_tokens

OpenCode Model Variants

• Placed OpenCode model variants at top level instead of inside options for better discoverability (#1317)

Skills Import Flow

The Skills import flow has been reworked for correctness and cleanup.

• Replaced implicit filesystem-based app inference with explicit ImportSkillSelection to prevent incorrect multi-app activation when the same skill directory exists under multiple app paths
• Added reconciliation to sync_to_app to remove disabled/orphaned symlinks
• MCP sync_all_enabled now removes disabled servers from live config
• Schema migration preserves a snapshot of legacy app mappings to avoid lossy reconstruction

Bug Fixes

WebDAV Password Clearing

• Fixed an issue where the WebDAV password was silently cleared when saving unrelated settings

Tool Message Parsing

• Fixed incorrect parsing of tool-use messages in certain proxy response formats

Dark Mode Styling

• Fixed dark mode rendering inconsistencies in UI components

Copilot Request Fingerprint

• Fixed request fingerprint generation for Copilot proxy to match expected format

Provider Form Double Submit

• Prevented duplicate submissions on rapid button clicks in provider add/edit forms (#1352, thanks @Hexi1997)

Ghostty Session Restore

• Fixed Claude session restore in Ghostty terminal (#1506, thanks @canyonsehun)

Skill ZIP Import Extension

• Added .skill file extension support in ZIP import dialog (#1240, #1455, thanks @yovinchen)

Skill ZIP Install Target App

• ZIP skill installs now use the currently active app instead of always defaulting to Claude

OpenClaw Active Card Highlight

• Fixed active OpenClaw provider card not being highlighted (#1419, thanks @funnytime75)

Responsive Layout with TOC

• Improved responsive design when TOC title exists (#1491, thanks @West-Pavilion)

Import Skills Dialog White Screen

• Added missing TooltipProvider in ImportSkillsDialog to prevent runtime crash when opening the dialog

Panel Bottom Blank Area

• Replaced hardcoded h-[calc(100vh-8rem)] with flex-1 min-h-0 across all content panels to eliminate bottom gap caused by mismatched offset values on different platforms

Documentation

Pricing Model ID Normalization

• Added documentation section explaining model ID normalization rules (prefix stripping, suffix trimming, @→- replacement) in EN/ZH/JA user manuals (#1591, thanks @makoMakoGo)

macOS Signed Build Messaging

• Removed all xattr workaround instructions and "unidentified developer" warnings from README, README_ZH, installation guides (EN/ZH/JA), and FAQ pages (EN/ZH/JA); replaced with "signed and notarized by Apple" messaging

⚠️ Risk Notice

GitHub Copilot Reverse Proxy Disclaimer

The Copilot reverse proxy feature introduced in this release accesses GitHub Copilot services through reverse-engineered, unofficial APIs. Please be aware of the following risks before enabling this feature:

1. Terms of Service: This feature may violate GitHub's Acceptable Use Policies and Terms for Additional Products and Features, which prohibit excessive automated bulk activity, unauthorized service reproduction, and placing undue burden on servers through automated means.
2. Account Risk: There are documented cases of GitHub issuing warning emails to users of similar tools, citing "scripted interactions or otherwise deliberately unusual or strenuous" usage patterns. Continued use after a warning may result in temporary or permanent suspension of Copilot access.
3. No Guarantee: GitHub may update its detection mechanisms at any time, and usage patterns that work today may be flagged in the future.

Users enable this feature at their own risk. CC Switch is not responsible for any account restrictions, warnings, or service suspensions resulting from the use of this feature.

Download & Installation

Visit Releases to download the appropriate version.

System Requirements

Windows

macOS

macOS builds are code-signed and notarized by Apple for a seamless install experience.

Homebrew (macOS)

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

Update:

brew upgrade --cask cc-switch

Linux

CC Switch v3.12.2

Common Config Protection During Proxy Takeover, Snippet Lifecycle Stability, Section-Aware Codex TOML Editing

中文版 → | 日本語版 →

Overview

CC Switch v3.12.2 is a reliability-focused patch release that addresses Common Config loss during proxy takeover and improves Codex TOML editing accuracy. Proxy takeover hot-switches and provider sync now update the restore backup instead of overwriting live config files; the startup sequence has been reordered so snippets are extracted from clean live files before takeover state is restored; and Codex base_url editing has been refactored into a section-aware model that no longer appends to the end of the file.

Release Date: 2026-03-12

Update Scale: 5 commits | 22 files changed | +1,716 / -288 lines

Highlights

• Empty state guidance: Provider list empty state now shows detailed import instructions with a conditional Common Config snippet hint for Claude/Codex/Gemini

• Proxy takeover restore flow rework: Hot-switches and provider sync now refresh the restore backup instead of overwriting live config files, preserving the full user configuration on rollback

• Snippet lifecycle stability: Introduced a cleared flag to prevent auto-extraction from resurrecting cleared snippets, and reordered startup to extract from clean state

• Section-aware Codex TOML editing: base_url and model field reads/writes now target the correct [model_providers.<name>] section

• Codex MCP config protection: Existing mcp_servers blocks in restore snapshots survive provider hot-switches via per-server-id merge instead of wholesale replacement, with provider/common-config definitions winning on conflict

New Features

Empty State Guidance

Improved the first-run experience with helpful guidance when the provider list is empty.

• Empty state page shows step-by-step import instructions
• Conditionally displays a Common Config snippet hint for Claude/Codex/Gemini providers (not shown for OpenCode/OpenClaw)

Changes

Proxy Takeover Restore Flow

The proxy takeover hot-switch and provider sync logic has been reworked to protect Common Config throughout the takeover lifecycle.

• Provider sync now updates the restore backup instead of writing directly to live config files when takeover is active
• Effective provider settings are rebuilt with Common Config applied before saving restore snapshots, so rollback restores the real user configuration
• Legacy providers with inferred common config usage are automatically marked with commonConfigEnabled=true

Codex TOML Editing Engine

Codex config.toml update logic has been refactored onto shared section-aware TOML helpers.

• New Rust module codex_config.rs with update_codex_toml_field and remove_codex_toml_base_url_if
• New frontend utilities getTomlSectionRange / getCodexProviderSectionName for section-aware operations
• Inline TOML editing logic scattered across proxy.rs now delegates to the new module

Common Config Initialization Lifecycle

The startup sequence has been reordered for more robust snippet extraction and migration.

• Startup now auto-extracts Common Config snippets from clean live files before restoring proxy takeover state
• Introduced a snippet cleared flag to track whether a user intentionally cleared a snippet
• Persisted a one-time legacy migration flag to avoid repeated commonConfigEnabled backfills

Bug Fixes

Common Config Loss

• Fixed multiple scenarios where Common Config could be dropped during proxy takeover: sync overwriting live files, hot-switches producing incomplete restore snapshots, and provider switches losing config changes

Codex Restore Snapshot Preservation

• Fixed Codex takeover restore backups discarding existing mcp_servers blocks during provider hot-switches; changed MCP backup preservation from wholesale table replacement to per-server-id merge so provider/common-config MCP updates win on conflict while backup-only servers are retained

Cleared Snippet Resurrection

• Fixed startup auto-extraction recreating Common Config snippets that users had intentionally cleared

Codex base_url Misplacement

• Fixed Codex base_url extraction and editing not targeting the correct [model_providers.<name>] section, causing it to append to the file tail or confuse mcp_servers.*.base_url entries for provider endpoints

Download & Installation

Visit Releases to download the appropriate version.

System Requirements

Windows

macOS

Note: Since the author doesn't have an Apple Developer account, you may see an "unidentified developer" warning on first launch. Please close it, then go to "System Settings" -> "Privacy & Security" -> click "Open Anyway", and it will open normally afterwards.

Homebrew (macOS)

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

Update:

brew upgrade --cask cc-switch

Linux

CC Switch v3.12.1

Stability Fixes, StepFun Presets, OpenClaw authHeader, and New Sponsor Partners

中文版 → | 日本語版 →

Overview

CC Switch v3.12.1 is a patch release focused on stability improvements and bug fixes. It resolves a Common Config modal infinite reopen loop, a WebDAV sync foreign key constraint failure, and several i18n interpolation issues. It also adds StepFun provider presets, OpenClaw input type selection and authHeader support, upgrades the default Gemini model to 3.1-pro, and welcomes four new sponsor partners.

Release Date: 2026-03-12

Update Scale: 19 commits | 56 files changed | +1,429 / -396 lines

Highlights

• Common Config modal fix: Resolved an infinite reopen loop in the Common Config modal and added draft editing support
• WebDAV sync reliability: Fixed a foreign key constraint failure when restoring provider_health during WebDAV sync
• StepFun presets: Added StepFun (阶跃星辰) provider presets including the step-3.5-flash model
• OpenClaw enhancements: Added input type selection for model Advanced Options and authHeader field for vendor-specific auth header support
• Gemini model upgrade: Upgraded default Gemini model to 3.1-pro in provider presets
• New sponsors: Welcomed Micu API, XCodeAPI, SiliconFlow, and CTok as sponsor partners

New Features

StepFun Provider Presets

Added provider presets for StepFun (阶跃星辰), a leading Chinese AI model provider.

• New preset entries for StepFun across supported applications
• Includes the step-3.5-flash model (#1369, thanks @hengm3467)

OpenClaw Enhancements

Enhanced the OpenClaw configuration with more granular control and better vendor compatibility.

• Added input type selection dropdown for model Advanced Options (#1368, thanks @liuxxxu)
• Added optional authHeader boolean to OpenClawProviderConfig for vendor-specific auth header support (e.g. Longcat), and refactored form state to reuse the shared type

Sponsor Partners

• Micu API: Added Micu API as sponsor partner with affiliate links
• XCodeAPI: Added XCodeAPI as sponsor partner
• SiliconFlow: Added SiliconFlow (硅基流动) as sponsor partner with affiliate links
• CTok: Added CTok as sponsor partner

Changes

• UCloud → Compshare: Renamed UCloud provider to Compshare (优云智算) with full i18n support across all three locales (EN/ZH/JA)
• Compshare Links: Updated Compshare sponsor registration links to coding-plan page
• Gemini Model Upgrade: Upgraded default Gemini model from 2.5-pro to 3.1-pro in provider presets

Bug Fixes

Common Config & UI

• Fixed an infinite reopen loop in the Common Config modal and added draft editing support to prevent data loss during edits
• Fixed toolbar compact mode not triggering on Windows due to left-side overflow (#1375, thanks @zuoliangyu)
• Fixed session search index not syncing with query data, causing stale list display after session deletion

Sync & Data

• Fixed foreign key constraint failure when restoring provider_health table during WebDAV sync

Provider & Preset

• Added missing authHeader: true to Longcat provider preset (#1377, thanks @wavever)
• Aligned OpenClaw tool permission profiles with upstream schema (#1355, thanks @bigsongeth)
• Corrected X-Code API URL from www.x-code.cn to x-code.cc

i18n & Localization

• Fixed stream check toast i18n interpolation keys not matching translation placeholders
• Fixed proxy startup toast not interpolating address and port values (#1399, thanks @Mason-mengze)
• Renamed OpenCode API format label from "OpenAI" to "OpenAI Responses" for accuracy

Special Thanks

Thanks to all contributors for their contributions to this release!

@hengm3467 @liuxxxu @bigsongeth @zuoliangyu @wavever @Mason-mengze

Download & Installation

Visit Releases to download the appropriate version.

System Requirements

Windows

macOS

Note: Since the author doesn't have an Apple Developer account, you may see an "unidentified developer" warning on first launch. Please close it, then go to "System Settings" -> "Privacy & Security" -> click "Open Anyway", and it will open normally afterwards.

Homebrew (macOS)

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

Update:

brew upgrade --cask cc-switch

Linux

CC Switch v3.12.0

Stream Check Returns, OpenAI Responses API Arrives, and OpenClaw / WebDAV Get a Major Upgrade

中文版 → | 日本語版 →

Overview

CC Switch v3.12.0 is a feature release focused on provider compatibility, OpenClaw editing, Common Config usability, and sync/data reliability. It restores the Model Health Check (Stream Check) UI with improved stability, adds OpenAI Responses API format conversion, expands provider presets for Ucloud, Micu, X-Code API, Novita, and Bailian For Coding, and upgrades WebDAV sync with dual-layer versioning.

Release Date: 2026-03-09

Update Scale: 56 commits | 221 files changed | +20,582 / -8,026 lines

Highlights

• Stream Check returns: Restored the model health check UI, added first-run confirmation, and fixed openai_chat provider support
• OpenAI Responses API: Added api_format = "openai_responses" with bidirectional conversion and shared conversion cleanup — simply select the Responses API format when adding a provider and enable proxy takeover, and you can use GPT-series models in Claude Code!
• OpenClaw overhaul: Introduced JSON5 round-trip config editing, a config health banner, better agent model selection, and a User-Agent toggle
• Preset expansion: Added Ucloud, Micu, X-Code API, Novita, and Bailian For Coding updates, plus SiliconFlow partner badge and model-role badges
• Sync and maintenance improvements: Added WebDAV protocol v2 + db-v6 versioning, daily rollups, incremental auto-vacuum, and sync-aware backup
• Common Config usability improvements: After updating a Common Config Snippet, it is now automatically applied when switching providers — no more manual checkbox needed

Main Features

Model Health Check (Stream Check)

Restored the Stream Check panel for live provider validation, improving the reliability of provider management.

• Restored Stream Check UI panel with single and batch provider availability testing
• Added first-run confirmation dialog to prevent unsupported providers from showing misleading errors
• Fixed detection compatibility for openai_chat API format providers

OpenAI Responses API

Added native support for providers using the OpenAI Responses API with a new openai_responses API format.

• New api_format = "openai_responses" provider format option
• Bidirectional Anthropic Messages <-> OpenAI Responses API format conversion
• Consolidated shared conversion logic to reduce code duplication

Bedrock Request Optimizer

Added a PRE-SEND phase request optimizer for AWS Bedrock providers to improve compatibility and performance.

• PRE-SEND thinking + cache injection optimizer (#1301, thanks @keithyt06)

OpenClaw Config Enhancements

Comprehensive upgrade to the OpenClaw configuration editing experience with richer management capabilities.

• JSON5 round-trip write-back: preserves comments and formatting when editing configs
• EnvPanel JSON editing mode and tools.profile selection support
• New config validation warnings and config health status checks
• Improved agent model dropdown with recommended model fill from provider presets
• User-Agent toggle: optionally append OpenClaw identifier to requests (defaults to off)
• Legacy timeout configuration auto-migration

Provider Presets

New and expanded provider presets covering more providers and use cases.

• Ucloud: Added endpointCandidates and OpenClaw defaults, refreshed templateValues / suggestedDefaults
• Micu: Added preset defaults and OpenClaw recommended models
• X-Code API: Added Claude presets and endpointCandidates
• Novita: New provider preset (#1192, thanks @Alex-wuhu)
• Bailian For Coding: New provider preset (#1263, thanks @suki135246)
• SiliconFlow: Added partner badge
• Model Role Badges: Provider presets now support model-role badge display

WebDAV Sync Enhancements

WebDAV sync introduces dual-layer versioning for improved sync reliability and data safety.

• New WebDAV protocol v2 + db-v6 dual-layer versioning
• Confirmation dialog when toggling WebDAV auto-sync on/off to prevent accidental changes
• Sync-aware backup: uses a sync-specific backup variant that skips local-only table data

Usage & Data

Enhanced usage statistics and data maintenance capabilities for finer-grained data management, significantly reducing database growth rate.

• Daily rollups: aggregate usage data by day to reduce storage overhead
• Auto-vacuum: incremental database cleanup to maintain database health
• UsageFooter extra statistics fields (#1137, thanks @bugparty)

Other New Features

• Session Deletion: Per-provider session cleanup with path safety validation
• Claude Auth Field Selector: Restored authentication field selector
• Failover Toggle on Main Page: Moved the failover toggle to display independently on the main page with a first-use confirmation dialog
• Common Config Auto-Extract: On first run, automatically extracts common config snippets from live config files
• New Provider Page Improvements: Improved new provider page experience (#1155, thanks @wugeer)

Architecture Improvements

Common Config Runtime Overlay

Common Config Snippets are now applied as a runtime overlay instead of being materialized into stored provider configs.

Before: Common Config content was merged directly into each provider's settings_config on save or switch. This caused shared configuration to be duplicated across every provider entry, requiring manual sync when changes were needed.

After: Common Config is only injected as a runtime overlay when switching providers and writing to the live file — provider entries themselves no longer contain shared configuration. This means modifying Common Config takes effect immediately without updating each provider individually.

Common Config Auto-Extract

On first run, if no Common Config Snippet exists in the database, one is automatically extracted from the current live config. This ensures users upgrading from older versions do not lose their existing shared configuration settings.

Periodic Maintenance Timer Consolidation

Consolidated daily rollups and auto-vacuum into a unified periodic maintenance timer, eliminating resource contention and complexity from multiple independent timers.

Bug Fixes

Proxy & Streaming

• Fixed OpenAI ChatCompletion -> Anthropic Messages streaming conversion
• Added Codex /responses/compact route support (#1194, thanks @Tsukumi233)
• Improved TOML config merge logic to prevent key-value loss
• Improved proxy forwarder failure logs with additional diagnostic information

Provider & Preset Fixes

• Renamed X-Code to X-Code API for consistent branding
• Fixed SSSAiCode /v1 path issue
• Removed incorrect www prefix from AICoding URLs
• Fixed new provider page line-break deletion issue (#1155, thanks @wugeer)

Platform Fixes

• Fixed cache hit token statistics not being reported (#1244, thanks @a1398394385)
• Fixed minimize-to-tray causing auto exit after some time (#1245, thanks @YewFence)

i18n Fixes

• Added 69 missing translation keys and removed remaining hardcoded Chinese strings
• Fixed model test panel i18n issues
• Normalized JSON5 slash escaping to prevent i18n string parsing errors

UI Fixes

• Fixed Skills count display (#1295, thanks @fzzv)
• Removed HTTP status code display from endpoint speed test to reduce visual noise
• Fixed outline button styling (#1222, thanks @Sube-py)

Performance

• Skip unnecessary OpenClaw config writes when config is unchanged, reducing disk I/O

Documentation

• Restructured the user manual for i18n and added complete EN/JA coverage
• Added OpenClaw usage documentation and completed settings documentation
• Added UCloud sponsor information
• Reorganized the docs directory and synced README feature sections across EN/ZH/JA

Notes & Considerations

• Common Config now uses runtime overlay: Common Config Snippets are no longer materialized into each provider's stored config. They are dynamically applied at switch time. Modifying Common Config takes effect immediately without updating each provider.
• Stream Check requires first-use confirmation: A confirmation dialog appears when using the model health check for the first time. Testing proceeds only after confirmation.
• OpenClaw User-Agent toggle defaults to off: The User-Agent identifier must be manually enabled in the OpenClaw configuration.

Special Thanks

Thanks to all contributors for their contributions to this release!

@keithyt06 @bugparty @Alex-wuhu @suki135246 @Tsukumi233 @wugeer @fzzv @Sube-py @a1398394385 @YewFence

Download & Installation

Visit Releases to download the appropriate version.

System Requirements

Windows

macOS

Note: Since the author doesn't have an Apple Developer account, you may see an "unidentified developer" warning on first launch. Please close it, then go to "System Settings" -> "Privacy & Security" -> click "Open Anyway", and it will open normally afterwards.

Homebrew (macOS)

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

Update:

brew upgrade --cask cc-switch

Linux

CC Switch v3.11.1

Revert Partial Key-Field Merging, Restore Common Config Snippet & Bug Fixes

中文版 → | 日本語版 →

Overview

CC Switch v3.11.1 is a hotfix release that reverts the Partial Key-Field Merging architecture introduced in v3.11.0, restoring the proven "full config overwrite + Common Config Snippet" mechanism. It also includes several UI and platform compatibility fixes.

Release Date: 2026-02-28

Update Scale: 8 commits | 52 files changed | +3,948 / -1,411 lines

Highlights

• Restore Full Config Overwrite + Common Config Snippet: Reverted partial key-field merging due to critical data loss issues; restores full config snapshot write and Common Config Snippet UI
• Proxy Panel Improvements: Proxy toggle moved into panel body for better discoverability of takeover options
• Theme & Compact Mode Fixes: "Follow System" theme now auto-updates; compact mode exit works correctly
• Windows Compatibility: Disabled env check and one-click install to prevent protocol handler side effects

Reverted

Restore Full Config Overwrite + Common Config Snippet

Reverted the partial key-field merging refactoring introduced in v3.11.0 (revert 992dda5).

Why reverted: The partial key-field merging approach had three critical issues:

1. Data loss on switch: Non-whitelisted custom fields were silently dropped during provider switching
2. Permanent backfill stripping: Backfill permanently removed non-key fields from the database, causing irreversible data loss
3. Maintenance burden: The whitelist of "key fields" required constant maintenance as new config keys were added

What's restored:

• Full config snapshot write on provider switch (predictable, complete overwrite)
• Common Config Snippet UI and backend commands
• 6 frontend components/hooks (3 components + 3 hooks)

Migration:

• If you upgraded to v3.11.0 and your providers lost custom fields, re-import your config or manually re-add the missing fields
• Common Config Snippet is available again — use it to define shared config that should persist across provider switches

Changed

• Proxy Panel Layout: Moved proxy on/off toggle from accordion header into panel content area, placed directly above app takeover options. This ensures users see takeover configuration immediately after enabling the proxy, avoiding the common mistake of enabling the proxy without configuring takeover
• Manual Import for OpenCode/OpenClaw: Removed auto-import on startup; empty state now shows an "Import Current Config" button, consistent with Claude/Codex/Gemini behavior

Fixed

• "Follow System" Theme Not Auto-Updating: Delegated to Tauri's native theme tracking (set_window_theme(None)) so the WebView's prefers-color-scheme media query stays in sync with OS theme changes
• Compact Mode Cannot Exit: Restored flex-1 on toolbarRef so useAutoCompact's exit condition triggers correctly based on available width instead of content width
• Proxy Takeover Toast Shows {{app}}: Added missing app interpolation parameter to i18next t() calls for proxy takeover enabled/disabled messages
• Windows Protocol Handler Side Effects: Disabled environment check and one-click install on Windows to prevent unintended protocol handler registration

Notes & Considerations

• Common Config Snippet is back: If you relied on this feature in v3.10.x and earlier, it works the same way again. Define shared config that should persist across all provider switches.
• v3.11.0 Partial Key-Field Merging users: If you noticed missing config fields after switching providers in v3.11.0, re-import your config to restore them.

Download & Installation

Visit Releases to download the appropriate version.

System Requirements

Windows

macOS

Note: Since the author doesn't have an Apple Developer account, you may see an "unidentified developer" warning on first launch. Please close it, then go to "System Settings" → "Privacy & Security" → click "Open Anyway", and it will open normally afterwards.

Homebrew (macOS)

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

Update:

brew upgrade --cask cc-switch

Linux

CC Switch v3.11.0

OpenClaw Support, Session Manager, Backup Management & 50+ Improvements

中文版 → | 日本語版 →

Overview

CC Switch v3.11.0 is a major update that adds full management support for OpenClaw as the fifth application, introduces a new Session Manager and Backup Management feature. Additionally, Oh My OpenCode (OMO) integration, the partial key-field merging architecture upgrade for provider switching, settings page refactoring, and many other improvements make the overall experience more polished.

Release Date: 2026-02-26

Update Scale: 147 commits | 274 files changed | +32,179 / -5,467 lines

Highlights

• OpenClaw Support: Fifth managed application with 13 provider presets, Env/Tools/AgentsDefaults config editors, and Workspace file management
• Session Manager: Browse conversation history across all five apps with table-of-contents navigation and in-session search
• Backup Management: Independent backup panel with configurable policies, periodic backups, and pre-migration auto-backup
• Oh My OpenCode Integration: Full OMO config management with OMO Slim lightweight mode support
• Partial Key-Field Merging (⚠️ Breaking Change): Provider switching now only replaces provider-related fields, preserving all other settings; the "Common Config Snippet" feature has been removed
• Settings Page Refactoring: 5-tab layout with ~40% code reduction
• 6 New Provider Presets: AWS Bedrock, SSAI Code, CrazyRouter, AICoding, and more
• Thinking Budget Rectifier: Fine-grained thinking budget control
• Theme Switch Animation: Circular reveal transition animation
• WebDAV Auto Sync: Automatic sync with large file protection

Main Features

OpenClaw Support (New Fifth App)

Full management support for OpenClaw, the fifth managed application following Claude Code, Codex, Gemini CLI, and OpenCode.

• Provider Management: Add, edit, switch, and delete OpenClaw providers with 13 built-in presets
• Config Editors: Three dedicated panels for Env (environment variables), Tools, and AgentsDefaults
• Workspace Panel: HEARTBEAT/BOOTSTRAP/BOOT file management and daily memory
• Additive Overlay Mode: Support config overlay instead of overwrite
• Default Model Button: One-click to fill recommended models; auto-register suggested models to allowlist when adding providers
• Brand & Interaction: Dedicated brand icon, fade-in/fade-out transition animation when switching apps
• Deep Link Support: Import OpenClaw provider configurations via URL
• Full Internationalization: Complete Chinese/English/Japanese support

Session Manager

A brand-new session manager to browse and search conversation history.

• Browse conversation history across Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw (#867, thanks @TinsFox)
• Table-of-contents navigation and in-session search
• Auto-filter by current app when entering the session page
• Parallel directory scanning + head-tail JSONL reading for optimized loading performance

Backup Management

An independent backup management panel for better data safety.

• Configurable backup policy: maximum backup count and auto-cleanup rules
• Hourly automatic backup timer during runtime
• Auto-backup before database schema migrations with backfill warning
• Support backup rename and deletion (with confirmation dialog)
• Backup filenames use local time for better clarity

Oh My OpenCode (OMO) Integration

Full Oh My OpenCode config file management.

• Agent model selection, category configuration, and recommended model fill (#972, thanks @yovinchen)
• Improved agent model selection UX with lowercase key fix (#1004, thanks @yovinchen)
• OMO Slim lightweight mode support
• OMO ↔ OMO Slim mutual exclusion (enforced at database level)

Workspace

• Full-text search across daily memory files, sorted by date
• Clickable directory paths for quick file location access

Toolbar

• AppSwitcher auto-collapses to compact mode based on available width
• Smooth transition animation for compact mode toggle

Settings

• First-use confirmation dialogs for proxy and usage features to prevent accidental operations
• New enableLocalProxy switch to control proxy UI visibility on home page
• More granular local environment checks: CLI tool version detection (#870, thanks @kv-chiu), Volta path detection (#969, thanks @myjustify)

Provider Presets

• AWS Bedrock: Support for AKSK and API Key authentication modes (#1047, thanks @keithyt06)
• SSAI Code: Partner preset across all five apps
• CrazyRouter: Partner preset with dedicated icon
• AICoding: Partner preset with i18n promotion text
• Updated domestic model provider presets to latest versions
• Renamed Qwen Coder to Bailian (#965, thanks @zhu-jl18)

Other New Features

• Thinking Budget Rectifier: Fine-grained thinking budget allocation control (#1005, thanks @yovinchen)
• WebDAV Auto Sync: Automatic sync with large file protection (#923, thanks @clx20000410; #1043, thanks @SaladDay)
• Theme Switch Animation: Circular reveal transition for a smoother visual experience (#905, thanks @funnytime75)
• Claude Config Editor Quick Toggles: Quick toggle switches for common settings (#1012, thanks @JIA-ss)
• Dynamic Endpoint Hint: Context-aware hint text based on API format selection (#860, thanks @zhu-jl18)
• Usage Dashboard Enhancement: Auto-refresh control and robust formatting (#942, thanks @yovinchen)
• New Pricing Data: claude-opus-4-6 and gpt-5.3-codex (#943, thanks @yovinchen)
• Silent Startup Optimization: Silent startup option only shown when launch-on-startup is enabled

Architecture Improvements

Partial Key-Field Merging (⚠️ Breaking Change)

Provider switching now uses partial key-field merging instead of full config overwrite (#1098).

Before: Switching providers overwrote the entire settings_config to the live config file. This meant that any non-provider settings the user manually added to the live file (plugins, MCP config, permissions, etc.) would be lost on every switch. To work around this, previous versions offered a "Common Config Snippet" feature that let users define shared config to be merged on every switch.

After: Switching providers now only replaces provider-related key-values (API keys, endpoints, models, etc.), leaving all other settings intact. The "Common Config Snippet" feature is therefore no longer needed and has been removed.

Impact & Migration:

• If you didn't use Common Config Snippets, this change is fully transparent — switching just works better now
• If you used Common Config Snippets to preserve custom settings (MCP config, permissions, etc.), those settings are now automatically preserved during switches — no action needed
• If you used Common Config Snippets for other purposes (e.g., injecting extra config on every switch), please manually add those settings to your live config file after upgrading

This refactoring removed 6 frontend files (3 components + 3 hooks) and ~150 lines of backend dead code.

Manual Import Replaces Auto-Import

Startup no longer auto-imports external configurations. Users now click "Import Current Config" manually, preventing accidental data overwrites.

OmoVariant Parameterization

Eliminated ~250 lines of duplicated code in the OMO module via OmoVariant struct parameterization.

OMO Common Config Removal

Removed the two-layer merge system, reducing ~1,733 lines of code and simplifying the architecture.

ProviderForm Decomposition

Reduced ProviderForm component from 2,227 lines to 1,526 lines by extracting 5 independent modules (opencodeFormUtils, useOmoModelSource, useOpencodeFormState, useOmoDraftState, useOpenclawFormState), significantly improving maintainability.

Shared MCP/Skills Components

Extracted AppCountBar, AppToggleGroup, and ListItemRow shared components to reduce duplication across MCP and Skills panels (#897, thanks @PeanutSplash).

Settings Page Refactoring

Refactored settings page to a 5-tab layout (General | Proxy | Advanced | Usage | About), reducing SettingsPage code from ~716 to ~426 lines.

Other Improvements

• Unified terminal selection via global settings with WezTerm support added
• Updated Claude model references from 4.5 to 4.6

Bug Fixes

Critical Fixes

• Windows Home Dir Regression: Restored default home directory resolution to prevent providers/settings "disappearing" when HOME env var differs from the real user profile directory in Git/MSYS environments
• Linux White Screen: Disabled WebKitGTK hardware acceleration on AMD GPUs (Cezanne/Radeon Vega) to prevent blank screen on startup (#986, thanks @ThendCN)
• OpenAI Beta Parameter: Stopped appending ?beta=true to /v1/chat/completions endpoints, fixing request failures for Nvidia and other apiFormat="openai_chat" providers (#1052, thanks @jnorthrup)
• Health Check Auth: Health check now respects provider's auth_mode setting, preventing failures for proxy services that only support Bearer authentication (#824, thanks @Jassy930)

Provider Preset Fixes

• Fixed OpenClaw /v1 prefix causing double path (/v1/v1/messages)
• Corrected Opus pricing ($15/$75 → $5/$25) and upgraded to 4.6
• Unified AIGoCode URL to https://api.aigocode.com across all apps
• Removed outdated partner status from Zhipu GLM presets
• Restored API Key input visibility when creating new Claude providers
• Hide quick toggles for non-active providers, show context-aware JSON editor hints

OMO Fixes

• Added missing omo-slim category checks across add/form/mutation paths
• Fixed OMO Slim query cache invalidation after provider mutations
• Synced OMO agent/category recommended models with upstream sources
• Added toast feedback for "Fill Recommended" button silent failures
• Removed last-provider deletion restriction for OMO/OMO Slim
• Reject saving OpenCode providers without configured models (#932, thanks @yovinchen)

OpenClaw Fixes

• Fixed 25 missing i18n keys, replaced key={index} with stable IDs, added deep link additive merge, and other code review issues
• Enhanced EnvPanel robustness (NaN guards, entry key names instead of array indices)
• Merged duplicate i18n keys to restore provider form translations

Platform Fixes

• Windows silent startup window flicker (#901, thanks @funnytime75)
• Title bar dark mode theme following (#903, thanks @funnytime75)
• Windows Skills path separator matching (#868, thanks @stmoonar)
• WSL helper functions conditional compilation

UI Fixes

• Toolbar height clipping causing AppSwitcher to be obscured
• Show update badge instead of green checkmark when newer version available
• Session Manager button only visible for Claude/Codex apps
• Unified SQL import/export card dark mode styling (#1067, thanks @SaladDay)

Other Fixes

• Replaced hardcoded Chinese strings in Session Manager with i18n keys
• Fixed Skill documentation URL branch and path resolution (#977, thanks @yovinchen)
• Added missing OpenCode install.sh installation path detection (#988, thanks @zhu-jl18)
• Fixed Skill ZIP symlink resolution (#1040, thanks @yovinchen)
• Added missing OpenCode checkbox in MCP add/edit form (#1026, thanks @yovinchen)
• Removed auto-import side effect from useProvidersQuery queryFn

Performance

• Parallel directory scanning + head-tail JSONL reading for session panel, significantly improving session list loading speed
• Removed unnecessary TanStack Query cache overhead for Tauri local IPC calls

Documentation

• Sponsor updates: SSSAiCode, Crazyrouter, AICoding, Right Code, MiniMax
• Added user manual documentation (#979, thanks @yovinchen)

Notes & Considerations

• OpenClaw is a newly supported app: OpenClaw CLI must be installed first to use related features.
• ⚠️ Common Config Snippet feature has been removed: Since provider switching now uses partial key-field merging (only replacing API keys, endpoints, models, etc.), user's other settings are automatically preserved, making Common Config Snippets unnecessary. See the "Architecture Improvements" section above for migration details.
• Auto-import changed to manual: External configurations are no longer auto-imported on startup. Click "Import Current Config" manually when needed.
• OMO and OMO Slim are mutually exclusive: Only one can be active at a time. Switching to one automatically disables the other.
• Backup is enabled by default: Automatic hourly backup during runtime. Adjust the policy in the Backup panel.

Special Thanks

Thanks to all contributors for their contributions to this release!

@TinsFox @keithyt06 @kv-chiu @SaladDay @jnorthrup @JIA-ss @clx20000410 @ThendCN @yovinchen @zhu-jl18 @myjustify @funnytime75 @PeanutSplash @Jassy930 @stmoonar

Download & Installation

Visit Releases to download the appropriate version.

System Requirements

Windows

macOS

Note: Since the author doesn't have an Apple Developer account, you may see an "unidentified developer" warning on first launch. Please close it, then go to "System Settings" → "Privacy & Security" → click "Open Anyway", and it will open normally afterwards.

Homebrew (macOS)

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

Update:

brew upgrade --cask cc-switch

Linux