CC Switch guide

Checked against the official README and user manual on 2026-10-20 (v4.0.16). FollowAgents has not tested it hands-on; CC Switch changes quickly, so the linked official pages win wherever they differ.

CC Switch is an open source desktop app (MIT) that manages the configuration of Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, Pi and MiniMax Code: switch API providers in one click and manage MCP servers, Skills and prompt files in one place instead of hand-editing JSON, TOML or YAML. It is not an agent itself, so it isn't in the FollowAgents catalog, but plenty of people rely on it alongside those agents. This guide covers install, switching, routing mode and the risks worth knowing first.

Step 1: Download from the official sources

The project says its only official website is ccswitch.io; installers are on GitHub Releases. Don't download it anywhere else — a tool like this sees all of your API keys.

CC Switch is GUI-only. For servers or SSH-only machines the README points to the community-maintained CC Switch CLI, which is not an official project.

Step 2: Add and switch providers

1. On first launch it imports your existing Claude Code, Codex, Gemini CLI and Grok Build settings as a provider named default and adds an official provider for each tool, so nothing is lost.
2. Pick a tool in the sidebar, click "+" at the top right, then choose one of 90+ presets and enter your key, or write a custom configuration.
3. Click "Enable". Claude Code picks it up without a restart; Codex, Gemini CLI and Grok Build need the terminal or tool restarted; Claude Desktop needs a full quit and reopen.
4. To go back to official sign-in (a Claude subscription or ChatGPT account), switch to the built-in "Claude Official", "OpenAI Official" and so on, restart the tool, and follow its own login flow.

OpenCode, OpenClaw, Hermes, Pi and MiniMax Code use "coexist" mode: "Add" writes several providers into the tool's own config at once, and you choose the model inside the tool.

Switching replaces only the key fields — endpoint, key, model and protocol. Plugins, hooks, MCP servers and comments you added stay as they are, and the original file is backed up to ~/.cc-switch/backups/live-first-write/ before the first rewrite. See the official quick start and FAQ.

Step 3: Routing mode (GPT in Claude Code, Claude in Codex)

Claude Code, Codex, Gemini CLI and Grok Build have "Direct / Routing" tabs. With routing on:

• The tool sends requests to CC Switch on your machine (http://127.0.0.1:15721 by default), which forwards them to the provider you picked and converts between Anthropic, OpenAI and Gemini API formats. That is why the config file then shows only the local address and a placeholder key, PROXY_MANAGED.
• Each tool can have a failover queue: a failed request moves on to the next provider.
• Using an OpenAI-format-only service (including many local model servers) in Claude Code requires routing, with the provider's "Upstream Format" set to match.
• Routing needs CC Switch running. When you quit, it writes the direct provider back to the config first.
• Official subscription logins (such as Claude Official) can't go through routing; Codex's OpenAI Official is the exception.

See the official routing section.

Know this before you rely on it

• Your keys live on your machine: providers, keys, MCP and usage records are in ~/.cc-switch/cc-switch.db, and ChatGPT, Copilot and Grok sign-ins in *_auth.json files beside it. Cloud sync (WebDAV, S3) copies that data to the storage you choose, so make sure it is trustworthy.
• Third-party relays are your risk: the README carries many sponsor ads for API relay services promising prices far below official rates. Through a relay, your code and prompts pass through that company; check whether it complies with the model vendor's terms and how it handles your data. FollowAgents recommends no relay service.
• A passing "connectivity check" proves little: it only checks that the address is reachable, not the key or the model name. When requests fail, check those and the upstream format.
• Uninstalling leaves your tools working: CC Switch always keeps one active configuration, which is why it won't delete the provider in use — switch to another one first.

Windows and WSL

CC Switch doesn't detect WSL by itself. To manage tools inside WSL, set that tool's config directory under "Settings → App config" to a WSL path such as \\wsl.localhost\Ubuntu\home\<user>\.claude. Routing writes 127.0.0.1 into the config, which WSL2's default NAT networking can't reach on the Windows side; switch WSL to mirrored networking.

FAQ

Is CC Switch free? Yes, MIT-licensed, source at farion1231/cc-switch. The model services you connect are what cost money.

Why does a model I picked inside the tool revert after switching? The model is a key field owned by the provider. A /model choice lasts until the next switch; to keep it, edit that provider's model in CC Switch.

Does CC Switch replace the agent? No — it only manages configuration; you still install Claude Code, Codex and the rest. See our Codex guide, OpenCode guide and Hermes Agent guide, or start from the AI coding agents ranking.