CC Switch Setup: Claude Code & Codex (2026)

Add QCode.cc to CC Switch for Claude Code and Codex CLI: provider forms, one-click switching, official-login coexistence, and restoring an overwritten config.

Need an API key? Sign up →·Endpoints & base URLs →

Last verified: 2026-09-18 · 📄 Per official docs (CC Switch v3.20.3, released 2026-09-11)

At a glance¶

CC Switch is a cross-platform desktop application (Windows / macOS / Linux) that manages API provider configurations for 9 tools from one UI: Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, MiniMax Code (list from the official README; the manual's screenshots lag slightly behind). This guide shows how to add QCode.cc as a custom provider in CC Switch, how to switch between multiple providers/accounts with one click, and covers common use cases and troubleshooting.

Why Use CC Switch¶

• No manual config editing: Visual forms replace settings.json / config.toml
• One-click provider switching: Switch between qcode.cc, official Anthropic, and local proxies instantly
• Claude + Codex ecosystem: Manage both Claude Code and Codex CLI configurations in a single app
• Multi-account / multi-plan management: Save several configs for the same provider (e.g. a work key and a personal key) and switch anytime
• System tray shortcuts: Switch providers from the tray menu without opening the main window

At its core, CC Switch is a "config profile switcher" — it writes each provider config into the standard config file of the corresponding CLI, overwriting on activate and swapping back when you switch. Understanding this prevents the misconception that multiple providers are active at once.

Prerequisites¶

• Claude Code CLI or Codex CLI installed
• A QCode.cc API Key (starts with cr_), available from the dashboard
• The same key works across multiple protocol endpoints (Anthropic, OpenAI, Gemini, etc.) — see Endpoints & API Formats

Install CC Switch¶

Download the installer for your platform from GitHub Releases:

Exact install steps and signing prompts per platform follow the project README.

Configure Claude Provider (for Claude Code)¶

Launch CC Switch → pick Claude in the top app switcher → click the “+” (Add provider) at the top right → in the app-specific providers tab choose Custom from the preset dropdown → edit the config JSON in the panel (UI wording shifts between versions; go by what your build shows):

Why asia.qcode.cc? It's QCode.cc's Asia node (nearest of Korea / Taiwan / Hong Kong) with the lowest latency for mainland China users; switch back to api.qcode.cc (global Route 53) if it's unstable. The same key works across all three domains: api / asia / us.

After saving, click Enable on the card (the card action buttons appear on hover) to make it the current Claude provider. CC Switch will automatically write ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN to ~/.claude/settings.json. Run claude in your terminal to verify the connection.

Choosing a Default Model¶

QCode.cc offers a full lineup from flagship to lightweight models. Switch in Claude Code with /model, or specify directly in config:

Rates and context sizes: read them live on qcode.cc/models — this page deliberately no longer copies numbers. Full lineup (GPT, Gemini, China-family models) is on the same page. Since v3.20.3 the Claude provider editor also has a per-role model mapping panel (Sonnet / Opus / Fable / Haiku / subagent) with a one-click apply-to-all-roles button.

Configure Codex Provider (for Codex CLI)¶

Pick Codex in the top app switcher → “+” Add provider → Custom → fill in as follows:

⚠️ The Codex provider editor has a “Needs Local Routing” toggle meant for upstreams that only speak Chat Completions. Leave it off for QCode — QCode serves the Responses protocol natively, and enabling it would require a local proxy to stay up.

CC Switch generates the equivalent ~/.codex/config.toml and ~/.codex/auth.json:

model_provider = "qcode"
model = "gpt-6-sol"
model_reasoning_effort = "high"

[model_providers.qcode]
name = "qcode"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true

Save, click Enable, then run codex to verify the connection. GPT model options: gpt-6-sol / gpt-5.6-terra / gpt-5.6-sol (rates and context: qcode.cc/models). Read the Codex CLI version from codex --version on your machine; do not trust a historical number in this page.

Switching Between Multiple Providers/Accounts¶

The core value of CC Switch is switching. A common setup:

1. Under the Claude tab, save several providers, e.g. QCode.cc (primary), QCode.cc (asia) (mainland node), Anthropic Official (backup).
2. To switch, click Enable on the target provider's card — CC Switch rewrites the corresponding ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN into ~/.claude/settings.json.
3. Make the new config live: the official README says Claude Code currently hot-switches provider data; the official FAQ and issue #3057 document the other case — settings.json on disk is already new, but the running session still hits the old provider. If the current session is still on the old node, close it and open a new terminal before running claude again. Codex and other CLIs: always reopen the terminal (FAQ).
4. Codex works the same way: switching the active item under the Codex tab rewrites ~/.codex/config.toml.

Tray shortcut: CC Switch stays in the system tray; since v3.13.0 the right-click menu is grouped into per-app submenus (Claude / Codex / Gemini), each submenu titled with the currently enabled provider and a usage summary — click a provider name to switch. Tray switching writes the same live files as Enable in the main window; pitfalls are in “After you are connected” below.

Multi-account / Multi-plan Example¶

Save two configs for the same QCode.cc account, each with a different API Key:

Switching the active provider seamlessly moves between the two quotas without mixing billing.

Use Cases¶

• Unstable network in China: Use asia.qcode.cc as primary, and one-click switch to the global api.qcode.cc when it jitters.
• Comparing providers: Run the same task through QCode.cc and official Anthropic to compare responses and cost.
• Team / personal separation: Use different keys to separate work and personal usage for easy accounting.
• Claude + Codex together: Manage both Claude Code and Codex CLI in one app, pointed at the Anthropic-protocol and OpenAI-protocol endpoints respectively.

Advanced Claude Code Features (Still Work via QCode)¶

CC Switch only switches providers; Claude Code's own capabilities are unaffected. After connecting to QCode, the following features work as usual (running on whatever model Claude Code is configured with):

Vision Input: Understand Requirements from Screenshots / Diagrams¶

Claude Code can feed images to vision-capable models: paste (Ctrl+V), drag-drop, or reference an image file path in your prompt. Common uses:

• Build UI from a mockup / screenshot
• Debug from an error screenshot
• Read architecture diagrams and charts

Vision-capable models via QCode include claude-opus-5 / claude-sonnet-5, plus still-on-sale claude-opus-4-8 / claude-sonnet-4-6 and GPT-5.x. Live capability flags: qcode.cc/models.

Note: this is image input (understanding), not image generation. To have a model generate images, use the gpt-image-2 model — see gpt-image-2 Image Generation.

Dynamic Workflows (Background Sub-agent Orchestration)¶

Include the keyword ultracode in your prompt (or simply ask to "run a workflow") to trigger Claude Code's dynamic workflows: it orchestrates tens to hundreds of background sub-agents in parallel, ideal for codebase-wide review, migration, and research. Agents keep running in the background while you continue working; view runs with the /workflows command. This capability runs on whatever model Claude Code is configured with — so it works when Claude Code points at QCode. Further reading: Subagents.

Headless Mode / Automation Output¶

In scripts and CI, run once with -p and specify an output format:

# Structured JSON (incl. result / total_cost_usd / usage / session_id), parse with jq
claude -p "Summarize test coverage in this repo" --output-format json | jq '.result'

# Newline-delimited streaming JSON events, good for real-time pipes
claude -p "Review src/ for security risks" --output-format stream-json

More pipe and CI usage in Automation & CI/CD.

About Gemini / Antigravity¶

CC Switch's visual list includes Gemini CLI, but note: Google has retired Gemini CLI (EOL 2026-06-18 for Pro/free tiers; enterprise paid keys are unaffected), succeeded by the Google Antigravity CLI (available since 2026-05-19). To use Gemini-family models via QCode, switch to Antigravity:

• CC Switch still maintains Gemini CLI as a first-class app; the entry is the same as for Claude / Codex
• Step-by-step Gemini setup via QCode lives on the Google Antigravity CLI page; exact keys follow the official docs

Gemini models still on sale and commonly cited here include gemini-2.5-pro and gemini-3.5-flash. Any multiplier and the exact rate come from qcode.cc/models — do not reuse a spoken “2x” unless that page shows it at the time.

Fallback Endpoints¶

If the primary endpoint is unreachable, switch to an alternative (the same key works everywhere):

Self-check: hitting the path of a Base URL directly returns 401 — that's expected, it means the path is correct and only auth is missing.

Shared Quota¶

The Claude and Codex providers in CC Switch share the same QCode.cc API Key and draw from the same subscription quota (see Billing). Adding two providers does not double-bill you. If you created multiple providers with different keys, each key is billed independently.

After you are connected: switch, coexist, recover¶

This section is the post-setup traffic that “CC Switch” searches actually bring. How to fill the form is above; this is what happens after it runs.

Several plans / several keys¶

One provider = one BASE_URL + key + (for Codex) model. You can keep several rows for the same QCode account, for example:

Only one provider is active at a time — CC Switch will not write two configs into ~/.claude/settings.json together. To compare official Anthropic and QCode, click Enable back and forth. Do not expect both to be live.

The CLI did not pick up the new provider¶

Check in this order; do not start by blaming the key:

1. Open ~/.claude/settings.json (or ~/.codex/config.toml for Codex) and confirm ANTHROPIC_BASE_URL / base_url is the row you just activated.
2. File changed, session did not: this is the behaviour in issue #3057 — Claude Code copies the env block from settings.json at process start. A running session does not re-read it. Close the current claude / codex and open a new terminal.
3. The official README says Claude Code now hot-switches. If your build does, you can skip the restart; if it is still hitting the old node, reopen the session.
4. The FAQ says Gemini CLI tray switches apply immediately. Gemini CLI itself is EOL (see above) — do not apply that sentence to Claude / Codex.

Coexist with official Anthropic / ChatGPT login¶

Official README / FAQ:

1. Add an Official Login preset (Claude / Codex) or Google Official (Gemini)
2. Click Enable
3. Reopen the matching CLI and run its own Log out / Log in (or OAuth)
4. After that you can flip between official login and the QCode.cc custom provider

Do not hand-merge official OAuth and a QCode ANTHROPIC_AUTH_TOKEN in settings.json — on activate, CC Switch rewrites the fields it owns. Switching among several official Codex accounts follows the README: Codex can switch between different official providers.

Tray-switch pitfalls¶

• Missing icon: macOS — menu bar settings; Windows — taskbar overflow; Linux may need libappindicator (official FAQ)
• Lightweight Mode (tray menu): the main window is destroyed (not hidden) and only the tray stays; the mode is not persisted — a normal start returns to regular mode; the first ccswitch:// deep link rebuilds the window and is a bit slower (official FAQ, since v3.13.0)
• Tray click, CLI unchanged: the tray writes the same live files as Activate. It does not kill a running claude. Reopen the session as above
• Suffixes like (asia) / (work) keep the tray menu readable

The config was overwritten — how to get it back¶

On activate / takeover, CC Switch writes provider fields into the CLI live files. Several issues (#2992, #4274; plus #1656, a feature request for merge-write behaviour) report a full-file overwrite that dropped keys CC Switch does not own (enabledPlugins, hooks, statusLine, permissions, …). Plugin files often remain on disk; they just no longer load because enabledPlugins is gone.

Recovery paths you can verify (official README / user manual, not a third-party chant):

1. App backups: ~/.cc-switch/backups/ (rotated; official text: last 10)
2. An export you made: settings export is named like cc-switch-export-{timestamp}.sql; import overwrites the current DB — export again before importing
3. Shared config snippet (README FAQ “plugins disappeared after a switch”): Edit Provider → Shared Config panel → “Extract from current provider”; later, leave the shared-config write checkbox checked on new providers (default; the README labels it inconsistently ("Write Shared Config" / "Apply shared config")). The default provider imported on first launch should still hold the original full set
4. Hand edits to Claude: if you only edited ~/.claude/settings.json and never extracted it into Shared Config, recover from your own backup / Time Machine / editor local history, then paste into Shared Config. The next activate will not magically merge

CC Switch’s own DB is ~/.cc-switch/cc-switch.db; device UI is ~/.cc-switch/settings.json. Deleting the latter only resets the UI; it does not restore Claude hooks.

Practical Tips¶

• Name with suffixes: Add suffixes like (asia) / (work) to provider names so tray switching is unambiguous at a glance.
• Check the file, then open a new session: trust ~/.claude/settings.json / ~/.codex/config.toml; a running process does not hot-reload (FAQ / #3057).
• No trailing slash: QCode requires Base URLs without a trailing / (otherwise SDKs build //v1/...-style broken paths).
• Keep keys separate: CC Switch stores keys independently per provider; remember to update each one when you rotate keys.
• Back up your config: If you hand-edited ~/.claude/settings.json, activating will overwrite your edits — back it up or extract it into the shared snippet first.

FAQ¶

The "Enable" button is unclickable after saving¶

Check in order: ① the endpoint field is not empty; ② the JSON / TOML in the panel is syntactically valid (hand edits break it most often); ③ try removing a trailing / from the Base URL (QCode endpoints require none. CC Switch's own handling of trailing slashes is not documented upstream; this order is our experience).

Every Claude Code request 400s on 2.1.265–2.1.267 (Artifact schema)¶

Claude Code 2.1.265–2.1.267 shipped an Artifact tool schema that strict gateways reject outright (400, Invalid schema for function 'Artifact'). Since CC Switch 3.20.3 (2026-09-11) the Claude provider editor has a “Disable Artifact Tool” quick toggle, which writes env.CLAUDE_CODE_DISABLE_ARTIFACT="1". The official Claude Code fix is upgrading to ≥2.1.268; see troubleshooting. We have not reproduced each QCode-side interaction — if you hit it, open a ticket with the request id.

401 Unauthorized error¶

1. Confirm the API Key starts with cr_ and has no leading or trailing spaces
2. Check that the key is valid at qcode.cc/dashboard
3. If Claude returns 401 but Codex works (or vice versa), the key in one of the providers was entered incorrectly — CC Switch stores keys independently per provider

Switching providers had no effect¶

First check that the live file already shows the new provider. If the file changed, close the current claude / codex session and open a new one (official FAQ; #3057). Do not only click the tray and keep typing in the old window.

Codex spins indefinitely on startup¶

Check that base_url follows the QCode endpoint convention and ends at /openai (not /openai/v1). wire_api = "responses" must stay. The most common miss: the top-level model_provider is absent or does not match the [model_providers.xxx] table name — Codex then silently falls back to the built-in openai endpoint (official issue #7263 documents the symptom).

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

Yes. CC Switch writes Claude config to ~/.claude/ and Codex config to ~/.codex/. The two configurations are completely independent. Run claude and codex in separate terminals as needed.

I hand-edited settings.json — will activating lose it?¶

Yes. On activate, CC Switch overwrites the corresponding fields in ~/.claude/settings.json with that provider's values. Some builds have been reported to replace the whole file and drop enabledPlugins / hooks (#2992, #4274). Put extras in the shared config snippet, back up before activating, and restore from ~/.cc-switch/backups/ or an exported .sql if they disappear.

How do I switch back to official Anthropic login?¶

Add the Official Login preset → Enable → reopen the CLI → run official Log out / Log in. Do not hand-build a hybrid “empty env but keep the cr_ key” config.

Aggregation mode in v4.0 and ccswitch:// imports in v4.0.10 (2026-10)¶

CC Switch released v4.0.0 on 2026-10-04 and v4.0.10 on 2026-10-12 (dates taken from the two release pages: v4.0.0 and v4.0.10). Every line quoted below is verbatim from the English release-notes files in the repository: docs/release-notes/v4.0.0-en.md and docs/release-notes/v4.0.10-en.md; the two release pages above are used only for the dates and carry the Chinese version. Nothing in this section was tested by us, and no import link was executed.

Aggregation mode (v4.0.0)¶

The new Aggregation mode puts models from several providers into one Claude Code or Codex model picker, so you can switch between them right inside the client

add a few providers, and their models all show up together in the Claude Code or Codex model picker

Whichever model you pick, the request goes straight to that provider, without ever leaving the client.

So several model services can be added, their models appear together in one model picker, and the request goes to whichever provider owns the model you chose, without leaving the client. The same notes state that this is opt-in, that it currently supports Claude Code and Codex, that it dispatches per selected model, and that it offers no failover:

Aggregation is opt-in and currently supports Claude Code and Codex. It routes each request by the model you pick, and does not offer failover.

On screen, the notes describe three tabs at the top of every app page — Direct / Routing / Aggregation — and stress that pressing a tab only changes what you are looking at; the card actions are Add and Remove, plus picking one provider as the default for requests that do not name an aggregated model:

Every app page has three tabs at the top: Direct / Routing / Aggregation. Clicking a tab only changes what you're looking at and never touches your config

Click "Add" or "Remove" on a provider card, then choose one provider as the default to handle requests that don't name an aggregated model

Two points matter for pay-per-token use. First, the notes warn that switching mid-session is possible, but each new model has to rebuild its prompt cache, so the first turn after a switch costs noticeably more (verbatim: You can change to another model partway through a session. Note that after each switch, the new model has to build its prompt cache again, so the first turn after switching costs noticeably more). On QCode, per-model rates are listed on https://qcode.cc/models. Second, a changed model list triggers a restart prompt, and Codex CLI users can restart the background service from that banner:

When the model list changes you're prompted to restart the client, and Codex CLI users can restart the background service from the banner in one click

v4.0.0 also changed how settings are written, which matters if you edit the files by hand:

switching providers now replaces only the key fields instead of rewriting the whole file

ccswitch:// deep-link import (v4.0.10)¶

The v4.0.10 notes call themselves the sixth fix release for the 4.0 line, centred on one-click import links:

The sixth fix release for 4.0 stable

This release focuses on one-click import links (ccswitch:// deep links)

The behaviour being fixed was clicking a deep link while the app was not open, itemized in the notes:

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 now also offers a choice about switching right after the import. The notes state that this switch is off by default and that turning it on shows a warning that client requests will be sent to the address inside the link (verbatim: The confirmation dialog lets you choose whether to switch right after import, and off by default; when it is on, the dialog warns that client requests will be sent to the address in the link).

On API formats, the notes state:

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

For you this means: when you import a QCode address into Claude Code or Codex through a deep link, look first at the API format the link declares (anthropic / openai_chat / openai_responses / gemini_native) — local routing has to be on beforehand only when that format is not native to the app in question (for example openai_chat in Claude Code); combinations the app does not support are rejected at parse time. Which address to use on the QCode side is unchanged from the endpoint table above and from Endpoints & API paths: https://api.qcode.cc/api for Claude, https://api.qcode.cc/openai/v1 for GPT and Chinese models, and Claude never goes through the OpenAI-compatible address. The same release also published site owner guides in Chinese, English and Japanese plus an online link generator (verbatim: Site owner guides in Chinese, English and Japanese and an online link generator are also published); this page does not reproduce their output.

Next Steps¶

• WorkBuddy Integration — the same key as a Tencent WorkBuddy custom model
• Claude Code Tutorial — Master the core Claude Code workflow
• Codex Tutorial — Go deeper with Codex CLI
• VS Code Integration — Use Claude Code directly in your editor
• Subagents — Orchestrate background agents with dynamic workflows
• Automation & CI/CD — Headless mode and script integration
• Billing — Understand plans and quota

Don't have a QCode.cc API Key yet? Head to qcode.cc/pricing to pick a plan — one key drives both Claude Code and Codex CLI inside CC Switch.

Enterprise →