前置说明必看避坑CC-Switch 是开源本地AI编程工具调度管理器用于统一管理Claude Code、Codex、Gemini CLI等AI编程客户端本地加密存储API密钥不上传隐私数据MIT开源免费。重要合规安全提醒仅使用官方渠道下载第三方网盘/破解包存在密钥窃取风险仅接入国内合规大模型API服务商禁止违规跨境直连境外服务所有API Key仅保存在本地电脑软件无云端上传行为v3.16.1为当前稳定版兼容Windows10/macOS12/全主流Linux发行版。一、官方渠道下载 v3.16.1分系统渠道1GitHub Releases原版推荐国内备用高速 https://pan.quark.cn/s/d6152047213b打开Releases页面找到v3.16.1根据系统下载对应包系统推荐安装包便携免安装包WindowsCC-Switch-v3.16.1-x64.msi自动更新CC-Switch-v3.16.1-x64-Portable.zipmacOSCC-Switch-v3.16.1-universal.dmgIntel/M2/M3通用CC-Switch-v3.16.1-mac.zipLinux.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# 赋予执行权限chmodx 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 URLAPI地址正确示例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.appLinux 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-switchLinux debsudo apt remove cc-switchAppImage直接删除文件即可。
保姆级 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分系统渠道1GitHub Releases原版推荐国内备用高速 https://pan.quark.cn/s/d6152047213b打开Releases页面找到v3.16.1根据系统下载对应包系统推荐安装包便携免安装包WindowsCC-Switch-v3.16.1-x64.msi自动更新CC-Switch-v3.16.1-x64-Portable.zipmacOSCC-Switch-v3.16.1-universal.dmgIntel/M2/M3通用CC-Switch-v3.16.1-mac.zipLinux.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# 赋予执行权限chmodx 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 URLAPI地址正确示例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.appLinux 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-switchLinux debsudo apt remove cc-switchAppImage直接删除文件即可。
