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.7 KiB
4.1 Proxy Service
Overview
The proxy service starts a local HTTP proxy through which all API requests are forwarded.
Primary uses:
- Record request logs
- Track API usage
- Support failover
- Centrally manage requests from multiple applications
Start the Proxy
Option 1: Main Interface Toggle
Click the Proxy Toggle button at the top of the main interface.
Toggle states:
- White: Proxy not running
- Green: Proxy running
Option 2: Settings Page
- Open "Settings > Advanced > Proxy Service"
- Click the toggle in the top-right corner
Proxy Configuration
Basic Configuration
| Setting | Description | Default |
|---|---|---|
| Listen Address | IP address the proxy binds to | 127.0.0.1 |
| Listen Port | Port the proxy listens on | 15721 |
| Enable Logging | Whether to record request logs | Enabled |
Modify Configuration
- Stop the proxy service (must stop first)
- Modify the listen address or port
- Click "Save"
- Restart the proxy
Modifying address/port requires stopping the proxy service first
Listen Address Options
| Address | Description |
|---|---|
127.0.0.1 |
Only accessible from local machine (recommended) |
0.0.0.0 |
Allow LAN access |
Running Status
When the proxy is running, the panel displays the following information:
Service Address
http://127.0.0.1:15721
Click the "Copy" button to copy the address.
Current Providers
Displays the currently used provider for each app:
Claude: PackyCode
Codex: AIGoCode
Gemini: Google Official
Statistics
| Metric | Description |
|---|---|
| Active Connections | Number of requests currently being processed |
| Total Requests | Total number of requests since startup |
| Success Rate | Percentage of successful requests (>90% green, <=90% yellow) |
| Uptime | How long the proxy has been running |
Failover Queue
The proxy panel displays the failover queue by app type:
Claude
├── 1. PackyCode [Currently Using] ●
├── 2. AIGoCode ●
└── 3. Backup Provider ○
Codex
├── 1. AIGoCode [Currently Using] ●
└── 2. Backup Provider ●
Queue details:
- Numbers indicate priority order
- "Currently Using" label indicates the active provider
- Health badges show provider status:
- Green: Healthy (0 consecutive failures)
- Yellow: Degraded (1-2 consecutive failures)
- Red: Unhealthy (3+ consecutive failures)
How It Works
Request Flow
sequenceDiagram
participant CLI as CLI Tool (Claude)
participant Proxy as Local Proxy (CC Switch)
participant API as API Provider (Anthropic)
participant DB as Data Store (Logger)
CLI->>Proxy: Send API request
Proxy->>DB: Record request log / track usage
Proxy->>API: Forward request
API-->>Proxy: Return response
Proxy-->>CLI: Return response
Configuration Changes
After starting the proxy and enabling app takeover, CC Switch modifies app configurations:
Claude:
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
}
}
Codex:
base_url = "http://127.0.0.1:15721/v1"
Gemini:
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
Stop the Proxy
Option 1: Main Interface Toggle
Click the proxy toggle button to turn it off.
Option 2: Settings Page
Turn off the toggle in the proxy service panel.
Post-stop Processing
When stopping the proxy, CC Switch will:
- Restore app configurations to their original state
- Save request logs
- Close all connections
Log Recording
Enable Logging
Enable the "Enable Logging" toggle in the proxy panel.
Log Contents
Each request record includes:
| Field | Description |
|---|---|
| Time | Request time |
| App | Claude / Codex / Gemini |
| Provider | Provider used |
| Model | Requested model |
| Tokens | Input/output token count |
| Latency | Request duration |
| Status | Success/failure |
View Logs
View request logs in the "Settings > Usage" tab.
FAQ
Port Already in Use
Error message: Address already in use
Solution:
- Change the port (e.g., to 5001)
- Or close the program occupying the port
Proxy Fails to Start
Check:
- Is the port occupied
- Are there sufficient permissions
- Is the firewall blocking it
Request Timeout
Possible causes:
- Network issues
- Provider server issues
- Incorrect proxy configuration
Solutions:
- Check network connection
- Try accessing the provider API directly
- Check provider configuration