在 AI 编程工具成为服务端开发标配的今天，Claude Code、Codex、Gemini CLI 等工具虽强大，但多工具间配置分散、API 供应商切换繁琐、手动编辑 JSON/TOML/.env 文件极易出错，严重拖慢开发节奏。CC-Switch 作为一款基于 Rust + Tauri 2 的跨平台开源桌面配置管理器，专为统一管理这些 AI CLI 工具而生。本文将带你从零开始，覆盖 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 启动快、内存占用低，配置仅存本地，安全无忧。内置 50+ 供应商预设，覆盖主流 API 服务商，无需手动填写端点。

二、Windows 安装：MSI 与便携版任选

Windows 用户有两种主流安装方式，根据场景灵活选择即可。

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

前往 GitHub Releases 页面，下载对应版本的 CC\-Switch\-v\{版本\}\-Windows\-x64\.msi 安装包（将版本号替换为实际版本，如 v3.13.0）。双击运行，若遇到 SmartScreen 提示“无法验证发行者”，点击「更多信息」→「仍要运行」（开源软件安全，属系统常规验证）。随后按向导点击「下一步」，保持默认安装路径（避免中文路径），完成安装后勾选启动即可。

2. ZIP 便携版

适合临时使用或系统用户名含中文的情况。下载 ZIP 包解压后直接运行 exe 文件，无需安装，删除即卸载，非常轻量。

三、macOS 安装：三种方式适配不同需求

macOS 用户可根据偏好选择 DMG、压缩包或 Homebrew 方式安装。

1. DMG 镜像（普通用户首选）

下载 CC\-Switch\-v\{版本\}\-macOS\.dmg 镜像文件，双击打开后将 CC\-Switch\.app 拖入「Applications」文件夹。首次打开若提示“无法验证开发者”，前往「系统设置」→「隐私与安全性」，点击「仍然打开」即可。

2. 压缩包版（免安装）

下载 CC\-Switch\-v\{版本\}\-macOS\.zip 压缩包，解压后将 CC\-Switch\.app 移入应用程序目录。右键点击 CC\-Switch\.app 选择「打开」，验证后即可运行。

3. Homebrew 安装（开发者最爱）

打开终端，执行以下命令即可完成安装与后续更新，无需手动下载安装包：

# 添加 CC-Switch 仓库
brew tap farion1231/ccswitch
# 安装 CC-Switch
brew install --cask cc-switch
更新时执行： 
brew upgrade --cask cc-switch

四、Linux 安装：.deb / .rpm / AppImage 全覆盖

Linux 发行版众多，CC-Switch 提供三种安装包，适配不同发行版。

1. Debian / Ubuntu 系列

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

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

2. Fedora / RHEL 系列

下载 CC\-Switch\-v\{版本\}\-Linux\-x86\_64\.rpm 安装包，执行：

sudo rpm -i CC-Switch-v{版本}-Linux-x86_64.rpm

3. 通用 AppImage 版

下载 CC\-Switch\-v\{版本\}\-Linux\-x86\_64\.AppImage 包，赋予执行权限后直接运行：

# 给 AppImage 包赋予执行权限
chmod +x CC-Switch-v{版本}-Linux-x86_64.AppImage
# 运行软件
./CC-Switch-v{版本}-Linux-x86_64.AppImage
✅ AppImage 无需安装，删除文件即卸载，适合所有发行版。

五、5 分钟快速上手：添加与切换供应商

无论哪个平台，CC-Switch 的核心操作一致。完成安装后，只需三步即可开始使用。

1. 首次启动与配置导入

启动后软件自动扫描本地已安装的 AI CLI 工具配置。若检测到已有配置，会提示「导入」，点击即可一键迁移，无需手动处理。

2. 添加供应商（Provider）

供应商 = 一套完整 API 配置（名称、Base URL、API Key、模型）。点击右上角「+」按钮，有两种添加方式：

  • 预设供应商（推荐）： 从「Preset」下拉框选择如 Claude Code、DeepSeek、Kimi 等，系统自动填充 API 端点，只需填写自己的 API Key 并命名即可。
  • 自定义供应商： 当预设中没有目标服务商时，选择「Custom」，手动填写名称、Base URL（⚠️ 末尾勿加斜杠，如 https://xiaomai\.win）、API Key 及模型。

3. 切换与验证

在供应商列表点击「Enable」，状态变为「Active」即切换成功。生效规则：Claude Code 支持热切换，无需重启终端；Codex、Gemini CLI 等需重启终端。切换后建议执行验证命令确认配置生效：

# 测试指令（任意 CLI 工具中输入）
hello, please introduce yourself
快捷技巧： 系统托盘支持右键快速切换供应商，无需打开主界面。

六、进阶玩法：多工具、MCP 与配置备份

基础配置完成后，可启用以下高级功能，进一步提升开发效率，所有功能全平台通用。

1. 多工具独立配置

主界面顶部标签页对应不同 CLI 工具（Claude、Codex、Gemini 等），可分别为每个工具添加独立供应商，互不干扰。例如，Claude Code 用 Kimi API，Codex 用 OpenAI API，完美解决多工具配置混乱问题。

2. MCP 服务器统一管理

MCP（Model Context Protocol）扩展了 AI CLI 工具的能力（如文件读取、网页搜索）。CC-Switch 提供统一管理面板，支持 stdio、HTTP、SSE 三种协议。若有 Deep Link（ccswitch:// 开头），点击即可自动导入配置，无需手动填写。

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

在「Skills」标签页，软件自动扫描 GitHub 公开仓库（官方+社区），勾选所需技能（如代码审查、规范化提交）后点击安装，自动同步到 Claude Code 的 Skills 目录，省去手动下载配置的麻烦。

4. Prompts 管理与 API 测速

使用 Markdown 编辑提示词模板，可绑定不同 CLI 工具，一键切换启用。同时，供应商列表会显示各节点延迟，自动优选最低延迟节点，提升 API 请求速度。

5. 配置备份与恢复

软件自动保留最近 10 个版本的配置文件，支持手动导出/导入。重装系统或更换设备时，可快速恢复所有配置。配置文件路径如下：

# 全平台通用路径（~ 代表当前用户目录）
~/.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 配置管理利器，彻底解决了多工具、多供应商切换繁琐、配置易错的痛点。无论你是刚入门的新手，还是经验丰富的服务端开发者，都能通过本文快速上手，将更多精力投入到代码逻辑与架构设计中。建议先完成基础配置，再逐步探索 MCP、Skills 等高级功能，解锁更高效的 AI 编程体验。

[AFFILIATE_SLOT_1]

如果你正在寻找更高效的 AI 编程工具组合，不妨试试 CC-Switch 搭配主流 CLI 工具，相信会带来惊喜。

[AFFILIATE_SLOT_2]