保姆级 CC-Switch v3.16.1 全流程教程｜小白零踩坑
前置说明（必看避坑）
CC-Switch 是开源本地AI编程工具调度管理器，用于统一管理Claude Code、Codex、Gemini CLI等AI编程客户端，本地加密存储API密钥，不上传隐私数据，MIT开源免费。
重要合规&安全提醒
- 仅使用官方渠道下载，第三方网盘/破解包存在密钥窃取风险；
- 仅接入国内合规大模型API服务商，禁止违规跨境直连境外服务；
- 所有API Key仅保存在本地电脑，软件无云端上传行为；
- v3.16.1为当前稳定版，兼容Windows10+/macOS12+/全主流Linux发行版。
一、官方渠道下载 v3.16.1（分系统）
渠道1：GitHub Releases（原版，推荐）
国内备用（高速）： https://pan.quark.cn/s/d6152047213b
打开Releases页面找到v3.16.1，根据系统下载对应包：
| 系统 | 推荐安装包 | 便携免安装包 |
|---|---|---|
| Windows | CC-Switch-v3.16.1-x64.msi（自动更新） | CC-Switch-v3.16.1-x64-Portable.zip |
| macOS | CC-Switch-v3.16.1-universal.dmg（Intel/M2/M3通用） | CC-Switch-v3.16.1-mac.zip |
| Linux | .deb(Ubuntu/Debian)、.rpm(Fedora) | .AppImage全发行版通用 |
渠道2：官网镜像 ccswitch.io（国内访问更快）
进入官网首页→Download，直接自动匹配系统下载v3.16.1安装包。
下载避坑点
- Windows下载弹出SmartScreen拦截：点更多信息→仍要运行，开源无数字签名属正常；
- 不要下载带“破解/绿色修改版”的二次打包文件；
- 下载后校验文件名必须带
v3.16.1，避免下成旧版。
二、分系统安装步骤（图文对照）
1. Windows MSI安装版（新手首选）
- 双击下载的
.msi安装包，弹出安装向导，点击Next； - 许可协议勾选
I accept，继续Next； - 关键：改安装路径
默认C盘，点击Change，选择D/E盘新建文件夹（例：D:\Tools\CCSwitch），避免C盘爆满； - 一路Next，等待进度条走完；
- 完成页勾选
Launch CC Switch，点击Finish自动启动。
Windows便携版（不想写注册表）
- 解压
Portable.zip到纯英文无空格路径（禁止中文文件夹！如D:\ccswitch，不能是D:\工具\CC切换）； - 直接双击
CC-Switch.exe运行，无安装流程，删除文件夹即卸载。
2. macOS 安装（DMG版）
- 双击
.dmg镜像，弹出窗口； - 将
CC Switch.app拖拽到右侧「应用程序」文件夹； - 首次打开提示无法验证开发者（正常）：
打开「系统设置→隐私与安全性」，下滑找到“CC Switch被阻止”，点击仍要打开； - 后续启动直接在启动台打开即可。
macOS Homebrew命令行快速安装（开发者）
打开终端逐条执行：
brew tap farion1231/ccswitch brewinstall--caskcc-switch3. Linux 安装
Ubuntu/Debian(.deb)
sudodpkg-icc-switch_3.16.1_amd64.deb# 缺失依赖执行修复sudoapt-finstall-y通用AppImage（所有Linux）
# 赋予执行权限chmod+x CC-Switch-v3.16.1.AppImage# 运行./CC-Switch-v3.16.1.AppImage三、首次启动初始化配置（零报错流程）
- 打开软件，等待自动扫描本地AI工具（Claude Code、Codex、Gemini CLI等）；
- 顶部工具栏是已识别工具切换栏，点对应图标切换管理对象；
- 弹窗询问「开机自启」：按需勾选（建议开发电脑开启）；
- 初始界面为空，下一步添加API服务商。
四、核心操作：添加&配置API服务商（最常用）
方式A：使用内置预设（小白首选，自动填地址）
- 主界面右上角点击**+ 添加供应商**；
- 在弹窗顶部切换「预设供应商」；
- 下拉选择服务商：DeepSeek、智谱GLM、Kimi、阿里百炼、MiniMax等50+模板；
- 仅需填写2项：
- Provider名称：自定义备注（如DeepSeek编程）
- API Key：你在服务商后台复制的密钥
- 点击
Add保存，自动填充BaseURL，无需手动修改。
方式B：自定义服务商（小众API/私有中转）
- 添加弹窗选择「自定义配置」；
- 3个必填项（致命避坑：BaseURL末尾不能带斜杠
/）- 名称：自定义
- Base URL：API地址（正确示例：
https://api.deepseek.com/v1；错误：https://api.deepseek.com/v1/） - API Key：密钥
- 可选：模型映射、自定义单价、备用故障转移服务商；
- 保存完成。
一键切换模型使用
- 选中顶部目标工具（Claude Code）；
- 服务商列表右侧点击启用按钮；
- 状态变为
Active即生效：- Claude Code：热切换，终端直接使用，无需重启；
- Codex/Gemini CLI：需要重启客户端生效。
五、进阶实用功能保姆级设置
1. 多密钥故障自动切换（避免会话崩溃）
- 添加2个及以上服务商；
- 打开软件「设置→路由配置」；
- 开启自动故障转移，设置重试次数、超时时间；
- 主服务商请求失败时，自动切备用API，不会中断代码会话。
2. MCP/Skills/系统提示词统一管理
右上角图标栏快速切换：
- 提示词：批量保存代码专用系统提示，一键绑定服务商；
- MCP：统一管理所有AI工具的本地MCP服务，不用分别改配置；
- Skills：插件能力批量开关。
3. Token用量&费用统计
左侧「用量面板」自动统计：请求次数、输入/输出Token、预估成本，支持按日期筛选，自定义各模型单价。
六、全平台高频踩坑&解决方案
下载/安装报错
- Windows解压/安装提示中文路径报错
解决：全部文件夹改为纯英文，不含空格、中文、特殊符号。 - macOS打开提示损坏
终端执行修复命令：xattr-cr/Applications/CC\Switch.app - Linux AppImage双击无反应
解决：右键→属性→权限，勾选「允许作为程序执行」。
API调用失败（90%新手踩这3个）
- BaseURL末尾多加
/→ 删除末尾斜杠重新保存； - API Key复制带空格 → 删除前后多余空格；
- 服务商余额不足/模型无权限 → 登录API后台检查额度。
切换后工具不生效
- Claude Code：关闭终端重新打开会话；
- Codex/Gemini CLI：完全退出软件重开；
- 软件权限不足：Windows右键以管理员运行，macOS授予磁盘完全权限。
密钥丢失/重装备份
- 软件右上角设置→配置备份，导出
.ccs-backup加密文件； - 重装后直接导入备份，一键恢复所有服务商密钥与设置。
七、卸载教程（干净无残留）
- Windows安装版：设置→应用，卸载CC-Switch；便携版直接删除文件夹；
- macOS：应用程序中将CC Switch拖到废纸篓；Homebrew卸载：
brew uninstall --cask cc-switch； - Linux deb：
sudo apt remove cc-switch；AppImage直接删除文件即可。