CC Switch
访问官网

CC Switch 安装与多模型切换教程

用一个桌面工具统一管理 Claude Code、Codex、Gemini CLI、OpenCode 和 OpenClaw 的 API Key、Base URL 与模型配置。

推荐
BLUF 摘要（点开查看）

这篇教程用 5 个章节、15 个操作点说明如何安装 CC Switch，并把多个 AI 工具的供应商配置集中管理；最终成功标准是在真实 CLI 里发起一次模型调用并正常收到回复。

教程概览（点开查看）

预计耗时：约 10-15 分钟

准备材料：API 平台账号、API Key、Base URL、模型名称，以及要配置的 Claude Code / Codex / Gemini CLI 等工具。

成功标志：真实 AI 工具里发起简单对话，模型能正常返回结果。

最容易卡住：工具标签选错、Base URL 路径写错、模型名和供应商文档不一致。

安全提醒：API Key 不要截图、不要写进公开仓库。

教程步骤（5 章 / 15 个操作点）
1. CC Switch 是什么2. 下载与安装3. 添加 API 供应商4. 在 AI 工具里验证5. 常见问题
1

CC Switch 是什么

CC Switch 是一个开源的跨平台桌面端 AI 编程工具配置中心。它可以接管 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 等工具的本地配置文件，用图形界面统一管理 API Key、Base URL、模型名称、代理、MCP 和 Skills，减少手动改 JSON、TOML、env 文件导致的配置错误。

1.1 适合谁使用

如果你经常在多个 API 供应商或多个 AI 编程工具之间切换，CC Switch 能明显减少重复配置成本。

  • 经常使用 Claude Code、Codex、Gemini CLI、OpenCode 或 OpenClaw
  • 同时购买了 DeepSeek、Kimi、智谱、通义千问、MiMo、OpenAI 等多个 API
  • 需要在便宜模型、强模型和备用节点之间快速切换
  • 不想手动编辑 settings.json、AGENTS.md、CLAUDE.md 或环境变量文件

1.2 核心能力

它不是单纯改 API 地址的小工具，而是把供应商配置、模型切换、MCP、Prompt 和 Skills 集中到一个面板里。

  • 多供应商一键切换：内置常见模型厂商和中转服务商预设
  • 配置可视化：在界面里填写 API Key、Endpoint、Model Name，降低格式错误概率
  • 系统托盘热切换：运行任务时可快速切换下一个模型或供应商
  • MCP 与 Skills 管理：把多个 AI 终端工具的扩展能力集中维护
  • 本地存储：配置数据保存在本机，适合重视密钥安全的用户

核心要点

  • 项目地址：github.com/farion1231/cc-switch
  • 配置前先准备好对应平台的 API Key、Base URL 和模型名称
  • 密钥仍然属于敏感信息，不要把截图或配置文件公开发布
2

下载与安装

CC Switch 通过 GitHub Releases 发布安装包。Windows 用户优先下载 MSI，macOS 用户下载 DMG，Linux 用户按发行版选择 deb、rpm 或 AppImage。

2.1 打开发布页面

进入 GitHub Releases 页面，展开最新版本的 Assets 区域。

2.2 Windows 安装

Windows 用户推荐下载 .msi 安装包，双击后按向导安装。

  • 优先选择 CC-Switch-版本号-Windows.msi
  • 如果电脑没有管理员权限，可选择 Portable zip 便携版
  • 便携版建议解压到不含中文和特殊字符的目录，例如 D:\Tools\CC-Switch

2.3 macOS 安装

macOS 用户下载 .dmg 文件，打开后把 CC Switch 拖入 Applications。

code
brew tap farion1231/ccswitch
brew install --cask cc-switch
  • 普通用户推荐使用 DMG 图形安装
  • 习惯 Homebrew 的用户可使用命令行安装
  • 安装后从启动台或应用程序目录打开 CC Switch

2.4 Linux 安装

Linux 用户按发行版选择对应包格式。AppImage 需要先赋予执行权限。

code
# Debian / Ubuntu
sudo apt install ./CC-Switch-*.deb

# Fedora / RHEL
sudo dnf install ./CC-Switch-*.rpm

# AppImage
chmod +x CC-Switch-*.AppImage
./CC-Switch-*.AppImage
  • Ubuntu、Debian、Linux Mint 优先使用 deb
  • Fedora、RHEL、CentOS、Rocky Linux 优先使用 rpm
  • 不确定发行版时可使用 AppImage

注意事项

  • 只从官方 GitHub 项目或可信发布页下载安装包
  • 安装前关闭来源不明的同名工具，避免混淆配置文件
3

添加 API 供应商

安装完成后，第一步是为你正在使用的 AI 工具添加供应商。以 Claude Code 为例，选择对应工具标签后添加 DeepSeek、Kimi、智谱、通义、MiMo 或 OpenAI 等供应商。

3.1 选择要配置的工具

打开 CC Switch 后，先选择 Claude Code、Codex、Gemini CLI、OpenCode 或 OpenClaw 对应标签，确保配置写入正确位置。

  • 使用 Claude Code 就选择 Claude Code 标签
  • 使用 Codex 就选择 Codex 标签
  • 多个工具都用时，建议逐个工具分别配置和测试
⚠️ 不要在错误的工具标签下添加供应商，否则实际使用的 AI 工具可能读不到配置。

3.2 添加供应商预设

点击 Add Provider 或右上角加号，从内置预设中选择你购买的 API 平台。

  • 优先使用内置预设，它会自动填好协议类型和常见 Endpoint
  • 如果平台不在预设列表里，选择自定义供应商
  • 填写 Provider Name、API Endpoint、API Key、Model Name
  • 保存前检查 Base URL 末尾路径是否和平台文档一致

3.3 示例：接入 OpenAI 兼容 API

多数国产和中转平台都提供 OpenAI 兼容格式，通常只需要填 API Key、Base URL 和模型名。

code
Provider Name: DeepSeek
API Endpoint: https://api.deepseek.com
API Key: sk-xxxxxxxxxxxxxxxx
Model Name: deepseek-v4-flash
  • DeepSeek 可使用 https://api.deepseek.com
  • MiMo 可使用 https://api.xiaomimimo.com/v1
  • 通义、Kimi、智谱等平台按各自官方文档填写
  • 保存后用对应 AI 工具发起一次简单对话测试

核心要点

  • 每个平台的 Base URL 和模型名可能会更新，最终以官方控制台或文档为准
  • 建议先配置一个低成本模型用于日常任务，再配置一个强模型用于复杂任务
  • 新增或切换供应商后，必要时重启对应 AI 终端工具以确保配置生效
4

在 AI 工具里验证

供应商保存后，需要在实际工具中验证。验证目标不是只看 CC Switch 里是否保存成功，而是确认 Claude Code、Codex 或其他工具能读取新配置并正常调用模型。

4.1 验证 Claude Code

打开一个新的终端窗口，进入项目目录后启动 Claude Code，发送一个简单问题。

code
claude
  • 建议重新打开终端，避免旧进程缓存旧配置
  • 询问简单问题，例如「请用一句话介绍当前模型」
  • 如果能正常回答，说明供应商配置已经生效
  • 如果报 401、403 或余额不足，优先检查 API Key 和账户状态

4.2 验证 Codex 或其他 CLI

选择对应工具标签配置后，用该工具自己的启动命令测试。

  • Codex、Gemini CLI、OpenCode、OpenClaw 都需要在各自标签下配置
  • 确认工具读取的是 CC Switch 写入的配置路径
  • 同一平台在不同工具下可能需要不同协议格式，保存前查看预设说明

4.3 使用托盘热切换

配置多个供应商后，可以通过系统托盘快速切换当前模型。

  • 日常轻量任务使用低成本模型
  • 复杂重构、长上下文分析时切换到强模型
  • 备用节点可作为 API 限流或故障时的替代方案
  • 切换后如未立即生效，重启对应 AI 工具或新开会话再试

注意事项

  • 不同 AI 工具对热切换的响应方式不同，遇到不生效时先新开会话验证
  • 不要把包含 API Key 的 CC Switch 配置库直接上传到公开仓库
5

常见问题

大多数问题集中在 API Key、Base URL、模型名、工具标签选错和旧进程缓存配置这几类。

5.1 保存后工具仍然没有响应

先确认配置写入的是你正在使用的工具标签，再重启终端和 AI 工具。

  • 检查是否选错 Claude Code、Codex 或 OpenCode 标签
  • 重新打开终端窗口
  • 确认对应 AI 工具本身已经安装并能启动
  • 查看 CC Switch 是否有配置保存失败或权限提示

5.2 提示认证失败

认证失败通常来自 API Key 错误、复制了多余空格、账户未充值或平台权限未开通。

  • 重新复制 API Key，避免前后空格
  • 确认账号已完成实名、充值或套餐开通
  • 检查 Key 是否被删除、禁用或过期
  • 不要把 OpenAI 平台的 Key 填到其他供应商预设里

5.3 提示模型不存在

模型名必须和供应商文档完全一致，大小写、连字符和版本号都可能影响调用。

  • 在平台模型列表里复制模型 ID
  • 使用 Fetch Models 或类似按钮拉取可用模型
  • 确认当前 API Key 有权限访问该模型
  • 不确定时先换成平台推荐的默认聊天模型测试

核心要点

  • 排查顺序：工具标签 → API Key → Base URL → 模型名 → 账户余额 → 网络代理
  • 配置成功后建议记录一组稳定可用的低成本模型，作为日常默认方案

关键词

多工具配置API KeyBase URL模型切换