Usage guide · as of 2026-10-13

CC Switch Guide: Switch APIs for Claude Code and Codex in One Click

As of 2026-10-13, switching Claude Code's API with CC Switch works like this: on the Claude page, click + at the top right to create a custom configuration, set ANTHROPIC_BASE_URL to https://api.qcode.cc/api and ANTHROPIC_AUTH_TOKEN to your key starting with cr_, save, then click Enable on the card. CC Switch writes both values into ~/.claude/settings.json, and clicking Enable on another card switches you over to that one. For Codex, create a second configuration on the Codex page with the Base URL https://api.qcode.cc/openai. The 4.0 line now has stable releases: as of 2026-10-13 the newest stable one is v4.0.11, published on 2026-10-13 (the previous v4.0.10 came out on 2026-10-12); 4.0 adds Aggregation mode, v4.0.10 is about ccswitch:// one-click import links and v4.0.11 adds uninstalling installed tools from the Apps page, covered below. This page covers installation, setup, switching and common problems, based on the QCode docs and the official CC Switch README.

Updated 2026-10-14

Point this tool at the QCode endpoint — one key for Claude, GPT and Chinese models.

#Install and requirements#Claude Code setup#Codex setup#Switch not taking effect

Four things to know before you start

/api

Address for Claude Code

Set ANTHROPIC_BASE_URL to https://api.qcode.cc/api and ANTHROPIC_AUTH_TOKEN to your key starting with cr_; no trailing slash.

/openai

Address for Codex

Set the Base URL to https://api.qcode.cc/openai, not /openai/v1, and keep wire_api = "responses" in the generated config.toml.

Enable

The one click that switches

Claude Code and Codex each have exactly one enabled configuration at a time; click Enable on another card and CC Switch writes that set back into the config file.

v4.0.11

Latest stable release (as of 2026-10-13)

Published on 2026-10-13 (UTC); the 4.0 line went stable with v4.0.4 (2026-10-07), while v4.0.0 (2026-10-04) to v4.0.3 (2026-10-06) are marked as previews on GitHub.

What CC Switch actually does

As of 2026-10-13, CC Switch is an open-source (MIT-licensed) cross-platform desktop app for Windows, macOS and Linux that manages the API configurations of command-line tools such as Claude Code and Codex as cards: one click on Enable swaps in another set. The QCode docs describe it as a configuration profile switcher.

It is not an inference endpoint itself; it only writes each configuration into the tool's standard config file (~/.claude/settings.json for Claude Code, ~/.codex/config.toml for Codex), overwriting it when you enable a card and swapping it back when you switch. So Claude Code and Codex each have only one configuration in effect at a time, and two sets never apply together.

The official README says it offers one-click switching with no more hand-editing of JSON, TOML or YAML files; the list of supported tools changes between versions, so check the official README.

Recent CC Switch releases (as of 2026-10-13)

As of 2026-10-13, the newest stable release on GitHub Releases is v4.0.11, published on 2026-10-13 (UTC). Its release notes say the release adds uninstall: installed tools can be uninstalled from the Apps page, but only installations whose source can be confirmed, and configuration and session data are kept.

The release before it, v4.0.10 published on 2026-10-12, 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, 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 came out with it.

The start of the line, v4.0.0 on 2026-10-04, was marked as a preview, like v4.0.1 and v4.0.2 on 2026-10-05 and v4.0.3 on 2026-10-06; v4.0.4 (2026-10-07) is published as stable, and so are v4.0.10 and v4.0.11. The v4.0 notes say the new Aggregation mode puts models from several providers into one Claude Code or Codex model picker so you can switch right inside the client, that it is opt-in and currently supports Claude Code and Codex, and that it dispatches each request by the model you pick without offering failover.

The config-writing core was rebuilt, so switching replaces only the key fields instead of rewriting the whole file, and everything else is kept. The earlier v3.20.4, published on 2026-09-22, fixed a bug where editing or switching away from a Codex configuration wiped the saved API key. The QCode CC Switch doc was updated on 2026-10-08 and states it was verified against the official docs for v3.20.3 (2026-09-11), last checked 2026-09-18, so interface labels may differ between versions.

Release and documentation timeline

2026-09-11

CC Switch v3.20.3 ships; the QCode CC Switch doc was verified against the official docs for this version. Per the QCode doc, the Claude editor gains a Disable Artifact Tool quick toggle from this release.

2026-09-22

v3.20.4 ships, fixing a bug where editing or switching away from a Codex configuration wiped the saved API key; it was the newest stable release on GitHub until v4.0.4 made 4.0 stable on 2026-10-07.

2026-10-04

The v4.0.0 preview ships with the new Aggregation mode, replacing only key fields on a switch instead of rewriting the whole file; v4.0.4 (2026-10-07) is stable, and by 2026-10-13 the line had reached v4.0.11; the v4.0.10 before it (2026-10-12) focused on one-click ccswitch:// import links, and v4.0.11 adds uninstalling installed tools.

Confirmed vs undocumented or conflicting

Confirmed (verbatim in the docs)

Each of the following can be checked word for word in the QCode docs, the official CC Switch README, its user manual or the GitHub release notes: the Claude Code configuration takes ANTHROPIC_BASE_URL = https://api.qcode.cc/api and ANTHROPIC_AUTH_TOKEN = a key starting with cr_, and enabling it writes both into ~/.claude/settings.json; the Codex Base URL is https://api.qcode.cc/openai, and CC Switch generates ~/.codex/config.toml and ~/.codex/auth.json with wire_api = "responses"; the Codex panel's toggle for local proxy conversion, meant for services that only support Chat Completions, stays off for QCode; only one configuration is enabled at a time; the Claude and Codex configurations can share one key; CC Switch stores a separate key for each configuration; the connectivity check on a card does not verify the key; as of 2026-10-13 the newest stable release on GitHub is v4.0.11, published on 2026-10-13 (the previous v4.0.10 on 2026-10-12), v4.0.0 to v4.0.3 are marked as previews and v4.0.4 (2026-10-07) onward is stable; the v4.0 notes say Aggregation is opt-in and puts models from several providers into one model list, and the v4.0.10 notes say a ccswitch:// import link is not lost even when the app is not running.

Undocumented or conflicting

This page draws no conclusion on three points. First, whether Claude Code needs a restart after a switch: the official README says Claude Code supports hot-switching with no restart, and the FAQ in the official user manual says a restart is usually unnecessary, adding only that if the change did not take effect you should close and reopen the terminal or restart the IDE; issue #3057, cited in the QCode doc, records a running session that kept using the old configuration.

Test on your own version, and if requests still go to the old address, reopen the session. Second, whether enabling a configuration wipes your manual edits to settings.json: the QCode doc records reports of some versions overwriting the whole file and dropping enabledPlugins and hooks, and it advises backing up first; the v4.0 notes and the user-manual FAQ say a switch replaces only the address, credentials, model and protocol fields, while your own plugins, hooks, permissions, MCP and environment variables, comments and formatting are all kept as they are, and 4.0 has been stable since v4.0.4 (2026-10-07), but this page has not tested how that version actually behaves.

Third, a trailing slash on the Base URL: QCode endpoints require none, and how CC Switch itself handles one is, per the QCode doc, not covered by the official docs.

CC Switch or editing config files by hand

CC Switch vs hand-editing

Both change the same files: CC Switch writes ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN into ~/.claude/settings.json and base_url and related keys into ~/.codex/config.toml; it is not an inference endpoint itself. If you often move between several setups, for example between asia.qcode.cc and api.qcode.cc on a mainland China network, or between the official login and QCode for comparison, CC Switch saves time.

If you only use one setup, or work on a server without a desktop, editing by hand is more direct: CC Switch ships only as a desktop app that needs a graphical interface, and for machines without a desktop the official README recommends the community-maintained CC Switch CLI.

Claude Code vs Codex

In CC Switch they are two pages with two configurations: Claude goes to ~/.claude/ and Codex to ~/.codex/, without interfering with each other, so you simply run claude and codex in separate terminals. The difference is protocol and address: Claude Code uses the Anthropic protocol with https://api.qcode.cc/api, and Codex uses the OpenAI Responses protocol with https://api.qcode.cc/openai.

The QCode docs state that Claude models only work through the Anthropic endpoint and that Codex must use Responses; both configurations can take the same cr_ key.

Six steps: install, configure, switch

  1. 1Install: download a package from CC Switch's GitHub Releases. Windows 10 and later take the .msi or the portable .zip; macOS 12 and later take the .dmg, or brew install --cask cc-switch; Linux takes .deb, .rpm or .AppImage (officially glibc 2.35+ and WebKitGTK 4.1 are required), and Arch uses paru -S cc-switch-bin.
  2. 2Set up Claude Code: pick Claude in the switcher at the top, click + at the top right, choose Custom as the preset, and in the configuration JSON set ANTHROPIC_BASE_URL to https://api.qcode.cc/api and ANTHROPIC_AUTH_TOKEN to your cr_ key; the name is up to you, and the docs example uses QCode.cc.
  3. 3Save, hover over the card and click Enable; CC Switch writes both values into ~/.claude/settings.json. Run claude in a terminal to check.
  4. 4Set up Codex: switch to Codex, click + and choose Custom, set the Base URL to https://api.qcode.cc/openai, the API Key to the same cr_ key and the default model to gpt-6-sol or gpt-5.6-terra; the name is up to you, and the docs example uses lowercase qcode (handy as a TOML key), which appears in config.toml as model_provider = "qcode". Leave off the panel's toggle for local proxy conversion, which is meant for services that only support Chat Completions.
  5. 5Save, click Enable and run codex to check; config.toml should contain base_url = "https://api.qcode.cc/openai" and wire_api = "responses".
  6. 6To switch later, click Enable on another card or click the configuration name in the system tray. First open ~/.claude/settings.json (for Codex, ~/.codex/config.toml) to confirm the address changed; restart the terminal for Codex, and if Claude Code still uses the old address, close the session and open a new one. If you save a second copy for asia.qcode.cc, add a suffix such as (asia) to its name so you can tell them apart in the tray. Two more things changed after 4.0. The first is Aggregation mode: it is opt-in from v4.0, the README says Claude Code 2.1.243 or later is required, and it offers no failover; once you add several providers, their models all appear in the Claude Code or Codex model picker and each request goes to the provider of the model you pick. For how to use it, see the separate CC Switch 4.0 Aggregation mode page on this site. The second is one-click import links: a ccswitch:// link on a provider's own website sets the configuration up for you, and from v4.0.10 (2026-10-12) the link is not lost even if CC Switch is not running, while the confirmation dialog lets you choose whether to switch right after import.

On QCode

On QCode, the Claude Code and Codex configurations can take the same cr_ key (created in the console): the key works across protocols, and the request path decides which protocol is used. The Claude Code configuration uses https://api.qcode.cc/api with models such as claude-sonnet-5, claude-sonnet-5-5 or claude-opus-5, and you can also change models with /model inside Claude Code; the Codex configuration uses https://api.qcode.cc/openai with gpt-6-sol or gpt-5.6-terra.

The three access domains offer the same features and accept the same key: us.qcode.cc serves North America and Europe, and for networks in mainland China the docs recommend asia.qcode.cc, with the paths unchanged, so you can keep one CC Switch configuration per domain. Sharing one key across the two configurations does not lead to double charges; usage is billed per token, and each model's rate is on /models. Every request can be looked up on probe.qcode.cc by entering your key.

Frequently asked questions

CC Switch switched, but Claude Code didn't pick it up. What now?

Check the file first, then reopen the session. Open ~/.claude/settings.json and confirm that ANTHROPIC_BASE_URL now shows the set you just enabled; if the file changed but the session didn't, close the running claude and start it again in a new terminal. Issue #3057, cited in the QCode doc, records exactly this: Claude Code reads the env block of settings.json into environment variables when the process starts, and a running session does not reread it. On whether a restart is needed at all, both official sources now say it usually is not: the official README says Claude Code supports hot-switching with no restart, and the user-manual FAQ says a restart is usually unnecessary, adding that if it did not take effect you should close and reopen the terminal or restart the IDE; for Codex, both say to restart the terminal. Switching from the tray writes the same file and does not end a running claude for you. If you use Aggregation, there is one more layer: the official README and the user-manual FAQ say changes to Claude Code's aggregated models take effect immediately, while Codex needs a full restart whenever you enter or leave Aggregation or change the aggregated model list. Aggregation is covered on the separate CC Switch 4.0 Aggregation mode page on this site.

How do I track down a 401 Unauthorized?

Usually one configuration has the wrong key. Make sure the key starts with cr_ and has no leading or trailing spaces, then check in the console that it is still valid. If Claude Code returns 401 while Codex works (or the other way round), the faulty one is that configuration: CC Switch stores a separate key per configuration, so update each one when you change keys. Also note that the connectivity check on a card only tests whether the address is reachable; the official user manual states that it does not verify the key, so a passing check does not prove the key is right.

Codex just keeps spinning after launch. What should I check?

Check ~/.codex/config.toml first. base_url should end at /openai, not /openai/v1, and wire_api = "responses" must stay. The QCode doc says the most common cause is a missing top-level model_provider, or one that does not match the [model_providers.xxx] table name; Codex then falls back to its built-in openai endpoint. After fixing it, reopen the terminal and run codex again.

Can I use Claude Code and Codex at the same time?

Yes. CC Switch writes the Claude configuration to ~/.claude/ and the Codex one to ~/.codex/; they don't interfere, so just run claude and codex in separate terminals. Both can take the same cr_ key: Claude Code at https://api.qcode.cc/api, Codex at https://api.qcode.cc/openai. The QCode docs state that sharing one key this way does not cause double charges just because you created a second configuration.

I edited settings.json by hand. Will enabling another configuration erase my changes?

Officially no, for the current version — this page has not tested it, so backing up before you enable is the safe move. The QCode doc states that when you enable a configuration, CC Switch overwrites the matching fields in ~/.claude/settings.json with that configuration's values, that it advises a backup beforehand, and that some versions were reported to overwrite the whole file, dropping enabledPlugins and hooks; the v4.0 release notes and the user-manual FAQ say switching now replaces only the key fields, while plugins, hooks, permissions, MCP and the environment variables you added yourself, comments and formatting are all kept as they are, and 4.0 has been stable since v4.0.4 (2026-10-07). If something is lost, restore it from ~/.cc-switch/backups/ (the official docs say the 10 most recent are kept) or from an export named cc-switch-export-{timestamp}.sql. Also, on first launch CC Switch imports your existing Claude Code and Codex setup as a configuration named default.

How do I switch back to the official Anthropic login?

Pick the built-in official configuration in the list (Claude Official for Claude Code, OpenAI Official for Codex; if you deleted it, add it back from the presets), click Enable, restart the CLI and go through the tool's own login flow: /login in Claude Code, codex login for Codex. After that you can move back and forth between the official login and your QCode custom configuration. The QCode doc warns against hand-building a hybrid config with an empty env block that still keeps a cr_ key.

Sources

Setup, addresses and troubleshooting: the QCode docs page on CC Switch (updated 2026-10-08; it states it was verified against the official docs for CC Switch v3.20.3 (2026-09-11) and last checked on 2026-09-18) and the page on endpoints and API formats (which protocol uses which endpoint, the three access domains and the trailing-slash rule), both crawled on 2026-10-13. CC Switch's own installation steps, system requirements, switching behavior, connectivity check and official login: the README in the CC Switch GitHub repository (MIT license) and the FAQ page of the official user manual, crawled the same day. Versions and dates: the GitHub Releases API and release notes for CC Switch (v3.20.4, v4.0.0 to v4.0.4, v4.0.10 and v4.0.11, with their publish dates and preview or stable flags), crawled the same day.

Connect CC Switch to QCode

One cr_ key: Claude Code at /api, Codex at /openai, one click on Enable to switch. Billed per token; see /models for each model's rate.

Not sure where to start?

Try it for a week

Small Pack: $4 for $30 of quota, valid 7 days

Use it every day

Starter: $9.00/month with $5 of quota every day — just $0.060 per $1 of quota, vs about $0.113 for the Medium Pack