CC-Switch 全平台下载、安装与使用全指南（Windows/macOS/Linux）

zzzb1234562026-04-30 8:58

前言

在 AI 编程工具普及的今天，Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 等工具已成为开发者标配，但多工具配置分散、API 供应商切换繁琐、手动改配置易出错等问题，严重拖慢开发效率。

CC-Switch 作为一款跨平台开源桌面配置管理器，基于 Rust + Tauri 2 开发，具备启动快、内存占用低、配置本地安全存储等优势，支持 Windows、macOS、Linux 全平台统一管理 AI 编程 CLI 工具，内置 50+ 供应商预设，彻底告别手动编辑 JSON、TOML、.env 配置文件的繁琐操作，是 AI 开发者必备的效率神器。

本文覆盖 Windows、macOS、Linux 全平台安装与使用，从零基础入门到进阶功能一站式讲解，步骤清晰、细节拉满，适合所有层级开发者快速上手，轻松搞定多工具配置管理难题。

一、核心信息速览（必看）

快速了解 CC-Switch 核心参数，按需选择配置方式，节省时间：

项目 详情
软件定位 AI 编程 CLI 工具统一配置管理器（开源跨平台）
支持平台 Windows 10+（64位）、macOS 12+、Linux（Ubuntu 22.04+/Debian 11+/Fedora 34+）
核心功能 供应商一键切换、系统托盘快切、MCP 统一管理、Skills 一键安装、Prompts 管理、API 测速、配置备份/恢复
存储方式 本地 SQLite 数据库，采用原子写入机制，防止配置文件损坏
推荐版本 v3.13.0 及以上（修复多项兼容问题，运行更稳定）
下载 https://pan.quark.cn/s/ce7ed4e4acd5

二、全平台安装包说明

CC-Switch 为不同系统提供专属安装包，适配各类使用场景，按需选择即可，避免无效下载：

  • Windows 系统：.msi 安装版（一键部署，新手首选）、.zip 便携版（无需安装，临时使用/中文用户名适配）

  • macOS 系统：.dmg 镜像（已公证，直接安装）、.zip 压缩包、Homebrew 命令行安装（开发者首选）

  • Linux 系统：.deb 包（Debian/Ubuntu 系列）、.rpm 包（Fedora/RHEL 系列）、.AppImage 通用包（无环境限制，直接运行）

三、全平台详细安装步骤（附避坑细节）

每个系统提供多种安装方式，步骤清晰，新手可直接跟着操作，全程无复杂命令，避开所有常见坑。

（一）Windows 安装

1. MSI 安装版（推荐，新手首选）

  1. 访问 GitHub Releases 页面，下载对应版本的 CC\-Switch\-v\{版本\}\-Windows\-x64\.msi 安装包（替换{版本}为实际版本号，如 v3.13.0）；

  2. 双击运行安装包，若遇到 Windows SmartScreen 提示"无法验证发行者"，点击「更多信息」，再点击「仍要运行」（开源软件安全无风险，此为系统常规安全验证）；

  3. 跟随安装向导，依次点击「下一步」，接受许可协议，安装路径默认即可（无需手动修改，避免中文路径）；

  4. 点击「安装」，等待 1-2 分钟完成安装，勾选「启动 CC-Switch」，点击「完成」，软件将自动启动。

（二）macOS 安装（三种方式，适配不同需求）

1. DMG 镜像安装（推荐，普通用户首选）

  1. 下载 CC\-Switch\-v\{版本\}\-macOS\.dmg 镜像文件；

  2. 双击打开镜像文件，将左侧的 CC\-Switch\.app 拖拽到右侧「Applications」文件夹中，完成安装；

  3. 首次打开软件时，若提示"无法验证开发者"，无需担心，前往「系统设置」→「隐私与安全性」，在页面下方找到对应提示，点击「仍然打开」即可正常启动。

2. 压缩包版（临时使用，无需安装）

  1. 下载 CC\-Switch\-v\{版本\}\-macOS\.zip 压缩包；

  2. 双击解压压缩包，将解压后的 CC\-Switch\.app 拖入「应用程序」目录；

  3. 右键点击 CC\-Switch\.app，选择「打开」，完成权限验证后即可运行。

3. Homebrew 命令行安装（开发者首选，便捷更新）

打开 macOS 终端（Terminal），依次执行以下命令，无需手动下载安装包：

bash 复制代码 
# 添加 CC-Switch 仓库
brew tap farion1231/ccswitch
# 安装 CC-Switch
brew install --cask cc-switch

后续更新软件，只需执行以下命令：

bash 复制代码 
brew upgrade --cask cc-switch

（三）Linux 安装（三种方式，适配不同发行版）

1. Debian / Ubuntu 系列（.deb 包，最常用）

下载 CC\-Switch\-v\{版本\}\-Linux\-x86\_64\.deb 安装包，打开终端，进入安装包所在目录，执行以下命令：

bash 复制代码 
# 安装 deb 包
sudo dpkg -i CC-Switch-v{版本}-Linux-x86_64.deb
# 若出现依赖缺失，执行以下命令修复
sudo apt -f install -y

安装完成后，在应用列表中找到 CC-Switch，点击即可启动。

2. Fedora / RHEL 系列（.rpm 包）

下载 CC\-Switch\-v\{版本\}\-Linux\-x86\_64\.rpm 安装包，打开终端，进入安装包所在目录，执行以下命令：

bash 复制代码 
sudo rpm -i CC-Switch-v{版本}-Linux-x86_64.rpm

安装完成后，直接在应用列表启动即可。

3. 通用 AppImage 版（无环境限制，所有 Linux 发行版适配）

下载 CC\-Switch\-v\{版本\}\-Linux\-x86\_64\.AppImage 包，打开终端，进入安装包所在目录，执行以下命令：

bash 复制代码 
# 给 AppImage 包赋予执行权限
chmod +x CC-Switch-v{版本}-Linux-x86_64.AppImage
# 运行软件
./CC-Switch-v{版本}-Linux-x86_64.AppImage

无需安装，执行命令即可运行，卸载只需删除该 AppImage 文件。

四、全平台通用快速上手（5 分钟搞定基础配置）

无论哪个系统，CC-Switch 的核心操作完全一致，只需掌握"添加供应商 → 切换供应商"，即可完成基础配置，快速使用。

1. 首次启动

启动 CC-Switch 后，软件会自动扫描本地已安装的 AI CLI 工具配置，若有已存在的配置，会提示"导入配置"，新手直接点击「导入」即可，无需手动操作；

主界面布局清晰：顶部为 CLI 工具标签页（如 Claude、Codex、Gemini），中间为供应商列表，右上角为「+」添加按钮，操作直观，无需额外学习。

2. 添加供应商（Provider）

供应商是一套完整的 API 配置，包含「供应商名称、API 端点（Base URL）、API 密钥（API Key）、模型」四部分，切换供应商即自动将配置写入对应 CLI 工具，无需手动修改文件。提供两种添加方式，按需选择：

方式 1：使用预设供应商（推荐，新手首选）

  1. 点击主界面右上角「+」按钮，选择「Add Provider」；

  2. 在弹出的窗口中，点击「Preset（预设）」下拉框，选择需要的供应商（如 Claude Code、OpenAI、Kimi、DeepSeek 等），预设会自动填充 API 端点，无需手动输入；

  3. 在「API Key」输入框中，填入自己的对应供应商 API 密钥（密钥需从对应供应商平台获取，如 Kimi 需在其官网控制台创建令牌）；

  4. 自定义供应商名称（如"Kimi API - Claude"），方便后续识别，点击「Add」，即可完成供应商添加，此时供应商会出现在主界面列表中。

方式 2：自定义供应商（预设中无目标供应商时使用）

  1. 点击主界面右上角「+」按钮，选择「Custom（自定义）」；

  2. 填写以下信息（以小麦 API 为例）：

    • 供应商名称：自定义（如"小麦 API - Codex"）；

    • API 端点（Base URL）：https://xiaomai\.win（重点：末尾不要加斜杠，否则会导致 API 请求失败）；

    • API 密钥：自己的小麦 API Key（格式通常为 sk-xxxx）；

    • 模型：根据需求选择（如 claude-sonnet-4-20250514）。

  3. 点击「Add」，完成自定义供应商配置。

3. 切换与启用供应商

  1. 在主界面的供应商列表中，找到需要启用的供应商，点击其右侧的「Enable（启用）」按钮；

  2. 当供应商状态变为「Active（活跃）」，说明切换成功；

  3. 生效规则（全平台通用）：

    • Claude Code：支持热切换，无需重启终端，切换后立即生效；

    • Codex、Gemini CLI、OpenCode 等其他工具：需关闭终端，重新打开后，新配置才会生效。

  4. 快捷切换：全平台支持系统托盘右键快速切换供应商，无需打开主界面，提升操作效率。

4. 配置验证（关键步骤，避免配置失败）

切换供应商后，建议立即验证配置是否生效，避免后续使用出错，全平台验证方法一致：

text 复制代码 
# 测试指令（任意 CLI 工具中输入）
hello, please introduce yourself

若 CLI 工具能正常返回响应，说明配置成功；若未响应，检查 API Key、Base URL 是否正确，或重启终端重试。

五、全平台通用高级功能（按需启用，提升效率）

完成基础配置后，可根据自身需求启用以下高级功能，进一步提升 AI 编程效率，所有功能全平台通用，操作一致。

1. 多工具独立配置

CC-Switch 顶部有对应 CLI 工具的标签页（如 Claude、Codex、Gemini、OpenCode），切换到对应标签页，可为每个工具单独添加供应商，互不冲突。例如：为 Claude Code 添加 Kimi API，为 Codex 添加 OpenAI API，各自独立生效，无需重复设置，解决多工具配置混乱问题。

2. MCP 服务器统一管理

MCP（Model Context Protocol）是 AI CLI 工具的扩展协议，用于扩展工具功能（如文件读取、网页搜索、上下文管理等）。CC-Switch 提供统一的 MCP 管理面板，一次配置可同步到所有支持的 CLI 工具，无需分别设置：

  1. 进入主界面顶部的「MCP」标签页；

  2. 点击「导入已有」，可导入已配置的 MCP 服务器；或点击「添加」，新建 MCP 服务器（支持 stdio、HTTP、SSE 三种协议）；

  3. 若有 MCP 服务器的 Deep Link（ccswitch:// 开头），点击即可自动导入，无需手动填写配置，操作便捷。

3. Skills 一键安装（Claude Code 专属）

Skills 是 Claude Code 的扩展功能，可实现代码审查、规范化提交、语法检查等功能，CC-Switch 支持一键安装，无需手动下载配置：

  1. 切换到主界面顶部的「Skills」标签页；

  2. 软件会自动扫描 GitHub 上的公开 Skills 仓库（包含官方、社区优质资源）；

  3. 找到需要的 Skills（如代码审查、规范化提交），勾选后点击「安装」，即可自动同步到 Claude Code 的 Skills 目录，无需手动操作。

4. Prompts 管理

支持用 Markdown 编辑系统提示词模板，可按不同 CLI 工具绑定对应提示词，需要时一键切换启用，无需重复输入，大幅提升提示词使用效率，尤其适合经常使用固定提示词的开发者。

5. API 测速与配置备份

  • API 测速：在供应商管理列表中，可查看每个供应商节点的延迟，自动优选延迟最低的节点，提升 API 请求速度；

  • 配置备份：软件自动保留最近 10 个版本的配置文件，支持手动导出/导入，防止配置损坏、丢失，重装软件后可快速恢复配置。

六、全平台配置文件路径（重要，备份/恢复必备）

掌握配置文件路径，方便后续备份、恢复配置，或解决配置损坏问题，全平台路径如下（通用路径+具体路径，清晰易懂）：

text 复制代码 
# 全平台通用路径（~ 代表当前用户目录）
~/.cc-switch/cc-switch.db       # 主配置数据库（核心文件，备份重点）
~/.cc-switch/settings.json     # 软件全局设置
~/.cc-switch/backups/          # 自动备份目录（保留最近10个版本）
~/.cc-switch/skills/           # Skills 扩展目录

# Windows 系统具体路径（替换"你的用户名"为实际用户名）
C:\Users\你的用户名\.cc-switch\

# macOS 系统具体路径
/Users/你的用户名/.cc-switch/

# Linux 系统具体路径（普通用户/root 用户）
/Users/你的用户名/.cc-switch/
/root/.cc-switch/

七、全平台常见问题解决方案（避坑指南）

整理全平台高频问题及解决方案，无需复杂排查，直接对照操作即可解决，新手必看：

常见问题 解决方案
切换供应商后，配置不生效 重启对应 CLI 工具的终端（Claude Code 除外，支持热切换）；检查 Base URL 末尾无多余斜杠
Windows 软件启动失败、白屏 更换便携版，解压到无中文、无空格的路径；删除 cc-switch.db 文件，重启软件重新配置
macOS 无法打开软件，提示"无法验证开发者" 前往「系统设置」→「隐私与安全性」，找到对应提示，点击「仍然打开」
配置损坏、丢失 从 ~/.cc-switch/backups/ 目录恢复备份；或删除 cc-switch.db 文件，重启软件重新添加配置
无法删除当前激活的供应商 先切换到其他供应商配置，再删除闲置的供应商（系统强制保留至少1个有效配置）
API 请求失败 检查 API Key 是否正确、未泄露；检查 Base URL 末尾无斜杠；确认供应商支持对应 CLI 工具的 API 格式
Linux 安装后无法启动 检查依赖是否安装完整（Debian/Ubuntu 执行 sudo apt -f install）；使用 AppImage 版重试

八、总结

CC-Switch 作为全平台 AI 编程 CLI 配置管理神器，完美解决了多工具、多供应商切换繁琐、配置分散、易出错的痛点，支持 Windows、macOS、Linux 全平台，界面简洁、操作简单、安全稳定，且开源免费。

无论你是零基础新手，还是重度 AI 编程开发者，都能通过本文快速完成安装、配置，大幅提升开发效率，彻底告别手动编辑配置文件的繁琐。建议安装后先完成基础配置，再根据自身需求启用 MCP、Skills 等高级功能，解锁更高效的 AI 编程体验。

如果本文对你有帮助，欢迎点赞、收藏、转发，关注博主获取更多 AI 工具实用教程！

相关推荐
云达闲人1 小时前
搭建DevOps企业级仿真实验环境：004Proxmox 内核调优与虚拟化优化
linux·服务器·devops·硬件加速·linux内核调优·虚拟化优化·内存气球
探序基因1 小时前
单细胞转录组Seurat去批次-FastMNN算法及大细胞量评测
linux·算法
Lugas Luo1 小时前
识别DDR故障的“数据总线测试算法”
linux·嵌入式硬件
BetterNow.1 小时前
安卓内存Previous为什么可以算进freeRam
android·linux·安卓·安卓性能·安卓内存
nashane1 小时前
HarmonyOS长列表scrollToIndex性能优化全解析
windows·harmonyos 5
时空自由民.1 小时前
ESP32 IDF HTTP OTA升级流程原理
linux·单片机
东北甜妹2 小时前
K8s -Daemonset,kube-proxy,service,statefulset
linux·运维·服务器
idolao2 小时前
CentOS 7 安装 xampp-linux-1.8.1.tar.gz 详细步骤（解压、启动、验证）
linux·运维·centos
热门推荐
01GitHub 镜像站点022026年4月AI大事件深度解读：大模型竞争进入“深水区“03近期有什么ai的新消息，新动态？ 2026.4月04Codex 接入 DeepSeek API 完整配置文档05【AI】2026 年具身智能模型和世界模型总结062026年AI编程工具终极横评：Cursor vs Claude Code vs Copilot07实测可用｜小米 MiMo 百万亿 Token 免费领，开发者速冲08在Windows 11上安装Docker的踩坑记录09裂开！ChatGPT 居然开始要手机号验证，附详细解决方法102026年AI前瞻：量子AI、具身智能与科学发现的新纪元