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.

CC Switch moves Claude Code onto AIHubMix through one provider card, one API key, and one model ID, and Claude Code picks up the change without a restart in the usual case. The result is a working Claude Code session against AIHubMix, with your hooks, permissions, MCP configuration, and plugins still in ~/.claude/settings.json, and a card click to switch back.

The engineering problem is not the switch. It is everything around it: the base URL path, the model ID the preset leaves out, and the ANTHROPIC_* exports in your shell profile that can override the file CC Switch just wrote. That last failure is quiet — no error about precedence, just requests going to the old endpoint.

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 sections below cover the parts that need judgment.

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. The repository and user manual are at github.com/farion1231/cc-switch.

Three modes matter:

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

Download only from ccswitch.io or the GitHub Releases page. A site that asks for payment or account credentials is not an official source.

Prerequisites

• Claude Code, runnable from a terminal. Check with claude --version. If it is missing, use 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 from one of the official sources above.

Step 1: Install CC Switch

OS	Install
macOS 12 Monterey or later	brew install --cask cc-switch, or the signed and notarized .dmg
Windows 10 or later	The .msi installer, or the portable .zip
Debian / Ubuntu	The .deb package
Fedora / RPM distributions	The .rpm package
Arch Linux	paru -S cc-switch-bin
Other Linux	The .AppImage; requires glibc 2.35+ and WebKitGTK 4.1

On first launch, CC Switch imports your existing Claude Code configuration as a provider named default and adds an official provider. Your original configuration is not lost, and 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 matter at this point.

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; Claude Code would append its own /v1/messages to it.

The preset uses ANTHROPIC_API_KEY; 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, and do not fill both with different values. The setup details, model IDs, and error reference are in the AIHubMix Claude Code documentation.

If the preset is missing — an older release, or a card you deleted — choose Custom Configuration and paste the JSON above. The provider card's endpoint manager can test latency, and the preset 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.

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

Focused commands

Three commands cover the whole path:

# CLI on PATH
claude --version

# end-to-end request through the configured provider
claude -p "1+1, output only the answer" --model claude-sonnet-5-5

# stale exports that can override the written configuration
grep -n "ANTHROPIC" ~/.zshrc ~/.bash_profile 2>/dev/null

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

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.

Provider configurations live 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.

Model aliases

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

Role	Variable	AIHubMix model ID
Default	ANTHROPIC_MODEL	claude-sonnet-5-5
Opus alias	ANTHROPIC_DEFAULT_OPUS_MODEL	claude-opus-5-5
Sonnet alias	ANTHROPIC_DEFAULT_SONNET_MODEL	claude-sonnet-5-5
Haiku alias	ANTHROPIC_DEFAULT_HAIKU_MODEL	claude-haiku-5-5
Fable alias	ANTHROPIC_DEFAULT_FABLE_MODEL	claude-fable-5-1

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.

Failure modes and fixes

Stale ANTHROPIC_* variables

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. The card says In use, but requests still go to the old endpoint.

CC Switch detects the conflict. A yellow banner at the top of the window warns that 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, run the third command above. 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.

Errors from AIHubMix

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

Error	What to do
401 no key provided	Check the base URL; clear stale env vars.
401 invalid key: AIHUBMIX_API_KEY	Use the real key, not the placeholder.
401 this key is not enabled	Check the key and quota in the console.
400 Incorrect model ID	Copy the full ID from the model list.

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.
• claude 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.

When direct mode is not enough

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 this walkthrough cannot verify for you

• Your CC Switch build. The steps follow v4.0.26 (November 2026). Later releases can move button labels; the configuration model is stable. An older release may not ship the AiHubMix preset, in which case use Custom Configuration.
• That Claude Code reloaded. The card shows the configuration was written. The /status base URL and the end-to-end command show the request path. If a session keeps the old provider, restart it.
• The card's connection check. It tests reachability, not your API key or your model. A passing result is not an end-to-end pass.
• Your account state. Check whether the key is enabled and has quota in the AIHubMix console; the error table gives the strings to look for.
• Model IDs. Copy them from the AIHubMix model list, and keep the casing; they are case-sensitive. The card's connection check does not validate the model ID.
• The error strings' provenance. They are quoted from AIHubMix's Claude Code documentation, not generated by your installation.
• Download legitimacy. Only ccswitch.io and GitHub Releases are official download sources. A site that asks for payment or account credentials is not.

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