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:
   bashCopy

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

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

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 and in 2.1 Add Provider → Codex OAuth Reverse Proxy.

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