mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-04-23 01:14:51 +08:00
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.
221 lines
5.1 KiB
Markdown
221 lines
5.1 KiB
Markdown
# 5.2 Frequently Asked Questions
|
|
|
|
## Installation Issues
|
|
|
|
### macOS Shows "Unidentified Developer"
|
|
|
|
**Problem**: First launch shows "Cannot open because it is from an unidentified developer"
|
|
|
|
**Solution 1**: Via System Settings
|
|
1. Close the warning dialog
|
|
2. Open "System Settings" > "Privacy & Security"
|
|
3. Find the CC Switch prompt
|
|
4. Click "Open Anyway"
|
|
5. Reopen the app
|
|
|
|
**Solution 2**: Via Terminal command (recommended)
|
|
```bash
|
|
sudo xattr -dr com.apple.quarantine /Applications/CC\ Switch.app/
|
|
```
|
|
|
|
The app can be opened normally after running this command.
|
|
|
|
### Windows: App Doesn't Launch After Installation
|
|
|
|
**Possible causes**:
|
|
- Missing WebView2 runtime
|
|
- Antivirus software blocking
|
|
|
|
**Solutions**:
|
|
1. Install [Microsoft Edge WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)
|
|
2. Add CC Switch to your antivirus software's whitelist
|
|
|
|
### Linux: Startup Error
|
|
|
|
**Problem**: AppImage won't start
|
|
|
|
**Solution**:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
# 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`
|
|
|
|
## Getting Help
|
|
|
|
### Submit an Issue
|
|
|
|
If none of the above solutions work:
|
|
|
|
1. Visit [GitHub Issues](https://github.com/farion1231/cc-switch/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\`
|