CC Switch 4.0 Aggregation Mode and One-Click Import
As of 2026-10-13, CC Switch 4.0 splits direct, routing and aggregation into three tabs at the top of each app page: the official release notes describe the new aggregation mode as putting models from several providers into one model list in Claude Code or Codex, and each request goes to the provider of the model you pick, with no need to leave the client. Everything this page says about CC Switch follows its GitHub release notes and README: v4.0.0 was published 2026-10-04 and v4.0.10 on 2026-10-12, and the newest entry in the official release list at check time is v4.0.11, published 2026-10-13. There is no command-line build of CC Switch itself — the official README says it only ships as a desktop app that requires a graphical interface — and since v4.0.10 a ccswitch:// import link is no longer lost when the app is closed, can declare its API format, and can ask whether to switch right after importing.
Updated 2026-10-13
Point this tool at the QCode endpoint — one key for Claude, GPT and Chinese models.
- Billed per token — live rates on /models
- Pay by card (Visa / Mastercard / AMEX), Apple Pay, Google Pay or crypto
- Self-service: top up and activate instantly
Four things worth knowing
Direct / Routing / Aggregation
Per the official notes, each app page now opens with these three tabs; clicking a tab only changes what you are looking at and does not touch your configuration, the button that really switches modes spells out what will happen, and going back to direct is one step with undo.
Claude Code version aggregation needs
The README's aggregation notes state that aggregation does not provide failover and that Claude Code requires version 2.1.243 or later; after the aggregated list changes Codex needs a restart, Claude Code does not.
One-click import links
The focus of v4.0.10. Official wording: clicking a link while the app is not running no longer loses it — the link is stored first and only counts as handled once the confirmation dialog appears. The dialog gained a switch-to-this-provider-after-import toggle, off by default.
The link declares the API format
A new site-owner parameter in v4.0.10: one parameter declares which API format the service speaks (anthropic, openai_chat, openai_responses and others) and CC Switch maps it to each app's own fields; links without it behave exactly as before.
What aggregation mode actually does
As of 2026-10-13, aggregation is the third connection mode CC Switch 4.0 adds, and the release notes describe it as a mode that puts models from several providers into one model list in Claude Code or Codex so you can switch inside the client. The pain point is equally specific — previously, to use another provider's model you had to go back to CC Switch, switch providers, then return to your client; now you add several providers and their models all appear in the client's model picker, and each request goes to the provider of the model you pick. The official limits are just as clear: aggregation has to be turned on manually, currently supports Claude Code and Codex, dispatches requests by the model you chose, and does not provide failover — format conversion and failover belong to routing. The README adds two more preconditions: Claude Code must be 2.1.243 or later, and Claude official subscriptions are currently unsupported in aggregation. This release also rewrites how configuration is written: switching a provider now replaces only address, credentials, model and protocol, and everything else is kept as it was.
What the official releases say and when they shipped
The v4.0.0 body opens by calling it the largest update CC Switch has had; the GitHub release records published_at as 2026-10-04T11:01:01Z with the prerelease flag set to true. The v4.0.10 body is subtitled as the sixth fix release of the 4.0 stable line, its published_at is 2026-10-12T16:38:21Z with prerelease false, and its first sentence says the release centres on the one-click import deep link, alongside a Chinese, English and Japanese integration guide and an online link generator. The project then published v4.0.11 on 2026-10-13 (published_at 2026-10-13T15:35:29Z, prerelease false), the newest entry in the official release list when this page was checked; its notes describe that release as adding an uninstall action for installed tools on the Apps page and turning the plan quota query on by default in every app, not only in Claude Code. v4.0.10 also rewrote the connection-mode description to lead with each mode's strength: direct stays closest to the client's own setup, routing hot-swaps providers and offers failover and format conversion, aggregation switches between several providers' models inside the client. The notes give the background too: CC Switch was released in August 2025, when API formats differed far more, so provider switching was originally a full overwrite — now rebuilt to replace only key fields.
The timeline around 4.0
The earliest entry in CC Switch's official GitHub release list is v2.0.3, with published_at 2025-08-22T00:12:40Z; the v4.0.0 release notes also place CC Switch's arrival in August 2025.
v4.0.0 ships, with prerelease true in the GitHub metadata: the interface is rebuilt from the sidebar to the tray, aggregation arrives, and config writing changes from a full rewrite to replacing key fields.
v4.0.10 ships with prerelease false: ccswitch:// links survive a closed app, site-owner parameters such as apiFormat are added with an online link generator, and in routing mode the haiku alias written into settings.json moves from claude-haiku-4-5 to claude-haiku-5-5.
Confirmed vs not stated
Confirmed (verbatim in the official release notes and README)
Each item below can be checked word for word in the release bodies and README captured for this page: direct, routing and aggregation are split into three tabs, and clicking a tab leaves your configuration untouched; aggregation puts models from several providers into one model list in Claude Code or Codex and dispatches by the model you pick; aggregation is opt-in, currently covers Claude Code and Codex, provides no failover, requires Claude Code 2.1.243 or later, and does not support Claude official subscriptions; when the aggregated list changes Codex needs a restart while Claude Code does not; provider switching moved from a full rewrite to replacing address, credentials, model and protocol only; v4.0.10 fixes the lost deep link when the app is closed, adds the switch-after-import toggle in the confirmation dialog (off by default) and the apiFormat parameter; the online generator covers providers, MCP, prompts and skills; the release dates are 2026-10-04 for v4.0.0, 2026-10-12 for v4.0.10 and 2026-10-13 for v4.0.11, all read from the GitHub published_at field.
Unverified and not stated by the project
Three things have no first-hand source, so do not plan around them. First, a command-line build of CC Switch itself: the README states the app only ships as a desktop program needing a graphical interface, and the one exception it names is a community-maintained CC Switch CLI, a separately released project — this page therefore publishes no commands for driving CC Switch from a terminal. Second, the official release pages disagree about what counts as stable: v4.0.0 carries prerelease true, while v4.0.10 calls 4.0 the stable line and carries prerelease false, and v4.0.11 carries prerelease false too; this page only lists the published_at dates and draws no conclusion. Third, online arguments about which similar tool is better have no verifiable source and are not repeated here, and although v4.0.10 states its database structure is still 20, that is no compatibility promise for later versions.
Direct, routing, aggregation: how to choose
Direct vs routing
In the official split, direct connects the client straight to the provider and suits everyday use; routing forwards through a local routing service on your machine to one provider, can convert API formats and set up failover, and suits incompatible formats or failover needs. A Codex provider pointed at QCode does not need it: QCode's docs say the local routing mapping switch in the Codex provider editor exists for services that only speak Chat Completions, and that it should stay off for QCode, which offers the Responses protocol itself.
Routing vs aggregation
Both run through the local routing service on your machine; the difference is dispatch. Routing sends requests to one provider, aggregation spreads them across several by the model you choose, which is what you want when mixing models inside one session. Aggregation offers no failover, has to be turned on manually, currently covers only Claude Code and Codex, and does not support Claude official subscriptions. The notes also warn that switching models mid-session makes the new model rebuild its prompt cache, so the first turn after a switch costs noticeably more.
Adding QCode in CC Switch 4.0
① Install or upgrade: the official README gives desktop packages and package-manager commands — the msi or portable zip on Windows 10 and above, brew install --cask cc-switch on macOS 12 and later, paru -S cc-switch-bin on Arch, and .deb, .rpm or .AppImage builds for other Linux distributions. For terminals the README is explicit that CC Switch itself only ships as a graphical desktop app; for servers, SSH sessions or machines without a desktop environment it points at the community-maintained CC Switch CLI, a separately released project with an interactive terminal UI and a command-line mode, installable with brew install cc-switch-cli, and it warns that the two share the ~/.cc-switch data directory by default and that the CLI's supported database version sometimes lags behind the desktop app. ② Claude side, following QCode's docs: start CC Switch, pick Claude in the app switcher, click the plus button to add a provider, choose the custom preset, set ANTHROPIC_BASE_URL to https://api.qcode.cc/api and ANTHROPIC_AUTH_TOKEN to the cr_ key from your console, save, then click Enable on that card — CC Switch writes both values into ~/.claude/settings.json — and run claude in a terminal to check the connection. ③ Codex side: add a custom provider under Codex with Base URL https://api.qcode.cc/openai; the config.toml in the docs names the provider qcode (the docs recommend lowercase, so it works as the TOML key name) with wire_api responses, and lists gpt-6-sol or gpt-5.6-terra as the default model; leave the local routing mapping switch off, and take your Codex version from codex --version on your own machine. ④ To use aggregation: open the Aggregation tab on the Claude or Codex page, add the providers you want to mix, then pick one as the default so requests that do not name an aggregated model go to it, and restart the client when the model list changes — the Codex CLI banner can restart its background service in one click. ⑤ To import through a link: after clicking a ccswitch:// link the import confirmation dialog appears; turn on the switch-after-import toggle if you want it applied immediately — when it is on, the dialog states that client requests will be sent to the address inside the link; QCode's docs add that the first launch triggered by a deep link rebuilds the window and is a little slower.
On QCode
CC Switch is not itself an inference endpoint — it only writes each CLI's configuration file, and the work is done by the key you get from QCode. One cr_ key from the console covers both protocols, because the key does not care about the protocol: the path decides it. The Claude provider takes ANTHROPIC_BASE_URL https://api.qcode.cc/api (Anthropic protocol, full path /api/v1/messages); the Codex provider takes base_url https://api.qcode.cc/openai with wire_api responses. Claude models only run on the Anthropic protocol endpoint, and putting one into the OpenAI-compatible path returns an error. Callable model IDs on QCode include claude-sonnet-5, claude-sonnet-5-5, claude-opus-5, claude-opus-5-5, claude-haiku-5-5, gpt-6.1-sol, gpt-6-sol, gpt-5.6-sol and gpt-5.6-terra. Setup is prepaid: you top up first and then buy a plan from that balance; Alipay, WeChat Pay, credit cards (Visa, Mastercard, AMEX), Apple Pay, Google Pay and cryptocurrency (many coins and networks) are all supported, with renminbi top-ups starting at ¥100 and dollar top-ups ranging from $1 to $2,000. Billed per token; per-model rates are listed on /models.
Frequently asked questions
What is aggregation mode in CC Switch 4.0?
It puts models from several providers into one model list. The official release notes describe the new aggregation mode as placing models from several providers into the same model list in Claude Code or Codex so you can switch inside the client: each request goes to the provider of the model you pick, with no need to leave the client. It has to be turned on manually, currently supports Claude Code and Codex, dispatches by the model you select, and does not provide failover.
Is there a CLI version of CC Switch?
Not of CC Switch itself. The README answers the question about a command-line or headless version directly: CC Switch only ships as a desktop app that requires a graphical interface. For servers, SSH sessions or machines without a desktop environment it recommends the community-maintained CC Switch CLI, a separately released project offering both an interactive terminal UI (TUI) and a command-line mode, installable with brew install cc-switch-cli; by default it shares the ~/.cc-switch data directory with the desktop app, and the README warns that the database version the CLI supports sometimes lags behind the desktop app. The other CLI-related feature in the README is the Apps page, which shows and updates the versions of command-line tools such as Claude Code and Codex — that is managing those tools, not driving CC Switch from a terminal. So this page lists no commands for driving CC Switch from a terminal; the install commands it quotes are the README's own.
Is a ccswitch:// import link lost when the app is closed?
No, not since v4.0.10. The official notes describe the old behaviour: on Windows and Linux clicking an import link with CC Switch not running started the app but showed no confirmation dialog, lightweight mode lost it during window rebuilds, and macOS asked twice for the same link. Now the link is stored first and is only treated as handled once the dialog appears, so an interruption does not drop it and an older link arriving later does not overwrite a newer one. QCode's docs add that the first launch triggered by a ccswitch:// deep link rebuilds the window and is a little slower.
Which endpoints go into the Claude and Codex providers in CC Switch?
Store one QCode provider for each client: the Claude entry takes ANTHROPIC_BASE_URL https://api.qcode.cc/api with your cr_ key, and the Codex entry takes base_url https://api.qcode.cc/openai with wire_api responses. Both use the same QCode.cc API Key, and QCode's docs say they share your plan quota and are not billed twice. Claude models only run on the Anthropic protocol endpoint and cannot be entered into the OpenAI-compatible one.
What should I watch out for in aggregation mode?
Five points the project states. Claude Code must be 2.1.243 or later; aggregation does not provide failover; it has to be turned on manually and currently supports Claude Code and Codex, with Claude official subscriptions currently unsupported; after the aggregated list changes Codex needs a restart while Claude Code does not; and switching models mid-session makes the new model rebuild its prompt cache, so the first turn after the switch costs noticeably more.
How do I top up QCode from mainland China?
With Alipay or WeChat Pay. QCode's payment docs state that for payments in renminbi from mainland China Alipay is the first choice — its fee is not passed on — with WeChat Pay as the alternative, and both credit a renminbi balance; the page also states the floor for renminbi top-ups is ¥100. After topping up, copy your cr_ key from the console into the custom CC Switch provider entry. Billed per token; per-model rates are listed on /models.
Sources
CC Switch side: the bodies and metadata of two GitHub releases in the official repository farion1231/cc-switch — v4.0.0 (published_at 2026-10-04T11:01:01Z, prerelease true) and v4.0.10 (published_at 2026-10-12T16:38:21Z, prerelease false) — plus the README on the main branch, all captured on 2026-10-13. QCode side: the docs.qcode.cc page for CC Switch setup (marked updated 2026-10-08), the endpoints and API paths page, the payment methods overview (updated 2026-10-01), captured the same day. The v4.0.11 release notes and the official release list were retrieved on 2026-10-14.
One API Key for Claude Code and Codex alike
Fill https://api.qcode.cc/api in the Claude entry and https://api.qcode.cc/openai in the Codex one; both providers use one and the same QCode.cc API key and share your plan quota. Billed per token; per-model rates are listed on /models.
Related reading
CC Switch guide: switch APIs in Claude Code and Codex
Creating a custom QCode provider on the Claude page, setting ANTHROPIC_BASE_URL to https://api.qcode.cc/api with your cr_ key, clicking Enable to write settings.json, and a separate Codex entry on /openai, plus what to do when a switch does not take or a 401 appears.
Codex CLI third-party API setup: config.toml, base_url, errors
How model_provider, base_url, wire_api and env_key fit together in config.toml, and how to read the common errors.
How to use Claude Code in China (2026): Alipay and WeChat Pay
Point ANTHROPIC_BASE_URL at QCode from the mainland, then top up with Alipay or WeChat Pay.
The statements on this page were checked on 2026-10-13, and the release records behind the current newest version were captured and checked again on 2026-10-14. CC Switch is a third-party open-source tool (MIT licence): its features, interface wording and switching behaviour are governed by its official release pages and README, this page makes no compatibility promise on its behalf, and it does not speak for either project. QCode configuration fields and payment details follow the official docs; changes there may happen without notice. Model availability is whatever /models shows.