CC-Switch
Manage and switch OneRouter provider settings for Claude Code, Codex, Gemini CLI, and OpenCode from one desktop application.
Standard mode connects directly to OneRouter
CC-Switch stores provider entries in a local SQLite database and writes the active entry into each tool's live configuration file. In standard mode it does not proxy or record API requests; the selected tool connects to OneRouter directly.
A successful switch may still require a new session
Claude Code can hot-load provider data, but an existing conversation may keep old credentials. Start a new Claude session first. Codex, Gemini CLI, OpenCode, and desktop clients normally require a new terminal session or app restart.
Standard mode and proxy mode
CC-Switch is free and open source under the MIT license. Official subscriptions and API providers can coexist as separate entries, but only one provider is active for each tool at a time.
| Mode | Request path | Behavior |
|---|---|---|
| Standard | Tool → OneRouter | Writes the active local configuration; no CC-Switch request proxy or local usage statistics |
| Proxy & Failover | Tool → local CC-Switch proxy → provider | Adds hot switching, protocol conversion, health checks, fallback, and request/token/cost statistics |
What CC-Switch manages
CC-Switch provides a visual provider manager for multiple coding tools. It is useful when one machine needs to keep official providers and OneRouter side by side, or when different projects require different models.
| Tool | Files managed by the tool | OneRouter protocol |
|---|---|---|
| Claude Code | ~/.claude/settings.json | Claude native |
| Codex | ~/.codex/config.toml and authentication settings | Responses API |
| Gemini CLI | ~/.gemini/.env | Gemini compatibility prefix |
| OpenCode | ~/.config/opencode/opencode.json | OpenAI-compatible |
| Other supported clients | Claude Desktop, OpenClaw, and Hermes Agent configuration | Follow each client's protocol |
Install CC-Switch
Install from the official CC-Switch GitHub Releases. Homebrew is recommended on macOS; Windows offers an MSI installer and portable ZIP; Linux offers DEB and AppImage packages.
| System | Package | If launch is blocked |
|---|---|---|
| macOS | DMG | Open it from Privacy & Security if macOS blocks an unidentified developer |
| Windows | Installer | Review the SmartScreen prompt and continue only when the downloaded file is from the official release page |
| Linux | DEB or AppImage | For AppImage, grant execute permission before launch |
brew tap farion1231/ccswitch
brew install --cask cc-switchFirst launch and import
CC-Switch automatically detects existing Claude Code, Codex, Gemini CLI, and OpenCode configuration and imports it as default providers. Review the detected paths and fields before switching. If a tool already works, export or back up its configuration first so you can restore it if needed.
Do not import credentials from unknown configuration files. OneRouter keys should remain on the local machine and should not be included in screenshots or shared configuration exports.
Configure OneRouter in 4 steps
- Select the target tool and open
Provider Management. - Choose
Add Provider, name itOneRouter, and select the matching protocol. - Enter the base URL, API key, and model mappings, then save.
- Select the saved entry and choose
Switch. Configure cross-app sharing only after each tool passes its own connection test.
Add the OneRouter provider
Select the target tool in CC-Switch, choose Add Provider, enter a recognizable provider name such as OneRouter, then fill the protocol-specific values below.
| Tool | Base URL | Credential | Important option |
|---|---|---|---|
| Claude Code | https://onerouter.com | OneRouter API Key | Use the Claude-native provider form |
| Codex | https://onerouter.com/v1 | OneRouter API Key | Responses API / wire_api = "responses" |
| Gemini CLI | https://onerouter.com/gemini | OneRouter API Key | Gemini API Key authentication |
| OpenCode | https://onerouter.com/v1 | OneRouter API Key | @ai-sdk/openai-compatible |
Claude Code configuration
Set the API root and key, then map CC-Switch's Haiku, Sonnet, and Opus speed tiers. These tiers are Claude Code aliases, not a requirement to choose one fixed model family.
These model IDs are examples, not permanent availability guarantees. Use complete slugs from Text & Chat Models or GET /v1/models. After switching, start a new Claude Code session and run /status.
| Claude tier | Purpose | Example mapping |
|---|---|---|
| Haiku | Fast, lightweight tasks | anthropic/claude-haiku-4.5 |
| Sonnet | Balanced default coding model | anthropic/claude-sonnet-4.6 |
| Opus | Complex reasoning and large changes | anthropic/claude-opus-4.8 |
Provider Name: OneRouter
Base URL: https://onerouter.com
API Key: YOUR_ONEROUTER_API_KEYCodex configuration
Use the OneRouter /v1 base URL and select Responses API. In Model Management, add the complete OneRouter model slugs you need, choose the default model, and set the reasoning level only to a value supported by that model.
CC-Switch writes the configuration for you, but checking ~/.codex/config.toml after the first switch is the fastest way to catch a wrong base URL or provider name.
model = "<MODEL_SLUG>"
model_provider = "onerouter"
[model_providers.onerouter]
name = "OneRouter"
base_url = "https://onerouter.com/v1"
env_key = "ONEROUTER_API_KEY"
wire_api = "responses"Gemini CLI configuration
Set the OneRouter Gemini compatibility URL and API key, choose Gemini API key authentication instead of Google OAuth or Vertex AI, then add available model IDs in Model Management and select a default.
OneRouter uses /gemini for Gemini CLI. Do not copy another provider's Vertex AI prefix into this field.
GEMINI_API_KEY="YOUR_ONEROUTER_API_KEY"
GOOGLE_GEMINI_BASE_URL="https://onerouter.com/gemini"OpenCode configuration
Choose @ai-sdk/openai-compatible, set the OneRouter /v1 address and API key, then add complete model IDs in Model Management. Model keys must exactly match the IDs returned by OneRouter.
{
"provider": {
"onerouter": {
"npm": "@ai-sdk/openai-compatible",
"name": "OneRouter",
"options": {
"baseURL": "https://onerouter.com/v1",
"apiKey": "YOUR_ONEROUTER_API_KEY"
},
"models": {
"<MODEL_SLUG>": { "name": "<MODEL_SLUG>" }
}
}
}
}Switch and verify
Select the target tool, choose the saved OneRouter provider, and click Switch. Reload the tool as described below, send a minimal prompt such as Reply with OK only, and confirm the request appears in OneRouter usage logs before starting a larger task.
| Tool | Reload after switching | Verification |
|---|---|---|
| Claude Code | Provider data can hot-switch; start a new conversation if credentials or models appear unchanged | Run /status |
| Codex | Start a new terminal session and relaunch | Confirm provider and default model before edits |
| Gemini CLI | Restart the CLI and check for a project .env override | Send a short prompt with the selected model |
| OpenCode / desktop clients | Fully quit and reopen the app | Check the active provider and model |
Universal Provider
A Universal Provider can synchronize one OneRouter provider identity across Claude Code, Codex, Gemini CLI, and OpenCode. Each app still keeps independent endpoint, protocol, default-model, and model-mapping values. Configure and test every tool separately before enabling cross-app synchronization.
Do not force one protocol onto every tool
A shared provider still needs tool-specific protocol handling: Claude uses the Claude-native root, Codex and OpenCode use /v1, and Gemini CLI uses the Gemini compatibility prefix.
Proxy and failover
Enable Proxy & Failover only after standard-mode direct access works. This mode places a local CC-Switch proxy in the request path and can provide hot switching, protocol conversion, health checks, automatic fallback, and a request/token/cost dashboard. Keep fallback chains short and use models with compatible capabilities.
Proxy mode changes the trust boundary
Standard mode does not inspect request traffic. Proxy & Failover mode can observe traffic to calculate statistics and route fallbacks, so review local logging, retention, and team security requirements before enabling it.
Frequently asked questions
| Symptom | How to fix it |
|---|---|
| Is CC-Switch free? | Yes. It is open source under the MIT license; download it only from the official repository. |
| Which operating systems are supported? | macOS, Windows, and Linux are supported through the packages listed above. |
| Can official subscriptions and API providers coexist? | Yes. Save them as separate entries, but only one provider is active per tool at a time. |
| Does standard mode proxy or log requests? | No. It writes the selected local configuration and the tool connects directly to OneRouter. |
| When are local usage statistics available? | Only when Proxy & Failover mode is in the request path. For billed usage and charges, review the OneRouter usage logs in the console. |
Troubleshooting
| Symptom | How to fix it |
|---|---|
| Switch succeeds but the tool still uses the old provider | Start a new conversation or terminal session, then verify which live configuration file CC-Switch updated. |
| 401 | Re-enter the complete OneRouter key and confirm CC-Switch wrote it to the target tool's credential location. |
| 404 | Check the tool-specific base URL. Codex and OpenCode use /v1; Claude does not; Gemini CLI uses /gemini. |
| Model not found | Use the complete model slug available to the current key and refresh the saved model list. |
| The model responds but tool calls fail | Confirm the selected protocol matches the client and the model supports tool calling; do not solve a protocol mismatch by changing only the model name. |
| macOS says the app cannot be opened | Verify the download source, then allow the app from Privacy & Security. Do not disable system security globally. |
| Imported configuration behaves unexpectedly | Restore the backup, add OneRouter as a new provider, and switch only after reviewing every field. |
| Failover changes capabilities | Use fallback models with matching tool, vision, reasoning, and context capabilities, or disable failover. |