CC Switch 下载与使用手册

该文档旨在帮助不熟悉CC Switch的用户下载和初步使用该软件。

此处只做基本说明，若想更了解CC Switch或是遇到报错，请大家移步官方文档中了解。

开始下载前请注意

根据官方文档中所说，任何要求付费、充值或索取登录凭据的“CC Switch”网站或客户端都不是官方渠道。

请一定注意不要受骗。

一、下载 CC Switch

请通过以下官方渠道下载，避免安装名称相似的非官方软件：

• CC Switch 官方网站
• CC Switch GitHub Releases

推荐选择官网下载，官网会自动识别你所使用的操作系统，较为方便，并且可以下载最新版本。

点击左上的“免费下载”，进入下载界面，如下图所示。

若想下载历史版本，可以去官方的github的 Releases 页面下载。

注意GitHub 下载页面中的文件较多，请根据自己的操作系统仔细选择：

下载文件后，要在终端窗口中进入下载目录进行安装。

Windows

1、系统要求

需要 Windows 10 及以上版本。

2、安装包下载

大多数使用 Intel 或 AMD 处理器 x64 版本的电脑，请下载：

CC-Switch-v版本号-Windows.msi

双击 .msi 文件，按照安装向导完成安装即可。

Windows ARM 电脑请选择：

CC-Switch-v版本号-Windows-arm64.msi

如何查看处理器版本号

1. 按 Win + I 打开“设置”。
2. 侧边栏进入“系统”。
3. 拉到最下方，打开“系统信息”或“关于”。
4. 找到“系统类型”。一般是基于 x64 的处理器或基于 ARM 的处理器；x86属于32位旧电脑，当前较少见。

安装程序没有反应

右键单击下载的安装包，选择“属性”，如果窗口底部出现“解除锁定”，勾选后点击“确定”，然后重新运行安装程序。

3、免安装下载（绿色版）

CC-Switch-v版本号-Windows-Portable.zip

解压到任意目录，运行 CC-Switch.exe。

安装时注意

将压缩包完整解压后，再运行其中的 CC-Switch.exe。不要直接在压缩包内运行程序，否则可能无法正常保存配置。

macOS

1、系统要求

macOS 12 （Monterey） 及以上。

2、Homebrew下载

# 安装
brew install --cask cc-switch

# 更新至最新版本
brew upgrade --cask cc-switch

3、安装包下载

下载：

CC-Switch-v版本号-macOS.dmg

打开 .dmg 文件，将 CC Switch.app 拖入“应用程序”文件夹，然后从“应用程序”中启动。

4、免安装下载（绿色版）

CC-Switch-v版本号-macOS.zip

解压 zip 得到 CC Switch.app，拖入“应用程序”文件夹，然后从“应用程序”中启动。

注意

CC Switch 的 macOS 安装包已经过 Apple 签名和公证，正常情况下可以直接打开。

Linux

Github资产中Linux版本同时提供 x86_64 和 ARM64 两种架构，文件名如下所示：

• CC-Switch-v版本号-Linux-x86_64.AppImage / .deb / .rpm
• CC-Switch-v版本号-Linux-arm64.AppImage / .deb / .rpm

请根据发行版和处理器架构选择安装包，其中AppImage后缀文件为通用版本，不清楚该下载哪一文件可选择这个。下面表格基于官方Github文档编写。

发行版	推荐格式	安装方式
Ubuntu / Debian / Linux Mint / Pop!_OS	.deb	详情见下面安装方式1
Arch Linux / Manjaro / 其他常见发行版	.AppImage	详情见下面安装方式2
Fedora / RHEL / CentOS / Rocky Linux	.rpm	详情见下面安装方式3
openSUSE	.rpm	详情见下面安装方式4

---

安装方式1

可以使用两种命令安装 .deb 文件：

#第一种，一般不会出现依赖问题
sudo apt install ./CC-Switch-v版本号-Linux-x86_64.deb

#第二种
sudo dpkg -i CC-Switch-v版本号-Linux-x86_64.deb

# 若有依赖问题
sudo apt-get install -f

---

安装方式2

AppImage 通常不需要安装，添加执行权限后运行即可：

#添加运行权限
chmod +x CC-Switch-v版本号-Linux-x86_64.AppImage

#运行
./CC-Switch-v版本号-Linux-x86_64.AppImage

#或者也可以直接把运行加在添加权限里面
chmod +x CC-Switch-v版本号-Linux-x86_64.AppImage && ./CC-Switch-v版本号-Linux-x86_64.AppImage

Arch Linux 用户也可以使用 AUR 安装，即不需要下载Github资产中的文件。可以使用不同的AUR工具：

#使用paru
paru -S cc-switch-bin

#使用yay
yay -S cc-switch-bin

---

安装方式3

可以使用两种方式安装

#第一种，会处理依赖关系，适合普通用户
sudo dnf install ./CC-Switch-v版本号-Linux-x86_64.rpm

#第二种
sudo rpm -i CC-Switch-v版本号-Linux-x86_64.rpm

#较老的系统可能没有第一种安装方式，可以试试
#请注意，这种方式官方并未提及，请谨慎使用
sudo yum install ./CC-Switch-v版本号-Linux-x86_64.rpm

---

安装方式4

使用openSUSE常用的包管理器zypper来安装。

sudo zypper install ./CC-Switch-v版本号-Linux-x86_64.rpm

---

---

二、配置前需要准备什么

在中转站控制台中准备以下信息：

信息	用途
网站地址	用于连接中转站
API Key	证明你有权调用模型，并从账户中扣除对应额度
Base URL	告诉 AI 辅助工具应该连接到哪个接口地址

保护 API Key

API Key 相当于账户凭证。不要将它发送到群聊、评论区，也不要在公开截图中展示。别人取得你的 API Key 后，可能会消耗你的账户额度。

• 你还需要安装准备使用的 AI 辅助工具。不同工具的安装和基本使用方法可以查看：Codex、Claude Code、OpenCode 或 Hermes。

三、添加 XTapi 配置

CC Switch 将不同的 API 服务称为“供应商”。下面的“添加供应商”，就是把 XTapi 的连接信息保存到 CC Switch 中。

CC Switch界面如下图所示。

1. 选择 AI 辅助工具

打开 CC Switch，在上图中蓝色圈起的切换区域选择准备配置的工具，例如 Codex、Claude Code、OpenCode 或 Hermes。

第一次使用时，CC Switch 可能会询问是否导入该工具已有的配置。如果此前已经配置过该工具，可以导入并保留；如果从未配置过，可以直接继续添加新的供应商。

2. 打开添加供应商面板

点击上图界面右上角的 “+” 按钮，进入添加供应商页面。页面如下图所示

如果只准备配置一个工具，选择“应用专属供应商”即可，也就是图片中的“Codex供应商”，因为我的AI辅助工具选择为“Codex”；如果同一组 API 信息需要同时用于多个受支持的工具，可以使用“统一供应商”。新手建议先从应用专属供应商开始。

3. 填写连接信息

图中红色圈起的预设列表中是没有 XTapi 的，请选择“自定义”。

鼠标滚轮往下滑动，填写具体配置。如何填写可参考下图。

• 供应商名称无要求，方便自己分类就行

• 官网链接请填写 "https://xtapi.site" 。

• API Key请填写网站的令牌密钥

• API 请求地址一般情况请填写 "https://xtapi.site/v1" ，若再XTapi网站中使用的模型为Claude，请填写 "https://xtapi.site" 。

其他配置保持默认即可。

4. 保存并启用

确认信息无误后点击“添加”或“保存”。返回供应商列表，找到刚刚创建的 XTapi 卡片并点击 “启用”。

卡片显示“已使用”后，说明 CC Switch 已经将这份配置写入对应工具的配置文件。

启用不等于已经发起请求

CC Switch 负责写入和切换配置。真正向模型发送请求的是 Codex、Claude Code、OpenCode 或 Hermes。

四、让新配置生效

不同工具读取配置的时间不同。为避免仍然使用旧配置，首次启用后建议关闭正在运行的 AI 辅助工具和终端，再重新打开。

打开对应工具后，可以先输入一个简单且不会修改文件的问题：

你好，请告诉我你当前使用的模型名称。

能够正常回复，说明基本配置已经生效。

请注意

模型自报的名称不一定可靠，询问模型名称是为了查看是否链接成功。 若使用模型较多，使用模型情况仍应以 XTapi 的调用记录或账单为准。

五、切换不同配置

以后添加其他 API 服务或 XTapi 的其他配置时，可以重复“添加供应商”的步骤。需要切换时有两种方式：

1. 打开 CC Switch，在目标供应商卡片上点击“启用”。
2. 在系统托盘中右键单击 CC Switch 图标，从对应工具的子菜单中选择供应商。

切换后，如果工具没有立即使用新配置，请按照上一节的方法重新启动对应工具和终端。

六、更新与配置备份

CC Switch 支持自动检查更新，也可以在“设置 → 关于”中手动检查。下载更新时仍建议确认来源是 ccswitch.io 或 github.com/farion1231/cc-switch。

CC Switch 会在本地保存供应商配置并自动生成备份。由于备份中可能包含 API Key，不要将配置数据库或导出文件公开发送给他人。

完成基础配置后，还可以继续了解 MCP、Prompts、Skills、用量统计和故障转移等功能。第一次使用时不需要开启这些高级功能，先确认基本调用正常即可。