4.2 App Routing

Overview

App routing means letting CC Switch route a specific application's API requests through the local routing service.

When routing is enabled:

• The app's API requests are forwarded through local routing
• Request logs and usage statistics can be recorded
• Failover functionality becomes available

Prerequisites

The routing service must be started before using the app routing feature.

Enable Routing

Location

Settings > Advanced > Routing Service > App Routing area

Steps

1. Ensure the routing service is started
2. Find the "App Routing" area
3. Enable the toggle for the desired apps

Routing Toggles

Multiple app routings can be enabled simultaneously.

How Routing Works

Configuration Changes

When routing is enabled, CC Switch modifies the app's configuration file to point the API endpoint to the local routing service.

Claude configuration change:

// Before routing
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}

// After routing
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
  }
}

Codex configuration change:

# Before routing
base_url = "https://api.openai.com/v1"

# After routing
base_url = "http://127.0.0.1:15721/v1"

Gemini configuration change:

# Before routing
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com

# After routing
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721

Request Forwarding

When the routing service receives a request:

1. Identifies the request source (Claude/Codex/Gemini)
2. Looks up the currently enabled provider for that app
3. Forwards the request to the provider's actual endpoint
4. Records the request log
5. Returns the response to the app

Routing Status Indicators

Main Interface Indicators

When routing is enabled, the main interface shows the following changes:

• Routing logo color: Changes from colorless to green
• Provider cards: The currently active provider shows a green border

Provider Card States

Disable Routing

Steps

1. Turn off the corresponding app's routing toggle in the routing panel
2. Or directly stop the routing service

Configuration Restoration

When disabling routing, CC Switch will:

1. Restore the app configuration to its pre-routing state
2. Save current request logs

Routing and Provider Switching

Switching Providers in Routing Mode

When switching providers in routing mode:

1. Click the "Enable" button on a provider in the main interface
2. The routing service immediately uses the new provider to forward requests
3. No need to restart the CLI tool

This is a major advantage of routing mode: provider switching takes effect instantly.

Switching Without Routing

When switching providers without routing:

1. Configuration file is modified
2. CLI tool must be restarted for changes to take effect

Multi-app Routing

Multiple apps can be routed simultaneously, each managed independently:

• Independent provider configurations
• Independent failover queues
• Independent request statistics

Use Cases

Scenario 1: Usage Monitoring

Enable routing + log recording to monitor API usage.

Scenario 2: Quick Switching

With routing enabled, switching providers does not require restarting CLI tools.

Scenario 3: Failover

Enabling routing is a prerequisite for using the failover feature.

Notes

Performance Impact

Routing adds minimal latency (typically < 10ms), negligible for most scenarios.

Network Requirements

In routing mode, CLI tools must be able to access the local routing address.

Configuration Backup

Before enabling routing, CC Switch backs up the original configuration and restores it when disabled.

FAQ

Requests Fail After Enabling Routing

Check:

• Is the routing service running normally
• Is the provider configuration correct
• Is the network working properly

Configuration Not Restored After Disabling Routing

Possible causes:

• Routing service exited abnormally
• Configuration file was modified by another program

Solutions:

• Manually edit the provider and re-save
• Or re-enable and then disable routing