Claude Code 供应商切换：5 分钟学会使用 CC Switch

本教程基于 CC Switch v4.0.26（2026 年 11 月）。后续版本的按钮名称可能会变，但配置模型保持稳定。

在不同供应商之间切换 Claude Code，通常需要编辑 ~/.claude/settings.json：基础 URL、API 密钥，有时还要改模型。只有一个供应商时，这还算好管理。但如果有两三个，就会变成一项小型维护工作，而且故障不易察觉，因为 shell 中过期的 ANTHROPIC_* 导出变量可能覆盖你刚编辑的文件。

CC Switch 将切换操作变成了一张可点击的卡片。它内置的 AiHubMix 预设会自动填入端点，你只需粘贴一个 API 密钥。Claude Code 通常会自动重新加载更改，无需重启。本教程将介绍完整的设置流程，然后说明 CC Switch 写入了什么、环境变量陷阱是什么，以及何时使用直接模式就足够了。

如果你只想看简版：安装 CC Switch，创建一个 AIHubMix 密钥，在 Claude Code 下选择 AiHubMix 预设，粘贴密钥，向供应商配置中添加 ANTHROPIC_MODEL=claude-sonnet-5-5，点击切换，然后运行 claude -p "1+1, output only the answer" --model claude-sonnet-5-5。本文其余部分将详细解释这些步骤。

CC Switch 是什么

CC Switch 是一款开源桌面应用（MIT 许可证，基于 Tauri + Rust + React），用于管理 Claude Code、Codex、Gemini CLI、OpenCode 及其他编程工具的供应商配置。它内置 90 多种供应商预设，也支持自定义供应商。

它不只是一个密钥切换工具：

• 直接模式会重写客户端配置文件中的密钥字段，让客户端直接与供应商通信。
• 路由模式会在本地启动一个网关 127.0.0.1:15721，支持 API 格式转换、故障切换、运行状况检查和请求日志。
• 聚合模式会将多个供应商的模型放入同一个 /model 列表。

项目仓库和用户手册位于 github.com/farion1231/cc-switch。只有 ccswitch.io 和 GitHub Releases 页面是官方下载来源；任何要求付款或提供账户凭据的网站都不是官方来源。

开始之前

你需要准备三样东西：

• 已安装 Claude Code，并且可以在终端中运行。使用 claude --version 检查。如果尚未安装，请使用官方安装程序：curl -fsSL https://claude.ai/install.sh | bash；或者在 Node.js 22 或更高版本环境下运行 npm i -g @anthropic-ai/claude-code。
• AIHubMix 账户和 API 密钥。在AIHubMix 控制台创建密钥。密钥通常以 sk- 开头。
• CC Switch 安装程序。从 ccswitch.io 或 GitHub Releases 下载。

第 1 步：安装 CC Switch

首次启动时，CC Switch 会将现有的 Claude Code 配置导入为名为 default 的供应商，并添加一个官方供应商。你的原始配置不会丢失，随时可以切换回去。

如果尚未安装 Claude Code，可以在 CC Switch 的应用页面中安装或升级。

第 2 步：创建 AIHubMix API 密钥

打开 AIHubMix API 密钥页面，创建一个密钥并复制。

文档中的占位符 AIHUBMIX_API_KEY 并非真实密钥。如果直接原样粘贴，请求会因 401 invalid key: AIHUBMIX_API_KEY 而失败。

第 3 步：将 AIHubMix 添加到 Claude Code

1. 在左侧边栏中选择Claude Code。
2. 点击右上角的+按钮。
3. 搜索 AiHubMix，或在第三方平台类别下找到它。
4. 名称和端点会自动填入：https://aihubmix.com。在API 密钥字段中粘贴你的密钥。
5. 点击添加。

该预设会存储两个环境变量：

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

该预设不会设置模型。AIHubMix 的指南将 ANTHROPIC_MODEL 视为核心变量，因此切换之前，请将它添加到同一个 env 代码块中：

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

如果没有设置模型，Claude Code 会发送自己的默认模型 ID，而 AIHubMix 可能不提供该模型。

有两点值得注意。

不要在基础 URL 后面添加 /v1。Claude Code 使用 Anthropic Messages 协议，并会自行构建请求路径。正确的地址是 https://aihubmix.com；https://aihubmix.com/v1 是供其他客户端使用的 OpenAI 兼容基础 URL，Claude Code 会在其后追加自己的 /v1/messages。

该预设使用 ANTHROPIC_API_KEY，而 AIHubMix 自己的 Claude Code 指南使用 ANTHROPIC_AUTH_TOKEN。AIHubMix 两种方式都接受：ANTHROPIC_AUTH_TOKEN 会发送 Bearer 请求头，而 ANTHROPIC_API_KEY 会发送 x-api-key。选择其中一种即可。不要给两者填入不同的值。AIHubMix 的设置详情、模型 ID 和错误参考，请参阅AIHubMix Claude Code 文档。

如果找不到该预设（例如使用较旧版本，或已删除该卡片），请选择自定义配置并粘贴上面的 JSON。供应商卡片中的端点管理器可以测试延迟；如果 aihubmix.com 无法解析，该预设还提供备用端点 https://api.aihubmix.com。

第 4 步：切换并验证

在直接选项卡中，点击 AiHubMix 卡片上的切换。配置写入后，按钮会变为正在使用。

Claude Code 会自动重新加载配置，通常无需重启。如果当前会话仍在使用旧供应商，请退出并重新启动。

验证整个请求链路：

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

如果返回 2，就表示请求已到达 AIHubMix。在交互式会话中，/status 里的 Anthropic base URL 一行应显示 https://aihubmix.com。

要快速切换，请使用系统托盘：右键点击 CC Switch 图标，打开 Claude Code 子菜单，然后点击某个供应商。子菜单标题会显示当前启用的供应商和配额摘要。

要切回官方供应商，请切换到Claude Official，重启 Claude Code，然后完成登录流程。

切换实际上会更改什么

在直接模式下，CC Switch 只会替换 ~/.claude/settings.json 中的连接和兼容性字段：ANTHROPIC_*、AWS_*、CLAUDE_CODE_USE_BEDROCK 等协议选择器、model、apiKeyHelper，以及少数针对特定供应商的兼容性选项，例如 CLAUDE_CODE_DISABLE_ARTIFACT 和上下文窗口。

permissions、hooks、enabledPlugins、statusLine、MCP 配置、注释以及你添加的其他内容都会保留。确切列表请参阅配置文件参考。

首次重写某个工具的配置前，CC Switch 会将原始配置备份到 ~/.cc-switch/backups/live-first-write/。如果 JSON 格式错误，它会拒绝写入，报告行号和列号，并保持文件不变。

陷阱：过期的 ANTHROPIC_* 变量

这是最容易让人误以为 CC Switch 没有生效的故障。

如果你之前参考手动设置指南，在 ~/.zshrc 或 ~/.bash_profile 中添加了 export ANTHROPIC_BASE_URL=... 或 export ANTHROPIC_AUTH_TOKEN=...，这些变量可能会覆盖 CC Switch 写入的值。你把卡片切换到 AIHubMix，但请求仍会发送到旧端点。

CC Switch 会检测到此冲突。窗口顶部会显示黄色横幅，提示环境变量可能会覆盖配置；详情中会列出变量名称、值和来源。删除所选项会移除这些变量，并在操作前将备份写入 ~/.cc-switch/backups/env-backup-<timestamp>.json。

手动检查方法：

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

注释掉旧的导出语句，然后运行 source ~/.zshrc，或打开一个新终端。AIHubMix 自己的文档建议，在由 CC Switch 管理配置时，移除全局 ANTHROPIC_* 变量。完整的冲突处理流程请参阅环境变量参考。

模型别名与切换

设置 ANTHROPIC_MODEL 后，Claude Code 默认使用 Sonnet 5.5。若想让 /model 别名（opus、sonnet、haiku、fable）解析为 AIHubMix 的模型 ID，仍需进行映射。将以下键添加到 env 中：

完整的供应商配置如下所示：

{
  "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 <name> → claude --model <name> → ANTHROPIC_MODEL → settings.json 中的 model 字段。从AIHubMix 模型列表复制模型 ID；它们区分大小写。

何时使用路由或聚合模式

对于 AIHubMix，直接模式是默认的最佳选择。该端点本身就支持 Anthropic Messages 协议，因此无需进行协议转换。

如果你需要故障切换队列，或想让 Claude Code 使用 OpenAI 格式的供应商，请使用路由模式。路由模式会让 Claude Code 连接到 http://127.0.0.1:15721，将配置中的密钥替换为 PROXY_MANAGED，并由 CC Switch 注入真实密钥。CC Switch 必须保持运行；退出后，它会将直接配置写回。官方 Claude 订阅不会经过路由；使用这类订阅时请使用直接模式。

如果你想在一个/model列表中使用多个供应商的模型，请使用聚合。默认供应商会处理不带前缀的请求；其他供应商的模型会显示为带ccs-前缀的名称。聚合模式不支持故障转移。此功能仅适用于 Claude Code 和 Codex，且不支持 Claude 官方订阅。ccs-模型列表需要 Claude Code 2.1.243 或更高版本。Claude Code 会立即应用模型列表的变更；Codex 则需要完全重启。

CC Switch 还能管理什么

• 用量：仪表板会汇总路由请求日志和本地会话日志。无需路由也可以扫描会话；费用根据日志中记录的模型计算，路由请求则单独记录。
• MCP：统一管理 MCP 服务器的面板，并同步到你选择的应用。
• 技能：在一个地方发现、安装和移除技能。
• 会话：搜索、查看、导出和恢复本地会话。
• 项目：将项目的供应商、MCP 服务器、技能和记忆文件保存为快照，然后按项目切换整套配置。

数据存储在~/.cc-switch/中，核心是一个 SQLite 数据库。默认情况下，自动备份会保留最近 10 份；此外还支持 WebDAV 或兼容 S3 的同步。数据库和导出的备份包含供应商配置（包括密钥），请将其视为机密。

故障排除

以下错误文本引自 AIHubMix 的 Claude Code 文档。

非错误类问题：

• 登录界面或Not logged in：检查/status；在 Settings → App config → Claude Code 下启用Skip Claude Code first-run confirmation；重启；确认已填入密钥。
• 切换未生效：可能是 shell 变量过时或会话已缓存；打开新的终端或重启 Claude Code。
• 卡片上的连接测试通过，但请求失败：该测试只检查是否可连接，不验证密钥或模型；运行端到端命令claude -p。
• 想要切回官方供应商：切换到 Claude Official，重启 Claude Code，然后重新登录。

如果在 macOS 上找不到claude命令，官方安装程序通常会将它安装到~/.local/bin/claude。将export PATH="$HOME/.local/bin:$PATH"添加到 shell 配置文件，然后打开新的终端。

检查清单

• [ ] 从 ccswitch.io 或 GitHub Releases 安装 CC Switch。
• [ ] 在 AIHubMix 控制台创建 API 密钥。
• [ ] 在 Claude Code → + → AiHubMix → 粘贴密钥 → 添加。
• [ ] 将ANTHROPIC_MODEL=claude-sonnet-5-5添加到供应商 JSON 配置中。
• [ ] 点击切换，并确认卡片显示正在使用。
• [ ] 从 shell 配置文件中移除过时的ANTHROPIC_*导出项。
• [ ] 运行claude -p "1+1, output only the answer" --model claude-sonnet-5-5并检查结果是否为2。

如果最后一条命令返回2，说明供应商切换已完成。接下来只需添加你想要的模型别名，并决定是否需要路由或聚合；对于大多数 AIHubMix 用户，直连模式就足够了。

常见问题

CC Switch 是免费的吗？
是的。它采用 MIT 开源许可证。你只需向所用 API 的供应商付费。

切换会删除我的 hooks、MCP 服务器或插件吗？
不会。直连切换只会替换端点、密钥、模型以及少数特定于供应商的选项。hooks、权限、MCP 服务器、插件和状态栏设置都会保留在文件中。

CC Switch 会上传我的 API 密钥吗？
供应商配置会存储在本地的~/.cc-switch/cc-switch.db中。如果启用 WebDAV 或 S3 同步，配置会同步到你控制的存储空间。数据库和备份中包含密钥，请将其视为机密。

我需要让 CC Switch 一直运行吗？
直连模式不需要。路由和聚合需要应用保持运行；退出 CC Switch 后，客户端会恢复为直连模式。

我可以同时使用 Claude Official 和 AIHubMix 吗？
直连模式一次只能启用一个供应商。聚合模式可以将多个供应商的模型放在同一个列表中，但不支持 Claude 官方订阅；要使用该订阅，请切回直连模式。

它能在 Windows 上运行吗？
可以。CC Switch 支持 Windows 10 及更高版本，并提供.msi安装程序或便携版。Linux 需要 glibc 2.35+ 和 WebKitGTK 4.1。

为什么供应商卡片显示连接正常，但 Claude Code 仍然失败？
卡片上的连通性检查用于测试端点是否可访问，不会验证 API 密钥或模型。请使用端到端命令claude -p测试完整链路。

来源

• CC Switch 代码仓库
• CC Switch 用户手册：添加供应商
• CC Switch 用户手册：切换供应商
• CC Switch 用户手册：配置文件
• AIHubMix 文档：Claude Code