CC-Switch 完整下载、安装、配置全教程（2026最新版）
一、官方下载渠道（安全无捆绑）
渠道1：GitHub Releases（推荐，最新稳定版）
一、下载（v3.16.1）
🚀 国内备用（高速下载）
https://pan.quark.cn/s/d6152047213b （含 v3.16.1 全平台包）
- 页面拉到底，点击Releases
- 找到最新版本，下滑到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|
渠道：macOS Homebrew一键安装（无需手动下载）
brew tap farion1231/ccswitch brewinstall--caskcc-switch三、分系统完整安装步骤
（一）Windows 安装（两种方案）
方案A：MSI标准安装版（新手首选）
- 下载
.msi安装包，双击运行 - 弹出Windows SmartScreen安全拦截：点击更多信息 → 仍要运行（开源软件无风险，系统默认拦截未签名程序）
- 安装向导：同意许可协议 → 自定义安装路径不要使用中文文件夹（推荐默认C盘）
- 勾选「创建桌面快捷方式」「启动CC-Switch」，点击安装，等待1分钟完成
- 完成后自动启动软件
方案B：便携绿色版（免安装，U盘可用）
- 下载
Portable.zip压缩包，解压到纯英文路径（如D:\Tools\CC-Switch） - 进入文件夹，双击
CC-Switch.exe直接启动 - 优势：无注册表、重装系统不丢失配置；缺点：无法开机自启
Windows常见报错处理
- 启动闪退：右键程序→以管理员身份运行，杀毒软件将文件夹加入白名单
- 端口占用：关闭其他AI代理工具，重启CC-Switch
（二）macOS 安装（两种方案）
方案A：DMG手动安装
- 下载
.dmg镜像，双击打开 - 将左侧
CC-Switch.app拖拽到右侧「应用程序」文件夹 - 首次打开提示无法验证开发者：
打开「系统设置 → 隐私与安全性」，下滑找到「仍要打开」，确认启动软件
方案B：Homebrew一键安装（终端）
# 拉取软件源brew tap farion1231/ccswitch# 一键安装brewinstall--caskcc-switch# 直接启动open/Applications/CC-Switch.app（三）Linux Debian/Ubuntu 安装
- 下载
.deb安装包，打开终端进入下载目录 - 执行安装命令：
sudodpkg-iCC-Switch-v*.deb# 若依赖缺失，修复依赖sudoapt-finstall- 应用列表找到CC-Switch启动
四、核心完整配置教程（全流程）
前置准备
提前准备好你的AI服务商信息：
- API Key（服务商后台创建，如DeepSeek、Kimi、阿里云百炼、OpenAI中转等）
- Base URL（API接口地址，大部分国内模型格式：
https://xxx.com/v1，末尾必须带/v1） - 支持的模型名称（服务商文档内标准model名）
步骤1：添加AI供应商（核心配置）
- 打开CC-Switch主界面，右上角点击+ 添加供应商
- 填写表单：
- 名称：自定义（如DeepSeek、Qwen、Kimi）
- Base URL：接口地址（必填，漏写
/v1会直接404报错） - API Key：粘贴密钥（软件本地加密存储，不上传第三方）
- 默认模型：填写该服务商常用模型名（如deepseek-coder-v2）
- 点击测试连接，提示「连通成功」再保存，最后点击启用该供应商
示例：DeepSeek标准配置
Base URL：https://api.deepseek.com/v1
默认模型：deepseek-coder-v2
步骤2：绑定本地AI编程客户端（Claude Code/Codex/Gemini CLI）
CC-Switch作用是接管客户端配置，实现一键切换：
- 主界面顶部会自动识别本地已安装工具：Claude Code、Codex、Gemini CLI
- 选中需要管理的工具，点击绑定工作区
- 软件自动读取工具原有配置文件并备份，后续切换供应商会自动重写配置
- 多工具操作逻辑：切换供应商后，所有绑定工具同步生效
步骤3：全局功能配置（进阶）
1. MCP服务管理
侧边栏MCP图标，可批量添加本地MCP技能服务，统一分配给所有AI客户端，不用每个工具单独配置。
2. 系统提示词模板
新建预设提示词（代码优化、单元测试、架构设计等），一键全局应用到所有模型会话。
3. 用量监控
左侧用量面板，自动统计各服务商Token消耗、费用预估，支持按天/月筛选。
4. 软件基础设置（左下角齿轮）
- 开机自启、最小化托盘（推荐开启，保持后台代理运行）
- 启动密码锁（多人共用电脑必开，保护API密钥）
- 数据导出/备份：定期导出配置防止丢失
- 本地代理端口：默认11434，端口冲突可自定义修改
步骤4：验证配置是否生效
- CC-Switch保持打开（必须常驻，关闭则AI客户端断连）
- 终端启动Claude Code / Codex
- 发送一段代码提问，能正常返回内容=配置完成
- 切换其他供应商，重启客户端即可切换模型
五、常见报错&排坑指南
- 调用返回404：Base URL缺少
/v1后缀，补全地址重试 - 401密钥错误：复制API Key时带空格，删除前后空格重新粘贴
- 连接超时：中转服务商网络故障，切换其他供应商
- 客户端无响应 Connection refused：CC-Switch未启动，或代理端口被占用
- 切换模型不生效：切换供应商后必须重启Claude Code/Codex
- 软件保存配置丢失：安装路径含中文，重新解压/安装到纯英文目录
六、安全使用注意事项
- API密钥仅本地加密存储，不要导出配置文件发群、截图上传，会泄露密钥
- 谨慎使用不知名第三方中转网关，优先官方/大厂模型接口
- 公用电脑务必开启「启动密码锁」，离开电脑最小化托盘
- 首次绑定工具前，手动备份工具原始
settings.json配置文件，防止异常覆盖 - 软件关闭后所有AI客户端无法调用API，日常保持后台常驻
七、卸载方法
- Windows：控制面板→程序→卸载CC-Switch；便携版直接删除文件夹
- macOS：应用程序右键移到废纸篓，终端清理残留
brew uninstall --cask cc-switch - Linux：
sudo apt remove cc-switch
