Claude Code provider switch: a CC Switch tutorial in 5 minutes

This tutorial follows CC Switch v4.0.26 (November 2026). Button labels may change in later releases; the configuration model is stable.

Switching Claude Code between providers usually means editing ~/.claude/settings.json: the base URL, the API key, and sometimes the model. With one provider that is manageable. With two or three, it becomes a small maintenance job — and the failure mode is quiet, because a stale ANTHROPIC_* export in your shell can override the file you just edited.

CC Switch turns the switch into a card you click. Its built-in AiHubMix preset fills the endpoint, and you paste one API key. Claude Code usually reloads the change without a restart. This tutorial walks through the full setup, then explains what CC Switch writes, the environment-variable trap, and when direct mode is enough.

If you only want the short version: install CC Switch, create an AIHubMix key, choose the AiHubMix preset under Claude Code, paste the key, add ANTHROPIC_MODEL=claude-sonnet-5-5 to the provider, click Switch, and run claude -p "1+1, output only the answer" --model claude-sonnet-5-5. The rest of this post is the detail behind those steps.

What CC Switch is

CC Switch is an open-source desktop app (MIT, Tauri + Rust + React) for managing provider configurations across Claude Code, Codex, Gemini CLI, OpenCode, and other coding tools. It ships more than 90 provider presets and supports custom providers.

It is more than a key switcher:

• Direct mode rewrites the key fields in the client's configuration file and lets the client talk to the provider.
• Routing mode runs a local gateway at 127.0.0.1:15721, with API-format conversion, failover, health checks, and request logs.
• Aggregation mode puts models from several providers into one /model list.

The repository and user manual are at github.com/farion1231/cc-switch. Only ccswitch.io and the GitHub Releases page are official download sources; any site that asks for payment or account credentials is not.

Before you start

You need three things:

• Claude Code installed and runnable from a terminal. Check with claude --version. If it is missing, use the official installer: curl -fsSL https://claude.ai/install.sh | bash, or npm i -g @anthropic-ai/claude-code with Node.js 22 or newer.
• An AIHubMix account and API key. Create one in the AIHubMix console. The key usually starts with sk-.
• A CC Switch installer. Download it from ccswitch.io or GitHub Releases.

Step 1: Install CC Switch

On first launch, CC Switch imports the existing Claude Code configuration as a provider named default and adds an official provider. Your original configuration is not lost; you can switch back at any time.

If Claude Code is not installed yet, the Apps page in CC Switch can install or upgrade it.

Step 2: Create an AIHubMix API key

Open the AIHubMix API keys page, create a key, and copy it.

The placeholder AIHUBMIX_API_KEY in the documentation is not a real key. If you paste it verbatim, the request fails with 401 invalid key: AIHUBMIX_API_KEY.

Step 3: Add AIHubMix to Claude Code

1. Select Claude Code in the left sidebar.
2. Click the + button in the top-right corner.
3. Search for AiHubMix, or find it under the third-party platforms category.
4. The name and endpoint are filled in automatically: https://aihubmix.com. Paste your key into API Key.
5. Click Add.

The preset stores two environment variables:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com"
  }
}

The preset does not set a model. AIHubMix's guide treats ANTHROPIC_MODEL as a core variable, so add it to the same env block before you switch:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5"
  }
}

Without a model, Claude Code sends its own default model ID, which may not be one AIHubMix serves.

Two details are worth knowing.

Do not append /v1 to the base URL. Claude Code speaks the Anthropic Messages protocol and builds the request path itself. https://aihubmix.com is correct; https://aihubmix.com/v1 is the OpenAI-compatible base for other clients, and Claude Code would append its own /v1/messages to it.

The preset uses ANTHROPIC_API_KEY, while AIHubMix's own Claude Code guide uses ANTHROPIC_AUTH_TOKEN. AIHubMix accepts both: ANTHROPIC_AUTH_TOKEN sends a Bearer header, and ANTHROPIC_API_KEY sends x-api-key. Pick one. Do not fill both with different values. The AIHubMix setup details, model IDs, and error reference are in the AIHubMix Claude Code documentation.

If the preset is missing — for example, in an older release or after you deleted the card — choose Custom Configuration and paste the JSON above. The provider card's endpoint manager can test latency; the preset also includes https://api.aihubmix.com as an alternate endpoint if aihubmix.com does not resolve.

Step 4: Switch and verify

On the Direct tab, click Switch on the AiHubMix card. The button changes to In use when the configuration has been written.

Claude Code reloads the configuration automatically; a restart is not usually required. If the current session keeps using the old provider, exit and start it again.

Verify the end-to-end path:

claude -p "1+1, output only the answer" --model claude-sonnet-5-5

A response of 2 means the request reached AIHubMix. In an interactive session, the Anthropic base URL line in /status should show https://aihubmix.com.

For quick changes, use the system tray: right-click the CC Switch icon, open the Claude Code submenu, and click a provider. The submenu title shows the active provider and a quota summary.

To go back to the official provider, switch to Claude Official, restart Claude Code, and complete the login flow.

What the switch actually changes

In direct mode, CC Switch replaces only the connection and compatibility fields in ~/.claude/settings.json: ANTHROPIC_*, AWS_*, protocol selectors such as CLAUDE_CODE_USE_BEDROCK, model, apiKeyHelper, and a few provider-scoped compatibility options such as CLAUDE_CODE_DISABLE_ARTIFACT and the context window.

permissions, hooks, enabledPlugins, statusLine, MCP configuration, comments, and anything else you added stay in place. The exact list is in the configuration-file reference.

Before the first rewrite of a tool's configuration, CC Switch backs up the original to ~/.cc-switch/backups/live-first-write/. If the JSON is malformed, it refuses to write, reports the line and column, and leaves the file unchanged.

The trap: stale ANTHROPIC_* variables

This is the failure that looks like CC Switch did not work.

If you previously followed a manual setup guide and added export ANTHROPIC_BASE_URL=... or export ANTHROPIC_AUTH_TOKEN=... to ~/.zshrc or ~/.bash_profile, those variables may override the values CC Switch writes. You switch the card to AIHubMix, but requests still go to the old endpoint.

CC Switch detects the conflict. A yellow banner at the top of the window says environment variables may override your configuration; the details show the variable name, value, and source. Delete Selected removes them and writes a backup to ~/.cc-switch/backups/env-backup-<timestamp>.json first.

To check manually:

grep -n "ANTHROPIC" ~/.zshrc ~/.bash_profile 2>/dev/null

Comment out the old exports, then run source ~/.zshrc or open a new terminal. AIHubMix's own documentation recommends removing global ANTHROPIC_* variables when CC Switch manages the configuration. The full conflict workflow is in the environment-variable reference.

Model aliases and switching

With ANTHROPIC_MODEL set, Claude Code's default is Sonnet 5.5. The /model aliases (opus, sonnet, haiku, fable) still need mapping if you want them to resolve to AIHubMix's model IDs. Add these keys inside env:

The complete provider configuration then looks like this:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5-1"
  }
}

Model selection priority, highest first: /model <name> → claude --model <name> → ANTHROPIC_MODEL → the model field in settings.json. Copy model IDs from the AIHubMix model list; they are case-sensitive.

When to use routing or aggregation

Direct mode is the right default for AIHubMix. The endpoint already speaks Anthropic Messages, so no protocol conversion is needed.

Use routing when you want a failover queue, or when you need to put an OpenAI-format provider behind Claude Code. Routing points Claude Code at http://127.0.0.1:15721, replaces the key in the config with PROXY_MANAGED, and injects the real key from CC Switch. The app must stay running; quitting CC Switch writes the direct configuration back. Official Claude subscriptions do not go through routing; use direct mode for those.

Use aggregation when you want models from several providers in one /model list. The default provider handles requests without a prefix; other providers' models appear with a ccs- prefix. Aggregation does not fail over. It is available for Claude Code and Codex only, and Claude official subscriptions are not supported in aggregation. The ccs- model list needs Claude Code 2.1.243 or newer. Claude Code picks up model-list changes immediately; Codex needs a full restart.

What else CC Switch manages

• Usage: the dashboard combines routed request logs with local session logs. Session scanning works without routing and is priced from the model recorded in the log; routed requests are logged separately.
• MCP: a unified panel for MCP servers, synced to the apps you select.
• Skills: discover, install, and remove skills from one place.
• Sessions: search, view, export, and resume local sessions.
• Projects: save a project's provider, MCP servers, skills, and memory files as a snapshot, then switch the whole set per project.

Data lives in ~/.cc-switch/, with a SQLite database at its center. Automatic backups keep the most recent 10 by default, and WebDAV or S3-compatible sync is available. The database and exported backups include provider configurations, including keys, so treat them as secrets.

Troubleshooting

The error strings below are quoted from AIHubMix's Claude Code documentation.

For non-error symptoms:

• Login screen or Not logged in: check /status; enable Skip Claude Code first-run confirmation under Settings → App config → Claude Code; restart; confirm the key is filled in.
• The switch has no effect: a stale shell variable or cached session; open a new terminal or restart Claude Code.
• The card's connection test passes but requests fail: the test checks reachability, not the key or model; run the end-to-end claude -p command.
• You want the official provider back: switch to Claude Official, restart Claude Code, and log in again.

If the claude command is not found on macOS, the official installer usually places it in ~/.local/bin/claude. Add export PATH="$HOME/.local/bin:$PATH" to your shell profile and open a new terminal.

Checklist

• [ ] Install CC Switch from ccswitch.io or GitHub Releases.
• [ ] Create an API key in the AIHubMix console.
• [ ] In Claude Code → + → AiHubMix → paste the key → Add.
• [ ] Add ANTHROPIC_MODEL=claude-sonnet-5-5 to the provider JSON.
• [ ] Click Switch and confirm the card shows In use.
• [ ] Remove stale ANTHROPIC_* exports from your shell profile.
• [ ] Run claude -p "1+1, output only the answer" --model claude-sonnet-5-5 and check for 2.

If the last command returns 2, the provider switch is complete. The remaining work is adding any model aliases you want and deciding whether you need routing or aggregation; for most AIHubMix users, direct mode is enough.

FAQ

Is CC Switch free?
Yes. It is MIT open source. You pay only the provider whose API you use.

Does switching delete my hooks, MCP servers, or plugins?
No. Direct switching replaces the endpoint, key, model, and a few provider-scoped options. Hooks, permissions, MCP servers, plugins, and status-line settings stay in the file.

Does CC Switch upload my API key?
Provider configurations are stored locally in ~/.cc-switch/cc-switch.db. If you enable WebDAV or S3 sync, they sync to storage you control. Databases and backups contain keys, so handle them as secrets.

Do I need to keep CC Switch running?
Not in direct mode. Routing and aggregation need the app running; quitting CC Switch returns the client to direct mode.

Can I use Claude Official and AIHubMix at the same time?
Direct mode has one active provider at a time. Aggregation can put several providers' models in one list, but the Claude official subscription is not supported there; switch back to direct to use it.

Does it work on Windows?
Yes. CC Switch supports Windows 10 and later with an .msi installer or a portable build. Linux needs glibc 2.35+ and WebKitGTK 4.1.

Why does the provider card show a healthy connection but Claude Code still fails?
The card's connectivity check tests whether the endpoint is reachable. It does not validate the API key or the model. Use the end-to-end claude -p command to test the full path.

Sources

• CC Switch repository
• CC Switch user manual: Add Provider
• CC Switch user manual: Switch Provider
• CC Switch user manual: Configuration Files
• AIHubMix documentation: Claude Code