CC Switch: install, configure and troubleshoot LYRouter access
CC Switch is a desktop app that manages provider settings for tools such as Claude Code and Codex; it does not call models itself. Once you add LYRouter as a provider in CC Switch and enable it, the target tool calls models through LYRouter. This page starts with the installation prerequisites, then shows how to configure the tool and make your first call.
Already installed? Go straight to Configure LYRouter.
Prerequisites
CC Switch manages the configuration of coding tools. It does not run model tasks itself and needs no separate Node.js runtime. Choose your operating system and prepare what the installation needs. Before you use a configuration, install the target tool, such as Claude Code or Codex CLI.
1. Check the system and architecture
Use Windows 10+, on x64 / ARM64. Check in PowerShell:
Get-CimInstance Win32_OperatingSystem | Select-Object Caption, Version, OSArchitecture
2. Prepare the installation directory and target tools
From the official Releases, choose the MSI or portable version for your architecture, and make sure the installation or extraction directory is writable. Install the target tools in the same runtime environment. CC Switch itself does not require an account.
1. Check system dependencies
It requires glibc 2.35+ and WebKitGTK 4.1, on x64 / ARM64. Use a desktop environment that meets these requirements, such as Ubuntu 22.04+ or Debian 12+:
cat /etc/os-release
uname -m
ldd --version
2. Prepare WebKitGTK and a desktop environment
If WebKitGTK 4.1 is missing on Ubuntu / Debian, install it from the system repositories:
sudo apt update
sudo apt install -y libwebkit2gtk-4.1-0
For other distributions, see the official installation requirements. The system libraries of RHEL / Rocky / Alma 8–9 do not meet the current requirements, and the package must match your distribution and architecture.
1. Check the system and processor
Use macOS 12+, on Intel or Apple Silicon:
sw_vers -productVersion
uname -m
2. Prepare an installation method and target tools
You can download the official DMG directly. To use the Homebrew method in the next section, first set up Homebrew following the official Homebrew instructions. Configure the environment that the target tool actually runs in; if the tool is not installed yet, read its installation guide first.
To connect to LYRouter you also need an enabled API key and a model available in the current workspace. Replace MODEL_ID in the examples with an actual system model identifier. CC Switch itself needs no account; the call credentials are used by the target tools it manages.
Install the app
- Download the installer from the official Releases.
- On Windows, install the MSI or extract the portable version; on macOS, open the DMG and drag the app into Applications; on Linux, choose deb, rpm or AppImage for your distribution.
- Start CC Switch and confirm that the tools you want to manage are installed.
On macOS you can also use brew install --cask cc-switch, as described in the official instructions.
Configure LYRouter
Choose the tool to manage, then add a LYRouter provider:
| Target tool | Protocol and address |
|---|---|
| Claude Code | Anthropic, https://api.lyrouter.com |
| Codex CLI | Responses, https://api.lyrouter.com/v1 |
Enter your LYRouter API key and an available model, enable the new provider and restart the target tool. Keep a copy of the tool's original configuration before switching. For the Codex fields, see the Codex guide; for the Claude fields, see the Claude Code guide.
Verify your first call
After enabling the LYRouter provider in CC Switch, restart the target tool (such as Claude Code or Codex) and send a minimal task such as "Reply OK" from it. Then check the generation endpoint, status and actual model in LYRouter's request logs. A successful connection test in CC Switch does not mean that generation or tool calling already works in the target tool.
Everyday use and troubleshooting
CC Switch is installed. Why can't I find the Claude Code or Codex command?
Answer: CC Switch does not replace installing the target tools. First complete the installation by following Claude Code, Codex CLI or the guide for the tool, reopen the terminal and check PATH, then check the configuration that CC Switch manages.
Why does the target tool still fail after I switched providers?
Answer: First check which target tool and configuration location CC Switch manages, then check the protocol and address: Claude Code uses the root address https://api.lyrouter.com, and Codex CLI uses https://api.lyrouter.com/v1 with Responses. CC Switch only manages configuration; the target tool must still be installed and use the correct model and LYRouter API key.
What should I check before switching models?
Answer: Make sure the new model is enabled in the current workspace, has at least one valid service source, and supports the protocol and tool capabilities the app needs. Use the system model identifier, not the display name.
Why does my configuration stop working after an app update?
Answer: First check the current app version and which configuration location it actually reads, then check the provider, address, key and model against "Configure LYRouter" on this page. The official resources linked on this page define the configuration requirements of each version.
A request returns 401 / 403. What should I check first?
Answer: Make sure you entered an enabled LYRouter API key, and check the model sources and access policies of the workspace the key belongs to. Use the specific error and the logs to find what rejected the request; see 401 / 403: authentication and access.
A request returns 429. Does retrying repeatedly help?
Answer: First find out whether a platform limit or an exhausted upstream quota caused it, then adjust concurrency, call frequency or resource configuration. Retry with bounded backoff instead of retrying immediately and repeatedly; see 429: rate limits and quotas.
The switch succeeded. Why are there still no generation logs in LYRouter?
Answer: Make sure the target tool actually read the switched configuration and is using the LYRouter provider and model, then send a minimal generation request. Search the request logs in the correct workspace by time and key; a successful configuration switch alone does not prove that calls go through the gateway.
Official resources
The requirements and installation methods below come from the tool's official documentation. For later versions, the official instructions take precedence.