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:

1. Add execute permission:

   chmod +x CC-Switch-*.AppImage
   

2. Make sure your system meets the requirements: glibc 2.35+ and WebKitGTK 4.1 (e.g., Ubuntu 22.04+, Debian 12+). A GLIBC_2.xx not found error means your system is too old; RHEL / Rocky / Alma 8–9 are not supported yet
3. If you get a FUSE-related error, install your distribution's FUSE 2 compatibility library (e.g., libfuse2 on Ubuntu), or use the .deb / .rpm package instead

See 1.2 Installation Guide → Linux.

Linux: Clicks Don't Register / Black Screen on Resize (Wayland + NVIDIA)

Problem: The web content area is completely unclickable (the title-bar minimize/maximize/close buttons still work), and the window black-screens on resize or maximize-restore. Common on Wayland sessions with an NVIDIA GPU.

Cause: The AppImage's GTK launch hook unconditionally forces GDK_BACKEND=x11 (XWayland) to dodge a historical native-Wayland crash. On newer Wayland + NVIDIA setups, forced XWayland leaves the WebKitGTK web content unable to receive pointer events. The existing WEBKIT_DISABLE_* mitigations don't help here because the root cause is the forced window backend, not rendering.

Solution: Use the dedicated CC_SWITCH_GDK_BACKEND environment variable to switch back to native Wayland (it is read before GTK init, and the hook never overrides it):

CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage

• When launching from a desktop icon, add it to the .desktop Exec= line (e.g. env CC_SWITCH_GDK_BACKEND=wayland /path/to/AppImage) or set it in your session environment — otherwise an icon launch won't see the variable.
• The variable is generic: on tiling Wayland compositors (sway/Hyprland) where clicks don't register, set CC_SWITCH_GDK_BACKEND=x11 instead.
• Leaving it unset behaves exactly as before (still x11), with no side effects.

Provider Issues

Provider Switch Doesn't Take Effect

Cause: The CLI tool needs to reload its configuration

Solutions:

• Claude Code: Supports hot switching, so a restart is usually unnecessary; if it didn't take effect, close and reopen the terminal, or restart the IDE
• Codex, Gemini CLI, Grok Build: Close and reopen the terminal or the CLI tool (a notice appears after a successful switch)
• Claude Desktop: Quit Claude Desktop completely and reopen it; with "Model mapping", also keep CC Switch running
• Additive apps (OpenCode, OpenClaw, Hermes, Pi, MiniMax Code): Make sure you clicked "Add" ("Enable" for Pi) and selected the corresponding model in the tool

In Routing mode, requests are forwarded to the new provider immediately; but if the switch changes the model, Codex, Gemini CLI and Grok Build may still need a restart. In Aggregation mode, Claude Code takes effect immediately; Codex needs a full restart after entering or leaving Aggregation or changing the aggregated model list; see the next entry. See 4.2 App Routing for details.

Codex Doesn't Show the Aggregated Models in /model

Codex only reads its model list at startup. After entering or leaving Aggregation mode, adding or removing an aggregated provider, or changing a provider's aggregated models, you need to restart Codex completely:

• Codex CLI: just closing the terminal and reopening codex isn't enough; all codex sessions in your terminals share one background daemon. When CC Switch detects that Codex is still using the old list, it shows a notice at the top of the Codex page; click "Restart Codex daemon" in the notice (this interrupts tasks running in the daemon).
• Codex desktop app: quit completely and reopen (on macOS press ⌘Q; just closing the window isn't enough).
• Editor extension: reopen the editor window.

Does Switching Providers Change My Plugins, Hooks and Other Settings

No. When switching providers in Claude Code, Codex, Gemini CLI and Grok Build, CC Switch only replaces the key fields in the config file (request address, Key, model name, API protocol and so on); plugins, hooks, permissions, MCP, environment variables you added yourself, comments and formatting are all kept as they are. For exactly which keys are changed, see 5.1 Configuration Files.

I Changed the Model in the Tool, but It Reverted After Switching Away and Back

The model is a key field and belongs to the provider. A model you change inside the tool (such as Claude Code's /model) stays in effect until the next switch; on switching it's replaced with the one saved on the target provider, and CC Switch doesn't save the model you changed in the tool back to the original provider. To use a model long term, edit that provider in CC Switch.

Why Can't I Delete the Provider in Use

Claude Code, Claude Desktop, Codex, Gemini CLI and Grok Build enable only one provider at a time and always keep one in use, otherwise the app couldn't work properly. To delete it, switch to another provider first. In Aggregation mode, the default provider can't be removed either; set another provider as the default first. Additive apps don't have this limit.

Using an OpenAI-Compatible Endpoint, Gemini or a Local Model in Claude Code

This needs routing. When editing the provider, under "Advanced Options" → "Upstream Format", choose the format that matches the provider: "OpenAI Chat Completions" for services that only offer a Chat Completions endpoint, "OpenAI Responses API" for those that offer a Responses endpoint, and "Gemini Native generateContent" for Gemini. Then click "Start routing" in the "Routing" tab on the Claude Code page. A wrong format, or not having started routing, usually produces a 404 or 405 error.

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 "Connectivity check" to confirm the address is reachable (note: the connectivity check does not verify the Key)

How to Restore Official Login

Steps:

1. Find the built-in official provider in the provider list (such as Claude Official, OpenAI Official, Google Official, Grok Official; if you deleted it, add it again from the presets)
2. Click "Enable" (you can't switch to an official provider in Routing mode; click "Back to direct" first; Codex's OpenAI Official card is the exception)
3. Restart the corresponding CLI tool
4. Follow the CLI tool's login flow

Routing and Aggregation Issues

Local Routing Fails to Start

Possible cause: Port is occupied

Solution:

1. Check port usage (default port 15721):

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

2. Close the program occupying the port
3. Or, in "Settings → Local routing → Service", stop the routing service first (if apps are still using routing, switch them back to direct first), change the "Listen port" to another port (1024–65535), and click "Save and restart service"

Why Did the Address in the Config File Become 127.0.0.1 After Starting Routing

In Routing and Aggregation modes, the tool's requests go to CC Switch's local routing first (by default http://127.0.0.1:15721) and are then forwarded to the provider you selected, so the tool's config file only holds the local address and the placeholder key PROXY_MANAGED; Claude Code's model names are also written as fixed aliases such as claude-sonnet-5 (the /model menu still shows the real model names). The real provider address, Key and models are all kept in CC Switch. Routing and Aggregation need CC Switch to keep running; quitting CC Switch automatically writes back to direct, and it reconnects on the next start.

Request Timeout with Local Routing On

Possible causes:

• Network issues
• Provider server issues
• Incorrect local routing configuration

Solutions:

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

Configuration Not Restored After Going Back to Direct

Possible cause: CC Switch exited abnormally

Solution:

1. Reopen CC Switch; on startup it restores each tool's config according to the state on this device
2. Or click "Back to direct" on the corresponding app page; "Switch all back to direct" in "Settings → Local routing" handles all apps at once
3. If it's still wrong, check that the current provider's endpoint URL is correct; you can also find the original config files from before CC Switch first rewrote them in ~/.cc-switch/backups/live-first-write/

Failover Issues

Failover Not Triggering

Checklist:

• Is the corresponding app in Routing mode (Aggregation mode doesn't do failover)
• Is the local routing service running
• Is auto failover on in the "Routing" tab on that app's page
• 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, in "Settings → Local routing → Service", stop and restart the routing 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 (if you changed the configuration directory under "Settings → Data → Location", use the changed directory)
2. Restore from backup: "Settings → Data → Backup & Restore" (backup files are in ~/.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 is an SQL backup file 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 "Scan session logs automatically" on, and does the corresponding CLI have session history (the data source when local routing is off)
• If you rely on routing request logs: is local routing running, is the corresponding app in Routing or Aggregation mode, and is "Record request usage" in "Settings → Local routing → Service" on
• Does the app support usage statistics (OpenClaw and Hermes don't yet)

Quota & Balance

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

Only OAuth account providers (GitHub Copilot, Codex OAuth reverse proxy, xAI OAuth) automatically display the quota once enabled. All other providers (including the subscription quota of the Claude / Codex / Gemini / Grok Build official providers, Token Plan and third-party balance queries) require you to open the "Usage Query" panel on the provider card, turn on "Enable usage query" and select a built-in template ("Official Subscription" for official providers) — 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 "In use" state (providers not in use 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 Accounts in the sidebar
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 "In use" 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

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.

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 / Accounts), multi-account management, and common failure scenarios in 2.1 Add Provider → Codex OAuth Reverse Proxy (Claude Provider).

Codex OAuth logged in but no quota shown

Solutions:

1. Confirm the OAuth login flow is completed in Accounts in the sidebar
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 Accounts 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 (each app's current-provider pointer is also recorded in this file, so you'll need to confirm them again after the reset)

Linux title-bar buttons (close / minimize / maximize) do not respond

Cause: On Linux (especially Wayland), the first time the window is shown — or after hide() to the tray and show() again — GTK's client-side decorations may not finish negotiating their input surfaces with the compositor. Typical symptom: the page still accepts clicks, but the native title-bar buttons do nothing.

CC Switch automatically reactivates focus and rebinds the title-bar buttons on startup, tray restore, deep links, and single-instance activation. If the buttons are still dead, try:

1. Enable Settings → General → Window and terminal → Enable app-level window controls;
2. Quit from the system tray menu;
3. AppImage users can set CC_SWITCH_GDK_BACKEND=x11 to switch the window backend.

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

CC Switch stores logs under its application configuration directory. By default this is .cc-switch in your home directory; if you changed the configuration directory under "Settings → Data → Location", use that custom location instead.

When submitting an Issue, attach the files relevant to the problem:

• General, network, or proxy errors: ~/.cc-switch/logs/cc-switch.log and its rotated files
• Application crashes: ~/.cc-switch/crash.log, crash.log.1, and crash.log.2
• The default Windows location is C:\Users\<username>\.cc-switch\...

The runtime log rotates at 20 MB and retains the four most recent archives. Restarting the application does not clear existing logs. Logs may contain runtime environment details, so review them before posting publicly.