CC Switch 简明使用指南
|
54

2293 字
|
10 分钟

CC Switch 是一款用于管理和切换 AI 编程工具供应商配置的跨平台桌面工具，支持 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 等。用它接入云石 API 的好处是：不用手改配置文件，点几下就能切换供应商与模型，还能一键备份/恢复配置。本文介绍它的安装、配置与常用操作。

一、适用版本

项目 要求
CC Switch 版本 v3.20.x（本文核对时最新为 v3.20.3）；建议 v3.16 以上
Windows Windows 10 及以上，x64 / ARM64
macOS macOS 12（Monterey）及以上，Intel / Apple Silicon
Linux 主流发行版，x64 / ARM64（提供 .deb、.rpm、.AppImage）
受管工具 Claude Code、Codex（CLI 与客户端）、Gemini CLI、OpenCode、OpenClaw 等

版本核对日期：2026-09-23。本文中标注「v3.7 起」的功能均已包含在当前版本中。

CC Switch 本身不是网络代理，它只是帮你把配置写进各工具的配置文件。接入云石仍需你自备令牌，令牌获取见《云石新手教程》。

二、前置条件

  • 已注册云石账号并创建令牌。Claude 系工具用 Claude 分组的令牌；Codex 系工具用 gpt 分组的令牌。
  • 要接管的工具（如 Claude Code、Codex）已安装完成。
  • 能访问下载源；若 GitHub 打不开，改用官网下载（见下文），不影响使用。

权限说明：

  • Windows 的 MSI 为用户级安装，普通账户即可完成，不需要管理员权限；便携版解压即用，不写注册表。
  • macOS 若提示「无法验证开发者」，到「系统设置 → 隐私与安全性」点「仍要打开」，不需要关闭 SIP。
  • Linux 的 AppImage 需要自行加执行权限（chmod +x）；用 .deb / .rpm 安装时才需要 sudo。
  • CC Switch 需要读写各工具的用户级配置目录（如 ~/.claude、~/.codex），这些都在你自己的用户目录内，不涉及系统目录。

三、安装配置

3.1 获取安装包

CC Switch 的 GitHub Releases 页面，选择对应系统的安装包

Windows

  • 推荐：下载 CC-Switch-v*-Windows.msi，双击安装，支持自动更新。
  • 免安装：下载 CC-Switch-v*-Windows-Portable.zip，解压即用。
  • ARM64 设备请选文件名中带 arm64 的制品。
  • 也可以用 winget：winget install --id farion1231.CC-Switch --exact
  • 若被 SmartScreen 拦截，点「更多信息」→「仍要运行」。

macOS

  • 推荐通过 Homebrew 安装：
brew tap farion1231/ccswitch
brew install --cask cc-switch
  • 或下载 .dmg / .zip，把 CC Switch.app 拖进「应用程序」。
  • 更新：brew upgrade --cask cc-switch

Linux

  • 提供多种格式：.deb、.rpm、.AppImage。
  • Debian / Ubuntu：sudo apt install ./CC-Switch-v*-Linux-x86_64.deb；其他发行版可用包管理器或直接解压运行 AppImage。
  • AppImage 首次运行需赋权：chmod +x CC-Switch-*.AppImage

3.2 添加云石供应商（Provider）

CC Switch 主界面概览

在主界面点击 Add Provider（右上角 +）→ 选择已有预设或创建自定义配置（API 地址、API Key、模型等）→ 往下滑：

点击 Add Provider 新建供应商配置

❗ 先在上方切到目标工具面板（此处选 Claude）❗

填写获取到的 URL 和 API_KEY。请求地址填 https://yyoo.xyz，供应商名称填 云石：

填写云石的请求地址与 API Key
https://yyoo.xyz
Claude 系工具用 https://yyoo.xyz；OpenAI 协议的工具（Codex、OpenClaw 等）需要在末尾加 /v1，即 https://yyoo.xyz/v1。填错会报 404。

3.3 模型配置

API 格式：选 Anthropic Messages（原生）或 OpenAI Chat Completions / Responses，要和工具匹配。

模型可直接填模型名（如 claude-sonnet-4-6、claude-opus-4-8、haiku-4-5），也可到模型广场复制。一般推荐 主模型（必填）+ Sonnet 模型：

填写主模型与 Sonnet 模型

配置完点保存，然后点启用。

保存并启用该供应商配置

四、核心操作

4.1 切换供应商

不同供应商的切换可以在主界面点「启用」完成，也可以在系统托盘菜单里快速切换：

测试连通性
在系统托盘中快速切换供应商

可以在设置里隐藏不用的项，只留下常用的（如 Claude、Codex、OpenCode、OpenClaw）：

在设置中配置托盘显示项

OpenClaw 的配置方式和 Claude 基本一致，唯一区别是 URL 需要加 v1：

https://yyoo.xyz/v1

4.2 为同一个工具配置多套模型（例如同时用 Claude 与 GPT）

一、在云石后台新建一个其他分组的令牌（例如需要 GPT 模型就建 gpt 分组）：

在后台新建另一个分组的令牌

二、回到 CC Switch，重新添加一个供应商：

再添加一个供应商条目

三、其他项无需改动，只需换成新分组的 Key，保存并启用即可：

仅替换 API Key 即可完成第二套配置

4.3 其他常用能力

  • MCP 管理：配置和管理 MCP 服务器，可为不同 AI CLI 工具分别启用或禁用。
  • Skills 插件管理（v3.7 起）：从 GitHub 扫描 Skill 库，一键安装 / 删除，增强 CLI 能力。
  • Prompts 管理（v3.7 起）：内置 Prompt 模板管理器，创建、切换、跨工具复用提示词预设。
  • 配置文件管理：Provider、MCP、Prompts、Skills 集中存于本地数据库，支持备份 / 恢复。

配套视频：超级简单！四分钟内教会你安装 Claude Code 与 CC Switch 模型路由

五、验证方法

步骤 操作 预期结果
1. 配置连通性 在供应商条目上点「测试连通性」 提示连通正常；失败说明地址、Key 或分组有问题
2. 配置已写入 用 CC Switch 打开对应工具的配置文件（Claude Code 为 ~/.claude/settings.json，Codex 为 ~/.codex/config.toml） 能看到 base_url 指向 yyoo.xyz
3. 工具侧生效 完全退出并重启被接管的工具，发一句「你好」 能正常流式回复
CC Switch 的配置是在工具启动时被读取的。切换供应商后必须重启目标工具，只关窗口常常不管用。

六、常见问题

1. GitHub Releases 打不开

改用官网 ccswitch.io 下载，走 Cloudflare 边缘节点，不依赖 GitHub 可达性。

2. 测试连通性失败 / 报 404

多半是协议与地址不匹配：Claude 系用 https://yyoo.xyz，OpenAI 协议类工具用 https://yyoo.xyz/v1。也可能是令牌分组不对（Codex 需 gpt 分组、Claude 需 Claude 分组）。

3. 切换供应商后不生效

目标工具没重启。请从系统托盘「完全退出」后重新打开。

4. 托盘菜单里看不到额度 / 不显示某些工具

在设置里把要显示的工具勾选出来，隐藏项不会出现在托盘菜单中。

5. macOS 提示「无法验证开发者」，无法打开

到「系统设置 → 隐私与安全性」，在下方点击「仍要打开」。不建议用 sudo spctl --master-disable 这类关闭全局校验的做法。

6. Linux 下 AppImage 双击没反应

chmod +x CC-Switch-*.AppImage
./CC-Switch-*.AppImage

7. 换电脑后配置全没了

CC Switch 的配置存在本地数据库里，不随账号同步。请在原机器上用「备份」导出，再在新机器上「恢复」。

七、回滚 / 卸载

7.1 只回滚配置（保留软件）

  • 在 CC Switch 里把云石供应商停用 / 删除，启用原来的官方或其它供应商，然后重启目标工具即可。
  • 操作前建议先「备份」一次配置，出问题可一键恢复。

7.2 完全卸载

平台 操作
Windows（MSI） 设置 → 应用 → CC Switch → 卸载；或 msiexec /x CC-Switch-v*-Windows.msi
Windows（winget） winget uninstall --id farion1231.CC-Switch --exact
Windows（便携版） 直接删除解压目录即可
macOS 把 App 拖入废纸篓；Homebrew 安装的用 brew uninstall --cask cc-switch
Linux .deb 用 sudo apt remove cc-switch；.rpm 用 sudo rpm -e cc-switch；AppImage 直接删文件
卸载 CC Switch 不会自动还原各工具的配置文件。如果卸载前处于「已接入云石」状态，请先手动把工具配置改回官方，或删除对应配置文件中的自定义供应商段后再卸载，否则工具会连不上任何服务。

八、更新记录

日期 版本 修改内容
2026-09-23 v2.0 知识库检查修订：补齐适用版本、前置条件、权限说明、验证方法、常见问题、回滚/卸载、更新记录；下载源补充官网 ccswitch.io 作为 GitHub 备用；更正「v3.7+」的过期表述为当前 v3.20.x；补充 Windows/macOS/Linux 各平台安装细节与 ARM64 说明；图片改为相对路径并补充 alt 文本
2026-09-22 v1.0 首次发布：下载安装、供应商与模型配置、托盘切换、MCP/Skills/Prompts 管理
CC Switch
上一篇
下一篇