Connect CC Switch to Routescope

CC Switch is a small desktop configuration tool. You click through a few screens and fill in a form, and it writes the Routescope endpoint and secret into Claude Code or Codex for you. You do not need to edit configuration files by hand.

This guide is written for first-time setup. Follow each step in order.

Last updated: 2026-07-13 Verified version: CC Switch v3.16.5

The Three-Step Flow

Prepare three things -> Add a Routescope provider in CC Switch -> Enable it and test

First: Which Tool Are You Using?

Claude Code and Codex are different tools, and they use different endpoint formats. Decide which one you are configuring, then read only that section:

• Using Claude Code: read "Configure Claude Code".
• Using Codex: read "Configure Codex".
• Using both: configure one first, confirm it works, then configure the other.

If you are not sure, most users should start with Claude Code.

Do not swap these endpoint values:

Step 1: Prepare Three Things

Before opening CC Switch, prepare the following.

1. Install CC Switch

Download it from the CC Switch website or the official CC Switch GitHub releases page.

2. Install the Tool You Want to Use

CC Switch only changes configuration. Claude Code or Codex itself must already be installed. Open a terminal:

• Windows: open PowerShell.
• macOS: open Terminal.
• Linux: open your system terminal.

If you use Claude Code, run:

claude --version

If you use Codex, run:

codex --version

If you see a version number, continue. If you see command not found or a similar error, install the tool first:

• Claude Code setup guide
• Codex CLI setup guide

3. Get a Routescope Secret and Model ID

The secret, or API Key, is the passcode. The model ID is the model you want the tool to use.

1. Sign in to the Routescope console.
2. Open Token Management and click Add Token.
3. Enter a token name, such as CC Switch.
4. For the first setup, keep quota, allowed models, and expiration at their defaults.
5. Save the token, then click Copy Access Code in the token list. Confirm it starts with sk-.
6. Open Model Plaza, find a model allowed by this token, and copy its full Model ID.

You should now have a full sk-... secret and a model ID.

Step 2: Add a Provider in CC Switch

A provider is the AI service entry that CC Switch will write into your local tool configuration. Here, you will add Routescope.

1. Open CC Switch.

2. At the top of the main window, select the tool you want to configure: Claude Code or Codex.

   This step matters: the provider values are written to the selected tool.

3. Click the + button in the upper-right corner.

4. Choose Application-specific provider. For first-time setup, do not choose a unified provider.

5. Under preset providers, choose Custom configuration.

You will then see fields such as provider name, API Key, and API endpoint. Read only the section for the tool you selected.

Configure Claude Code

If you are configuring Codex, skip to "Configure Codex".

Step 1: Fill in Basic Information

Enter the following values exactly:

Check these before continuing:

• The sk- prefix is still present.
• The endpoint does not end with /v1.
• The endpoint does not have an extra trailing /.

Step 2: Confirm Advanced Options

Expand Advanced Options and confirm these defaults:

For first-time setup, leave other options unchanged.

Step 3: Choose the Model

1. Find Model Mapping and click Fetch model list.
2. In the Sonnet row, choose your prepared model ID as the actual request model.
3. Click One-click setup to apply the same model to the other roles.
4. Set Default fallback model to the same model ID.

Using the same model for all roles is the least error-prone first setup. You can split roles later after confirming more models are available.

If Fetch model list does nothing, first check the API Key and endpoint. If it still does not work, paste the model ID manually into the actual request model field.

Step 4: Save and Enable

1. Click Add / Save at the bottom.

2. Return to the Claude Code provider list and find the Routescope card.

3. Click Enable on the card and confirm it shows the active/current state.

Step 5: Start and Verify

Open PowerShell or a terminal and run:

claude

Ask a normal question, for example:

Describe yourself in one sentence.

After you receive a normal response, verify that the request really went through Routescope:

1. Open the Routescope console and go to Operation Records.
2. Find the new record from the same time.
3. Confirm the status is successful and the model matches what you selected.

Only a successful record in Routescope confirms the connection is complete.

If Claude Code Still Asks You to Sign In

1. Open CC Switch and go to Settings -> General.
2. Enable Skip Claude Code first-time installation confirmation.
3. Close Claude Code, then start it again with claude.

Configure Codex

If Claude Code is already configured, you can configure Codex later.

Step 1: Fill in Basic Information

Enter the following values exactly:

Check two things: the sk- prefix is still present, and the endpoint ends with exactly one /v1.

Step 2: Choose the Upstream Format

Expand Advanced Options, find Upstream format, and choose:

Responses (native)

Do not choose Chat Completions (requires routing), and do not enable local routing.

Step 3: Change the Model Name

Find the config.toml editor and locate the line starting with model =, for example:

model = "gpt-5.5"

Only replace the value inside the quotes with the model ID copied from Routescope:

model = "your-real-model-id"

Do not delete model =, do not delete the quotes, and leave anything you do not understand unchanged.

Also confirm these two lines are present:

base_url = "https://api.routescope.ai/v1"
wire_api = "responses"

CC Switch saves the secret for you, so you do not need to paste it again.

Step 4: Save and Enable

1. Click Add / Save at the bottom.
2. Return to the Codex provider list and find the Routescope card.
3. Click Enable and confirm it shows the active/current state.

Step 5: Reopen the Terminal

Codex does not always reload configuration immediately. Close the current terminal and open a new one:

1. Close the current PowerShell / terminal window.
2. Open a new one.
3. Run codex, then ask a normal question.

Step 6: Verify Routescope Usage

1. Open the Routescope console and go to Operation Records.
2. Find the new record from the same time.
3. Confirm the status is successful and the model matches the config.toml value.

Only a successful Routescope record confirms the setup is complete.

Switching Tools After Setup

1. At the top of CC Switch, select Claude Code or Codex.
2. Click Enable on the provider card.
3. Claude Code usually applies the switch immediately. If not, close the current claude session and reopen the terminal.
4. Codex requires closing and reopening the terminal.

Troubleshooting

Before deeper troubleshooting, do this once: after changing configuration, click Enable on the provider card again, then test from a newly opened terminal.

claude or codex Command Not Found

The tool is not installed, or the terminal was opened before installation. Install it, close the terminal, reopen it, and run claude --version or codex --version.

401 or 403

Check these items in order: the secret is complete, the sk- prefix is still present, the token is not disabled or expired, quota remains, the model is allowed by the token, and IP restrictions are not blocking the request.

If all of those are correct, old local environment variables may be overriding CC Switch. Clear them and reopen the terminal:

unset ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL

On Windows, run this in Git Bash. Then click Enable on the card again.

404

• Claude Code: use https://api.routescope.ai, without /v1.
• Codex: use https://api.routescope.ai/v1, with /v1.
• Do not add an extra trailing /.

model not found or Model Unavailable

1. Return to the Routescope console and confirm which models the token can use.
2. Copy the full model ID.
3. Claude Code: reset the actual request model and default fallback model. Codex: update model in config.toml.
4. Save and enable again.

Claude Code Reports context_management: Extra inputs are not permitted

This is not usually a bad secret. Edit the Claude Code Routescope provider and add this line under env in the JSON configuration:

"CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"

Do not remove existing secret, endpoint, or model values. Save, enable again, and restart Claude Code. If you never see this error, you do not need this setting.

The AI Replies, but Routescope Has No Operation Record

The active provider is probably not Routescope, or old environment variables are pointing the request elsewhere.

1. Confirm the selected tool at the top of CC Switch is correct.
2. Confirm the Routescope card is active/current, and click Enable again if needed.
3. Clear old environment variables as described in the 401 / 403 section.
4. Codex users must also reopen the terminal.

Advanced Codex: Authentication Still Fails

In rare cases, a custom Codex provider may need requires_openai_auth changed to false in config.toml. This is advanced troubleshooting; contact Routescope support before changing it.

Keep These Defaults for First-Time Setup

• Full URL mode: off.
• Claude Code API format: Anthropic Messages (native).
• Claude Code auth field: ANTHROPIC_AUTH_TOKEN (default).
• Codex upstream format: Responses (native).
• Local route takeover: not needed.

References

• CC Switch GitHub repository
• CC Switch manual: Add provider
• CC Switch manual: Switch provider