CC-Switch 下载安装与入门教程

## CC-Switch 下载安装与入门教程

## 一、CC-Switch 是什么

CC-Switch（CC Switch）是一款**开源、跨平台的桌面配置管理工具**，主要用于集中管理 Claude Code、Codex 等 AI 编程工具的 API 接入信息，实现多模型服务一键切换。

它解决的问题很具体：Claude Code、Codex、Gemini CLI 这些工具各自有一套配置格式——Claude Code 是 `settings.json`，Codex 是 `auth.json` + `config.toml`，Gemini CLI 是 `.env`。想从 A 服务商切到 B，就得手动去改对应的 JSON 或 TOML 文件；渠道一多，谁在用哪个地址、哪个 Key，很快就记不清了。

CC-Switch 把这些整理成可视化的"配置档位"：

- **核心作用**：把不同服务商的 API Key、接口地址、模型配置保存成一张张供应商卡片，切换时自动把选中卡片的内容写入对应工具的配置文件，不用再手动改 JSON、TOML 或环境变量。
- **支持平台**：Windows、macOS、Linux 原生桌面应用（Tauri 2 构建），界面操作为主，系统托盘也能切换。
- **适用场景**：同时维护多个 AI 模型渠道、需要在官方订阅与中转站之间来回切换、或在多台设备间保持同一套接入配置的开发者。

### 1.1 基本信息

| 项目        | 内容                                        |
| --------- | ----------------------------------------- |
| 官方网站      | `https://ccswitch.io`                     |
| 开源仓库      | `https://github.com/farion1231/cc-switch` |
| 开源协议      | MIT                                       |
| 技术栈       | Tauri 2（Rust + React），安装包小、启动快            |
| 撰写本文时最新版本 | v4.0.22（2026-10-30 发布）                    |
| 内置供应商预设   | 90+（含 AWS Bedrock、NVIDIA NIM、各家社区中转）      |

> **完全免费**：项目完全开源免费，任何要求付费才能下载的"CC-Switch 官网"都是假冒站点，请只认上面两个地址。

### 1.2 它管理哪些工具

截至目前，CC-Switch 支持 14 个客户端（不用的可以在「应用」页隐藏）：

| 客户端                                                            | 写入的配置文件                              | 切换后生效方式        |
| -------------------------------------------------------------- | ------------------------------------ | -------------- |
| Claude Code                                                    | `~/.claude/settings.json`            | 热切换，无需重启       |
| Codex                                                          | `~/.codex/auth.json` + `config.toml` | 重启终端 / CLI     |
| Gemini CLI                                                     | `~/.gemini/.env` + `settings.json`   | 重启 CLI         |
| Grok Build                                                     | `~/.grok/config.toml` 等              | 重启 CLI         |
| Claude Desktop                                                 | 应用配置                                 | 完全退出后重开        |
| OpenCode / OpenClaw / Hermes / Pi / MiniMax Code / Kimi Code 等 | 各自配置目录                               | 点"启用"写入，工具内选模型 |

本文以最常用的 **Claude Code 与 Codex** 为主线讲解，其它工具流程相同，只是填的字段不同。

## 二、下载

所有安装包都发布在 GitHub Releases 页：`https://github.com/farion1231/cc-switch/releases/latest`。把下面表里的 `v4.0.22` 换成页面上的最新版本号即可。

### 2.1 按系统选包

| 系统                | 文件                                                      | 说明                                   |
| ----------------- | ------------------------------------------------------- | ------------------------------------ |
| Windows x64       | `CC-Switch-v4.0.22-Windows.msi`                         | **推荐**，安装版，支持自动更新                    |
| Windows x64       | `CC-Switch-v4.0.22-Windows-Portable.zip`                | 便携版，解压即用，不写注册表                       |
| Windows ARM       | `CC-Switch-v4.0.22-Windows-arm64.msi` / `-Portable.zip` | ARM 设备专用                             |
| macOS             | `CC-Switch-v4.0.22-macOS.dmg`                           | **推荐**，拖进「应用程序」即完成安装                 |
| macOS             | `CC-Switch-v4.0.22-macOS.zip`                           | 通用二进制，解压后拖入「应用程序」                    |
| Debian / Ubuntu 系 | `CC-Switch-v4.0.22-Linux-x86_64.deb`（另有 arm64）          | `sudo apt install ./CC-Switch-*.deb` |
| Fedora / RHEL 系   | `CC-Switch-v4.0.22-Linux-x86_64.rpm`（另有 arm64）          | `sudo dnf install ./CC-Switch-*.rpm` |
| 任意发行版             | `CC-Switch-v4.0.22-Linux-x86_64.AppImage`               | 加执行权限直接运行                            |

### 2.2 系统要求

| 系统      | 最低要求                                                                             |
| ------- | -------------------------------------------------------------------------------- |
| Windows | Windows 10 及以上                                                                   |
| macOS   | macOS 12（Monterey）及以上，Intel 与 Apple Silicon 通用                                   |
| Linux   | x86_64 或 ARM64，glibc 2.35+ 且带 WebKitGTK 4.1（Ubuntu 22.04+、Debian 12+、较新的 Fedora） |

> RHEL / Rocky / Alma 8–9 目前官方明确不支持。老系统的用户可以关注 Releases 页后续变化，或改用工具自身的手动配置方式。

### 2.3 GitHub 下载慢怎么办

- 可以给 Release 资产链接加常用的 GitHub 加速前缀（社区镜像），**下载后务必核对文件大小与哈希**；
- 也可搜索"CCSwitch 网盘"找到热心网友同步的安装包，同理注意来源可信；
- macOS 用户优先走 Homebrew（下一节），由 cask 自动处理下载与校验，不依赖浏览器下载速度。

## 三、安装

### 3.1 Windows

**1. 双击 MSI 安装**：一路下一步即可。安装版支持应用内自动更新。

**2. 便携版**：解压 zip 到任意目录，运行其中的 `CC-Switch.exe`。不写注册表，适合放 U 盘或公司受限环境。

### 3.2 macOS

**方式一（推荐）：Homebrew**

```bash
brew install --cask cc-switch
```

以后升级：

```bash
brew upgrade --cask cc-switch
```

**方式二：手动下载 DMG**，打开后把 CC Switch 拖进「应用程序」。

官方 macOS 版已通过 Apple 代码签名与公证，正常双击即可打开；如果你下载的是未签名的历史版本，首次打开提示"无法验证开发者"时，先关闭提示，再到「系统设置 → 隐私与安全性」点"仍要打开"。

### 3.3 Linux

按发行版选一种：

```bash
# Debian / Ubuntu / Mint / Pop!_OS
sudo apt install ./CC-Switch-*.deb

# Fedora / RHEL / CentOS / Rocky
sudo dnf install ./CC-Switch-*.rpm

# openSUSE
sudo zypper install ./CC-Switch-*.rpm

# 其它发行版 / 不确定：AppImage
chmod +x CC-Switch-*.AppImage
./CC-Switch-*.AppImage
```

Arch / Manjaro 用户推荐 AUR：`paru -S cc-switch-bin`。

## 四、首次启动

第一次打开 CC-Switch，它会做两件事：

**1. 自动导入现有配置**：把你机器上已有的 Claude Code、Codex、Gemini CLI、Grok Build 配置各导入为一张名为 **`default`** 的供应商卡片，同时为每个工具加上一张官方登录预设卡片。**已有的配置一条都不会丢**——你可以先装工具再配 CC-Switch，也可以反过来。

**2. 建立本地数据库**：所有数据默认存在用户主目录的 `.cc-switch` 文件夹：

| 文件 / 目录         | 内容                                  |
| --------------- | ----------------------------------- |
| `cc-switch.db`  | SQLite 数据库：供应商、MCP、提示词、Skills、用量记录等 |
| `settings.json` | 本机设置（各工具配置目录、备份策略、云同步连接）            |
| `backups/`      | 自动备份，默认每 24 小时一次，保留最近 10 份          |
| `logs/`         | 运行日志与崩溃日志                           |

> 这些数据只在本地，不会上传。需要多设备同步时，可在「设置」里把存储目录指向 WebDAV / S3 / 坚果云等自有网盘（见第十一章）。

## 五、添加供应商：以本站中转为例

下面用 `https://api.zaimod.com` 作为中转站地址，演示给 Claude Code 和 Codex 各加一张供应商卡片。其它服务商流程完全一样。

### 5.1 准备一枚令牌

到中转站控制台「令牌」页新建一枚令牌（分组按你要用的模型选，模型限制列表留空即代表支持全部模型），复制以 `sk-` 开头的 Key 备用。

### 5.2 给 Claude Code 添加供应商

**1. 侧边栏选 Claude Code**，点右上角 **「+」→ 添加供应商**。

**2. 选「自定义」**（或从 90+ 预设里挑一个相近的再改地址）。关键字段：

| 字段      | 填什么                                            |
| ------- | ---------------------------------------------- |
| 名称      | 随意，比如 `cxhao 中转`（显示在卡片上）                       |
| API 地址  | `https://api.zaimod.com` —— **纯域名，结尾不要带 `/v1`** |
| API Key | 粘贴上一步复制的令牌                                     |
| 模型      | 四个档位各填一个可用模型 ID（以控制台模型列表为准）                    |

**3. 保存**。启用这张卡片后，CC-Switch 会把内容写进 `~/.claude/settings.json`，效果等价于：

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的令牌",
    "ANTHROPIC_BASE_URL": "https://api.zaimod.com",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-haiku-4-5"
  }
}
```

> 为什么 Claude Code 的地址不带 `/v1`：Claude Code 会自己在后面拼 `/v1/messages`。手写配置时写 `/v1` 会变成 `/v1/v1/messages` 报 404——这是手改 JSON 最常见的翻车点，而 CC-Switch 的预设会按协议替你处理，这也是它比手写省心的地方。

### 5.3 给 Codex 添加供应商

同样在侧边栏切到 **Codex**，点「+」添加。Codex 这边地址**要带 `/v1`**（它走 OpenAI 协议，请求发往 `{base_url}/responses`）：

| 字段       | 填什么                        |
| -------- | -------------------------- |
| 名称       | 比如 `cxhao codex`           |
| Base URL | `https://api.zaimod.com/v1` |
| API Key  | 同一枚令牌即可                    |
| 模型       | 例如 `gpt-5.5`，以控制台列表为准      |

启用后写入 `~/.codex/auth.json` 与 `config.toml`：

```json
{
  "OPENAI_API_KEY": "sk-你的令牌"
}
```

```toml
model_provider = "cxhao"
model = "gpt-5.5"

[model_providers.cxhao]
name = "cxhao"
base_url = "https://api.zaimod.com/v1"
wire_api = "responses"
requires_openai_auth = true
```

> 同一个服务商，Claude Code 填纯域名、Codex 填带 `/v1`，**别互相抄**。两份配置文件是独立写入的，互不影响。

### 5.4 切换供应商

两种方式任选：

- **主界面**：选中某张卡片，点「启用」（部分工具显示为「添加」）；
- **系统托盘**：直接点供应商名称，立即生效。

切换只替换连接信息（地址、Key、模型），你自己加的 hooks、MCP、注释等内容会保留。

## 六、确认切换是否生效

不同工具的验证方式：

**1. Claude Code**：热切换，重开会话即可。启动屏左下角显示 `API Usage Billing` 说明在走 API 计费（中转生效）；显示 `Claude Pro / Max` 说明还在官方订阅。也可以在会话里输入 `/status` 查看 Base URL 与模型。

**2. Codex**：重启终端（或退出后台 daemon）后再看。打开 `~/.codex/config.toml` 确认 `base_url` 已变成目标地址。

**3. 通用硬判据**：到中转站控制台的「使用日志」页看有没有新的调用记录，这是最可靠的依据。

> **注意「连通性检查」的局限**：供应商卡片上的连通性检查只测试地址是否可达，**不发真实模型请求**，因此它验证不了 Key 是否有效、模型名是否正确。地址通、请求 401，通常是 Key 填错或分组不对；这种请求级错误要到「用量」页的请求日志里看具体报错。

## 七、三种工作模式

每张供应商卡片可选三种模式之一，日常用「直连」就够，后两种进阶用：

| 模式              | 原理                                                                                | 适合                                         |
| --------------- | --------------------------------------------------------------------------------- | ------------------------------------------ |
| 直连（Direct）      | 配置文件里直接写服务商地址，工具直连                                                                | 最简单，绝大多数场景                                 |
| 路由（Routing）     | 配置文件里写本地路由 `http://127.0.0.1:15721`（Key 为占位符 `PROXY_MANAGED`），请求先经过 CC-Switch 再转发 | 自动做接口格式转换（如让 Codex 用 Claude 系服务商）、热切换、故障转移 |
| 聚合（Aggregation） | 把多家服务商的模型合并成一个模型列表写进 Claude Code / Codex，每个请求按所选模型路由到对应服务商                        | 一套配置里混用多家模型                                |

路由与聚合模式下，CC-Switch 必须保持运行；退出前它会把直连配置写回配置文件，避免断网。真正的地址、Key、模型都保存在 CC-Switch 里，「用量」页能看到每次请求"请求模型 → 实际模型"的映射。

## 八、切回官方登录

想暂时回到官方订阅时：

**1.** 在对应工具的供应商列表里找到内置的官方预设卡片（Claude 官方 / OpenAI 官方 / Google 官方），点「启用」；

**2.** 重启终端后，按工具自己的流程重新登录：Claude Code 用 `/login`，Codex 用 `codex login`；

**3.** 之后就能在官方卡片与第三方卡片之间随意切换，不必反复登录。

官方卡片不经过本地路由；如果启用了路由模式，先切回直连再选官方卡片。

## 九、数据与备份

- **备份**：默认每 24 小时自动备份一次到 `~/.cc-switch/backups/`，保留最近 10 份，策略可在「设置 → 数据」调整，也可手动备份 / 恢复。
- **多设备同步**：「设置」里开启自定义配置目录后，可把存储位置指向 WebDAV / S3（如坚果云、iCloud、OneDrive），多台设备指向同一目录即可同步。注意本机设置与 OAuth 凭据不参与同步。
- **卸载**：卸载 CC-Switch 不会删除各工具已写好的配置文件；当前生效的配置继续有效，只是不能再一键切换。想彻底清理时再手动删除 `~/.cc-switch` 目录。

## 十、常见问题（FAQ）

### 10.1 切换了但没生效？

按顺序排查：确认卡片真的处于启用状态（高亮）；Codex / Gemini / Grok 这类工具需要**重启终端**，Claude Desktop 需要**完全退出**（托盘里也退出）再打开；检查是否同时手改过工具配置文件，手动改动会被下次切换覆盖，启用中的卡片编辑时会优先显示实际生效的配置。

### 10.2 连通性检查通过，但请求 401？

连通性检查只测地址可达。401 说明地址对、凭证不对：检查 Key 是否复制完整、令牌是否被禁用、分组是否支持你填的模型。详细报错可在「用量」页的请求日志里查看。

### 10.3 CC-Switch 会不会看到我的数据？

不会上传。供应商、Key、用量记录都存在本地 `~/.cc-switch/`；开启云同步时数据也只写到你自己配置的存储里。

### 10.4 升级后旧配置会丢吗？

不会。配置存放在 SQLite 数据库里，升级程序会自动做 Schema 迁移；数据库之外还有自动备份兜底。

### 10.5 一个工具能配多少个供应商？

没有限制。同一工具下可以建任意多张卡片（比如官方一张、多个中转各一张），用拖拽调整顺序；正在使用的卡片不能删除，需先切到别的卡片。支持复制现有卡片快速创建变体。

## 十一、附录

### 11.1 相关链接

| 资源          | 地址                                                        |
| ----------- | --------------------------------------------------------- |
| 官方网站（含用户手册） | `https://ccswitch.io`                                     |
| GitHub 仓库   | `https://github.com/farion1231/cc-switch`                 |
| 下载最新版       | `https://github.com/farion1231/cc-switch/releases/latest` |
| 更新日志        | `https://ccswitch.io/changelog`                           |

### 11.2 本站地址对照

| 工具              | 接口地址                       | 说明                          |
| --------------- | -------------------------- | --------------------------- |
| Claude Code     | `https://api.zaimod.com`    | 纯域名，不带 `/v1`                |
| Codex           | `https://api.zaimod.com/v1` | 带 `/v1`，协议选 `responses`     |
| Gemini CLI      | `https://api.zaimod.com`    | 写入 `GOOGLE_GEMINI_BASE_URL` |
| 通用 OpenAI 兼容客户端 | `https://api.zaimod.com/v1` | 请求发往 `/v1/chat/completions` |

上一篇：Kimi Code CLI 配置{else}上一篇：没有了下一篇：CC-Switch 配置 Codex{else}下一篇：没有了