docs/release-notes/v3.16.2-en.md
Following the v3.16.1 Codex stability patch, this release mainly broadens data portability and usage observability — adding S3-compatible cloud sync, OpenCode session usage sync, and an official-subscription quota template — while continuing to harden Codex's Chat Completions routing for third-party providers, fixing a batch of Windows / macOS platform issues, adding the CherryIN and ZenMux providers, and fully refreshing the trilingual user manual.
This release adds an S3 backend for cloud sync and more usage data sources. If you want to use them, start with these docs:
[!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.16.2 is a maintenance update following v3.16.1. After the previous release focused on the security of Codex official authentication and local routing takeover, this release concentrates on two things. First, broadening data portability and usage observability — adding S3-compatible cloud sync (a second cloud-backup backend alongside WebDAV), OpenCode session usage sync, and a quota-statistics template for official subscriptions. Second, continuing to polish the edges exposed when Codex routes third-party providers through Chat Completions — stream-truncation detection, tool_choice when tools is empty, custom-tool metadata, reasoning-token statistics, file / audio attachment conversion, and more.
This release also fixes a batch of local proxy robustness issues (ephemeral port resolution, the takeover placeholder restore loop, Anthropic system message normalization, the upstream 413 message, and Claude Desktop's [1m] model routing), addresses several Windows / macOS platform experience issues, adds the CherryIN and ZenMux providers, and fully refreshes the trilingual user manual.
Release date: 2026-06-07
Stats: 41 commits | 132 files changed | +11,116 / -1,636 lines
tool_choice rejection when tools is empty, custom-tool metadata loss, and missing reasoning-token stats, and added file / audio attachment conversion plus a /v1/models reachability endpoint.system message normalization, the upstream 413 message, and Claude Desktop 1M-context model routing.Cloud Sync now supports S3-compatible object storage as a second backend alongside WebDAV, signing requests with a self-implemented AWS Signature V4 for the broadest possible compatibility. The settings page offers one-click presets for AWS S3, MinIO, Cloudflare R2, Alibaba Cloud OSS, Tencent Cloud COS, Huawei OBS, and a custom endpoint, with connection testing, manual upload / download, and auto-sync on configuration changes (the providers, endpoint, MCP, prompt, skill, settings, and proxy tables — not high-frequency data like usage logs). Enabling S3 sync disables a running WebDAV sync and vice versa (#1351).
Added OpenCode as a usage-statistics source that reads per-message token, cost, and model data from OpenCode's local SQLite database and imports it into the usage records, with a dedicated "OpenCode" app filter tab and an "OpenCode Session" data-source label. The database path respects OPENCODE_DB and XDG_DATA_HOME (defaulting to ~/.local/share/opencode on all platforms), only finalized messages are imported, and the freshness check includes the WAL file so just-written sessions are not skipped (#3215).
Because some users were concerned that the IP issuing the usage query could differ from the IP issuing in-app requests, risking an account ban, the official-subscription usage template for Claude / Codex / Gemini official providers is now an explicit, opt-in template that queries plan quota via CLI / OAuth credentials, replacing the previous implicit auto-query for official providers. The template is off by default, is enabled from the usage-script modal, and supports a configurable refresh interval. When using this feature, enabling the proxy's TUN mode is recommended.
Added a proxy rectifier that replaces Anthropic image blocks with an [Unsupported Image] placeholder when the routed model is text-only (declared, or detected by a built-in model-name heuristic) or the upstream rejects image input, so conversations are not interrupted. The settings page provides a toggle for this fallback, plus a separate toggle for the heuristic detection (which can be turned off to avoid misjudging multimodal models).
Added ZenMux as a Token Plan Coding Plan provider. You can manually enter its API key and base URL in the usage-script modal, and it renders used / quota in USD (#2709).
Added the CherryIN aggregator gateway as a quick-config preset across all 7 managed apps — Claude Code / Claude Desktop / OpenClaw / Hermes use the Anthropic-format endpoint (open.cherryin.net), OpenCode uses @ai-sdk/anthropic (/v1), Codex uses the OpenAI-compatible endpoint, and Gemini CLI uses the Gemini-compatible endpoint — with the official brand icon, placed next to AiHubMix (#3643).
/v1/modelsThe local proxy now responds to GET /v1/models, which Codex CLI probes at startup, returning the CC Switch-managed Codex model catalog. A stale-catalog guard was added: it parses the live config.toml and only serves the catalog when model_catalog_json still points at the CC Switch-owned catalog file, avoiding exposing a previous provider's leftover catalog to Codex (#3818).
Codex's Responses→Chat conversion now maps input_file parts (carrying file_id or inline file_data) and input_audio parts into their Chat Completions equivalents, and emits top-level input_* items that were previously dropped, so file and audio attachments reach Chat-only Codex upstreams.
Rearranged the Usage Dashboard hero and summary cards into a more compact layout, consolidating the real-token total, request count, and cost into a single top row (#3426).
Updated the SSSAiCode preset's website, signup, and API base URLs to the sssaicodeapi.com domain, and refreshed its candidate endpoint nodes (default node-hk.sssaicodeapi.com, plus node-hk.sssaiapi.com and node-cf.sssaicodeapi.com) across all 7 app presets.
When a Chat Completions upstream ends a stream without a finish_reason or [DONE], CC Switch no longer treats it as a normal completion: it finalizes normally only when the stream truly ended; emits an incomplete (max_output_tokens) response when partial output was produced; and emits a failed stream_truncated event when nothing was produced. Late-arriving reasoning is also backfilled onto still-active streaming tool calls.
tool_choice Without ToolsThe Responses→Chat conversion now drops tool_choice and parallel_tool_calls when the final tools array is missing or empty (including when all tools are filtered out), avoiding 503/400 errors from strict OpenAI-compatible upstreams (vLLM, enterprise gateways) with "When using tool_choice, tools must be set." (#3640).
Custom Codex tools (such as the freeform apply_patch tool) now embed their full original definition — including format and grammar metadata — as a compact, order-stable JSON block in the generated Chat function description, instead of being replaced with a generic placeholder, so they remain usable on Chat Completions upstreams (#3644).
reasoning_tokensThe Chat→Responses usage conversion now always includes output_tokens_details.reasoning_tokens (defaulting to 0), even when a provider omits completion_tokens_details or returns a non-object, satisfying Codex CLI's strict requirement and avoiding repeated response-parse failures and retries (#3514).
The cross-turn reasoning cache in Codex Chat history now covers the full tool-call set (function_call, custom_tool_call, tool_search_call) and their outputs, not just plain function calls, so apply_patch and tool-search calls keep their own reasoning_content when restored via previous_response_id.
When the proxy is configured to listen on port 0 (OS-assigned), takeover now starts the proxy first to obtain the real port before writing live configs and the database, avoiding client URLs pointing at an invalid :0 address; if no concrete port has been resolved yet, the Claude Desktop gateway URL is rejected outright.
If a previous proxy stop failed to restore the original live config and left proxy placeholders in live, taking over again no longer overwrites the good backup with the proxy config, and restore no longer writes the placeholder back to live: both paths detect the placeholder state and rebuild live from the current provider as the source of truth, fixing cases where the proxy toggle became a no-op and the client was pinned to the local proxy address (#3689).
During local routing takeover, only providers explicitly classified as official are now blocked from switching, instead of also disabling custom providers whose endpoint lives in meta or whose fields are simply unfilled. The disabled "Enable" button now shows a lighter hint tooltip instead of the previous red "Blocked" badge.
When saving the proxy with a listen address of localhost, it is now normalized to 127.0.0.1 before persisting, avoiding binding inconsistencies (#3016).
system Message NormalizationFor Anthropic-format providers, system-role entries inside the messages array are now collapsed and merged into the top-level system field (preserving original order and any existing top-level system), avoiding strict upstreams rejecting non-leading system messages; OpenAI Chat routing is unaffected (#3775).
Claude Desktop appends a [1m] marker to the model name when the 1M-context beta is active (e.g. claude-opus-4-8[1m]). The proxy now strips that suffix before route matching so exact, alias, legacy, and role-keyword matching all resolve correctly, fixing route_unknown (HTTP 400) failures when switching to a 1M model mid-conversation; the original model name is still kept in the route_unknown error for diagnostics.
When a Codex upstream gateway rejects an oversized request body with HTTP 413, the proxy now returns a dedicated message explaining that this is the provider's server-side body-size limit (not a CC Switch local limit), with actionable recovery steps (run /compact, remove large logs or inline images, or ask the provider to raise the limit), instead of echoing the upstream's raw HTML error page.
When toggling proxy takeover fails, the proxy panel toast now includes the specific error detail returned by the backend, instead of only a generic failure message (#3656).
Raised the streaming infinite-whitespace abort threshold from 20 to 500 consecutive whitespace characters, avoiding false aborts of legitimate tool calls whose arguments contain deeply indented code (Python, YAML, Rust, Markdown), while still catching the real Copilot infinite-whitespace bug (#2647).
Via a unified tier-to-label mapping, fixed rendering of official subscription tiers in the tray and quota display: Claude / Codex no longer drop the 7-day window, Gemini Pro / Flash / Flash-Lite tiers no longer leak raw machine names, and multi-window plans (e.g. Opus + Sonnet) now show the worst utilization instead of the first match.
Some Anthropic-compatible streaming providers (e.g. Qwen, MiniMax) report the full context as input_tokens in message_start, double-counting the cached portion already reported separately and artificially lowering the displayed cache hit rate. The parser now prefers the smaller positive input_tokens from message_delta and adopts the paired cache counts from the same usage block; native Claude and OpenRouter-converted paths are unchanged.
The Zhipu Coding Plan quota query was hard-coded to api.z.ai, so users on the mainland preset (open.bigmodel.cn) could not retrieve usage when the international endpoint was unreachable. The quota request now routes to the host matching the user's configured base URL (#3702).
Adapted MiniMax Coding Plan quota to its new balance API (which returns remaining-percent fields instead of the usage counts the old parser relied on, which left tiers empty and the tray showing no usage), filtered out non-coding models (such as video), handled plans without a weekly limit, and added default pricing for the MiniMax M3 model (#3518).
Fixed the Zhipu / Z.AI GLM Coding Plan presets to the /api/coding/paas/v4 endpoints (covering Codex, OpenCode, OpenClaw, Hermes), and made the model-list probe query {base}/models first for base URLs that already end in a /v{N} version segment (keeping /v1/models as a fallback), so the "Fetch models" button no longer 404s on versioned endpoints (#3524).
Codex now writes only the relative filename cc-switch-model-catalog.json to config.toml instead of an absolute path (Codex CLI resolves it from the config directory), fixing the model catalog breaking on WSL and symlinked setups where the absolute path could not be translated (#3614).
The APINebula OpenCode preset now loads @ai-sdk/openai-compatible instead of @ai-sdk/openai, so requests use the OpenAI Chat Completions format the relay expects, rather than the Responses API that fails against chat-completions-only upstreams.
On Windows, quitting CC Switch could leave a dead tray icon behind until the mouse passed over it. The app now explicitly removes the tray icon before exiting, so it disappears cleanly when the process ends (#3797).
Sets an explicit Windows AppUserModelID at runtime and writes the same ID and product icon onto the installer's desktop and start-menu shortcuts, so CC Switch shows the correct icon and groups properly in the taskbar (#3457).
When scanning installed skills on Windows, backslash path separators are now normalized to forward slashes, so skills nested in subdirectories (e.g. skills/my-skill) are matched by the update check instead of being silently skipped (#3430).
Disabled autocomplete, autocorrect, autocapitalize, and spellcheck on the shared text Input component, so macOS no longer auto-capitalizes or auto-corrects the first letter typed into configuration fields (#3626).
For Codex requests sent from VS Code, the session preview could show selection or open-file content instead of the real prompt when a markdown heading preceded the injected request. The backend title and frontend preview now both match the last "## My request for Codex:" heading (the IDE injects the real request as the final section), so the preview reflects the user's prompt (#3593).
Corrected the "Apply to Claude Code plugin" description in Simplified and Traditional Chinese to write "VS Code" properly instead of "Vscode", aligning with the English and Japanese strings (#3228).
Refreshed the README localizations and the en / zh / ja user manuals to reflect all 7 managed apps (adding Claude Desktop and Hermes to the intro and overview copy), corrected the OpenCode config path to ~/.config/opencode/ (opencode.json), documented Hermes config files, updated the language docs to four languages, corrected per-app MCP / prompt / skill support, noted that export now produces a timestamped SQL backup that includes usage logs, and documented the pricing model-ID matching rules (#3411).
Added a Chinese / English / Japanese guide explaining how to keep Codex official remote control and official plugins working while routing model traffic to third-party APIs, and linked it from the v3.16.1 release notes.
Updated the Release Notes links in each language README to v3.16.1, and fixed broken curly-quote characters in the README_ZH sponsor blocks so their HTML attributes render correctly (#3772).
Cloud Sync runs only one backend at a time. Enabling S3 auto-sync disables a running WebDAV auto-sync and vice versa. If you previously used WebDAV, make sure both ends are aligned before switching to S3, so you don't assume the old backend is still backing up.
Codex reads model_catalog_json at startup. Even though this release rewrites the model catalog to a relative path and adds the /v1/models reachability endpoint, you still need to restart Codex after editing the model mapping table for the /model menu to refresh.
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.
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.16.2:
GET /v1/models endpoint, thanks @CSberlin.tool_choice when tools is empty, thanks @Postroggy.reasoning_tokens in Chat→Responses, thanks @yeeyzy.system messages, thanks @Dearli666.Thanks also to everyone who reported Codex Chat routing, local proxy takeover, usage statistics, and platform compatibility issues after v3.16.1. Many of these fixes came directly from real-world reproduction details.
Visit Releases and download the build for your system.
| System | Minimum Version | Architecture |
|---|---|---|
| Windows | Windows 10 and later | x64 |
| macOS | macOS 12 (Monterey)+ | Intel (x64) / Apple Silicon (arm64) |
| Linux | See table below | x64 / ARM64 |
| File | Description |
|---|---|
CC-Switch-v3.16.2-Windows.msi | Recommended - MSI installer with auto-update |
CC-Switch-v3.16.2-Windows-Portable.zip | Portable build, unzip and run |
| File | Description |
|---|---|
CC-Switch-v3.16.2-macOS.dmg | Recommended - DMG installer, drag to Applications |
CC-Switch-v3.16.2-macOS.zip | Unzip and drag to Applications, Universal Binary |
CC-Switch-v3.16.2-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.16.2-Linux-x86_64.AppImage / .deb / .rpmCC-Switch-v3.16.2-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 |