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](https://github.com/farion1231/cc-switch/releases).

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

## Quota & Balance

### Why do some providers show quota automatically while others need manual enabling?

Only **official subscription types** (Claude / Codex / Gemini official login, GitHub Copilot, Codex OAuth reverse proxy) automatically display the quota after enabling the provider. **All other providers** (including Token Plan and third-party balance queries) need the **Usage Query** switch to be manually turned on and a built-in template selected in the provider card — because the same request URL may expose both "plan" and "balance" query modes, requiring you to pick the right one. See [2.5 Usage Query → Manual Enable](../2-providers/2.5-usage-query.md#manual-enable-built-in-templates--custom-scripts).

### Official subscription provider shows no quota

**Check**:
1. Confirm the provider is in "Currently Active" state (inactive providers do not trigger queries)
2. For Copilot / Codex OAuth, check whether the OAuth token is still valid; if the card shows "Session Expired", log in again in the **OAuth Auth Center**
3. Check network connectivity
4. Click the refresh icon on the card to manually re-query

### Token Plan or third-party balance still not shown after enabling

**Check**:
1. Confirm the **Enable Usage Query** toggle is on in the "Usage Query" panel
2. A suitable built-in template is selected and saved
3. Click **Test Script** to see the specific error
4. The provider must be in "Currently Active" state for background auto-refresh

### Codex usage does not match the direct-connection numbers

v3.13.0 switched Codex usage from estimation to **precise parsing based on JSONL session logs**, with normalized model names for consistent pricing lookup. New data aligns with official bills. If you still see old estimated data, delete the historical entries or wait for new session data to overwrite them.

## Codex OAuth Reverse Proxy

### How do I log in to Codex OAuth?

See the complete Device Code login flow (verification code + browser authorization), both entry points (Add Provider panel / OAuth Auth Center), multi-account management, and common failure scenarios in [2.1 Add Provider → Codex OAuth Reverse Proxy (Claude Provider)](../2-providers/2.1-add.md#codex-oauth-reverse-proxy-claude-provider).

### What are the risks of enabling the Codex OAuth reverse proxy?

The Codex OAuth reverse proxy accesses your ChatGPT account's Codex service through a **reverse-engineered OAuth flow**. This may violate OpenAI's Terms of Service, carries the risk of account restrictions or suspensions, and provides no guarantee of long-term availability. **By enabling, you assume all risks**.

See the full disclaimer in the [v3.13.0 Release Notes → Risk Notice](../../../release-notes/v3.13.0-en.md#️-risk-notice) and in [2.1 Add Provider → Codex OAuth Reverse Proxy](../2-providers/2.1-add.md#codex-oauth-reverse-proxy-claude-provider).

### Codex OAuth logged in but no quota shown

**Solutions**:
1. Confirm the OAuth login flow is completed in **OAuth Auth Center** (Settings → OAuth Auth Center, with the Beta label)
2. Check whether the token is still valid — if the card shows "Session Expired", the token cannot be refreshed
3. If expired, remove the account in the OAuth Auth Center and log in again

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

### Can deep links still wake the main window in Lightweight Mode?

Yes. Starting from v3.13.0, CC Switch covers all window re-show paths (normal launch, deep links, singleton activation, tray `show_main`, and Lightweight Mode return). Clicking a `ccswitch://` link **rebuilds the main window on demand** and displays the import confirmation dialog. The first open is slightly slower than normal state (window rebuild required), but subsequent switches return to normal speed.

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