CC Switch 详细部署教程

CC Switch 是一款跨平台的桌面应用，用于统一管理 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes 等 AI 编程工具的 API 供应商配置。它让你告别手动编辑 JSON/TOML 配置文件的繁琐，通过图形界面一键切换不同的 API 提供商（如官方、中转、自建等）。

📋 目录

  1. CC Switch 简介与核心功能
  2. 系统要求
  3. 部署与安装
  4. 快速上手指南
  5. 高级功能概览
  6. 常见问题与故障排除

🧠 CC Switch 简介与核心功能

CC Switch 的核心价值在于它成为了 AI 编程工具的“统一遥控器”。它解决了每个 AI 工具（如 Claude Code, Codex）都有各自不同配置格式和存放路径的问题。

功能模块 核心能力
供应商管理 内置 50+ 主流供应商预设（官方、中转等），一键添加、切换和编辑配置。
一键切换 支持在主界面或系统托盘中即时切换活动供应商。Claude Code 支持热重载，切换后无需重启。
扩展管理 统一管理 MCP 服务器、提示词 (Prompts) 和 技能 (Skills)，一处编辑，多应用同步。
代理与高可用 提供本地代理服务，支持自动故障转移 (Failover)、熔断器、请求整流和用量统计。
会话管理 浏览、搜索和恢复跨应用的对话历史记录。
云同步 通过 WebDAV 在多台设备间同步配置数据。

💻 系统要求

在开始安装前，请确保你的系统满足以下要求：

平台 最低版本要求 架构
Windows Windows 10 及以上 x64 / ARM64
macOS macOS 12 (Monterey) 及以上 Intel (x64) / Apple Silicon (arm64)
Linux Ubuntu 22.04+ / Debian 11+ / Fedora 34+ x64 / ARM64

注意：CC Switch 本身是配置管理工具，但它所管理的 CLI 工具（如 Claude Code, Codex, Gemini CLI）通常需要 Node.js 18 LTS 或更高版本 的环境，请提前安装好。

📦 部署与安装

1. 获取安装包

唯一官方渠道：GitHub Releases 页面 或项目官网 ccswitch.io。请警惕任何要求付费或登录的非官方渠道。

2. Windows 安装

方式一：MSI 安装包（推荐）

  1. 下载 CC-Switch-v{版本号}-Windows.msi。
  2. 双击运行，按照指引完成安装。
  3. 安装完成后，可从开始菜单或桌面快捷方式启动。

方式二：便携版 (Portable)

  1. 下载 CC-Switch-v{版本号}-Windows-Portable.zip。
  2. 解压到任意目录，直接运行 CC-Switch.exe 即可。

3. macOS 安装

方式一：Homebrew（推荐） 

1
2
brew tap farion1231/ccswitch
brew install --cask cc-switch

更新软件：

1
brew upgrade --cask cc-switch

方式二：手动安装 DMG

  1. 下载 CC-Switch-v{版本号}-macOS.dmg。
  2. 双击打开 DMG，将 CC Switch.app 拖入 Applications 文件夹。

提示：macOS 版本已通过 Apple 代码签名和公证，可直接打开，无需额外设置。

4. Linux 安装

Arch Linux (AUR) 

1
2
3
4
# 使用 paru
paru -S cc-switch-bin
# 或使用 yay
yay -S cc-switch-bin

Debian / Ubuntu (.deb) 

1
2
3
4
# 下载 .deb 包后
sudo dpkg -i CC-Switch-v{版本号}-Linux-x86_64.deb
# 如有依赖问题
sudo apt-get install -f

通用 AppImage 

1
2
3
4
# 下载 .AppImage 文件后添加执行权限
chmod +x CC-Switch-v{版本号}-Linux-x86_64.AppImage
# 运行
./CC-Switch-v{版本号}-Linux-x86_64.AppImage

Linux (Wayland + NVIDIA) 故障排除：如果遇到界面点击无反应或调整大小时黑屏，请尝试通过环境变量切换渲染后端启动：

1
CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage

🚀 快速上手指南

安装并启动 CC Switch 后，按照以下 5 步完成首次配置：

第一步：选择应用
在 CC Switch 顶部导航栏，选择你要配置的 AI 工具，例如 Claude Code。

第二步：添加供应商

  1. 点击右上角的 + (Add Provider) 按钮。
  2. 在“预设 (Preset)”下拉菜单中，选择你的 API 供应商（例如 SiliconFlow、DeepSeek 或自定义 Custom）。选择预设后，端点地址 (Endpoint URL) 通常会自动填充。
  3. 在 API Key 字段中，粘贴你从该供应商平台获取的密钥。
  4. 点击 Add 保存。

第三步：切换供应商

  1. 在供应商列表中，找到你刚添加的卡片。
  2. 点击卡片上的 Enable 按钮。卡片边框变为蓝色，表示已激活。

第四步：激活配置
根据你使用的工具，配置生效方式不同：

  • Claude Code / Gemini CLI：支持热重载，切换后无需重启终端。
  • Codex / OpenCode / OpenClaw：需要关闭并重新打开终端。

第五步：验证配置
在终端中启动对应的 CLI 工具（如 claude），发送一条测试消息（如 “Hello”）。如果 AI 正常回复，则表示配置成功。

首运行提示：若首次启动 Claude Code 时出现登录或引导界面，可在 CC Switch 的 设置 (Settings) → 通用 (General) 中开启 “跳过 Claude Code 首次运行确认” 选项，再重启 Claude Code 即可跳过。

🛠️ 高级功能概览

除了基础的供应商管理，CC Switch 还提供了强大的扩展功能：

  • MCP 统一管理：在 MCP 面板中，可统一添加 MCP 服务器，并选择同步到哪些应用（Claude Code, Codex, Gemini CLI等）。
  • Prompts 管理：在 Prompts 面板，可用 Markdown 编辑器创建提示词预设，一键激活并同步到 CLAUDE.md、AGENTS.md 等文件。
  • Skills 管理：在 Skills 面板，可从 GitHub 仓库一键安装或卸载 Skills 扩展。
  • 代理与故障转移：在 代理服务 中开启后，可配置应用接管和故障转移队列。当主供应商不可用时，自动切换到备用供应商，提高稳定性。

🔧 常见问题与故障排除

1. 切换供应商后不生效怎么办？

  • 检查：确认是否已点击 Enable 按钮激活。
  • 工具要求：对于 Codex、OpenCode 等工具，是否已重启终端。
  • Claude Code 特例：支持热重载，无需重启。

2. 忘记数据存储位置？

  • 数据库及配置：~/.cc-switch/cc-switch.db
  • 备份目录：~/.cc-switch/backups/（自动轮转，保留最近10份）
  • Skills 目录：~/.cc-switch/skills/

3. 如何恢复到官方登录？

  1. 在添加供应商时，选择预设中的“官方登录” (Claude/Codex) 或“Google 官方” (Gemini)。
  2. 启用该供应商。
  3. 重启对应的 CLI 工具，然后按照其官方登录流程操作即可。

4. Windows 安装后无法启动？

  • 确保已安装 Microsoft Edge WebView2 运行时。
  • 检查杀毒软件是否拦截，将 CC Switch 加入白名单。

📚 总结

CC Switch 通过将繁琐的配置文件编辑抽象为直观的图形界面，大幅提升了管理 Claude Code、Codex 等 AI 编程工具的效率。其核心流程“选择工具 → 添加供应商 → 一键启用”非常清晰，且内置的 MCP、Skills 统一管理功能，使其成为 AI 开发工作流中一个强大的“控制中心”。