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 Moyi API:
- Click Provider Management in the left sidebar
- Click Add Provider
- Choose the OpenAI-compatible format
- Fill in:
- Name: Moyi API
- Base URL: Moyi API's gateway URL
- API Key: Your key from the Moyi API 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 + Moyi API Combo
The best of both worlds: use CC Switch as your management panel, but set Moyi API 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 Moyi API's gateway advantages: 99.3% cache hit rate, 0.3x-0.5x effective pricing, 99.98% SLA
- No local routing needed: Bypass CC Switch's problematic local router entirely
- Easy setup: Just add Moyi API as a Provider in CC Switch
Configuration Steps
For detailed instructions, see Build a Full-Power AI Coding Setup: CC Switch + Moyi API.
Common Error Troubleshooting
401 Unauthorized
Cause: Invalid or expired API Key Fix: Check your Moyi API console API Key status, regenerate and update CC Switch
402 Payment Required
Cause: Insufficient account balance Fix: Top up your Moyi API account
502 Bad Gateway
Cause: Backend service temporarily unavailable Fix: Check Moyi API'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 Moyi API as primary with alternatives as backup
FAQ
What's the difference between CC Switch and Moyi API?
CC Switch is a local routing manager. Moyi API is a cloud LLM gateway. They work together — CC Switch for management, Moyi API 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 + Moyi API combo?
CC Switch is free and open-source. Moyi API 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 Moyi API as your Provider, the cloud gateway connects directly to backend APIs — no local VPN needed.