CC-Switch

CC-Switch is a cross-platform local configuration management tool that can save multiple Providers for coding tools like Claude Code and Codex, and write the currently enabled configuration to the respective tool's configuration files. It allows switching between AGTCloud and other saved configurations without manually editing files each time.

This tutorial covers app-specific Providers for Claude Code and Codex. Requests are sent directly from the corresponding coding tool to AGTCloud without enabling CC-Switch Local Proxy, Failover, protocol conversion, or Universal Provider.

Switching operations will modify the local tool configuration

CC-Switch updates the active configuration files for Claude Code or Codex. Before first use, confirm that the existing configuration was imported correctly, then export a backup before adding AGTCloud.

Preparation

Before you start, please confirm that you have:

Install Claude Code or Codex and confirm that it starts normally;
Register and log in to AGTCloud;
Create the AGTCloud API Key on the API Keys page;
From the Model Marketplace, copy a model ID that is available to the current API Key and supports the target tool's protocol;
Prepare a test project that does not include sensitive code or production credentials.

Claude Code should choose a model that supports Anthropic Messages; Codex should choose a model that supports OpenAI Responses. MODEL_ID is the placeholder to be replaced, not the actual model name.

Download and install CC-Switch

Obtain installation packages only from the CC-Switch official website or GitHub Releases. Any website or client that asks you to top up, pay, or submit login credentials for CC-Switch itself is not an official channel.

For regular installation, select the current version of Windows MSI from GitHub Releases;
If you don't want to install it, you can choose Windows Portable ZIP;
After extracting the Portable version, run CC-Switch.exe;
If Windows blocks it from running, first check the file source and digital signature, and do not disable system security features.

CC-Switch manages configuration; it does not replace Claude Code or Codex. Confirm that the target coding tool starts normally before continuing.

First startup and backup

Check the automatic import results

When starting for the first time, CC-Switch will attempt to import existing local configurations such as Claude Code and Codex. Open the corresponding app pages separately and confirm that the official configuration or custom provider is already listed in the list.

Retain the original Provider

Do not delete the official auto-import configuration. If you need to exit AGTCloud later, you can re-enable the provider to restore the original connection method.

Export data for backup

Go to Settings → Advanced → Data Management and use the export feature provided by the current version to save the backup. Backup files may contain API keys and other sensitive provider information. Please save them in an appropriate location and do not upload them to a repository or public cloud drive.

This tutorial does not require direct editing of the configuration file

CC-Switch is responsible for writing the configuration of the corresponding tool. Do not overwrite ~/.claude/settings.json or ~/.codex/auth.json or ~/.codex/config.toml just to apply examples from other platforms.

Add AGTCloud Provider

At the top, select the app you want to configure, click the Add button in the upper right corner, then use the custom configuration under "Dedicated App Vendors." Claude Code and Codex use different protocols and base URLs, so you should create Providers separately.

Open the Claude Code Provider page

At the top of CC-Switch, select Claude Code, click Add Provider, and choose "Custom" or the Custom Provider entry corresponding to the current version.

Fill in the connection information

Field	Value
`Provider Name`	`AGTCloud`
`Base URL`	`https://api.agtcloud.cn`
`API Key`	`your-api-key`
`Primary Model`	`MODEL_ID`
`Authentication`	Use API Key, do not use it `ANTHROPIC_AUTH_TOKEN`

For the Base URL, enter only the API Origin shown on this page. Do not append /v1; Claude Code automatically requests /v1/messages.

Configure model-role mappings

If the current version shows Haiku, Sonnet, and Opus model-role mappings, you can initially map all three roles to the same MODEL_ID that supports Anthropic Messages. Configure different models only after confirming the capabilities of each model.

Save but do not enable the proxy for now

Save the Provider. Do not enable Local Proxy, Failover, protocol conversion, or other advanced routing features.

Authenticate using API Key

AGTCloud's Claude Code configuration authenticates with the API Key provided through ANTHROPIC_API_KEY. Do not substitute ANTHROPIC_AUTH_TOKEN or a Bearer Token configuration copied from another platform.

Enable and verify the configuration

Enable AGTCloud

Return to the Provider list for the corresponding app and click "Enable" on the AGTCloud card. Confirm that the card shows "Currently Enabled" or the equivalent status in the current version.

Reload the target tool

Claude Code can usually detect configuration changes, but it is recommended to start a new session for verification;
Codex needs to close the current terminal window, then reopen the terminal and start Codex.

Do not use old sessions that have already sent requests to determine whether the switch was successful.

Check the current configuration

Execute in the target tool:

/status

Check the Provider, Base URL, authentication source, and model ID. Claude Code should not show a duplicated /v1; the Codex Base URL should end with exactly one /v1.

Initiate read-only tests

Enter the following in a safe test project containing README.md:

Please read the README.md and summarize the project's purpose in three points. Do not modify any files.

If the result returns normally without unauthorized modifications, it means the basic connection has been established. This step will generate normal API usage.

Use the system tray for quick switching

CC-Switch provides independent Provider lists for different applications in the system tray. Right-click the tray icon, enter the Claude or Codex submenu, and select the Provider you want to enable.

Tray switching is just another configuration entry point and does not require enabling Local Proxy. After switching Codex, you should still reopen the terminal.

Switch back to the original setup

Open the Claude Code or Codex page in CC-Switch;
Find the official Provider imported at first launch;
Click "Enable";
For Claude Code, open a new session to confirm the change. For Codex, reopen the terminal and start Codex again.

Claude Code and Codex Providers are isolated from each other. Switching Claude Code does not automatically modify Codex, and vice versa.

Frequently Asked Questions

Issue	What to check	Resolution
Couldn't find a suitable installation package	Download sources, operating system, and processor architecture	Only get the current version from `ccswitch.io` or official GitHub Releases
The original Provider did not appear	Initial import results and the original tool configuration path	First, make sure Claude Code or Codex is installed and configured in place, then reopen CC-Switch
CC-Switch cannot write the configuration when enabled	Configuration file permissions and whether the file is in use	Close the target tool, check permissions for the user configuration directory, and try again
Returns `401`	API Key and authentication method	Use a valid API Key; for Claude Code, do not use `ANTHROPIC_AUTH_TOKEN`
Returns `403`	API Key status, account permissions, and model access	Check the current API Key and the models available to the account in the console
Returns `404`	Base URL, duplicated `/v1`, full endpoint, and model ID	Use `https://api.agtcloud.cn` for Claude Code and `https://api.agtcloud.cn/v1` for Codex. Do not enter a full request endpoint
The model list cannot be loaded	`/v1/models` Support, network, and API Key	Copy the complete model ID visible from the Model Marketplace and manually fill it in
Claude Code still uses the old configuration	Provider enables state and old session caching	Confirm that the AGTCloud card is currently enabled, then open a new Claude Code session and execute the `/status`
Codex still uses the old configuration	Whether the terminal has restarted	Close the current terminal window, reopen the terminal, and then start Codex
A normal conversation succeeds, but tool calling fails	Model protocol and tool-calling capabilities	For Claude Code, choose a model that supports Anthropic Messages and tool calls; for Codex, choose a model that supports Responses
The Base URL becomes `/v1/v1`	Application type and URL format	Remove `/v1` from the Claude Code URL; for Codex, keep exactly one `/v1`

If you encounter issues that cannot be located, record the target tool, request time, API Base URL, model ID, HTTP status, and redacted error messages, then review Error and Troubleshooting. Do not submit full API Key or CC-Switch data backups.

Safety advice

Do not put API keys in screenshots, logs, repositories, or shared configurations;
CC-Switch data exports may contain sensitive Provider information and should be properly stored as credential backups;
Only download and install CC-Switch from official channels; do not submit platform login credentials to third-party clients;
Initial verification uses security test projects, keeping Claude Code and Codex operation approvals enabled;
If an API Key is suspected of leaking, immediately disable or remove it in the console, then create a new Key.