CC Switch v4.0.9

The fifth fix release for 4.0 stable

This release reworks the whole flow for adding a provider: the form follows the order you fill it in, with the model list right after the address and Key; clicking "Fetch Models" opens a dialog automatically, with each model's context window and support for reasoning and image input already looked up; check the models you want and click "Apply" to add them to the list together with their parameters, and uncheck them in the same dialog to remove them; field descriptions move into "?", and hints follow whether the app is currently in Direct, Routing or Aggregation mode. It also fixes Codex new threads and automations failing on some upstreams and leaving the whole thread unable to continue: DeepSeek, OpenCode Zen and others reached through Routing via the Chat protocol returned 400, and xAI native Responses returned 422. For Claude Desktop in WSL2 and other clients that cannot reach this machine's loopback, you can now enter a "Connection address" under "Settings → Local routing". For everything new in 4.0, see the v4.0 release notes.

A reworked flow for adding providers

This release goes through the forms for adding and editing providers from top to bottom, mainly the three layouts for Claude Code, Codex and Aggregation. The model list used to sit under the advanced options, after the default model it determines; fetched models could only be added one at a time below the list, and each parameter filled in automatically then had to be checked one by one; nearly every field had a paragraph of gray text below it, and some hints did not match the mode you were actually in. Here is the flow now, in the order you fill it in:

1. Address, Key and upstream format. First pick a preset or enter the address and Key. When you choose an upstream format, the hint follows the app's current mode: when the app is in Direct mode and the chosen format needs conversion, a hint below the format says either that this card is in use in Direct mode and requests will fail once it is saved with this format, or that this format needs a switch to Routing or Aggregation first. When Claude Code's upstream format is OpenAI Chat or Responses, authentication fields that would not be used are no longer shown.

2. Model list: fetch, pick, fill in parameters automatically. Codex's model list has moved out of the advanced options to right after the address and Key, and is named "Models", as in the Aggregation layout. For Claude Code Aggregation, Codex, OpenCode and MiniMax Code, models are now added to the model list like this:

Click "Fetch Models" on the model list.
Once fetching succeeds, the "Select models" dialog opens automatically. Each model already shows its context window and whether it supports reasoning and image input; the values come from a preset with the same address first, then from models.dev looked up by the provider's address, and then from the model vendor's own entry.
Check the models you want and click "Apply". New models are appended to the end of the list with their parameters filled in from the values shown in the dialog, and the "Filled in context window and other parameters for … Please double-check." prompt no longer appears.

The same dialog also handles removal: checked means "in the list", configured models are checked by default, and unchecking them and clicking "Apply" removes them from the list; clicking "Cancel" changes nothing. Models that stay keep their original order and settings. Configured models the provider did not return this time are listed separately in a "Not in the provider's list" group and can be cleaned up at the same time. The dialog supports search, select all / select none and showing only selected models, and shows how many are selected; after one fetch, the button becomes "Select models", and clicking it again does not fetch again; when needed, click "Fetch again" in the dialog.

3. Default model: the first row of the list. When Codex has a model list, the first row is the default model, and there is no longer a separate default model input box; renaming or deleting the first row changes the default model accordingly. When the list was empty, adding a model automatically puts the current default model in the first row, so adding a list does not change the default model. Cards without a model list still keep the default model input box: these cards use Codex's built-in /model menu, and once a list is added the menu shows only the models in the list. The Aggregation model lists also drop the ★ and "Make default model" on each row, and the rule is likewise that the first row is the default.

4. Subagents (Codex, new). The Codex form adds "Sub-agent Model" and "Sub-agent reasoning effort", which map to the config.toml keys under [agents]: default_subagent_model and default_subagent_reasoning_effort. Leaving one empty deletes the corresponding key, and subagents use the main agent's setting; when you switch providers these two follow, and other settings under [agents] are left alone. When the model entered is not in the model list, the form says so and can add it with one click: Codex cannot get the context window of a model that is not in the list, and when Routing converts requests to the Chat / Anthropic protocol, that model is also replaced with the default model. In Aggregation mode these two are not written and subagents follow the main model, so that after the main agent switches to another provider's model, subagents are not sent back to the default provider.

5. Advanced options. The "Full URL" switch is only useful for gateways with non-standard endpoint paths and has moved into the advanced options; for cards that already have it on, the advanced options expand automatically when editing. User-Agent and request overrides are merged into one block, with a single note that they only take effect in Routing and Aggregation modes.

Throughout the form: descriptions move into "?". What a field is and when to use it now sit in the "?" after the field name; the page keeps only the consequences you need to watch for, such as having to restart Codex after changing the model list, or a 400 error when the max output exceeds the actual limit. On managed-account cards (Codex sign-in, xAI sign-in and Copilot), fields the backend never reads are no longer shown; the notice about leftover fields from older versions is shortened to one sentence; the description of Claude Desktop's model modes is now one sentence: use Direct when the provider offers native Claude models, and Model Mapping for third-party models such as DeepSeek and Kimi.

New

"Settings → Local routing" adds "Connection address". The proxy address CC Switch writes into client configs (including Claude Desktop's gateway address) used to always be derived from the listen address, and when listening on 0.0.0.0 it wrote 127.0.0.1. Claude Desktop sessions in WSL2 (NAT mode) cannot reach Windows' loopback, so they could never connect, and changing the listen address to 0.0.0.0 did not help. Now set the listen address to 0.0.0.0 and enter a Windows address that WSL can reach in "Connection address", and the proxy address written to clients uses it instead. Saving rewrites the clients currently going through Routing right away, without restarting the routing service. This setting is stored only on this device and is not carried to other devices by cloud sync.

New presets: SoruxGPT, IKunCode, RunToken, BotCF, YYLX, TokenFlux and OpenModel.

Fixes

When Codex created a new thread or ran an automation, DeepSeek and other upstreams returned 400 and the whole thread became unusable. When the Codex desktop app creates a new thread, it inserts into the history a tool result with no matching tool call (the create_thread receipt). When Routing converted Responses to the Chat protocol, such results used to be sent as role=tool messages, and strict Chat upstreams such as DeepSeek and OpenCode Zen rejected every request in that thread. Tool results with no matching call are now turned into a marked user message, and any images in them are still sent as images; tool results that have a matching call are handled exactly as before.
When Codex used xAI native Responses, it got 422 and the thread could not recover. The receipts the Codex desktop app inserts (new thread, automation update, heartbeat, cross-thread message) have no call_id, so xAI rejects the whole request with "missing call_id", and since the receipts stay in the history, nothing in that thread could be sent afterwards. Now, only for requests going to xAI, these receipts are rewritten into user messages with the same marker, keeping their text and images; entries with a call_id and other upstreams are not affected.
When Claude Code's upstream format was OpenAI Chat or Responses, Routing sent x-api-key. The request header used to depend only on the Key's variable name, so cards using ANTHROPIC_API_KEY sent x-api-key, which OpenAI-format upstreams do not accept. OpenAI formats now always use Authorization: Bearer, and for Anthropic format the header is still decided by the variable name.
Claude Code Aggregation mode used only the default provider's compatibility switches. When a model from another provider was picked, requests could use features that provider does not support and fail. All members' settings are now merged according to the nature of each switch: features such as experimental betas, Artifacts and the auto mode server are turned off as soon as any one member turns them off; tool search, always-on effort, fine-grained tool streaming and similar are on only when all members turn them on. Switches related to the extra request body, thinking and the context window still follow the default provider.
The interface language was wrong at startup and only corrected itself after opening Settings. The language on the first screen came from the browser cache, so when the cache was empty or stale (for example after clearing WebView data, or copying ~/.cc-switch to a new computer), the system language was shown first. The saved language setting is now read and applied right at startup.
On macOS, API addresses on the local network could not be reached. CC Switch now asks macOS for "Local Network" permission. The first time it connects to a local network address, the system shows an authorization prompt, and that request may still fail; click "Allow" and try again. If you denied it before, turn on CC Switch under "System Settings → Privacy & Security → Local Network".
The page flashed when opening the provider edit panel. The edit panel used to open a loading page first and then switch to the content; it now opens once the content is ready, keeping the same fade-in as the add panel.

Other: The Flatpak build docs fix how the --bundles argument is written, and explain how to skip the update bundles when you don't have a signing private key.

Upgrade Notes

The database schema is unchanged, still at 20. The new presets only affect newly added providers.

Thanks

Thanks to @NeeYoonc (tool results in Codex threads with no matching call no longer causing 400 from Chat upstreams), @allenxu09 ("Connection address" for local routing), @chivopic (macOS Local Network permission), @NestorRay (the flash when opening the edit panel) and @zydo (Flatpak build docs) for their contributions.

Thanks to @loulanyue for submitting a fix for the same issue earlier, and to @OriyukiAkari for confirming through testing that xAI native Responses had this issue too. Thanks to @Z-Eternal, @xulimeng2022, @flame916, @hej56230-commits, @Soliton1912, @gggjjto, @KinJ and @xue-ding-e for reporting issues, providing reproduction details and helping verify fixes.

For the full technical details, see the CHANGELOG.

12 KiB Raw Permalink Blame History