CC Switch Guide (2026): Install It and Switch Claude Code & Codex Providers in One Click

This guide covers v4.0.12 (October 2026). Version 4 replaced the old top tabs with a sidebar and added Routing and Aggregation modes, so v3 screenshots you find elsewhere won't match.

What CC Switch does

Every AI coding CLI keeps its provider settings in a different file: Claude Code in ~/.claude/settings.json, Codex in ~/.codex/config.toml, Gemini CLI in a .env file. Moving between an official account, a cheaper gateway and a local model means editing them by hand. CC Switch gives you a card per provider and an Enable button.

What makes it safe to use on a setup you care about:

• It only touches the connection fields. Switching replaces the endpoint, key, model and API format. Your plugins, hooks, MCP servers, permissions and comments stay as they are.
• It backs up first. Before rewriting a tool's config file for the first time, CC Switch saves the original under ~/.cc-switch/backups/live-first-write/.
• Uninstalling it is harmless. Tools keep running on the last configuration CC Switch wrote.

It also manages MCP servers, Skills and prompts across tools, shows usage and remaining balance on provider cards, and has an Apps page that installs and upgrades the CLIs themselves.

Direct, Routing and Aggregation

Version 4 has three connection modes, picked with the tabs at the top of each tool's page:

Clicking a tab only changes what you're looking at. Nothing switches until you click Start routing or Switch to Aggregation on that page.

Download and install

Requirements: Windows 10 or later, macOS 12 or later (Universal build for Apple silicon and Intel), or Linux with glibc 2.35+ and WebKitGTK 4.1 (Ubuntu 22.04+, Debian 12+, recent Fedora).

• Windows: download CC-Switch-v<version>-Windows.msi and run it, or use the portable .zip. Pick the arm64 files on ARM PCs. If the installer does nothing, right-click it → Properties → check Unblock.
• macOS: brew install --cask cc-switch, or download the .dmg and drag the app to Applications. It's signed and notarized, so it opens without warnings.
• Linux: .deb for Debian/Ubuntu (sudo dpkg -i), .rpm for Fedora, .AppImage for anything else that meets the requirements. On Arch, run paru -S cc-switch-bin.

CC Switch doesn't need Node.js. It manages tools you've already installed, or you can install them from its Apps page. Setup guides: Claude Code · Codex CLI.

First launch

On first launch, CC Switch:

1. Imports each tool's current configuration as a provider named default, so whatever works now keeps working.
2. Adds an official provider for each tool (Claude Official, OpenAI Official, Google Official and so on), which is how you switch back to a normal sign-in later.

Add a provider

Select a tool in the sidebar, then click + in the top-right corner. You have three options.

1. Import from your provider's dashboard

Many API gateways have an Import to CC Switch button that opens a ccswitch:// link. CC Switch then shows a confirmation dialog listing the endpoint, a masked key, the models and any extra settings, and flags anything suspicious, such as a localhost address. The switch after import toggle at the bottom is off by default. Turn it on to start using the provider immediately.

On api.foo, the gateway behind these docs, go to Console → API Keys, click ⋯ next to a key, choose CC Switch, pick the app (Claude, Codex or Gemini) and a primary model, then click Open CC Switch. The endpoint is filled in for you: https://api.foo for Claude and Gemini, https://api.foo/v1 for Codex.

2. Use a built-in preset

CC Switch ships with 90+ presets for vendors and gateways. Search by name (for example "kimi", "openrouter" or "bedrock"), pick one, paste your API key and click Add.

3. Custom configuration

If your provider isn't listed, choose Custom configuration at the top of the list and enter the endpoint and key yourself. The endpoint format depends on the tool:

The download icon next to the model field fetches the provider's model list from its /v1/models endpoint. A 401 means the key is wrong. A 404 means the provider doesn't publish a model list, so type the model ID by hand.

Switch providers

Click Enable on a provider card, or pick the provider from the CC Switch menu in the system tray (macOS menu bar). When the change applies depends on the tool:

Back to your official account: enable the built-in official provider (Claude Official, OpenAI Official, …), restart the tool and sign in its usual way: /login in Claude Code, codex login for Codex.

Codex specifics

• Current Codex only speaks the OpenAI Responses API. Providers that only offer Chat Completions are marked Requires routing.
• When you switch Codex to a third-party provider, CC Switch writes the key into experimental_bearer_token for that provider in ~/.codex/config.toml and leaves ~/.codex/auth.json, your ChatGPT sign-in, alone. Switching back to OpenAI Official restores the ChatGPT session.
• Restart Codex after every switch.

"Requires routing", explained

A Requires routing badge means the provider's API format doesn't match what the tool speaks. For example, Claude Code only speaks Anthropic's Messages API, and some providers only offer OpenAI's.

To use such a provider:

1. Open the tool's page, click the Routing tab, then Start routing.
2. CC Switch rewrites the tool's config to point at a local address (http://127.0.0.1:15721 by default) with the placeholder key PROXY_MANAGED. The real endpoint and key stay inside CC Switch.
3. Keep CC Switch running. When you quit it, it writes the direct config back first.
4. Click Back to direct when you're done.

Routing also gives you a failover queue: when a request fails, CC Switch retries the next provider in line, with a circuit breaker so a dead provider isn't hammered.

Troubleshooting

The tool still uses the old provider

• Restart Codex or Gemini CLI after switching. Claude Code should switch live. If it doesn't, reopen the terminal or editor.
• Look for a yellow environment variable conflict banner at the top of CC Switch. Variables like ANTHROPIC_BASE_URL or OPENAI_API_KEY set in your shell profile or Windows environment override the config files CC Switch writes. Open View details, select the variables and delete them. CC Switch backs them up first. Then restart your terminal.

The connectivity check passes, but requests fail

The check on a provider card only confirms the endpoint is reachable. It doesn't send a real request, so it can't catch a wrong key or model name. Re-copy the key, confirm the model ID against the provider's list, and check the /v1 rule in the table above. In Routing mode, Usage → request logs shows the exact upstream error.

My config file now points to 127.0.0.1

Routing or Aggregation mode is on. That's expected. Click Back to direct to restore the provider's real endpoint.

I can't delete the active provider

CC Switch always keeps one provider active per tool, so the tool never ends up with no configuration. Switch to another provider first, then delete it.

Windows: it won't open or closes immediately

Install the Microsoft Edge WebView2 runtime, and whitelist CC Switch in your antivirus if it's being blocked.

Linux: the AppImage won't start

Make it executable with chmod +x CC-Switch-*.AppImage. GLIBC_2.xx not found means your distro is too old, since glibc 2.35+ is required and RHEL/Rocky/Alma 8–9 aren't supported. FUSE errors go away after installing libfuse2 or switching to the .deb/.rpm.

Uninstall CC Switch

Your coding tools keep working with whatever provider was active last. CC Switch's own data (providers, backups, logs) lives in ~/.cc-switch. Delete that folder for a full cleanup.

Related

• How to install Claude Code
• Install Codex CLI and set up config.toml