一、官方下载渠道（安全无捆绑）

渠道1：GitHub Releases（推荐，最新稳定版）

访问 https://github.com/farion1231/cc-switch/releases

下载（v3.16.1）

国内备用（高速下载）

夸克网盘下载 | 百度网盘下载（提取码: 75u4）

  1. 页面拉到底，点击 Releases
  2. 找到最新版本，下滑到Assets，对应系统包：
系统安装包类型文件名称
Windows标准安装版CC-Switch-vx.x.x-Windows.msi
Windows便携免安装版CC-Switch-vx.x.x-Windows-Portable.zip
macOS镜像安装包CC-Switch-vx.x.x-macOS.dmg
Linux(Debian/Ubuntu)deb安装包CC-Switch-vx.x.x-Linux.deb
CC Switch GitHub Releases页面

渠道2：macOS Homebrew一键安装（无需手动下载）

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

二、分系统完整安装步骤

（一）Windows 安装（两种方案）

方案A：MSI标准安装版（新手首选）

  1. 下载 .msi 安装包，双击运行
  2. 弹出Windows SmartScreen安全拦截：点击更多信息 → 仍要运行（开源软件无风险，系统默认拦截未签名程序）
  3. 安装向导：同意许可协议 → 自定义安装路径不要使用中文文件夹（推荐默认C盘）
  4. 勾选「创建桌面快捷方式」「启动CC-Switch」，点击安装，等待1分钟完成
  5. 完成后自动启动软件

方案B：便携绿色版（免安装，U盘可用）

  1. 下载 Portable.zip 压缩包，解压到纯英文路径（如 D:\Tools\CC-Switch）
  2. 进入文件夹，双击 CC-Switch.exe 直接启动
  3. 优势：无注册表、重装系统不丢失配置；缺点：无法开机自启

Windows常见报错处理

（二）macOS 安装（两种方案）

方案A：DMG手动安装

  1. 下载 .dmg 镜像，双击打开
  2. 将左侧 CC-Switch.app 拖拽到右侧「应用程序」文件夹
  3. 首次打开提示无法验证开发者：打开「系统设置 → 隐私与安全性」，下滑找到「仍要打开」，确认启动软件

方案B：Homebrew一键安装（终端）

# 拉取软件源
brew tap farion1231/ccswitch
# 一键安装
brew install --cask cc-switch
# 直接启动
open /Applications/CC-Switch.app

（三）Linux Debian/Ubuntu 安装

  1. 下载 .deb 安装包，打开终端进入下载目录
  2. 执行安装命令：
sudo dpkg -i CC-Switch-v*.deb
# 若依赖缺失，修复依赖
sudo apt -f install
  1. 应用列表找到CC-Switch启动

三、核心完整配置教程（全流程）

前置准备

提前准备好你的AI服务商信息：

  1. API Key（服务商后台创建，如DeepSeek、Kimi、阿里云百炼、OpenAI中转等）
  2. Base URL（API接口地址，大部分国内模型格式：https://xxx.com/v1，末尾必须带 /v1）
  3. 支持的模型名称（服务商文档内标准model名）

步骤1：添加AI供应商（核心配置）

  1. 打开CC-Switch主界面，右上角点击 + 添加供应商
  2. 填写表单：
    • 名称：自定义（如DeepSeek、Qwen、Kimi）
    • Base URL：接口地址（必填，漏写 /v1 会直接404报错）
    • API Key：粘贴密钥（软件本地加密存储，不上传第三方）
    • 默认模型：填写该服务商常用模型名（如 deepseek-coder-v2）
  3. 点击测试连接，提示「连通成功」再保存，最后点击启用该供应商

示例：DeepSeek标准配置
Base URL：https://api.deepseek.com/v1
默认模型：deepseek-coder-v2

步骤2：绑定本地AI编程客户端（Claude Code/Codex/Gemini CLI）

CC-Switch作用是接管客户端配置，实现一键切换：

  1. 主界面顶部会自动识别本地已安装工具：Claude Code、Codex、Gemini CLI
  2. 选中需要管理的工具，点击绑定工作区
  3. 软件自动读取工具原有配置文件并备份，后续切换供应商会自动重写配置
  4. 多工具操作逻辑：切换供应商后，所有绑定工具同步生效

步骤3：全局功能配置（进阶）

1. MCP服务管理

侧边栏MCP图标，可批量添加本地MCP技能服务，统一分配给所有AI客户端，不用每个工具单独配置。

2. 系统提示词模板

新建预设提示词（代码优化、单元测试、架构设计等），一键全局应用到所有模型会话。

3. 用量监控

左侧用量面板，自动统计各服务商Token消耗、费用预估，支持按天/月筛选。

4. 软件基础设置（左下角齿轮）

步骤4：验证配置是否生效

  1. CC-Switch保持打开（必须常驻，关闭则AI客户端断连）
  2. 终端启动Claude Code / Codex
  3. 发送一段代码提问，能正常返回内容=配置完成
  4. 切换其他供应商，重启客户端即可切换模型

四、常见报错 & 排坑指南

  1. 调用返回404：Base URL缺少 /v1 后缀，补全地址重试
  2. 401密钥错误：复制API Key时带空格，删除前后空格重新粘贴
  3. 连接超时：中转服务商网络故障，切换其他供应商
  4. 客户端无响应 Connection refused：CC-Switch未启动，或代理端口被占用
  5. 切换模型不生效：切换供应商后必须重启Claude Code/Codex
  6. 软件保存配置丢失：安装路径含中文，重新解压/安装到纯英文目录

五、安全使用注意事项

  1. API密钥仅本地加密存储，不要导出配置文件发群、截图上传，会泄露密钥
  2. 谨慎使用不知名第三方中转网关，优先官方/大厂模型接口
  3. 公用电脑务必开启「启动密码锁」，离开电脑最小化托盘
  4. 首次绑定工具前，手动备份工具原始 settings.json 配置文件，防止异常覆盖
  5. 软件关闭后所有AI客户端无法调用API，日常保持后台常驻

六、卸载方法