CC Switch (ccswitch.io) is the most popular desktop control panel for AI coding tools. It manages API configurations for Claude Code, Codex, Gemini CLI, OpenClaw, and other major agent tools from one place — with hot-swappable API routing, automatic failover, and shared sessions across multiple apps.
If this is your first time hearing about CC Switch, or you just downloaded it and are exploring, this guide is for you. We'll start from "what is CC Switch" and work up to advanced multi-provider load balancing.
What is CC Switch and Why Do You Need It?
The Problem CC Switch Solves
Every AI coding tool (Claude Code, Codex, etc.) needs API endpoint and API key configuration. If you use multiple tools, you configure each one separately. Switch API providers and you update every tool again.
CC Switch fixes this: one dashboard, one place to configure providers — all tools share them.
Key Features
- Hot-swappable API routing: Switch providers without restarting your agent tools
- Unified agent management: Claude Code, Codex, Gemini CLI — managed from one place
- Automatic failover: Fall back to backup providers if the primary fails
- Session sharing: Share login states and sessions between tools
- MCP management: Centralized Model Context Protocol server configuration
Installation and Basic Setup
Download and Install
CC Switch supports all major desktop platforms:
Windows:
- Download
.msior.exefrom ccswitch.io - Double-click and follow the wizard
macOS:
brew tap farion1231/ccswitch
brew install --cask cc-switch
Linux:
.deb(Debian/Ubuntu) or.rpm(Fedora/RHEL) packages- Arch Linux:
paru -S cc-switch-bin
Initial Setup
- Launch CC Switch
- Choose your language
- Configure your first Provider
Adding a Provider
CC Switch ships with 50+ preset providers. Here's how to add TeamoRouter:
- Click Provider Management in the left sidebar
- Click Add Provider
- Choose the OpenAI-compatible format
- Fill in:
- Name: TeamoRouter
- Base URL: TeamoRouter's gateway URL
- API Key: Your key from the TeamoRouter console
- Click Save
CC Switch Limitations
While CC Switch is an excellent tool, its local routing architecture has some inherent limitations:
1. Reconnecting Issues
CC Switch's local router doesn't play well with system proxies/VPNs, often triggering "cc switch reconnecting" — WebSocket heartbeats timeout passing through two layers (local router → system proxy).
2. Configuration Loss
Updates, multiple instances, and file permission issues can silently wipe your configuration.
3. VPN Conflicts
Local router + system proxy = routing conflicts, DNS resolution mismatches, and connection failures.
4. Local Process Dependency
CC Switch runs as a desktop app. Process crashes, sleep mode, and network switches interrupt your workflow.
For a deep dive into these issues, see CC Switch vs VPN: The Ultimate Solution.
The CC Switch + TeamoRouter Combo
The best of both worlds: use CC Switch as your management panel, but set TeamoRouter as your backend Provider instead of relying on CC Switch's local routing.
Why This Combo Works
- Keep CC Switch's convenience: GUI-based agent tool management
- Get TeamoRouter's gateway advantages: 99.3% cache hit rate, 0.3x-0.5x effective pricing, 99.6% SLA
- No local routing needed: Bypass CC Switch's problematic local router entirely
- Easy setup: Just add TeamoRouter as a Provider in CC Switch
Configuration Steps
For detailed instructions, see Build a Full-Power AI Coding Setup: CC Switch + TeamoRouter.
Common Error Troubleshooting
401 Unauthorized
Cause: Invalid or expired API Key Fix: Check your TeamoRouter console API Key status, regenerate and update CC Switch
402 Payment Required
Cause: Insufficient account balance Fix: Top up your TeamoRouter account
502 Bad Gateway
Cause: Backend service temporarily unavailable Fix: Check TeamoRouter's operations status page, or wait for automatic recovery
Provider Health Check Failed
Cause: CC Switch can't reach the Provider's Base URL Fix: Verify the Base URL is correct and network is connected
Advanced: Multi-Provider Load Balancing and Failover
CC Switch supports multiple providers with failover rules:
- Add multiple providers in Provider Management
- Set priority order in Routing Rules
- Configure failover triggers (timeout, HTTP error codes)
- Set TeamoRouter as primary with alternatives as backup
FAQ
What's the difference between CC Switch and TeamoRouter?
CC Switch is a local routing manager. TeamoRouter is a cloud LLM gateway. They work together — CC Switch for management, TeamoRouter as the backend.
Which agent tools does CC Switch support?
Claude Code, Codex, Gemini CLI, OpenClaw, OpenCode, VS Code Cline, WorkBuddy, Cherry Studio, and more.
Do I need to pay for the CC Switch + TeamoRouter combo?
CC Switch is free and open-source. TeamoRouter offers 50% off on your first $25, with effective costs around 10%-30% of official API pricing.
Can I use CC Switch without a VPN?
Yes. With TeamoRouter as your Provider, the cloud gateway connects directly to backend APIs — no local VPN needed.