CC-Switch/docs/user-manual/en/5-faq/5.2-questions.md

5.2 Frequently Asked Questions

Installation Issues

macOS Installation

CC Switch for macOS is code-signed and notarized by Apple. You can download and install it directly without any additional steps. If you encounter issues, try downloading the latest version from the Releases page.

Windows: App Doesn't Launch After Installation

Possible causes:

• Missing WebView2 runtime
• Antivirus software blocking

Solutions:

1. Install Microsoft Edge WebView2
2. Add CC Switch to your antivirus software's whitelist

Linux: Startup Error

Problem: AppImage won't start

Solution:

# Add execute permission
chmod +x CC-Switch-*.AppImage

# If it still fails, try
./CC-Switch-*.AppImage --no-sandbox

Provider Issues

Provider Switch Doesn't Take Effect

Cause: The CLI tool needs to reload its configuration

Solutions:

• Claude Code: Close and reopen the terminal, or restart the IDE
• Codex: Close and reopen the terminal
• Gemini: Tray switching takes effect immediately, no restart needed

API Key Invalid

Troubleshooting steps:

1. Confirm the API Key is copied correctly (no extra spaces)
2. Confirm the API Key hasn't expired
3. Confirm the endpoint URL is correct
4. Use the speed test to verify connectivity

How to Restore Official Login

Steps:

1. Select the "Official Login" preset (Claude/Codex) or "Google Official" preset (Gemini)
2. Click "Enable"
3. Restart the corresponding CLI tool
4. Follow the CLI tool's login flow

Proxy Issues

Proxy Service Fails to Start

Possible cause: Port is occupied

Solution:

1. Check port usage:

   # macOS/Linux
   lsof -i :49152
   
   # Windows
   netstat -ano | findstr :49152
   

2. Close the program occupying the port
3. Or try modifying the configuration to restore the default port:
   • Open "Settings > Proxy Service"
   • Click the "Reset to Default" button

Request Timeout in Proxy Mode

Possible causes:

• Network issues
• Provider server issues
• Incorrect proxy configuration

Solutions:

1. Check network connection
2. Try accessing the provider API directly (disable proxy)
3. Check if provider configuration is correct

Configuration Not Restored After Disabling Proxy

Possible cause: Proxy exited abnormally

Solution:

1. Edit the current provider
2. Check if the endpoint URL is correct
3. Save to update the configuration

Failover Issues

Failover Not Triggering

Checklist:

• Is the proxy service running
• Is app takeover enabled
• Is auto failover enabled
• Are there backup providers in the queue

Failover Triggering Too Frequently

Possible causes:

• Unstable primary provider
• Circuit breaker threshold set too low

Solutions:

1. Check primary provider status
2. Increase the failure threshold (e.g., from 3 to 5)
3. Consider changing the primary provider

All Providers Are Circuit-Broken

Solutions:

1. Wait for the recovery wait time to expire (default 60 seconds)
2. Or restart the proxy service to reset states

Data Issues

Configuration Lost

Possible causes:

• Configuration directory was deleted
• Database corruption

Solutions:

1. Check if the ~/.cc-switch/ directory exists
2. Restore from backup: ~/.cc-switch/backups/
3. Or import from a previously exported configuration file

Import Configuration Failed

Possible causes:

• Incorrect file format
• Version incompatibility

Solutions:

1. Confirm the file was exported by CC Switch
2. Check if the file content is complete
3. Try opening with a text editor to check format

Usage Statistics Data Is Empty

Checklist:

• Is the proxy service running
• Is app takeover enabled
• Is log recording enabled
• Have requests been going through the proxy

Other Issues

Tray Icon Not Showing

macOS:

• Check menu bar icon settings in System Settings

Windows:

• Check taskbar settings to ensure the CC Switch icon is not hidden

Linux:

• System tray support may need to be installed (e.g., libappindicator)

UI Display Issues

Solutions:

1. Try switching themes (light/dark)
2. Restart the app
3. Delete ~/.cc-switch/settings.json to reset settings

Update Failed

Solutions:

1. Check network connection
2. Manually download and install the latest version
3. If using Homebrew: brew upgrade --cask cc-switch

Lightweight Mode

How to Enter Lightweight Mode?

Toggle "Lightweight Mode" from the system tray menu. The main window closes, and CC Switch runs as a tray-only app. Toggle again or click "Open main window" to exit.

App Uses Less Memory in Lightweight Mode?

Yes. Lightweight Mode destroys the main window and its web view, reducing memory usage significantly while keeping tray menu functionality available.

Getting Help

Submit an Issue

If none of the above solutions work:

1. Visit GitHub Issues
2. Search for similar issues
3. If none found, create a new Issue
4. Provide the following information:
   • Operating system and version
   • CC Switch version
   • Problem description and reproduction steps
   • Error messages (if any)

Log Files

Attach log files when submitting an Issue:

• macOS/Linux: ~/.cc-switch/logs/
• Windows: %APPDATA%\cc-switch\logs\