docs/release-notes/v3.16.0-en.md
Chat Completions → Responses format conversion for Codex (you can now use DeepSeek, Kimi, GLM in Codex!), unified Codex provider identity and history, an all-around upgraded app management surface, partner preset expansion, default model / pricing matrix upgraded to GPT-5.5 and Claude Opus 4.8, and proxy / format-conversion robustness hardening
[!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. Multiple imposter websites have recently been spotted impersonating CC Switch to solicit payments and harvest account credentials, with some users already reporting financial losses. 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 so we can take down the imposter site as quickly as possible.
The two headline capabilities in this release are Codex third-party provider Chat Completions routing and in-app managed CLI tool management. If you want providers that only speak the OpenAI Chat protocol (DeepSeek, Kimi, MiniMax, etc.) to work directly in Codex, or want to install / upgrade CLI tools from one place inside the app, start with these two:
CC Switch v3.16.0's development since v3.15.0 centers on promoting third-party Codex providers to first-class citizens through Chat Completions routing. Codex natively only speaks the OpenAI Responses API and GPT-family models; this release lets CC Switch's local proxy convert Codex's outgoing Responses requests into Chat Completions and rebuild the JSON and SSE streaming responses back into Responses shape, preserving reasoning_content / inline <think> blocks / streamed reasoning summaries / tool calls / previous_response_id follow-ups along the way, normalizing error envelopes, and probing Chat-format providers correctly in Stream Check. It ships 22 Chat-routing presets with explicit model catalogs (DeepSeek, Zhipu GLM, Kimi, MiniMax, StepFun, Baidu Qianfan, Bailian, ModelScope, Longcat, BaiLing, Xiaomi MiMo, Volcengine Agentplan, BytePlus, DouBao Seed, SiliconFlow, Novita AI, Nvidia, and more).
Codex third-party providers' identity and history are unified and hardened this release: all third-party providers now normalize to the stable custom model-provider bucket, with a one-shot device migration that rewrites historical JSONL sessions and the state_5.sqlite threads table (originals backed up under ~/.cc-switch/backups/), preventing past sessions from appearing to vanish when provider ids change. It also fixes OAuth login state, user-selected catalog models, and user-authored provider ids being overwritten during live reads / switches.
This release also adds an in-app managed CLI tool lifecycle: the Settings / About tab becomes a tool management panel for Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes, with silent install / update, update-all, conflict diagnostics, source-aware anchored upgrades, WSL handling, and visible "installed but not runnable" states.
The provider ecosystem and model matrix are refreshed in tandem: added APIKEY.FUN, APINebula, AtlasCloud, SudoCode, Xiaomi MiMo Token Plan, and Claude Desktop Official presets; refreshed partner links and default models / pricing across apps; upgraded the default Claude Opus line to 4.8 and GPT defaults to 5.5 where applicable. Plus extensive polish and fixes across usage observability, Traditional Chinese localization, docs, and proxy / format-conversion robustness.
Release date: 2026-05-29
Stats: 101 commits | 221 files changed | +27,063 insertions | -3,052 deletions
<think> / tool-call state, normalizes error envelopes, and probes Chat-format providers correctly in Stream Check.custom model-provider bucket, with a one-shot migration for historical JSONL sessions and state_5.sqlite threads, plus fixes that preserve OAuth login state, user-selected catalog models, and user-authored provider ids during live reads / switches.tool_calls streams, managed-account takeover auth, MiMo reasoning output, Gemini Native tool-call replay, and several panic-prone proxy paths.Codex providers can now be served by upstreams that only speak the OpenAI Chat Completions API. CC Switch's local proxy converts Codex's outgoing Responses requests into Chat Completions and rebuilds the Chat response (both JSON and SSE) back into Responses shape, preserving reasoning_content, inline <think> blocks, streamed reasoning summaries, tool calls, and previous_response_id follow-ups. A bounded Codex Chat history cache restores tool calls before their tool outputs.
💡 Special thanks to @EldenPdx for PR #2804: this feature's Chat ↔ Responses format conversion references the implementation in his PR.
Enabled Chat Completions routing with explicit model catalogs for major Chinese/Asian providers — DeepSeek, Zhipu GLM (+ en), Kimi, MiniMax (+ en), StepFun (+ en), Baidu Qianfan Coding Plan, Bailian, ModelScope, Longcat, BaiLing, Xiaomi MiMo (+ Token Plan), Volcengine Agentplan, BytePlus, DouBao Seed, SiliconFlow (+ en), Novita AI, and Nvidia. Each preset declares its context window so the UI can size the model-mapping rows.
Codex provider forms now expose a model catalog (model + display name + context window per row) that is the single source of truth for the upstream model list, projected to ~/.codex/cc-switch-model-catalog.json.
Stream Check now probes Chat-format Codex providers against /chat/completions with a Chat-shaped body instead of /v1/responses, and aligns its URL fallback order with the production CodexAdapter (origin-only base URLs hit /v1/<endpoint> first) so a non-404 error on the bare path no longer flags a working provider as down.
When a Codex provider is served through Chat Completions routing, CC Switch now auto-detects the upstream's reasoning interface from its name, base URL, and model — injecting the correct thinking parameter (thinking:{type}, enable_thinking, reasoning_split, top-level reasoning_effort, or OpenRouter's native reasoning:{effort} object) with no manual setup. Aggregator/hosting platforms (OpenRouter, SiliconFlow) are matched platform-first, since the same model can expose different reasoning controls on different platforms. Providers that only expose a thinking on/off switch (Kimi, GLM, Qwen, MiniMax, MiMo, SiliconFlow) drop the effort level instead of forwarding an unsupported field — so changing Codex's reasoning effort has no effect for them — while providers with real effort tiers (DeepSeek, OpenRouter, and StepFun's step-3.5-flash-2603 only) pass the level through. OpenRouter specifically uses the native reasoning:{effort} object, clamps max to xhigh (its enum has no max), and forwards an explicit effort:"none" so reasoning can be turned off.
Codex config editing now exposes a Goal Mode toggle and a Remote Compaction toggle for third-party providers; new Codex templates default to disable_response_storage = true while still allowing explicit goal support.
Added Xiaomi MiMo Token Plan presets with specs aligned to the official documentation (#2803, thanks @BlueOcean223).
Added a Claude Desktop Official preset that restores the native Claude Desktop login, plus a localized Claude Desktop user guide (en / zh / ja).
Added silent install / update commands for managed CLI tools, latest-version checks, per-tool and batch actions, update-all, and diagnostics for multiple installations across PATH, Homebrew, npm, pnpm, bun, volta, fnm, nvm, scoop, WinGet, Windows native paths, and WSL.
The Settings / About surface can now diagnose conflicting tool installations, show the concrete install source and version for each path, and generate backend-planned upgrade commands anchored to the actual installation source.
The backend now emits usage-log-recorded when proxy logs, session-log syncs, or rollups write usage data; Usage Dashboard listens for that event and invalidates its queries immediately instead of waiting for the next polling interval (#3027, thanks @in30mn1a).
Added zh-TW UI localization and a settings language option (#3093, thanks @LaiYueTing).
Added README_DE.md and linked it from the existing README language switchers (#2994, thanks @flitzrrr).
Added APIKEY.FUN, APINebula, AtlasCloud, and SudoCode partner presets across the supported app surfaces, with partner copy, icons, and README entries.
Codex filters resume history by model_provider, so switching between provider-specific ids made past sessions appear to vanish. All third-party providers now normalize to a single stable custom bucket (reserved built-in ids like openai / ollama are preserved), with a one-shot device migration that rewrites historical JSONL sessions and the state_5.sqlite threads table and backs up originals under ~/.cc-switch/backups/codex-history-provider-migration-v1/.
Removed the API Format selector from the Codex form (wire_api is always responses, so the selector misleadingly implied a protocol change); the model mapping table is now the only source of truth with no hidden default entries, and the form notes that a Codex restart is required after catalog changes since model_catalog_json is loaded at startup. Only the "Needs Local Routing" toggle remains.
Reframed the OFF / ON hints as action guidance (when to enable) rather than scenario descriptions, synced across zh / en / ja.
Live Codex config reads no longer force-rewrite a user's model_provider field, and provider-scoped experimental_bearer_token handling now preserves OAuth login state when switching between third-party providers.
Managed tool installation now prefers official native installers where available, falls back to package managers when appropriate, runs self-update first for compatible tools, anchors upgrades to the detected install source, and locks duplicate batch actions while work is in flight.
The About settings page now presents installed / latest versions, install and update actions, conflict diagnostics, WSL shell preferences, and clearer status for broken or unrunnable tools.
Upgraded the default Claude Opus model to 4.8, moved GPT-based presets and templates to GPT-5.5 where applicable, refreshed pricing seeds, aligned Claude Desktop model mapping with Claude Code's three-role tiers, and renamed the OpenCode Go preset to drop a stale model suffix.
Updated ShengSuanYun referral links, Atlas Cloud UTM links, and partner copy across README locales and provider metadata.
Installation simplified to brew install --cask cc-switch now that CC Switch is in the official Homebrew repository; the personal-tap requirement was removed from all READMEs.
Replaced JSON stringify / parse deep-copy patterns with a shared deepClone helper and extracted a shared useTauriEvent hook (#3140, thanks @ChongBiaoZhang).
The Codex Chat-to-Responses bridge previously passed upstream error bodies through untouched, leaving Codex clients unable to recognize MiniMax base_resp, raw OpenAI Chat errors, or plain-text / HTML error pages. Errors are now regularized into the standard {error: {message, type, code, param}} envelope with the original HTTP status preserved; non-JSON bodies are wrapped and truncated to 1KB at a UTF-8 char boundary. Also fixed a pre-existing append-vs-insert bug that emitted a duplicate Content-Type header on rewritten JSON bodies.
MiniMax's OpenAI-compatible endpoint strict-rejects any non-leading system message (error 2013). All system fragments are now collapsed into a single leading message (joined in original order), losslessly for permissive backends too.
Editing the active Codex provider triggered a live read that omitted modelCatalog, so a subsequent save silently destroyed user-configured model mappings. Live reads now reverse-parse the on-disk catalog projection to round-trip the same shape the save path writes.
Broke a bidirectional sync cycle between the catalog table and its parent state that caused severe UI jittering when adding or editing entries.
A model the client selects from the catalog (e.g. via /model) is no longer overwritten by config.toml's default model.
Restored a unique call-id fallback when Codex omits or rewrites previous_response_id, stopped deriving cache identity from previous_response_id, and canonicalized parseable JSON string payloads in tool conversions for stable prefix-cache reuse.
The Responses-to-Chat conversion now injects stream_options.include_usage (merging into any client-provided stream_options) when a request is streaming, so OpenAI-compatible upstreams like Kimi and MiniMax emit the trailing usage chunk again. Previously their streamed token / cost / cache stats were recorded as zero on the Codex Chat path.
Thinking models like Kimi/Moonshot and DeepSeek reject an assistant message that carries tool_calls without a non-empty reasoning_content. When cross-turn history recovery misses (proxy restart, ambiguous call_id, or a turn with no upstream reasoning), a placeholder reasoning_content is now backfilled in a final pass — genuine trailing reasoning still attaches first — so the request no longer fails with reasoning_content is missing in assistant tool call message.
Managed-account providers (GitHub Copilot / Codex OAuth) now drop token env keys and write only the ANTHROPIC_API_KEY placeholder when taking over Claude Live config, with an outbound guard that refuses to send the PROXY_MANAGED placeholder upstream.
Claude Desktop profile data is now synced during proxy takeover, model routes align with the Claude Code three-role tiers, and the Cowork egress profile has been corrected (#3157, #3172, thanks @MelorTang, @JGSphaela).
Local Routing now sources takeover model fields from the target provider on managed accounts instead of carrying stale model values.
Normalized DeepSeek Anthropic-compatible tool-thinking history so later turns can replay reasoning / tool-call context without malformed messages (#3203, thanks @Q3yp).
Fixed a Claude-compatible streaming edge case where an empty tool_calls array reset block state and broke streamed responses (#2915, thanks @zhizhuowq).
Added MiMo reasoning_content support on the Claude Code proxy path (#2990, thanks @zhangyapu1).
Fixed functionResponse.name resolution (422) and thought_signature replay (400) for synthesized tool-call IDs in long multi-turn sessions (#2814, thanks @Tiancrimson).
collect_jsonl_files() now scans subagent JSONL logs that were previously missed, so subagent token usage is counted in session cost (session-log mode only) (#2821, thanks @LaoYueHanNi).
Fixed a Codex usage-sync panic on non-ASCII model names, custom usage-script summaries, and missing real-time refresh after usage rollups (#3027, #3129, thanks @in30mn1a, @hanhan3344).
When the 5-hour bucket is at 0% utilization, ZhiPu's API omits nextResetTime; the old i64::MAX sentinel sorted those entries last, letting the weekly bucket incorrectly claim the five-hour slot. Tiers now sort so a missing nextResetTime maps to the five-hour bucket, so tray and usage quota display stays correct for ZhiPu coding plans.
Installing from skills.sh search results now uses the unique key instead of the directory name, so skills that share a directory name install the correct one (#2784, thanks @zhaomoran); also fixed a skill sync copy fallback (#2791, thanks @rogerdigital).
Reduced the price input step to 0.0001 so sub-cent costs like DeepSeek cache reads can be entered (#2793, closes #2503, thanks @rogerdigital).
Ghostty now opens a single clean window instead of cloning existing tabs, and other terminals open a new window via open -na (#2801, closes #2798, thanks @luw2007).
Version probing no longer masks unrunnable installs, prerelease tools are handled correctly in version checks, batch updates run per tool, install / update buttons stay locked during preflight, anchored upgrade branches enforce absolute paths, and WSL installer paths use native Unix installers when needed.
Fixed Codex mise environment detection (#2822, thanks @iambinlin).
Codex archived sessions are now included in session discovery (#2861, thanks @nanmen2).
Empty tool-call argument payloads are coerced to {} during Codex Chat conversion so upstreams and clients receive valid JSON.
Importing Claude providers through deeplinks now preserves custom environment fields (#2928, thanks @doutuifei).
Synced OMO recommended models with upstream defaults and improved Fill Recommended feedback.
ShengSuanYun (胜算云) presets now carry the vendor prefixes the upstream gateway requires — anthropic/…, google/…, and openai/… (e.g. anthropic/claude-sonnet-4.6, google/gemini-3.1-pro-preview) — across the Claude Code, Claude Desktop, Codex, Gemini, OpenCode, and OpenClaw presets, including the Claude Code routing env (ANTHROPIC_MODEL / ANTHROPIC_DEFAULT_{HAIKU,SONNET,OPUS}_MODEL), so they resolve to valid upstream models instead of failing to route.
Reclassified the ClaudeAPI preset (Claude Code and Claude Desktop) from third_party to aggregator so its model test button is no longer disabled by the third-party Claude gate; the partner star is unaffected since it is driven by isPartner, not category.
Version checks now handle prerelease tool versions without misclassifying update state.
Removed a fixed width constraint that clipped app-switcher text (#3161, thanks @loocor).
Added an active-flag pattern to App.tsx effects to prevent listener leaks on unmount, and guarded against storing undefined language in localStorage (#2827, thanks @Zylo206).
Removed the LionCC sponsor entry and LionCCAPI presets across READMEs, provider configs, and locales (icon asset retained).
Removed the AICoding partner from README sponsor listings, provider presets, and i18n metadata.
Removed the Kimi For Coding preset from the Codex preset catalog.
Dropped generated CLI uninstall command hints from the tool-management UI while keeping conflict diagnostics visible.
Documented Chat Completions routing, provider support, reasoning auto-detection, and Local Routing guidance in the changelog and user manual.
Updated settings documentation for the new managed tool lifecycle and Hermes installer behavior.
Added localized Claude Desktop guide pages and screenshots for provider setup, import, model mapping, and Local Routing context.
Updated installation docs and READMEs to recommend the official Homebrew cask and refreshed the v3.15.0 release-note imposter-site warning wording across locales.
The first launch after upgrading runs a one-shot migration of Codex history: third-party providers are normalized into the custom bucket and historical JSONL sessions plus the state_5.sqlite threads table are rewritten. Originals are backed up under ~/.cc-switch/backups/codex-history-provider-migration-v1/. This step fixes the "past sessions vanish after switching provider" problem — history resumes correctly after the migration.
Codex loads model_catalog_json at startup, so after editing the model mapping table in CC Switch you must restart Codex for the new catalog to take effect.
For providers that only expose a thinking on/off switch (Kimi, GLM, Qwen, MiniMax, MiMo, SiliconFlow), changing the reasoning effort in Codex (model_reasoning_effort: low / medium / high) has no effect — CC Switch will not forward an unsupported effort field to them. Only providers with real effort tiers (DeepSeek, OpenRouter, and StepFun's step-3.5-flash-2603 only) actually honor the level.
The default Claude Opus model line is upgraded to 4.8 and GPT defaults to 5.5 where applicable. If you rely on a pinned older default model, check the model fields of the relevant presets / templates after upgrading.
This release inherits the risk notices originally introduced in v3.12.3 / v3.13.0 / v3.15.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.
Codex Third-Party Provider Chat Routing: Converting and forwarding Codex requests through CC Switch's local proxy 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.
Claude Desktop Third-Party Provider Switching via Proxy Gateway: Routing Claude Desktop traffic through CC Switch's in-app proxy gateway to a third-party provider exposes those requests to that provider's billing, compliance, and data-retention policies — read the target provider's terms of service before using.
By enabling these features, users accept all associated risks. CC Switch is not responsible for any account restrictions, warnings, or service suspensions that result from using these features.
Visit Releases to download the appropriate version.
| OS | Minimum Version | Architecture |
|---|---|---|
| Windows | Windows 10 or later | x64 |
| macOS | macOS 12 (Monterey) or later | Intel (x64) / Apple Silicon (arm64) |
| Linux | See table below | x64 / ARM64 |
| File | Description |
|---|---|
CC-Switch-v3.16.0-Windows.msi | Recommended - MSI installer, supports auto-update |
CC-Switch-v3.16.0-Windows-Portable.zip | Portable, extract and run, no registry writes |
| File | Description |
|---|---|
CC-Switch-v3.16.0-macOS.dmg | Recommended - DMG installer, drag into Applications |
CC-Switch-v3.16.0-macOS.zip | Extract and drag into Applications, Universal Binary |
CC-Switch-v3.16.0-macOS.tar.gz | For Homebrew installation and auto-update |
macOS builds are Apple code-signed and notarized — install directly.
🎉 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 artifacts are published for both x86_64 and ARM64 (
aarch64). The architecture is included in the asset filename — pick the one matching your machine'suname -moutput:
CC-Switch-v3.16.0-Linux-x86_64.AppImage/.deb/.rpmCC-Switch-v3.16.0-Linux-arm64.AppImage/.deb/.rpm
| Distribution | Recommended | Installation |
|---|---|---|
| Ubuntu / Debian / Linux Mint / Pop!_OS | .deb | sudo dpkg -i CC-Switch-*.deb or sudo apt install ./CC-Switch-*.deb |
| Fedora / RHEL / CentOS / Rocky Linux | .rpm | sudo rpm -i CC-Switch-*.rpm or sudo dnf install ./CC-Switch-*.rpm |
| openSUSE | .rpm | sudo zypper install ./CC-Switch-*.rpm |
| Arch Linux / Manjaro | .AppImage | Add execute permission and run, or use AUR |
| Other distros / not sure | .AppImage | chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage |