CC Switch 从安装到使用教程

1. 认识 CC Switch

CC Switch 是一个跨平台桌面管理工具，用来统一管理 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw 和 Hermes 的供应商配置。它的价值是把原本需要手动编辑的 JSON、TOML、.env 等配置，变成可视化添加、启用、备份和切换。

支持多个工具

在一个界面里分别管理 Claude、Codex、Gemini、OpenCode、OpenClaw、Hermes 等应用的供应商。

内置供应商预设

包含官方、聚合服务和常见第三方中转。选择预设后通常只需要填写 API Key。

统一管理扩展

MCP、Prompts、Skills、用量统计、代理路由、会话管理都可以在应用内集中处理。

2. 安装前准备

系统要求

系统	最低要求
Windows	Windows 10 及以上，x64
macOS	macOS 12 Monterey 及以上，Intel 或 Apple Silicon
Linux	Ubuntu 22.04+、Debian 11+、Fedora 34+ 等主流发行版

CLI 工具环境

CC Switch 是管理器，本身不替代 Claude Code、Codex、Gemini CLI 等命令行工具。需要使用对应 CLI 时，请先准备 Node.js 18 LTS 或更高版本。

node --version
npm --version

安装常用 CLI 工具

Claude Code

npm install -g @anthropic-ai/claude-code

Codex

npm install -g @openai/codex

Gemini CLI

npm install -g @google/gemini-cli

国内网络下载较慢时，可按需使用 npm 镜像源：npm config set registry https://registry.npmmirror.com。

3. 安装 CC Switch

Win

Windows

打开 GitHub Releases。
下载 CC-Switch-v{版本号}-Windows.msi 安装包，或下载 Windows-Portable.zip 绿色版。
安装包双击运行；绿色版解压后运行 CC-Switch.exe。

如果安装程序无反应，右键文件打开「属性」，在「常规」页勾选「解除锁定」。

mac

macOS

推荐使用 Homebrew：

brew tap farion1231/ccswitch
brew install --cask cc-switch

更新：

brew upgrade --cask cc-switch

也可以从 Releases 下载 macOS.dmg，打开后拖入「应用程序」。官方说明 macOS 版本已签名并公证。

AUR

Arch Linux

paru -S cc-switch-bin
# 或
yay -S cc-switch-bin

Linux

Debian / Ubuntu / 通用 Linux

下载对应架构的 .deb、.rpm 或 .AppImage。
Debian/Ubuntu 可执行：

sudo dpkg -i CC-Switch-v{版本号}-Linux-*.deb
sudo apt-get install -f

AppImage 方式：

chmod +x CC-Switch-v{版本号}-Linux-*.AppImage
./CC-Switch-v{版本号}-Linux-*.AppImage

4. 首次启动与 5 分钟配置

启动应用并选择受管工具

打开 CC Switch 后，确认窗口正常显示，系统托盘出现图标。根据实际使用场景切换到 Claude、Codex、Gemini 或其他应用面板。

导入现有配置

首次启动可把当前 CLI 工具已有配置导入为默认供应商。这样后续切换失败时，你仍然有一个可回退的原始配置。

添加新供应商

点击右上角 +，选择预设，填写 API Key，确认名称和端点后点击「添加」。预设会自动填充大部分参数。

5. 添加供应商的三种方式

使用预设

适合大多数用户。选择 Claude、Codex、Gemini、OpenCode 或 OpenClaw 面板里的供应商预设，填入 API Key 即可。

DeepSeek Kimi MiniMax OpenRouter SiliconFlow

自定义配置

适合预设里没有的服务。Claude 常见字段是 ANTHROPIC_API_KEY 和 ANTHROPIC_BASE_URL；Gemini 常见字段是 GEMINI_API_KEY 和 GOOGLE_GEMINI_BASE_URL。

统一供应商

适合一个 API Key 同时给 Claude Code、Codex、Gemini 使用的中转服务。创建后勾选要同步的应用，后续修改可「保存并同步」。

自定义配置示例

Claude Code

{
  "env": {
    "ANTHROPIC_API_KEY": "your-api-key",
    "ANTHROPIC_BASE_URL": "https://api.example.com"
  }
}

Codex

model_provider = "custom"
model = "gpt-5.2"
disable_response_storage = true

[model_providers.custom]
name = "custom"
base_url = "https://api.example.com/v1"
wire_api = "responses"
requires_openai_auth = true

关于 Codex Chat Completions 供应商

DeepSeek、Kimi、GLM、MiniMax 等仅支持 Chat Completions 协议的供应商，通常需要启用「需要本地路由映射」。选择官方预设时 CC Switch 会自动配置模型映射；使用自定义供应商时要确认本地路由服务和 Codex 接管已开启。

6. 切换供应商与生效方式

主界面切换

进入对应应用面板，例如 Claude 或 Codex。
找到目标供应商卡片。
点击「启用」。
等待卡片状态变为「当前启用」。

托盘快速切换

右键系统托盘里的 CC Switch 图标。
进入 Claude、Codex 或 Gemini 子菜单。
点击目标供应商名称。
按对应工具要求重启或直接使用。

应用	切换后是否要重启	CC Switch 修改的典型文件
Claude Code	通常即时生效，支持热重载	`~/.claude/settings.json`
Codex	需要关闭并重新打开终端	`~/.codex/auth.json`、`~/.codex/config.toml`
Gemini CLI	通常即时生效，每次请求重新读取配置	`~/.gemini/.env`、`~/.gemini/settings.json`
OpenCode / OpenClaw	通常需要关闭并重新打开终端	对应工具配置文件

7. 常用扩展功能

MCP 管理

点击「MCP」进入统一面板，通过模板或自定义配置添加服务器，再选择同步到 Claude、Codex、Gemini、OpenCode 或 Hermes。

Prompts

使用 Markdown 编辑器维护提示词预设。激活后可同步到 CLAUDE.md、AGENTS.md、GEMINI.md 等 live 文件。

Skills

从 GitHub 仓库或 ZIP 安装技能，支持软链接、文件复制、自定义仓库和批量更新检测。

代理与故障转移

本地代理可做协议转换、应用接管、自动故障转移、健康监控和请求统计。需要 Chat Completions 转 Responses 时尤其重要。

用量与余额

用量仪表盘可查看请求数、Token、成本趋势。部分官方订阅或第三方模板可展示配额和余额。

云同步与备份

可将配置目录放在 Dropbox、OneDrive、iCloud、坚果云、NAS 或通过 WebDAV 同步，适合多设备使用。

8. 常见问题与处理

切换后不生效

先确认是否需要重启终端。Codex、OpenCode、OpenClaw 通常要关闭终端并重新打开；Claude Code 和 Gemini 多数场景可以即时生效。

Claude Code 首次启动要求登录

在「设置 → 通用」开启「跳过 Claude Code 初次安装确认」，然后重新启动 Claude Code。该选项会写入 ~/.claude/settings.json 的 skipIntroduction 字段。

想恢复官方登录

添加「官方登录」预设，切换过去后重启对应 CLI，再按官方登录或 OAuth 流程操作。

数据保存在哪里

数据库位于 ~/.cc-switch/cc-switch.db，本地设置位于 ~/.cc-switch/settings.json，备份目录位于 ~/.cc-switch/backups/。

供应商无法删除

CC Switch 会保留一个当前激活配置，避免删除所有配置后对应应用无法正常运行。不常用的应用可以在设置里关闭显示。

Codex OAuth 反向代理风险

官方文档提示该功能通过逆向工程 OAuth 流程访问 ChatGPT 账号的 Codex 服务，可能违反服务条款并带来账号风险。启用前应阅读项目文档中的风险说明。

参考来源

内容整理自 cc-switch GitHub 仓库、README_ZH.md、中文用户手册目录、安装指南、快速上手、添加供应商与切换供应商文档。页面整理日期：2026-06-04。