docs/release-notes/v3.16.4-en.md
After v3.16.3 made usage billing accurate, this release shifts the focus to polishing the Codex proxy chain and enriching the usage / pricing tooling — migrating Chinese providers to native Responses, decoupling the upstream-format selector from model mapping, decompressing zstd request / error bodies, and a batch of tool-call and OAuth-through-proxy fixes — while also adding local proxy request overrides, an in-app recovery screen when the database version is too new, native Windows ARM64 builds, and a wave of preset and branding updates (SubRouter, OpenCode Go, the CTok→ETok rename, the Kimi brand refresh, and a prime-partner badge).
This release is mostly polish and expansion, with the new capabilities landing mainly in the usage dashboard and the provider form's advanced options. The following docs are worth reading alongside it:
[!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.4 is a maintenance update following v3.16.3. This release tightens the Codex proxy chain — switching several Chinese providers that have native OpenAI Responses endpoints to the native format (dropping the Responses→Chat route-takeover conversion), promoting "upstream format" out of the "local routing" toggle into its own control, adding decompression for zstd request and error response bodies, and fixing a string of tool-call and "OAuth module bypassing the global proxy" issues.
Alongside that, this release enriches the usage and pricing tooling (import pricing from models.dev, AK/SK usage queries for Volcengine Ark Coding / Agent Plan, a live end time for custom date ranges, GLM-5.2 and Doubao Seed 2.1 pricing), adds a batch of proxy and resilience capabilities (custom header / request-body overrides, an in-app recovery screen when the database version is too new, native Windows ARM64 builds), and brings a wave of preset and branding updates (SubRouter and OpenCode Go subscriptions, the CTok→ETok rename, the Kimi brand refresh and prime-partner badge, and a Kimi K2.7 Code sponsor banner).
Release date: 2026-06-27
Stats: 53 commits | 126 files changed | +8,149 / -1,016 lines
When the SQLite user_version is newer than the current app's supported SCHEMA_VERSION (for example after downgrading to an older release, or because a third-party client wrote the file), startup used to die in a native "retry / quit" dialog — where "retry" just fails again. The app now routes to a dedicated recovery screen: when an update is available it offers a one-click "Upgrade App" button (download + install + restart, with a progress bar), and when none is available it explains that even the latest version cannot read this database. The "too new" check runs before any write to the database, so the app never runs DDL against a database it cannot understand; a native close in recovery mode exits cleanly (the tray has not been created yet). (#4575)
Provider configs can now define custom header and request-body overrides that the local proxy applies when forwarding, exposed via new fields in the Claude and Codex provider forms. Input is validated against a protected-header list that blocks overriding security-sensitive headers. (#4589)
The usage panel can now query Volcengine Ark's Coding Plan and Agent Plan quotas. Because the Ark control-plane OpenAPI (open.volcengineapi.com) requires an account-level AccessKey signature rather than an inference API key, the usage script gains a dedicated AK/SK input area with a clickable link straight to the Volcengine IAM key-management console (https://console.volcengine.com/iam/keymanage); the proxy implements Volcengine Signature V4 (an AWS SigV4 variant: a fixed canonical-header order, the HMAC-SHA256 algorithm, and the ark service scope). It first probes GetAFPUsage (the Agent Plan's 5-hour / weekly / monthly quotas) to auto-detect the plan and falls back to GetCodingPlanUsage, parsing the window label from the Level field (with a guard for ResetTimestamp <= 0), and adds the monthly tier label across the usage footer, the tray menu, and all four locales.
The "Add Pricing" panel gains an "Import from models.dev" button: it fetches https://models.dev/api.json, supports full-text search across the entire catalog, and imports the selected entries through the same update_model_pricing path as manual entry. Imported model ids are normalized by the backend's clean_model_id_for_pricing rules (strip the provider prefix, lowercase, truncate the : suffix, map @ to -, drop the [1m] marker) so the persisted rows actually match cost-attribution queries. A companion fix changes "backfill zero-cost over a range" to match in Rust by raw model alias (route prefixes, :free variants, date suffixes) rather than by exact SQL string match, so newly priced alias rows are priced immediately instead of waiting for the next startup backfill (fixes #4017). (#4079)
Release artifacts now include native Windows ARM64 builds, so ARM Windows devices can grab the matching native build instead of relying on x64 emulation. The release matrix now also runs each platform independently (fail-fast disabled), so a job that fails for a missing secret (e.g. macOS signing in a fork) no longer cancels its still-running siblings. (#3950)
The custom date-range picker gains a "follow the current time as the end time" checkbox; when enabled, the end time becomes read-only and tracks now, so usage data always reflects the live consumption from the chosen start to the present moment. This is especially useful within the Coding Plan's 5-hour quota window. liveEndTime is now part of the React Query cache key, so a live range and a fixed range with the same endpoint no longer share the same stale cache entry. (#4438)
The session detail header now shows the session log's file name next to the project directory (hover for the full path, click to copy), so you can locate and open the underlying JSONL file directly from the UI. For long file names without spaces, such as the ~70-character Codex rollout names, it truncates at max-w-[200px] to avoid overflowing into the action buttons in a narrow window. (#4113)
The Skills import button in the top bar now shows a green dot and a tooltip when there are unmanaged Skills on disk available to import, so you can tell at a glance that a Skill on disk hasn't been brought under management yet. The scan runs once on mount and is shared across navigations (30s staleTime + keepPreviousData) to avoid redundant disk IO.
Added the OpenCode Go (opencode.ai/zen/go) preset, covering Claude, Codex, and OpenCode, using a paste-ready bare API key (no OAuth). The Codex preset uses openai_chat conversion with a GLM / Kimi / DeepSeek / MiMo model catalog (and without a static codexChatReasoning, inferring each model's capabilities), while OpenCode points at /zen/go/v1 via @ai-sdk/openai-compatible. All four OpenCode Go presets — Claude, Claude Desktop, Codex, and OpenCode — carry the referral link and in-app promotion copy; the promotion banner now shows on partnerPromotionKey alone (no longer bound to isPartner), so a preset can surface a referral promotion without earning the gold paid-partner star (which incidentally brings the existing MiniMax promotion back into view).
The first-party Moonshot Kimi presets (Kimi / Kimi For Coding / Kimi K2.7 Code) are now marked as prime partners: instead of the gold star they render a solid gold heart (no badge border) and, in the default (Original) sort, float to just after the official-category presets and before the rest. The grouping is done with a three-way partition that keeps each group's internal order, and an official preset that is also marked prime-partner stays only in the official group.
The seed model pricing now includes GLM-5.2 (#4385) and Doubao Seed 2.1 Pro / Turbo, so these models' usage is priced correctly instead of being recorded at zero cost. Doubao prices use Volcengine's official list pricing (converted at roughly 7.14); cache_creation stays at 0 because Doubao bills cache storage by time rather than by token writes, and the existing 2.0 rows are retained for historical accounting.
The Kimi For Coding preset now defaults CLAUDE_CODE_AUTO_COMPACT_WINDOW to 262144, matching Kimi's official documentation, and exposes it via templateValues so users can customize the value for future models or performance tuning. (#4401)
Added SubRouter (subrouter.ai, an AI relay aggregator that lets one key reach many models across many providers) as a preset covering all seven managed apps — an Anthropic-format endpoint for Claude Code / Claude Desktop / OpenClaw / Hermes, an OpenAI-compatible /v1 endpoint (gpt-5.5) for Codex and OpenCode, and a Gemini-compatible /v1beta endpoint (gemini-3.5-flash) for Gemini CLI — with its own brand icon, a gold partner star, four-language promotion copy, and a referral signup link prefilled to the API-key registration page (?aff=l3ri). (#4522)
Several Chinese providers (Qwen / DashScope, Xiaomi MiMo, Volcengine Doubao, Meituan LongCat, MiniMax domestic / international) now expose native OpenAI Responses endpoints, so their Codex presets switch to apiFormat: "openai_responses", connecting directly to the upstream instead of going through the Responses→Chat route-takeover conversion. Dropping the no-longer-needed codexChatReasoning and modelCatalog also keeps the "local routing mapping" toggle unchecked by default. SiliconFlow-hosted MiniMax stays on openai_chat because that is a third-party endpoint, not MiniMax's own base_url. The remaining chat-based providers also refreshed stale model ids (GLM 5.1→5.2, StepFun 3.5-flash-2603→3.7-flash, Ling 2.5-1T→2.6-1T).
The Codex provider form previously bound Chat format conversion and route takeover (model mapping) to the same toggle, which meant a provider offering a native Responses API couldn't use model mapping without forcing Chat Completions conversion. "Upstream format" (Chat Completions / Responses) is now a separate, always-visible selector, while the local routing toggle only controls the advanced subsection (the model-mapping catalog, plus reasoning capabilities when the format is Chat). Its initial state is derived from whether a saved catalog exists, adding no new persisted field; the four-language (zh / en / ja / zh-TW) codexConfig copy was rewritten to match.
The DouBaoSeed preset now points to doubao-seed-2-1-pro (replacing doubao-seed-2-0-code-preview-latest) across all six clients (claude, claude-desktop, codex, opencode, openclaw, hermes), updates the display name to "Doubao Seed 2.1 Pro", and corrects the OpenClaw cost fields from 0.002 / 0.006 to 0.84 / 4.2 USD per million tokens to match the new model.
Following the vendor's domain, endpoint, and trademark rename, all user-facing branding migrates from CTok to ETok (ctok.ai→etok.ai, api.ctok.ai→api.etok.ai, plus the internal id, display name, icon, and README partner banner), across every client preset. The Codex history-migration whitelist still keeps ctok as a legacy id alongside the new etok, so existing users' local session history stays correctly bucketed after the rename.
The Kimi presets that OpenCode and OpenClaw previously labeled "Kimi K2.7 Code" are renamed to "Kimi" to match the other apps (OpenCode's provider display name is renamed too); the model label still keeps "Kimi K2.7 Code" because it describes the actual model.
The CodeMirror JsonEditor in the usage-script dialog, the provider form, and the universal provider form now follows the app theme via useDarkMode(), switching to the oneDark editor theme instead of staying light while the rest of the app is already dark. (#4556)
The "Add Provider" dialog tightens the vertical spacing from the title to the tabs and from the tabs to the cards from 24px to 12px, and adds an always-visible fixed footer hint guiding users to fill in the fields below after choosing a preset. FullScreenPanel gains an optional contentClassName prop so the padding override applies only to this panel without affecting other panels that share it.
The inline Kimi placeholder mark is replaced with the vendor's refreshed mark. The K glyph uses currentColor so it follows the theme text color (dark in light mode, white in dark mode), while the brand accent color is fixed to the new #1783FF, with the metadata fallback color aligned accordingly.
The Settings About page no longer shows the Fable 5 Verified commemorative banner that 3.16.3 added beside the app name to mark a special build; the banner image and its marker are removed, and the About panel returns to the standard version-badge layout.
CopilotAuthManager and CodexOAuthManager hardcoded Client::new() at construction, so their auth flows (token exchange, fetching the /models list, determining model vendor, device-code and OAuth refresh requests) ignored the configured global proxy and connected directly to the target services. On Copilot, a direct connection made /models return 0 Claude models, breaking live model resolution, and the upstream rejected requests with 400 model_not_supported. Both managers now pull from the shared client on each request (crate::proxy::http_client::get()), honoring the global proxy URL and supporting runtime hot reload. Fixes #2016 and #2931. (#4583)
Codex Desktop sends zstd-compressed request bodies when authenticating to the Codex backend, which broke local proxy routing because the handlers parsed the raw compressed bytes directly with serde_json. The proxy now decompresses the request body before JSON parsing (gzip / br / deflate, plus the newly added zstd support, including stacked encodings like gzip, zstd), across three Codex handlers, and strips the stale content-encoding / content-length / transfer-encoding request headers so the forwarder regenerates them. Upstream non-2xx error bodies are decompressed the same way, so compressed rate-limit and auth details are no longer dropped and hidden from the client. Fixes #3764 and #3696. (#3817)
thinking: disabledDeepSeek's Anthropic-compatible endpoint rejects requests where thinking.type=disabled coexists with an effort parameter, returning HTTP 400, which broke Claude Code 2.1.166+ sub-agents (Workflow / Dynamic Workflow) that hardcode thinking: disabled. Rather than overriding the client's intent, the proxy now strips the conflicting output_config.effort / reasoning_effort parameters for the official DeepSeek endpoint, since sub-agents don't need to surface reasoning anyway. (#4239)
Reverted the #3775 change that hoisted role=system messages on Anthropic-compatible providers from messages[] up to the top-level system field. The DeepSeek endpoint natively accepts inline system messages, and the rewrite changed the request prefix; keeping messages in place preserves the prompt prefix and avoids a suspected cache-hit-rate regression (see #4297). The unrelated Windows test fix and the tool-thinking-history normalization from #3775 are retained.
Some upstreams send empty or missing function names in streaming tool-call deltas, which used to produce invalid Codex Chat output items (or an unknown_tool fallback). Accumulated tool-call state is no longer overwritten by an empty delta, and tool calls that never receive a call_id and a valid name are skipped at finalization, across the streaming, non-streaming, and legacy function_call paths. (#4159)
When Codex makes a follow-up Chat request that references a previous_response_id, its function_call items may carry only the call_id. History enhancement previously backfilled only reasoning / reasoning_content, leaving the function's name, arguments, status, and other fields empty; it now restores all cached tool-call fields from history so the call can be correctly reconstructed for the Chat upstream. (#4160)
Writing Codex's base_url into config.toml previously replaced or removed only one matching assignment per section, so a section that already contained multiple base_url lines kept the extras and accumulated duplicates. setCodexBaseUrl now collapses all matches in the target section or at the top level (replacing the first, removing the rest), and the TOML base_url regex now handles escaped quotes. (#4316)
Codex session-history migration previously scanned only ~/.codex/state_5.sqlite and the sqlite_home location in config.toml, so when Codex's SQLite state was relocated via the CODEX_SQLITE_HOME environment variable, the state DB was never scanned and its threads stayed in the old provider bucket. The codex_state_db_paths helper shared by both the third-party and unified-session migrations now falls back to CODEX_SQLITE_HOME (the sqlite_home in config still takes precedence).
Launching a provider terminal on macOS / Linux previously hardcoded bash, so zsh / fish users' rc files weren't loaded. The launcher now detects the user's default shell from $SHELL (falling back to /bin/zsh on macOS, /bin/bash on Linux) and execs into it with the clean-start flag, while the launch script itself now uses POSIX sh for portability (e.g. fish, and NixOS where /bin/sh may not exist). (#4140, fixes #1546)
When a custom Claude config directory is configured, MCP server reads and writes now resolve to the MCP file under that directory instead of the default location, isolating MCP state per profile. The old "copy on access" migration of the legacy file was removed in favor of resolving the override path directly. (#3431)
After searching in the "Add Provider" preset selector, results briefly couldn't be clicked or selected. The requestAnimationFrame select() that fought the input and swallowed the first character (e.g. "gateway" → "ateway") was removed, input auto-focus on the open-and-click path was restored, and pressing Ctrl/Cmd+F while the search box is already open now refocuses it. The provider list's typing guard was also narrowed to the Ctrl/Cmd+F branch so Escape can still close the search panel. (#4315)
Fixed several display and interaction issues: repository management actions stay available while browsing skills.sh, and refresh stays available when a repository returns empty results; overly long provider names and website URLs on provider cards now truncate instead of overflowing; the OMO model-variant dropdown truncates the selected label with a full-text tooltip; and Select menu items show a checkmark on the currently selected item. (#4323)
Switching tabs in the Settings dialog used to keep the previous tab's scroll position, sometimes landing halfway down the new tab; the scroll container now resets to the top whenever the active tab changes. (#4165)
The pinned sponsor banner at the top of all four README languages (en / zh / ja / de) is now Kimi K2.7 Code, replacing the previous MiniMax M2.7 banner. The copy reflects the K2.7 Code release (a coding-oriented agentic model with thinking-token usage down roughly 30% from K2.6), the banner is now served from in-repo assets (assets/partners/banners/kimi-banner-en.png / kimi-banner-zh.png) instead of the Moonshot CDN, and it carries a clickable call to action pointing at the aff=cc-switch Moonshot console.
Added a three-language (zh / en / ja) guide explaining what the unified Codex session history toggle's enable-time migration (when enabled) and ledger-based restore (when disabled) actually do, why session data is never truly deleted (only re-tagged + auto-backed-up), and how to verify whether files really are on disk or were just filed into another provider's drawer. It includes a symptom table for the common "my sessions are gone" misunderstanding and disk-verification commands for macOS / Linux / Windows, and is linked as the first item in the v3.16.3 release notes' "Usage Guides".
The install guide no longer asks users to run brew tap farion1231/ccswitch before brew install --cask cc-switch; this deprecated tap step is removed from the en / ja / zh user manuals, and the cask now installs directly. (#4319)
Added a star-history global ranking badge next to the existing Trendshift badge across all four README languages, with light / dark theme variants.
The "developers in mainland China click here" link in the ByteDance / Volcengine Ark sponsor entry now points to Volcengine's ai618 activity page, replacing the previous codingplan referral URL, across all four README languages.
Replaced the low-resolution ccsub.jpg sponsor logo with the vector ccsub.svg, letterboxed from 2046x648 to 2046x850 (roughly 2.406:1) so it matches the other sponsor-table banners and renders at the same 62px height. All four README languages point to the new asset.
This release switches the Codex presets of several Chinese providers with native Responses endpoints (Qwen / DashScope, Xiaomi MiMo, Volcengine Doubao, Meituan LongCat, MiniMax domestic / international) to openai_responses and removes their modelCatalog. Existing providers already configured from these presets are unaffected and keep their configuration as-is; if you want to switch to native Responses (dropping the format-conversion takeover), re-pick the preset once and save. SiliconFlow-hosted MiniMax stays on openai_chat and is not part of this migration.
If you opened the database with a higher version of CC Switch and then switched back to an older version, the older version will enter the new "database version too new" recovery screen on startup and guide you to upgrade to a version that can read the database. This is expected behavior — upgrading to the latest version restores normal operation.
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.4:
Thanks also to everyone who reported Codex proxy chain, usage billing, local proxy robustness, and platform compatibility issues after the v3.16.3 release. Many of these patches came directly from real-world reproduction clues.
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.16.4-Windows.msi | Recommended - MSI installer with auto-update |
CC-Switch-v3.16.4-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.16.4-macOS.dmg | Recommended - DMG installer, drag to Applications |
CC-Switch-v3.16.4-macOS.zip | Unzip and drag to Applications, Universal Binary |
CC-Switch-v3.16.4-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.4-Linux-x86_64.AppImage / .deb / .rpmCC-Switch-v3.16.4-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 |