CC Switch v4.0.10

The sixth fix release for 4.0 stable

This release focuses on one-click import links (ccswitch:// deep links): clicking a link while CC Switch is not running no longer loses it; links can declare the API format, import Pi providers and bring the site's own icon; Codex and Grok Build links keep the provider's own configuration instead of having it replaced with a fixed template; and the confirmation dialog lets you choose whether to switch right after import. Site owner guides in Chinese, English and Japanese and an online link generator are also published. Provider icons can now be uploaded from local images, and once saved to "My Icons" any provider can use them; the usage page adds first-token time, which can be estimated from session logs even when routing is off. It also fixes upstreams that require thinking rejecting Claude Code's haiku-tier requests in Routing mode, Codex sessions left by using an official account through routing in v3.20 and earlier failing to open, and Grok Build third-party providers being unable to generate session titles. For everything new in 4.0, see the v4.0 release notes.

One-click import links

What changes for users

Clicking a link while CC Switch is not running no longer loses it. On Windows and Linux, clicking a one-click import link while CC Switch was not open used to start the app, but the import confirmation dialog did not appear; in lightweight mode the link was also lost when the window was recreated. On macOS the same link brought up the confirmation dialog twice. Links are now stored first and only count as handled once the confirmation dialog has been shown, so they are not lost if something interrupts along the way, and an older link arriving later does not overwrite a newer one.
The confirmation dialog lets you choose whether to switch right after import. The confirmation dialog for provider links adds a "Switch to this provider after import" switch, off by default; when it is on, the dialog warns that client requests will be sent to the address in the link. Coexist-mode apps such as OpenCode, OpenClaw, Hermes and MiniMax Code get a switch like "Add to the OpenCode config after import", and Pi gets "Enable in Pi after import"; these two kinds are on by default. For prompts it is "Enable after import". The enabled value in a link only sets the switch's initial state. With the switch off, only the provider is saved and the client config is not changed, even if this is the app's first provider.
Links with a usage query script turn on usage query by default after import. A site owner attaches a script to the link because they want you to see your balance right after import; previously you had to turn it on manually. Links that set usageEnabled=false still keep it off; links without a script behave as before. The script runs in a sandbox and can send only one request, over HTTPS to the same origin as the provider address, and the confirmation dialog still shows the full script as before.
Codex links keep the provider's own configuration. When a link carried a full config.toml, only the Key, address and model used to be taken out and put into a fixed template, losing the provider's authentication method, request headers, WebSocket support and model catalog URL. Now the parts that belong to this provider are kept: connection and authentication fields, model, reasoning effort, context window, subagent model and so on; the model catalog URL is kept only when it has the same origin as the API address, because Codex sends the provider's credentials when fetching it. Global settings such as [features], MCP and permissions are not imported. Provider configurations that would make Codex run commands or read local credentials (auth, aws, gateway_oauth, env_http_headers) are rejected outright. Links without a configuration import exactly as before.
Grok Build links keep the model configuration. Links with a config.toml used to be replaced with a fixed template too, losing the display name, description, API type and context window. Now the model table that [models] default points to is kept, while the address, Key and model still come from the link parameters; links that use auth_provider, env_http_headers or mtls_cert_dir are rejected. A provider takes only one table in Grok Build, so other model tables are not imported.
Values that would be expanded and executed are always rejected. Coexist-mode apps expand some special syntax in their configs: in Pi, values starting with ! are run as commands and $NAME / ${NAME} read environment variables; OpenCode has {env:} / {file:}; OpenClaw and Hermes have ${...}. When a link contains this syntax, it could run commands or send secrets and file contents from this machine to the address in the link. This is now checked when parsing the link, merging configs and building the provider, and the import is rejected if any is found.
Other: Links with configUrl now say it is not supported as soon as they are opened, instead of failing after you confirm; prompt links support MiniMax Code, and MCP links support Pi and MiniMax Code; the tray menu refreshes right after a provider is imported.

New parameters for site owners

apiFormat: One parameter declares the upstream API format (anthropic / openai_chat / openai_responses / gemini_native), and CC Switch turns it into each app's own fields. Non-native formats for Claude Code, Codex and Grok Build need local routing to be on; combinations an app does not support are rejected when the link is parsed. Links without this parameter behave as before.
Pi provider links: Newly supported. After import they are written to Pi's models.json, and the link must include a model.
iconUrl: The https address of the site's own logo. It is downloaded and shown at the top as soon as the confirmation dialog opens, and becomes the card's custom icon after import; if the download fails, the import still goes ahead and the card falls back to a built-in icon or the first letter of the name. The image is redrawn and saved as a small PNG; the address itself is neither saved nor rendered. Downloads connect only to public addresses and pin the resolved result, so a second DNS lookup cannot point somewhere else; each redirect hop is checked, up to 3 hops. No system proxy, no cookies, a 5-second timeout, 256 KB maximum, and the file type must match the content.

Site owner guide and online generator

Site owner integration guide (also in 中文 and 日本語): how to generate links, how to put a "one-click import" button on your page (the link is fetched from your backend when the button is clicked, so the Key never appears in the page source), what to show when the user hasn't installed CC Switch, and how to attach a usage query script. Sites built with New API or Sub2API already have an "Import to CC Switch" button in their Key list; the difference is that New API links carry no usage query script, so users don't see a balance after import.
Online link generator: changed from a test page into a generator for site owners, covering four kinds of links (provider, MCP, prompt, Skill), listing the apiFormat options available for each app, with built-in usage script templates, and checking icon / iconUrl with the same rules as the app. The generator link in the user manual pointed to a GitHub Pages address that was never set up and opened a 404; the manual and README now point here.

New

Provider icons can be uploaded from local images and kept in "My Icons" for reuse. The icon picker is split into two groups, "My Icons" and "Built-in Icons", and the search box filters both. Click "Upload", the first tile in "My Icons", pick a PNG, JPG, WebP or SVG (up to 2 MB) and give it a name (the file name by default), and it is saved to "My Icons" and used for the current provider; from then on other providers and other apps can pick it directly without uploading it again, and uploading the same image again reuses the existing entry. Hover over an icon to rename or delete it; cards store the image itself, so renaming or deleting does not affect providers already using it. Images are shrunk to a 96×96 PNG, and "My Icons" and provider configs both travel with cloud sync, with no separate files saved on disk; SVGs are converted to bitmaps first, any scripts and external requests inside them are not run, and the original file does not go into the database. Site icons brought in by one-click import links are shown as "Current icon" and can be saved to "My Icons". In the picker, one click on an icon now selects it and closes the picker; to remove the icon, click "Clear icon" next to the search box.

The usage page shows first-token time. The routing service has always recorded first-token time, but it used to be visible only in hover tooltips and request details. Provider stats and model stats now have a "First token" column, which takes the median of successful streaming requests through the routing service, so occasional slow requests from queuing or cold starts don't pull it up; the request log also adds a "First token" column after "Speed". When routing is off, it is estimated from session log timestamps and shown with ≈: for Claude Code, from replies that start with thinking; for Codex, from timestamps written by newer versions; replies that start with body text or a tool call have no estimate. Records imported before the upgrade are not backfilled.

Usage query adds a Sub2API template. The templates in "Configure usage query" add Sub2API, which needs only the provider's Key and address, with or without /v1; it shows the plan name, and unlimited subscriptions no longer show as a negative balance.

New presets: NekoCode (Claude Code, Claude Desktop, Codex, OpenCode, OpenClaw, Hermes, Pi; MiniMax Code uses the Pi preset). YYLX is shown as 「鱼鱼连线」 in the Simplified Chinese interface (「魚魚連線」 in Traditional Chinese); the English interface still shows YYLX.

Fixes

In Routing mode, upstreams rejected Claude Code's haiku-tier requests (#8118). Routing mode writes fixed model aliases into settings.json, and Claude Code decides how to send thinking parameters based on the alias. The haiku tier used to be written as claude-haiku-4-5; Claude Code considers that model able to turn thinking off, so it sent requests with thinking turned off, which upstreams that require thinking reject outright. It is now claude-haiku-5-5, sent the same way as the sonnet and opus tiers. Routing itself still maps by the "haiku" keyword, so the model it picks does not change.
Codex sessions left by using an official account through routing in v3.20 and earlier could not be opened (#7948). From v3.17 to v3.20, when an official account went through local routing, Codex recorded its sessions under cc-switch-official; v4.0 no longer writes that table, so when Codex resumed those sessions it reported "Model provider cc-switch-official not found". CC Switch now moves them back to Codex's built-in openai group at startup, changing only the session records and not touching config.toml. These sessions used the official sign-in all along and Codex always treated them as OpenAI, so behavior does not change after the move.
Grok Build could not generate session titles with a third-party provider (#7003). When models.session_summary was not set, Grok Build generated titles with the built-in grok-4.6 but sent the request to the default model table's address, which third-party upstreams reject. Now, when you switch providers, session_summary follows the current provider if it is unset or points to a table CC Switch wrote, and it is removed when you switch back to the official account; a built-in model or a table you set yourself is left alone.
OpenRouter and Novita cards showed "Plan expired" when the balance was zero (#8148). When the balance was zero or negative, the Key actually still worked, but the card and the tray showed the plan as expired. They now show "Balance used up"; when the API returns a missing or malformed balance, an error is reported instead of treating it as a zero balance.
After switching models mid-thread in Codex, usage was recorded under the previous model. When the model is changed in Codex's thread settings, the log does not always get a new turn context, so usage import used to record later requests under the previous model name (or as unknown when there was no earlier record) and price them at the previous model's rate. That setting is now read. Records already imported are not rewritten automatically; if the source session logs still exist, click "Rebuild Codex Usage" under "Data sources" on the usage page (the database is backed up automatically before rebuilding).
After changing a config directory in Settings without clicking Save, changing another setting saved the directory too (#7849). When other settings auto-save, only confirmed directories are now included, and discarded drafts no longer stay in the input box either.
On Windows, the window flashed when opening the add or edit provider page. v4.0.9 fixed the edit page showing a loading page first, but the full-page fade still flashed on Windows. These two pages no longer fade in and out; other pages are not affected.
On Windows, a deleted desktop shortcut came back with every update. An MSI upgrade uninstalls the old version and then fully installs the new one, and it used to create the desktop shortcut again every time. It is now created only on a fresh install; on upgrade it is kept only if the original shortcut is still there.

Other: The description of "Connection mode" now leads with what each mode is good at: Direct is the most native, Routing can hot-switch providers and supports failover and format conversion, and Aggregation lets you switch seamlessly between models from several providers inside the client. All usage table columns are now left-aligned, and the provider and model columns in the request log give up some width to the number columns. The Japanese interface changes 「高級オプション」 to 「詳細オプション」.

Upgrade Notes

The database schema is unchanged, still at 20.

If Claude Code is already in Routing mode, CC Switch writes the new haiku alias into settings.json when it starts after the upgrade, and new Claude Code sessions will use it.
The Codex session migration runs automatically when CC Switch starts, once per Codex config directory, and the session records from before the change are backed up in the existing session-group migration backup directory. If you manually restored the cc-switch-official table and still use it, this migration is skipped.
The new presets only affect newly added providers.

Thanks

Thanks to @funkpopo (OpenRouter showing the plan as expired when the balance is zero, and Codex usage recorded under the wrong model after switching models mid-thread), @hulkbig (unconfirmed directories being saved when settings auto-save) and @NestorRay (the flash on Windows when opening provider pages) for their contributions.

Thanks to @hao-lin-lwh, @desmonna, @mossonli, @enderzcx, @nbcoming, @liyangdeamo-svg, @linhay and @aofee for reporting issues, providing reproduction details and helping verify fixes.

For the full technical details, see the CHANGELOG.

16 KiB Raw Permalink Blame History Unescape Escape