CC Switch 配置

软件介绍

什么是 CC Switch

CC Switch 是一款跨平台桌面应用，专为使用 AI 工具的开发者设计。它帮助你统一管理 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw 和 Hermes 等受管应用的配置。

解决什么问题

在日常开发中，你可能会遇到这些痛点：

多供应商切换麻烦：使用不同的 API 供应商（官方、中转服务商），需要手动修改配置文件
配置分散难管理：Claude Code、Claude Desktop、Codex、Gemini、OpenCode、OpenClaw、Hermes 各有独立的配置文件，格式不同
无法监控用量：不知道 API 调用了多少次，花了多少钱
服务不稳定：单一供应商出问题时，整个工作流中断

CC Switch 通过统一的界面解决这些问题。

核心功能

供应商管理

一键切换多个 API 供应商配置
支持预设模板，快速添加常用供应商
统一供应商功能，跨应用共享配置
Claude Desktop 第三方供应商、直连模式与模型映射
用量查询与余额显示
端点速度测试

扩展功能

MCP 服务器：管理 Model Context Protocol 服务器，扩展 AI 能力
Prompts：管理系统提示词预设，快速切换不同场景
Skills：安装和管理技能扩展

代理与高可用

本地代理服务，记录请求日志和用量统计
自动故障转移，主供应商失败时自动切换备用
熔断器机制，防止频繁重试失败的供应商
详细的 Token 用量追踪与成本估算

支持的应用

应用	说明
Claude Code	Anthropic 官方的 AI 编程助手
Claude Desktop	Claude 桌面应用，支持官方登录与第三方 3P profile
Codex	OpenAI 的代码生成工具
Gemini CLI	Google 的 AI 命令行工具
OpenCode	开源 AI 编程终端工具
OpenClaw	开源 AI 助手（多供应商网关）
Hermes	Hermes Agent，支持供应商、MCP、Skills 和 Memory 管理

支持的平台

Windows 10 及以上
macOS 12 (Monterey) 及以上
Linux Ubuntu 22.04+ / Debian 11+ / Fedora 34+（x64 / ARM64）

技术架构

CC Switch 使用现代化的技术栈构建：

前端：React 18 + TypeScript + Tailwind CSS
后端：Tauri 2 + Rust
数据存储：SQLite（供应商、MCP、Prompts）+ JSON（设备设置）

这种架构确保了：跨平台一致的体验、原生级别的性能、安全的本地数据存储。

安装指南

官方渠道与系统要求

请只从 ccswitch.io、GitHub Releases 或项目源码仓库获取 CC Switch。任何要求付费、充值或索取登录凭据的“CC Switch”网站或客户端都不是官方渠道。

系统	最低版本	架构
Windows	Windows 10 及以上	x64
macOS	macOS 12 (Monterey) 及以上	Intel (x64) / Apple Silicon (arm64)
Linux	见下方发行版说明	x64 / ARM64

前置要求

安装 Node.js

CC Switch 管理的 CLI 工具（Claude Code、Codex、Gemini CLI）需要 Node.js 环境。

推荐版本：Node.js 18 LTS 或更高版本

Windows

访问 Node.js 官网
下载 LTS 版本安装包
运行安装程序，按提示完成安装
验证安装：

node --version
npm --version

macOS

brew install node

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

Linux

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

安装 CLI 工具

Claude Code

方式一：Homebrew（macOS 推荐）

brew install claude-code

方式二：npm

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

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

Codex

方式一：Homebrew（macOS 推荐）

brew install codex

方式二：npm

npm install -g @openai/codex

npm install -g @openai/codex --registry=https://registry.npmmirror.com

Gemini CLI

方式一：Homebrew（macOS 推荐）

brew install gemini-cli

方式二：npm

npm install -g @google/gemini-cli

npm install -g @google/gemini-cli --registry=https://registry.npmmirror.com

💡 提示

如果经常遇到下载慢的问题，可以全局设置镜像源：

npm config set registry https://registry.npmmirror.com

Windows

安装包方式

访问 Releases 页面
下载 CC-Switch-v{版本号}-Windows.msi
双击运行安装程序
按提示完成安装

注意：运行安装程序后如果没有任何反应，可以在文件上点击右键，在弹出的菜单中打开属性，常规页中的安全勾选解除锁定。

绿色版（免安装）

下载 CC-Switch-v{版本号}-Windows-Portable.zip
解压到任意目录
运行 CC-Switch.exe

macOS

方式一：Homebrew（推荐）

brew install --cask cc-switch

更新到最新版本：

brew upgrade --cask cc-switch

方式二：手动下载

下载 CC-Switch-v{版本号}-macOS.dmg（推荐）或 CC-Switch-v{版本号}-macOS.zip
打开 DMG，或解压 zip 得到 CC Switch.app
拖动到「应用程序」文件夹

CC Switch macOS 版本已通过 Apple 代码签名和公证，可直接安装打开，无需额外操作。

Linux

ArchLinux

使用 AUR 助手安装：

paru -S cc-switch-bin

yay -S cc-switch-bin

Debian / Ubuntu

根据架构下载 CC-Switch-v{版本号}-Linux-x86_64.deb 或 CC-Switch-v{版本号}-Linux-arm64.deb
安装：

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

sudo apt-get install -f

AppImage（通用）

根据架构下载 CC-Switch-v{版本号}-Linux-x86_64.AppImage 或 CC-Switch-v{版本号}-Linux-arm64.AppImage
添加执行权限：

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

运行：

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

验证安装

安装完成后，启动 CC Switch：

应用窗口正常显示
系统托盘出现 CC Switch 图标
应用切换器中能看到已启用的受管应用，并能切换到目标应用面板

自动更新

CC Switch 内置自动更新功能：

启动时自动检查更新
有新版本时在界面显示更新提示
点击即可下载并安装

也可以在「设置 → 关于」中手动检查更新。

卸载

Windows

通过「设置 → 应用」卸载
或运行安装目录下的卸载程序

macOS

将 CC Switch.app 移到废纸篓
可选：删除配置目录 ~/.cc-switch/

Linux

sudo apt remove cc-switch

paru -R cc-switch-bin

配置详情

本节帮助你在 1 分钟内完成首次配置。
以 Codex Desktop 为例，其它应用也是万变不离其宗。

第一步：切换到 Codex 面板

在主界面上方应用切换器中选择 Codex。

如果你没有看到该入口，请到：
设置 → 通用 → 应用可见性，确认 Codex 没有被隐藏。

第二步：添加供应商

基本选项

点击主界面右上角的 + 按钮
在预设供应商中选择自定义配置，手动配置
填写供应商名称，如「Flash Code」
填写 API Key，如「sk-xxxxxxxxxxx」
填写 API 请求地址，填入「https://api.flashpocket.cn」（如果打开了完整URL，则要填入为「https://api.flashpocket.cn/v1」）

高级选项

上游格式，点击下拉选择为「Chat Completions」
需要本地路由映射开关「打开」
支持思考模式开关「打开」
支持思考等级开关「打开」
模型映射
- 先点击添加模型按钮，再点击获取模型列表按钮
- 如果前面「API Key」和「API 请求地址」填入正确的话，可以直接在下拉选择到具体模型

点击添加按钮

第三步：打开路由

在设置中选择路由，将本地路由中的在主页面显示本地路由开关「打开」。

第四步：切换供应商

添加完成后，供应商会出现在列表中。

方式一：主界面切换

点击供应商卡片的「启用」按钮

方式二：托盘快速切换

右键系统托盘图标
直接点击供应商名称

第五步：打开路由

在主界面左上方的路由开关点击「打开」。

⚠️ 注意

最后需要重启 Codex Desktop，且使用过程中不能关闭 CC Switch。

至此，恭喜你已经完成了 Codex Desktop 的配置！

常见问题

切换后不生效？

切换供应商后，各 CLI 工具的生效方式不同：

应用	生效方式
Claude Code	✅ 即时生效（支持热重载）
Codex	需要关闭并重新打开终端
Gemini	✅ 即时生效（每次请求重新读取配置）
OpenCode	需要关闭并重新打开终端
OpenClaw	需要关闭并重新打开终端

如依旧不生效，确保重启了终端或 CLI 工具。配置文件在切换时已经更新，但运行中的程序不会自动重新加载。

找不到预设？

如果你的供应商不在预设列表中，选择「自定义配置」手动配置。

如何恢复官方登录？

选择「官方登录」预设（Claude/Codex）或「Google 官方」预设（Gemini），重启客户端后按登录流程操作。

如何跳过 Claude Code 初次安装确认？

如果 Claude Code 首次启动时提示需要登录或显示初始化引导，请在 CC Switch 中开启「跳过 Claude Code 初次安装确认」选项：

打开 CC Switch「设置 → 通用」
开启「跳过 Claude Code 初次安装确认」开关
重新启动 Claude Code

⚠️ 注意

此选项会写入 ~/.claude/settings.json 的 skipIntroduction 字段，跳过官方的新手引导流程。

如何验证配置？

启动对应的 CLI 工具并输入简单的问题进行测试：

claude
> 你好，测试一下

codex
> 你好，测试一下

gemini
> 你好，测试一下

opencode
> 你好，测试一下

openclaw
> 你好，测试一下

如果 AI 能正常回复，说明配置成功。