cc-switch 安装与使用全指南

前言

随着 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes Agent 等 AI 编码工具的快速迭代，开发者需要在不同的 API 提供商之间频繁切换。手动编辑各工具的 JSON/TOML/.env 配置既繁琐，又极易出错。cc-switch 正是为此而生：它是一款跨平台（Windows | macOS | Linux）的 All‑in‑One Manager，使用 Tauri 打造的桌面 UI，统一管理 50+ AI 代理配置、MCP 与 Skills，支持一键快速切换。

官方站点: https://ccswitch.io

下面我们结合项目源码（https://github.com/farion1231/cc-switch）给出从源码到实战的完整流程。

1. 获取源码与编译

1.1 环境准备

发行版	必装依赖	说明
Ubuntu/Debian	build-essential git cmake libssl-dev	编译 C++ 与 Tauri 所需的 OpenSSL
CentOS/RHEL	Development Tools git cmake openssl-devel	同上
Arch Linux	base-devel git cmake openssl	同上

使用对应包管理器安装后，确保 node 与 pnpm 已就绪（项目使用 pnpm 管理前端依赖）。

1
2
3
# 以 Ubuntu 为例
sudo apt update && sudo apt install -y build-essential git cmake libssl-dev nodejs npm
npm i -g pnpm

1.2 拉取源码并编译

1
2
3
4
5
6
7
8
9
# 克隆仓库
git clone https://github.com/farion1231/cc-switch.git ~/cc-switch
cd ~/cc-switch

# 安装前端依赖
pnpm install

# 编译 Tauri 桌面应用（Linux 默认生成 AppImage）
pnpm tauri build

编译成功后，src-tauri/target/release/bundle/appimage/cc-switch_*.AppImage 即为可执行文件。直接双击或在终端执行即可启动 UI。

若只想获取预编译二进制，可在 GitHub Releases 页面下载对应平台的安装包（.deb、.rpm、AppImage）。

2. 基础使用与配置

2.1 添加 AI 代理

打开 cc-switch 主界面 → Providers → Add Provider。在弹窗中填写下列必填字段：

字段	示例	说明
Provider Name	Kimi	自定义标识
API Base URL	https://api.kimi.ai/v1	官方或自建代理地址
API Key	sk-xxxx	访问凭证
Model	Kimi‑Code‑V2	目标模型

保存后，右侧会自动生成对应 MCP（Model‑Context‑Protocol）配置文件，供 Claude Code、OpenClaw 等工具直接引用。

2.2 快速切换

在 Profiles 页面可以创建多个 Profile（如 default、code‑only、gemini）。每个 Profile 关联若干 Provider，支持一键切换：

1
2
# 通过 UI 切换，也可使用 CLI
cc-switch use code-only

切换后，cc-switch 会自动写入对应工具的配置文件（如 ~/.config/claude-code/config.json），实现全局生效。

2.3 脚本钩子

1
2
hooks:
  on_switch: "~/scripts/notify_switch.sh"

notify_switch.sh 将收到 old_profile new_profile 两个参数，可用于告警、日志或自动重启依赖服务。

3. 实战案例

3.1 多模型混合使用

假设你在同一项目中需要 Claude Code（主代码生成）和 Gemini CLI（多语言翻译），可以这样配置两套 Provider 并创建两份 Profile：

1
2
3
4
5
profiles:
  claude:
    providers: ["Claude‑Opus"]
  gemini:
    providers: ["Gemini‑Pro"]

随后在终端执行 cc-switch use claude 即可让 Claude Code 自动读取最新的 API Key；切换到 gemini 时，Gemini CLI 将使用对应的 Key。

3.2 CI/CD 自动化

在 GitHub Actions 中加入以下步骤，即可在构建阶段使用统一的代理配置，避免因网络限制导致 pip install、npm install 超时：

1
2
3
4
5
6
7
steps:
  - name: Install cc-switch (AppImage)
    run: |
      curl -L https://github.com/farion1231/cc-switch/releases/latest/download/cc-switch_amd64.AppImage -o cc-switch.AppImage
      chmod +x cc-switch.AppImage
      ./cc-switch.AppImage --no-gui --import-provider https://example.com/provider.json
      ./cc-switch.AppImage use ci-proxy

4. 常见问题排查

问题	解决方案
启动报错 libssl.so.1.1 not found	安装对应 OpenSSL 兼容包：sudo apt install libssl1.1（Ubuntu）或 sudo yum install openssl11（CentOS）。
UI 没有显示已添加的 Provider	检查 ~/.config/cc-switch/providers.json 是否被正确写入；如果路径被误删，重新 Add Provider 即可。
CLI cc-switch use 无效	确认已经 Reload 配置或手动运行 cc-switch reload 让 UI 与本地数据库同步。

5. 结语

cc-switch 为跨平台 AI 代理管理提供了统一入口、一键切换与可视化配置三大核心价值，极大降低了在 Claude、Codex、Gemini、OpenClaw 等工具间切换的成本。无论是本地开发、跨地区接口调试，还是 CI/CD 自动化，配合脚本钩子都能实现全链路透明代理。

文章发布于 2026‑07‑17，转载请注明出处。