CC Switch Setup

Point CC Switch at QCode.cc for Claude Code and Codex CLI: forms, multi-plan switching, coexistence with official login, switches that do not apply, and recovering an overwritten config

CC Switch Setup¶

CC Switch is a cross-platform desktop application (Windows / macOS / Linux) that provides a unified visual interface for managing API provider configurations across CLI tools such as Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw. 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 → switch to the Claude tab on the left → click Add Provider in the top right → select Custom → fill in the fields as shown:

Why asia.qcode.cc? It's QCode.cc's Hong Kong node 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 four domains: api / asia / us / eu.

After saving, click Activate to set it as 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 are a 2026-08-16 snapshot from qcode.cc/models; use that page live. Do not delete 4.x — only move the default recommendation to the 5 line. Full lineup (GPT, Gemini, China-family models) is on the same page.

Configure Codex Provider (for Codex CLI)¶

Switch to the Codex tab → Add Provider → Custom → fill in the fields as shown:

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

model_provider = "qcode"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
disable_response_storage = true

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

Save and activate, then run codex to verify the connection. GPT model options: gpt-5.6-terra / gpt-5.6-sol / gpt-5.6-luna / gpt-5.5 / gpt-5.4 / gpt-5.6-mini (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 Activate next to the target provider — 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; right-click the tray icon to switch directly between saved providers without opening the main window. Exact menu items depend on your app version. Tray switching writes the same live files as Activate 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:

• Edit ~/.config/antigravity/config.toml
• Set base_url to https://api.qcode.cc/openai/v1, supply your QCode API Key, and pick a model
• Antigravity is new and evolving — exact config keys should 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 Activate 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): main window closes, tray stays. Features remain; 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, #1656) 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 “Write shared config” checked (default) on new providers. 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: No Base URL may end with /, or it may produce an incorrect path.
• 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 "Activate" button is grayed out after saving¶

Make sure there is no trailing / at the end of ANTHROPIC_BASE_URL / Base URL. CC Switch is sensitive to trailing slashes.

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 in config.toml ends with /openai (not /openai/v1). The wire_api = "responses" field must also be present.

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.

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.