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.

ModeRequest pathBehavior
StandardTool → OneRouterWrites the active local configuration; no CC-Switch request proxy or local usage statistics
Proxy & FailoverTool → local CC-Switch proxy → providerAdds 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.

ToolFiles managed by the toolOneRouter protocol
Claude Code~/.claude/settings.jsonClaude native
Codex~/.codex/config.toml and authentication settingsResponses API
Gemini CLI~/.gemini/.envGemini compatibility prefix
OpenCode~/.config/opencode/opencode.jsonOpenAI-compatible
Other supported clientsClaude Desktop, OpenClaw, and Hermes Agent configurationFollow 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.

SystemPackageIf launch is blocked
macOSDMGOpen it from Privacy & Security if macOS blocks an unidentified developer
WindowsInstallerReview the SmartScreen prompt and continue only when the downloaded file is from the official release page
LinuxDEB or AppImageFor AppImage, grant execute permission before launch
brew tap farion1231/ccswitch
brew install --cask cc-switch

First 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

  1. Select the target tool and open Provider Management.
  2. Choose Add Provider, name it OneRouter, and select the matching protocol.
  3. Enter the base URL, API key, and model mappings, then save.
  4. 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.

ToolBase URLCredentialImportant option
Claude Codehttps://onerouter.comOneRouter API KeyUse the Claude-native provider form
Codexhttps://onerouter.com/v1OneRouter API KeyResponses API / wire_api = "responses"
Gemini CLIhttps://onerouter.com/geminiOneRouter API KeyGemini API Key authentication
OpenCodehttps://onerouter.com/v1OneRouter 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 tierPurposeExample mapping
HaikuFast, lightweight tasksanthropic/claude-haiku-4.5
SonnetBalanced default coding modelanthropic/claude-sonnet-4.6
OpusComplex reasoning and large changesanthropic/claude-opus-4.8
Provider Name: OneRouter
Base URL: https://onerouter.com
API Key: YOUR_ONEROUTER_API_KEY

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

ToolReload after switchingVerification
Claude CodeProvider data can hot-switch; start a new conversation if credentials or models appear unchangedRun /status
CodexStart a new terminal session and relaunchConfirm provider and default model before edits
Gemini CLIRestart the CLI and check for a project .env overrideSend a short prompt with the selected model
OpenCode / desktop clientsFully quit and reopen the appCheck 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

SymptomHow 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

SymptomHow to fix it
Switch succeeds but the tool still uses the old providerStart a new conversation or terminal session, then verify which live configuration file CC-Switch updated.
401Re-enter the complete OneRouter key and confirm CC-Switch wrote it to the target tool's credential location.
404Check the tool-specific base URL. Codex and OpenCode use /v1; Claude does not; Gemini CLI uses /gemini.
Model not foundUse the complete model slug available to the current key and refresh the saved model list.
The model responds but tool calls failConfirm 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 openedVerify the download source, then allow the app from Privacy & Security. Do not disable system security globally.
Imported configuration behaves unexpectedlyRestore the backup, add OneRouter as a new provider, and switch only after reviewing every field.
Failover changes capabilitiesUse fallback models with matching tool, vision, reasoning, and context capabilities, or disable failover.