# 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

| Toggle | Effect |
|--------|--------|
| Claude Routing | Route Claude Code requests |
| Codex Routing | Route Codex requests |
| Gemini Routing | Route Gemini CLI requests |

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**:

```json
// 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**:

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

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

**Gemini configuration change**:

```bash
# 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

| State | Border Color | Description |
|-------|--------------|-------------|
| Currently Active | Blue | Provider in the config file (non-routing mode) |
| Routing Active | Green | Provider actually used by routing |
| Normal | Default | Unused provider |

## 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