docs/release-notes/v3.17.0-en.md
This release brings a long-awaited capability: one-click "Projects" switching — save your current provider, MCP, Skills, and memory files as a single named snapshot, swap the whole set for another one from the title bar or tray with a single click, and have the state of the project you're leaving automatically saved back on the way out. The Codex side gets plenty too: your official ChatGPT subscription account can now route through the local proxy as well, getting the same routing and usage statistics as third-party providers; the GPT-5.6 family's context window and Sol / Terra / Luna three-tier pricing land in one step; and a native Anthropic Messages upstream format is added — is Claude Code banned at your company but the Claude API isn't? You can now use Claude-family models directly inside Codex. On top of that comes a big wave of correctness fixes: upstream failures no longer turn into "empty replies", cache-write tokens are no longer double-billed, deleted MCP servers no longer come back from the dead, and Kimi For Coding's 256K window finally takes effect for real.
The new capabilities in this release land mainly in the project switcher at the top of the home page, the Codex provider form, and the usage dashboard. The following docs are worth reading alongside it:
Kimi / Kimi For Coding presets together with local routing to handle the protocol conversion.[!WARNING]
Only Official Channels (Please Read)
CC Switch is a fully free and open-source desktop app, and we do not charge users any fees. Please only obtain the software through the official channels listed below:
Channel Only Official Website ccswitch.io Source github.com/farion1231/cc-switch Downloads GitHub Releases Author @farion1231 Report an Imposter GitHub Issues Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake. If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues.
CC Switch v3.17.0 is a major feature release following v3.16.5, centered on Projects: you can save the current provider, MCP, Skills, and memory-file state of Claude Code / Claude Desktop / Codex as a named snapshot — say a "Development" set for a coding directory and a "Drawing" set for a writing-and-drawing directory — and swap the whole set with one click from the switcher at the top of the home page or the "Projects" tray submenu. Before you switch, the state of the project you're about to leave is automatically saved back, so a project always holds exactly what you last left it as. The second main thread is Codex: your official ChatGPT subscription account can now be taken over by the local proxy route (no API key needed — Codex's own login credentials are passed through verbatim and your official login is never overwritten); paired with a corrected client identity, the latest subscription models like gpt-5.6-luna no longer falsely 404; GPT-5.6's 372K context-window injection, Sol / Terra / Luna three-tier pricing (including the 1.25× cache-write rate), and preset default models all land together; and the Codex upstream format gains a native Anthropic Messages protocol — which targets a very real scenario: plenty of companies ban the Claude Code client but do not ban the Claude API, and those users can now point Codex directly at the Claude API (or any gateway that only offers /v1/messages) and keep using Claude-family models inside Codex.
For everyday-use correctness, this release makes three concentrated waves of fixes. Proxy bridge: semantic failures returned inside a 2xx are no longer turned into an empty reply but trigger failover instead; reasoning content, tool results, and the system role round-trip losslessly across the Responses↔Anthropic bridge; prompt-cache breakpoint injection is more thorough, so long conversations no longer resend everything at full price each turn. Usage billing: cache-write tokens were previously billed twice — once at the input rate and once at the cache-creation rate — and are now corrected (the database is upgraded to schema v13 so historical data stays consistent); usage and quota queries automatically retry on transient network failures and no longer cache a failure body as real data. Codex config.toml: MCP servers you deleted in the app no longer come back on provider switch; when parsing a live file fails, sync errors out rather than blanking the whole file; and the "Apply Common Config" merge is moved to the backend so comments and key order are no longer scrambled. Also included: Kimi For Coding's 256K window finally taking effect, Codex subagent and free-tier quota accounting filled in, Zhipu team-plan quota queries, OpenCode form enhancements, and a batch of preset updates.
Release date: 2026-07-13
Stats: 69 commits | 172 files changed | +21,067 / -2,464 lines
gpt-5.6-luna no longer falsely 404s.anthropic, you can connect directly to the Claude API or any gateway that only offers /v1/messages, with the local proxy handling the two-way Responses↔Anthropic conversion and standard 5-minute prompt-cache injection built in.This is the headline feature of the release. You can save your current provider, MCP, Skills, and memory-file state as a named "project", then swap the whole set with one click from the project switcher at the top of the home page or the "Projects" tray submenu, instead of toggling each piece by hand.
Here's a typical scenario: you have one directory for coding and another for writing or drawing. Coding wants one provider, plus MCP like filesystem / GitHub, code-review Skills, and a memory file spelling out your engineering conventions; writing or drawing often wants a different provider, a different set of MCP, and completely different prompts. Bouncing between the two used to mean switching providers, toggling MCP and Skills one by one, and then editing the memory file; now you save the two states as two projects — "Development" and "Drawing" — and when you switch directories to work, one click in CC Switch puts the whole configuration in place.
Projects span three scopes — Claude Code, Claude Desktop, and Codex (the only dimension CC Switch manages for Claude Desktop is the provider, so its snapshots contain only the provider and applying one touches no other dimension).
A few design points worth knowing:
If you don't use Projects, you can turn off "Show project switcher" under Settings → Home Display, which only hides the home-page entry — the tray submenu and project data are unaffected. It's backed by a new profiles table (the database migrates automatically, no manual steps), with UI copy in sync across all four locales.
A Codex session using a ChatGPT subscription (OAuth or API-key login) can now route through CC Switch's local proxy too — official-account traffic gets routing, format conversion, and usage statistics identical to third-party providers. Just pick the built-in "OpenAI Official" entry in the provider panel or tray to take it over (if you deleted it before, it's restored automatically when you add a provider); the card badge shows "Official account routing" while routing.
The implementation deliberately achieves zero credential storage: instead of writing any placeholder key to auth.json, it projects a dedicated model_provider pointing at the local proxy into config.toml, and Codex sends its own ChatGPT authorization header to the proxy, which passes it through verbatim to the official endpoint — the credentials on the codex-official line are always empty. The official login itself is never overwritten: on takeover, OAuth / API-key material is preserved into the backup, and a 401 / 403 from the official side is treated as a non-retryable error, so failover never quietly moves your conversation to another account. Accordingly, the copy for the "Preserve Codex official login on switch" setting has been updated — under route takeover the official login is always preserved, so that toggle now only governs third-party direct switches that don't route through the proxy.
Three things were done around the GPT-5.6 family:
CLAUDE_CODE_MAX_CONTEXT_TOKENS and CLAUDE_CODE_AUTO_COMPACT_WINDOW (both 372000) are auto-injected into the live settings.json, so Claude Code no longer auto-compacts prematurely at its default 200K window nor overflows the upstream. The injection is strictly gated: it only injects when every configured model key points at the gpt-5.6 family (gpt-5.5's catalog window swings between 272K and 372K, so it's deliberately not inherited); your manually set values always win; and it's stripped on switch-away under mirrored conditions, so a program default is never baked into your provider config.gpt-5.6-luna, main model / sonnet / opus → gpt-5.6), and the custom Codex config.toml template's default model follows suit.gpt-5.6 and its per-effort suffix variants align to the Sol rate.This feature comes from a very real need: plenty of companies ban the Claude Code client for compliance reasons, but do not ban the Claude API. For those users the model itself is available; what's missing is a permitted client — and Codex can now fill that slot. Pick the new anthropic option in a Codex provider's upstream-format selector, and you can connect directly to the Claude API or any gateway offering the native Anthropic Messages protocol (/v1/messages); the local proxy handles the two-way conversion of requests, responses, and streaming between Responses and Anthropic, and you chat and use tools inside Codex as usual while Claude-family models run behind the scenes. The form provides the supporting pieces: an auth-field selector (ANTHROPIC_AUTH_TOKEN sends Authorization: Bearer, the default; or ANTHROPIC_API_KEY sends x-api-key), an optional Claude Code client-impersonation toggle (off by default), and a per-provider max-output-token override (Codex doesn't send model_max_output_tokens, and when unset it falls back to a conservative 8192, which may truncate long or heavy-reasoning replies). The conversion bridge auto-injects standard 5-minute prompt-cache markers (system prompt, tools, and history go through the cache instead of being resent at full price each turn), supports the [1m] long-context marker with the corresponding beta header, and reports a truncated stream faithfully as incomplete rather than disguising it as success. (#5071)
The top-level model key in config.toml is now an editable field in the form: when a new model (e.g. gpt-5.6) ships, you can point an existing provider at it directly without waiting for a preset update (presets only affect newly added providers). The field is two-way synced with the TOML editor, its candidate list is the union of the model-mapping catalog and the provider's /models endpoint, and when a value isn't in the catalog it offers a one-click "Add to mapping". An explicitly entered value always wins over the implicit backfill from the mapping's first row; model names and base_url are TOML-escaped on write, eliminating any chance that remote data from /models injects a forged config line.
The "on switch-away, write shared preferences from the live config back to the common config" behavior v3.16.5 added for Claude now covers Codex: when you switch away from a Codex provider that has the common config enabled, the shareable portion is first re-extracted from its live config.toml to update the common config and then carried to the next provider — the preferences you edited directly in the running Codex config are no longer lost on switch, and deleted keys aren't quietly re-injected. The extractor strictly strips provider-specific and injected content (model / model_provider / base_url / wire_api, the entire [model_providers] table, the MCP projection, the API-key fallback field, the model-catalog pointer, and the injected web_search sentinel), so secrets never enter the shared snippet. All failures only warn and never block the switch.
The Claude provider form gains a "subagent" model row that writes CLAUDE_CODE_SUBAGENT_MODEL, letting subagents spawned by Claude Code run on a model you specify (usually a cheaper or faster one). It supports the [1M] marker; since the subagent model never appears in the /model menu, the row shows a "not shown in /model" placeholder with no display-name field. The proxy takeover path and the model mapper support it too: when the request model matches the configured subagent model it's passed through as-is instead of being folded to the default model; the key is also excluded from the shared common config so it doesn't leak across providers. (#4830)
The Claude form's fallback model field (ANTHROPIC_MODEL) now carries the same 1M checkbox that the Sonnet / Opus / Fable tiers have long had: when the fallback model is backed by a 1M window you can declare it faithfully, instead of it being silently treated as 200K. Checking it appends the [1M] marker to the model id, unchecking strips it. (#5124, fixes #3679)
Zhipu's team plan (team-edition Coding Plan) uses the same quota endpoint but requires ?type=2 and two extra request headers (bigmodel-organization / bigmodel-project), which the personal-edition query can't reach. The usage-script dialog gains a "Zhipu GLM Team" template; fill in the API key + organization ID + project ID to query team quota, and if any of the three is missing you get a clear prompt to complete it. Copy is in sync across all four locales. (#5128)
The OpenCode provider form fills in two pieces of config that previously required hand-editing JSON: a Headers editor (provider-level options.headers, such as the HTTP-Referer / X-Title that OpenRouter's leaderboard wants, with add/remove rows and case-insensitive deduplication) and per-model token limits (model.limit.context / model.limit.output numeric inputs, cleared to remove). The "extra options" block becomes a collapsible section that auto-expands when it has content; along the way, a fix stops the old placeholder filter from wrongly deleting genuine option keys that start with option-. (#2907)
Seeded pricing for Tencent Hunyuan Hy3 (256K context), released 2026-07-06 (converted from the launch-day list price of CNY 1 / 4 / 0.25 per million tokens); both the hunyuan-hy3 and hy3 ids now hit, so their usage no longer shows $0. Note that Hy3 is actually tiered by input length, and the current price table is seeded at the lowest tier, so long-context requests will underestimate cost — to be corrected once the official billing page is clear.
When Codex routes through the local proxy and converts to a Chat Completions upstream, it now injects prompt_cache_key in a provider-aware way: auto-enabled for Kimi Coding and the OpenAI official endpoint, explicitly on for the Kimi preset, and left off for unknown OpenAI-compatible gateways to avoid a 400 from strict-schema gateways. The key value only ever takes an explicit client value or a real client session ID, and never generates a random UUID (which would drop every request into a different cache bucket, defeating the purpose). Advanced options offer an auto / enabled / disabled tri-state override.
The generated Codex model catalog now only declares input_modalities = ["text"] for models on CC Switch's confirmed exact text-only roster; GPT, aliases, new suffix variants, and any unknown model all fail open to ["text", "image"] — fixing GPT-family models being falsely reported as "images not supported" in the Codex IDE extension. The rectifier's "text-only model precheck" toggle continues to govern only the proxy-side active request rewriting, not the catalog declaration; catalog reverse-import also collapses the inferable capability away, so a future roster correction or a model upgrading to multimodal takes effect automatically.
The Codex (ChatGPT / GPT-5.6) and Kimi For Coding presets no longer show the "Max Context Tokens" and "Auto-Compact Window" inputs in the form; the values are pinned directly in the preset env (Codex 372000 / 372000, Kimi For Coding 262144 / 262144) — the vast majority of users never need to touch these two numbers. The two keys are kept in env on purpose: pinning them explicitly makes the local compaction trigger point immune to a remote experimental config dialing it down. The rare users who do want to change the numbers can still edit both keys directly in the provider's JSON editor.
Removed the obsolete per-provider testConfig overrides (timeout, retry count, degradation delay threshold): the lightweight base_url probe now always uses the global connectivity-check config, while automatic failover remains fully driven by the proxy's separate timeout and circuit-breaker settings. The settings UI and interface naming also migrate from "model test" terminology to "connectivity check".
After adding a universal (multi-app) provider through the "Add Provider" dialog, it's now immediately pushed to each live target config, no longer requiring a manual sync afterward. A sync failure doesn't block the add — the provider is saved, with a non-blocking warning shown if the sync fails. (#2811)
LongCat-Flash-Chat / LongCat-2.0-Preview to LongCat-2.0, declaring the real 1M (1048576) context window. LongCat-2.0 is a text-only model, and the proxy's media-scrub whitelist is updated in sync — images pasted into a conversation are replaced with an unsupported marker rather than hard-rejected upstream. (#4838)sudocode.us preset is replaced in place by the new sponsor SudoCode at sudocode.chat, covering six clients (the Claude family connects directly to Anthropic passthrough; Codex / OpenCode / OpenClaw / Hermes default to gpt-5.6-sol).websiteUrl to product homepages, restoring the attribution-parameter campaign / invite links (this is by design).OpenAI Compatible custom-template entry was removed from the OpenCode and OpenClaw preset lists — the built-in custom provider flow already offers the same starting point, so the selector no longer shows two entries pointing at the same place. Existing providers are unaffected.When routing through local proxy takeover with an official Codex OAuth account, the latest subscription models (e.g. gpt-5.6-luna) previously returned a misleading 404 Model not found — even though the account had access. The root cause is that ChatGPT's Codex backend does model-group routing by the originator + version headers, and cc-switch previously self-reported originator: cc-switch with no version, which routed it to a group where luna wasn't yet deployed. Takeover requests now send the same originator: codex_cli_rs + version: 0.144.1 as the real Codex CLI, satisfying luna's minimum client-version requirement — confirmed fixed by A/B testing against the real backend.
When the proxy bridges an Anthropic-format client (Claude Code / Claude Desktop) to an OpenAI Responses upstream, a semantic failure hidden inside an HTTP 2xx body (a status:"failed" object, an error envelope, or a response.failed SSE event before the first output) was previously converted into a silent empty turn. These failures are now recognized as real errors inside the retry loop, so failover can retry with a different provider; a stream that ends cleanly but with incomplete content is faithfully marked truncated rather than complete; a gateway that ignores stream:true and returns the whole JSON document is recognized and expanded into a full streaming lifecycle; and when the client history itself is malformed, it errors immediately instead of retrying a guaranteed-to-fail request against every provider.
Content crossing the Responses↔Anthropic bridge in multi-turn tool loops is no longer lost or corrupted: encrypted reasoning entries round-trip losslessly (also eliminating the problem where a failed round-trip got the next request rejected upstream); the streaming converter supports the official reasoning event vocabulary and recovers tool arguments from the terminal event when a gateway skips the deltas; a structured tool result's is_error flag, images, and PDF documents are fully preserved in both directions instead of being flattened into a single JSON string; and system / developer messages in history are correctly promoted to Anthropic system instead of being silently demoted to user turns. On billing, when the upstream request succeeds but the subsequent conversion fails, usage is still recorded rather than dropped.
The input_tokens reported by Codex / Gemini-style providers include both cache reads and cache writes, but the cost calculation previously only subtracted cache reads — so cache-write tokens were billed twice, once at the input rate and once at the cache-creation rate. Both are now deducted first, and the cache-write number is no longer lost across format conversions (Chat↔Responses↔Anthropic). To keep historical data consistent, the database adds a column recording the storage semantics of each row's input_tokens (schema v12→v13 auto-migration): old rows are recomputed under the old semantics, new rows under the new, and Claude-style rows are unaffected.
On the proxy paths that inject Anthropic cache_control breakpoints (the Codex takeover bridge and the Bedrock native optimizer), the injector now uses the four-breakpoint budget more thoroughly: beyond the tail of tools, the tail of the system prompt, and the latest cacheable message, when budget remains it also anchors an earlier user message, keeping the stable prefix within Anthropic's 20-block lookback window — so long, tool-heavy conversations keep hitting the prompt cache instead of resending the system prompt, tools, and history at full price each turn. Caller-supplied breakpoints are preserved as-is (never removed, reordered, or rewritten); injected markers all use the standard 5-minute TTL.
The CLAUDE_CODE_AUTO_COMPACT_WINDOW=262144 added to the Kimi For Coding preset in 3.16.4 in fact never took effect: Claude Code caps unrecognized model ids at a 200K window and takes the compaction window as min(model window, configured value), so 262144 got clamped back to 200K. This release fills in the two missing pieces — the preset now also pins CLAUDE_CODE_MAX_CONTEXT_TOKENS, and it explicitly routes each tier's model to the endpoint's kimi-for-coding alias (a claude- prefixed id makes Claude Code ignore both window parameters; a non-Claude alias is the key to unlocking the large window). Saved providers also get these two window defaults auto-injected on switch, but the alias routing only lives in the preset — a provider saved from the old preset is still effectively 200K and needs a one-time re-apply of the preset (see "Upgrade Notes").
The authoritative MCP-server data lives in the database, and the [mcp_servers] in the Codex live config.toml is only a projection re-synced after every write — but on switch-away this projection was baked into the provider snapshot, so a server you deleted in the app came back to life the next time you activated that provider, and per-entry reconciliation could never clear the orphan. On switch-away, [mcp_servers] (including the legacy [mcp.servers]) is now stripped from the stored snapshot, and an already-polluted snapshot self-heals on its next switch-away. One visible side effect: a hand-written [mcp_servers.*] section in a Codex provider config is stripped out of the snapshot on its first switch-away — from now on, define Codex's MCP servers through the MCP manager (see "Upgrade Notes").
Two fixes. First, when writing a single MCP server to Codex, if the existing config.toml fails to parse, the old logic fell back to an empty document and wrote the whole thing back — the entire file was blanked down to that one MCP entry; it now returns a validation error and leaves the file untouched. Second, "Import from App" previously swallowed each importer's error as 0, so a broken Codex config would only show "imported 0 servers"; it now imports best-effort per app and, on failure, reports exactly which app failed. The projection on switch and save is also scoped to the target app only, so one app's live-file parse failure no longer blocks the others by association, nor falsely reports an already-successful switch as a failure.
Checking / unchecking "Apply Common Config" in the Codex provider form previously went through a front-end TOML implementation that reformatted the whole file (parse → merge → serialize): comments were dropped, keys were reordered, and empty table headers like [model_providers] appeared out of nowhere — the culprit behind "config.toml keeps getting reordered". The merge now goes through a backend command sharing the same merge semantics as writing the live config, so hand-written formatting fully survives the mid-edit merge; a double guard (operation sequence number + config baseline check) was also added for the fast-switch race introduced by going async, so an earlier-issued-but-later-arriving stale result doesn't overwrite newer state.
When switching from a third-party endpoint to a Codex-managed provider, ~/.claude/settings.json had both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN placeholders written, causing Claude Code to warn "Both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY set" on every launch. It now injects only one: Codex-managed uses ANTHROPIC_AUTH_TOKEN, Copilot uses ANTHROPIC_API_KEY, and any other token key is cleared. Note: after upgrading, if the live config already carries both keys, the "skip rewrite if config unchanged" short-circuit means the warning may persist — toggle the Claude route off and on once (or switch providers once) to trigger a rewrite (see "Upgrade Notes"). (#5095, fixes #4919)
Usage and quota queries frequently showed a "query failed" that a manual refresh couldn't clear, because all transport-layer failures (including a mid-read timeout while reading the response body) were folded into "succeeded, but the result is a failure" — so the front-end's auto-retry never fired, and the failure body was cached as real data. Transport failures now return an error faithfully: react-query's auto-retry kicks in, HTTP 429 is treated as transient like 5xx, retained last-good data expires normally on a 10-minute window, and the footer keeps a retry entry and the real error message in the failure state. (fixes #3820)
The token usage of Codex subagent (spawned agent) sessions previously never made it into local statistics: subagent logs carry the parent thread's session_id, so multiple subagents' records collided and were discarded as duplicates. The parser now builds a unique identity from each file's own thread_id, and recognizes the replay of the parent thread's history at the start of a subagent log — using it only to recover the cumulative baseline, not to double-bill; archived logs also inherit the sync cursor by filename, so re-parsing only imports the new portion. (#5187)
Codex free accounts are metered on a rolling 30-day window (rather than the paid tier's weekly window), but the front-end whitelist and tray grouping didn't recognize the 30_day tier — with a free account's only tier filtered out, the quota footer went entirely blank and the tray showed no quota at all. The 30-day tier now renders correctly in both the footer and the tray, with labels in sync across all four locales. (#4886, fixes #3651)
The usage dashboard's auto-refresh interval was previously component-local state that reset to 30 seconds on every restart. It's now persisted via a new app setting, with changes applied optimistically and rolled back automatically on save failure. (#5057)
Fable is the fourth Claude model-mapping tier added in v3.16.3, but its two keys ANTHROPIC_DEFAULT_FABLE_MODEL(_NAME) were left off the provider-specific exclusion list — so one provider's Fable model pin could leak into the shared common config and then be injected into other providers. It's now stripped like the haiku / sonnet / opus tiers, and Fable-tier proxy takeover support was filled in along the way (writing a stable role alias on takeover, cleaning up stale values on switch-away). (#5206, fixes #4272)
Two provider-side fixes: when a client-sent tool's input_schema lacks a top-level type (or is an empty {}), the proxy conversion would be rejected by a strict gateway; the root schema now auto-fills type: "object" (only the root, leaving nested subschemas untouched); and the issue where an uncategorized provider imported from history or hand-built showed no Claude API Key input on edit is fixed — the field now shows for any provider that isn't an official / cloud-vendor category. (#5069)
When the local proxy takes over Volcengine Coding Plan running GLM 5.2, image blocks in a request no longer produce an unrecoverable 400: the text-only roster exactly includes glm-5.2 (deliberately not prefix-matching, so a future multimodal glm-5.2v isn't caught), and the preventive path strips images before the request goes out; the gateway's error message that doesn't contain the word image (Model only support text input) is also recognized by the reactive path's self-identifying-phrase roster, triggering the media fallback. (fixes #5025)
opencode session resume <id> to the current CLI's opencode -s <id>. (#2359)chatgpt.com/backend-api/codex bare); batch checks skip it, and an individual resolve reports a clear error.A new step-by-step guide (in Chinese / English / Japanese, with UI screenshots) explaining how to use Kimi inside Codex CLI via CC Switch's local routing: newer Codex CLI speaks the OpenAI Responses protocol, while the Kimi Open Platform (pay-as-you-go, kimi-k2.7-code) and Kimi For Coding (membership, kimi-for-coding) both expose Chat Completions endpoints, so a direct connection usually 404s on /responses. The guide covers the whole flow from adding a provider from the built-in preset to the four-step protocol-conversion chain.
The open-source AI infrastructure project new-api joins the sponsor table in the four-language READMEs.
If you're using a provider created from the Kimi For Coding preset, please re-pick it from the preset and save once: the key to the 256K window — routing each tier's model to the kimi-for-coding alias — only lives in the new preset, so a provider saved from the old preset still compacts prematurely at 200K even after upgrading.
[mcp_servers.*] Will Be Stripped from the SnapshotTo root out "deleted MCP servers coming back", switching away from a Codex provider strips the [mcp_servers] section from the stored snapshot. If you have an MCP server hand-written directly in a Codex provider config, it will disappear from the snapshot on the first switch-away from that provider — please instead define Codex's MCP servers through the MCP manager (MCP tab), where the entries are authoritative and get projected into the live config automatically.
If Claude Code still warns "Both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY set" after upgrading, it's because the takeover logic short-circuits and skips the rewrite when the live config is unchanged. Toggle Claude's route off and on once (or switch providers once) to write the corrected single-placeholder config, and the warning goes away.
On the first launch of v3.17.0, the database automatically migrates from schema v11 to v13 (adding the projects table and the usage-semantics column), with no manual steps. If you're in the habit of rolling back to an older version, back up ~/.cc-switch/cc-switch.db first.
This release continues the risk notices from previous versions for reverse-proxy-style features.
Codex OAuth reverse proxy: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the v3.13.0 release notes for details. The "official ChatGPT account proxy route takeover" added in this release is the same class of usage, so please be aware of the same risk.
Codex third-party provider Chat routing: when CC Switch local proxy converts and forwards Codex requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
Claude Desktop third-party provider proxy switching: when CC Switch's built-in proxy gateway forwards Claude Desktop requests to third-party providers, you must also follow the target provider's billing, compliance, and data-retention terms.
By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
Thanks to the following contributors for the features and fixes in v3.17.0:
Thanks also to everyone who reported Codex official routing, cache billing, MCP sync, and quota query issues — a good portion of this release's fixes came directly from reproduction clues in these real-world scenarios.
Visit Releases and download the build for your system.
| System | Minimum Version | Architecture |
|---|---|---|
| Windows | Windows 10 and later | x64 / ARM64 |
| macOS | macOS 12 (Monterey)+ | Intel (x64) / Apple Silicon (arm64) |
| Linux | See table below | x64 / ARM64 |
| File | Description |
|---|---|
CC-Switch-v3.17.0-Windows.msi | Recommended - MSI installer with auto-update |
CC-Switch-v3.17.0-Windows-Portable.zip | Portable build, unzip and run |
Windows ARM64 devices should pick the artifact whose file name carries the arm64 tag.
| File | Description |
|---|---|
CC-Switch-v3.17.0-macOS.dmg | Recommended - DMG installer, drag to Applications |
CC-Switch-v3.17.0-macOS.zip | Unzip and drag to Applications, Universal Binary |
CC-Switch-v3.17.0-macOS.tar.gz | For Homebrew install and auto-update |
Homebrew install:
brew install --cask cc-switch
Upgrade:
brew upgrade --cask cc-switch
Linux assets are available for both x86_64 and ARM64 (aarch64). Choose the file whose architecture tag matches your machine's uname -m output:
CC-Switch-v3.17.0-Linux-x86_64.AppImage / .deb / .rpmCC-Switch-v3.17.0-Linux-arm64.AppImage / .deb / .rpm| Distribution | Recommended Format | Install Command |
|---|---|---|
| Ubuntu / Debian / Linux Mint / Pop!_OS | .deb | sudo dpkg -i CC-Switch-*.deb or sudo apt install ./CC-Switch-*.deb |
| Fedora / RHEL / CentOS / Rocky Linux | .rpm | sudo rpm -i CC-Switch-*.rpm or sudo dnf install ./CC-Switch-*.rpm |
| openSUSE | .rpm | sudo zypper install ./CC-Switch-*.rpm |
| Arch Linux / Manjaro | .AppImage | Make executable and run directly, or use AUR |
| Other distributions / unsure | .AppImage | chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage |