bbed2a1fe1
Reorganize docs/user-manual/ from flat structure to language subdirectories (zh/, en/, ja/) with shared assets/. Move existing Chinese docs into zh/, fix image paths, add multilingual navigation README, and translate all 23 markdown files (~4500 lines each) to English and Japanese.
4.5 KiB
4.2 App Takeover
Overview
App takeover means letting CC Switch's proxy intercept and forward a specific application's API requests.
When takeover is enabled:
- The app's API requests are forwarded through the local proxy
- Request logs and usage statistics can be recorded
- Failover functionality becomes available
Prerequisites
The proxy service must be started before using the app takeover feature.
Enable Takeover
Location
Settings > Advanced > Proxy Service > App Takeover area
Steps
- Ensure the proxy service is started
- Find the "App Takeover" area
- Enable the toggle for the desired apps
Takeover Toggles
| Toggle | Effect |
|---|---|
| Claude Takeover | Intercept Claude Code requests |
| Codex Takeover | Intercept Codex requests |
| Gemini Takeover | Intercept Gemini CLI requests |
Multiple app takeovers can be enabled simultaneously.
How Takeover Works
Configuration Changes
When takeover is enabled, CC Switch modifies the app's configuration file to point the API endpoint to the local proxy.
Claude configuration change:
// Before takeover
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.anthropic.com"
}
}
// After takeover
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
}
}
Codex configuration change:
# Before takeover
base_url = "https://api.openai.com/v1"
# After takeover
base_url = "http://127.0.0.1:15721/v1"
Gemini configuration change:
# Before takeover
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
# After takeover
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
Request Forwarding
When the proxy receives a request:
- Identifies the request source (Claude/Codex/Gemini)
- Looks up the currently enabled provider for that app
- Forwards the request to the provider's actual endpoint
- Records the request log
- Returns the response to the app
Takeover Status Indicators
Main Interface Indicators
When takeover is enabled, the main interface shows the following changes:
- Proxy 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-proxy mode) |
| Proxy Active | Green | Provider actually used by the proxy |
| Normal | Default | Unused provider |
Disable Takeover
Steps
- Turn off the corresponding app's takeover toggle in the proxy panel
- Or directly stop the proxy service
Configuration Restoration
When disabling takeover, CC Switch will:
- Restore the app configuration to its pre-takeover state
- Save current request logs
Takeover and Provider Switching
Switching Providers in Takeover Mode
When switching providers in takeover mode:
- Click the "Enable" button on a provider in the main interface
- The proxy immediately uses the new provider to forward requests
- No need to restart the CLI tool
This is a major advantage of takeover mode: provider switching takes effect instantly.
Switching Without Takeover
When switching providers without takeover:
- Configuration file is modified
- CLI tool must be restarted for changes to take effect
Multi-app Takeover
Multiple apps can be taken over simultaneously, each managed independently:
- Independent provider configurations
- Independent failover queues
- Independent request statistics
Use Cases
Scenario 1: Usage Monitoring
Enable takeover + log recording to monitor API usage.
Scenario 2: Quick Switching
With takeover enabled, switching providers does not require restarting CLI tools.
Scenario 3: Failover
Enabling takeover is a prerequisite for using the failover feature.
Notes
Performance Impact
The proxy adds minimal latency (typically < 10ms), negligible for most scenarios.
Network Requirements
In takeover mode, CLI tools must be able to access the local proxy address.
Configuration Backup
Before enabling takeover, CC Switch backs up the original configuration and restores it when disabled.
FAQ
Requests Fail After Takeover
Check:
- Is the proxy service running normally
- Is the provider configuration correct
- Is the network working properly
Configuration Not Restored After Disabling Takeover
Possible causes:
- Proxy exited abnormally
- Configuration file was modified by another program
Solutions:
- Manually edit the provider and re-save
- Or re-enable and then disable takeover