Configure CC Switch

CC Switch manages provider configurations for Codex, Claude Code, Gemini CLI, and other clients. This guide shows how to import LLMAPI configuration directly from the website's API Key page without copying a service URL or editing configuration files by hand.

Before you begin

1. Create or select an API key compatible with the coding client on the website's API Key page.
2. Install and open the client you intend to use at least once. Only CLI users need to confirm that the corresponding command is available:

codex --version
claude --version

Run only the command for the client you intend to use. If it already prints a version, you do not need to reinstall Node.js, Codex, or Claude Code. Codex Desktop and IDE extension users do not need to install a CLI just for this step.

You also do not need to run mkdir -p ~/.codex or mkdir -p ~/.claude in advance. CC Switch creates or updates the relevant user-level configuration when you enable a provider. If you already have custom configuration, back up the relevant files before switching for the first time.

Install CC Switch

Download CC Switch only from the official website or GitHub Releases. The current official builds support Windows 10 or later, macOS 12 or later, and common x64 or ARM64 Linux distributions.

System	Recommended installation
Windows	Download the Windows.msi for your architecture from Releases. A Windows-Portable.zip build is also available.
macOS	Run brew install --cask cc-switch, or download macOS.dmg from Releases and move the app to Applications.
Linux	Choose the .deb, .rpm, or .AppImage package for your distribution and architecture.

Launch CC Switch at least once after installation and confirm that its main window opens. The installer registers the ccswitch:// protocol used by one-click imports.

Import from the website's API Key page

1. Open CC Switch first.
2. Sign in to the website and open the API Key page.
3. Find the Regular API key you want to use and select Import to CCS.
4. If the page asks you to choose a client, select the client you actually use. For example, an Antigravity group asks you to choose Claude Code or Gemini CLI.
5. When the browser asks for permission to open CC Switch, allow it.
6. CC Switch displays an import confirmation. Verify that the provider name, target client, and service URL belong to the current website, then confirm the import.
7. Find the imported provider under the corresponding client in CC Switch and select Enable.

The website chooses the import target from the key's group. For example, an OpenAI group imports into Codex, while an Anthropic group imports into Claude Code. The import also includes the website's public service URL, the API key, a default model when applicable, and usage-query configuration. Do not edit or share the import link opened by the browser.

Importing adds the provider. CC Switch updates the selected client's user-level configuration only after you enable that provider.

Verify the configuration

Codex

Codex must be restarted after switching providers. Verify the client you actually use:

• Codex CLI: fully quit it, then run the following from a project directory:

codex

• Codex Desktop: fully quit and reopen the app, then create a new task.
• Codex IDE extension: reload the editor window or restart the editor, then create a new task.

Claude Code

Claude Code normally detects the switched configuration. Verify the client you actually use:

• Claude Code CLI: fully quit it, then run:

claude

• Claude Code IDE extension: run Developer: Reload Window from the command palette, then send a new request. You do not need to install the CLI just to verify the extension.

The configuration is active when the client enters its interactive interface and can complete a request.

Switch providers later

To switch a route or API key later, open the relevant client in CC Switch, find the target provider, and select Enable. Claude Code normally reads the new configuration immediately. Codex must be quit and restarted.

Switching is isolated by client. Enabling a provider under Claude does not also change the active Codex provider.

Troubleshooting

Symptom	Resolution
Import to CCS is not displayed	An administrator may have hidden the action. Use the manual steps in Configure Codex or Configure Claude Code.
The page reports that CC Switch is not installed or its protocol is not registered	Launch CC Switch manually and retry. If it still does not open, reinstall it from an official package to register ccswitch://.
The browser does not open CC Switch	Check whether the browser blocked an external application and allow the current website to open CC Switch.
The provider was imported but the client still uses old settings	Confirm that the provider is shown as active in CC Switch. Fully quit and restart Codex after switching.
The provider was imported into the wrong client	Delete or disable the incorrect entry, then select Import to CCS again with the same key and choose the correct client. An Antigravity group can be re-imported for either Claude Code or Gemini CLI.
The API returns 401	Check that the imported key is complete, active, and is a Regular API key.
The model is unavailable	Query the model list with the same key, or select a regular group that supports the intended client and model before importing again.

For additional installation, switching, and protocol troubleshooting, see the CC Switch English user manual.