CC Switch 完整使用指南：Claude Code / Codex / Gemini CLI 多供应商配置管理

AI瑶·2026-08-14教程

CC Switch 完整使用指南：Claude Code / Codex / Gemini CLI 多供应商配置管理

文档基于 CC Switch 官方用户手册（v3.16.0，更新于 2026-05-29）项目：github.com/farion1231/cc-switch ｜官网：cc-switch.cc

视频演示

B 站上有一份 CC Switch 的视频教程，可直接在线观看：

一、CC Switch 是什么？

CC Switch 是一款基于 Tauri 2 构建的跨平台桌面应用（支持 Windows / macOS / Linux），专为使用 AI 编程工具的开发者设计，统一管理以下 8 个受管应用的配置：

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

它解决的核心痛点：多供应商切换麻烦（官方/中转要手动改配置）、配置分散难管理（各工具配置文件格式不同）、无法监控用量、单一供应商故障时整个工作流中断。

核心功能一览：

一键切换多个 API 供应商配置，50+ 预设供应商（Anthropic、OpenAI、Google 及国内主流中转）
统一供应商：一份配置跨多个应用共享
MCP 服务器统一管理（多应用双向同步）
Prompts 提示词管理（CLAUDE.md / AGENTS.md / GEMINI.md 跨应用同步）
Skills 技能一键安装（GitHub 仓库 / ZIP）
本地代理服务：请求日志、自动故障转移、熔断器、Token 用量追踪
用量查询与余额显示、系统托盘快速切换、云同步（Dropbox / OneDrive / iCloud / WebDAV）

二、安装指南

⚠️ 官方渠道（重要）

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

前置要求：Node.js

CC Switch 管理的 CLI 工具（Claude Code、Codex、Gemini CLI）需要 Node.js 环境，推荐 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 config set registry https://registry.npmmirror.com

CC Switch 本体安装

系统	方式
Windows	下载 `CC-Switch-v{版本号}-Windows.msi` 双击安装；或绿色版 `Windows-Portable.zip` 解压直接运行
macOS	`brew install --cask cc-switch`（推荐）；或下载 `.dmg`（已签名公证，可直接打开）
Linux (Arch)	`paru -S cc-switch-bin` 或 `yay -S cc-switch-bin`
Linux (Debian/Ubuntu)	下载 `.deb` 后 `sudo dpkg -i CC-Switch-*.deb`
Linux (通用)	下载 `.AppImage`，`chmod +x` 后运行

Windows 运行安装程序无反应时：右键文件 → 属性 → 常规 → 安全 → 勾选「解除锁定」。

验证安装

启动后：① 应用窗口正常显示；② 系统托盘出现图标；③ 应用切换器中能看到已启用的受管应用。

三、快速上手（5 分钟）

第一步：添加供应商

点击主界面右上角 + 按钮
在「预设」下拉框选择供应商（常用：智谱 GLM、MiniMax、DeepSeek、Kimi、PackyCode 等）
填写 API Key（预设会自动填充端点地址）
点击「添加」

💡 第一次使用建议先导入现有 CLI 工具配置作为默认供应商，再新增要切换的供应商。

第二步：切换供应商

主界面：点击供应商卡片的「启用」按钮
系统托盘：右键托盘图标 → 悬停到对应应用子菜单 → 点击供应商名称（无需打开主界面）

第三步：生效方式（关键差异）

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

第四步：验证配置

claude    # 然后输入 "你好，请简单介绍一下自己"
codex     # 同上
gemini    # 同上

AI 能正常回复即配置成功。

Claude Code 首次启动提示登录/初始化引导时，可在 CC Switch「设置 → 通用」开启「跳过 Claude Code 初次安装确认」，它会写入 ~/.claude/settings.json 的 skipIntroduction 字段。

四、供应商管理进阶

应用专属供应商 vs 统一供应商

应用专属供应商：仅用于当前选中的应用（Claude Code / Claude Desktop / Codex / Gemini / OpenCode / OpenClaw / Hermes），适合先跑通单条线路
统一供应商：一份配置跨多个应用共享。适合同时在 Claude Code、Codex、Gemini 之间共享一套中转服务的人。修改统一供应商后关联应用会同步更新；删除也会一并删除关联配置

自动获取模型列表

添加/编辑供应商时，表单里有模型字段的（Claude Code、Claude Desktop、Codex、Gemini、OpenCode、OpenClaw、Hermes），可以：

先填好 API Key 和端点地址
点击模型输入框旁的「获取模型」按钮
CC Switch 调用该端点的 /v1/models 拉取可用模型
从按类别分组的下拉菜单选择

常见错误：401/403（Key 错误）、404/405（端点不支持 /v1/models，需手动填）、超时（端点慢）。

自定义配置格式

预设没有的供应商，可切到「自定义」手动配置：

Claude 格式（JSON）：

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

Codex 格式（两个文件）：~/.codex/auth.json 存 API Key（OPENAI_API_KEY）；~/.codex/config.toml 存模型与端点：

model_provider = "custom"
model = "gpt-5.2"
model_reasoning_effort = "high"
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 协议的供应商（DeepSeek、Kimi、GLM、MiniMax 等），选择对应预设时「需要本地路由映射」开关会自动配置好，无需手动处理。

切换时修改的配置文件

应用	配置文件
Claude	`~/.claude/settings.json`
Codex	`~/.codex/auth.json` + `~/.codex/config.toml`
Gemini	`~/.gemini/.env` + `~/.gemini/settings.json`

五、扩展功能

MCP 管理：统一管理 Claude / Codex / Gemini / Grok Build / OpenCode / Hermes 的 MCP 服务器，双向同步，支持 Deep Link 导入
Prompts：Markdown 编辑器创建预设，激活后同步到 live 文件（CLAUDE.md / AGENTS.md / GEMINI.md），带回填保护
Skills：从 GitHub 仓库或 ZIP 一键安装，支持自定义仓库管理、SHA-256 更新检测与批量更新、skills.sh 公共注册表搜索
会话管理器：浏览、搜索、恢复支持的会话来源
工作区文件与每日记忆（OpenClaw）：工作区文件管理与每日记忆功能

六、代理与高可用

本地代理服务：记录请求日志和用量统计，支持格式转换
应用级代理接管：为 Claude / Codex / Gemini / Grok Build 独立配置代理，具体到单个供应商
自动故障转移：主供应商失败时自动切换备用供应商
熔断器机制：防止频繁重试失败的供应商（默认熔断时长 60 秒）
用量统计：趋势图表、缓存归一化真实 token 与缓存命中率、定价配置；官方订阅类（Claude/Codex/Gemini/Copilot）自动展示剩余额度
模型检查（Stream Check）：健康检测与延迟测试，覆盖 Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes

七、常见问题 FAQ（精选）

切换后不生效？

Claude Code / Gemini：确认使用了最新配置（热重载或每次读取）；仍不行则重启终端
Codex / OpenCode / OpenClaw：必须重启终端。配置启用后不要在旧终端里测试

启用后还是走官方账号？

检查：① 旧终端没重启；② 工具的环境变量覆盖了配置文件；③ CC Switch 改的是另一个工具的配置；④ 导入的是默认配置但没启用新供应商。

API Key 无效？

确认 Key 复制正确（无多余空格）
确认 Key 未过期
确认端点地址正确
用 CC Switch 的速度测试验证连接

提示模型名错误？

先确认供应商支持 Anthropic / OpenAI / Gemini 哪种格式
确认模型名完全一致
中转站要问清是否做了模型别名映射
不要自己猜模型名（能在一个工具跑通不代表另一个也能）

切换后插件配置不见了？

CC Switch 使用「通用配置片段」功能：在「编辑供应商 → 通用配置面板」点击「从当前供应商提取」，把通用数据（Key 和请求地址之外的插件等）提取到通用配置；新建供应商时勾选「应用通用配置」（默认勾选）即可写入。所有配置项保存在第一次导入的默认供应商里，不会丢失。

为什么总有一个激活中的供应商无法删除？

设计原则是「最小侵入性」：即使卸载软件也不影响应用正常使用，所以系统总会保留一个正在激活中的配置。

配置丢失？

检查 ~/.cc-switch/ 目录是否存在；从 ~/.cc-switch/backups/ 恢复；或导入之前导出的 SQL 备份文件。

故障转移没触发？

检查清单：代理服务是否运行、应用接管是否开启、自动故障转移是否开启、队列中是否有备用供应商。

Linux (Wayland + NVIDIA) 点击无响应 / 黑屏？

用专用环境变量切回原生 Wayland：

CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage

（tiling 合成器下若反而失效，可设 CC_SWITCH_GDK_BACKEND=x11。）

八、安全提示

只从官方渠道下载：ccswitch.io / GitHub Releases；任何要付费、充值、索要登录凭据的网站都是假冒
不要把 Claude、OpenAI、Google 账号密码填到任何非官方页面
Codex OAuth 反向代理有风险：通过逆向 OAuth 流程访问 ChatGPT 账号的 Codex 服务，可能违反 OpenAI 服务条款，存在账号被限制/暂停风险，启用即自行承担
提交 Issue 前先检查日志（~/.cc-switch/logs/cc-switch.log）是否含敏感信息

参考链接

GitHub 仓库：https://github.com/farion1231/cc-switch
官网：https://cc-switch.cc/
官方用户手册：https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/zh/README.md
供应商配置教程：https://cc-switch.cc/tutorials/provider-setup
Releases（下载）：https://github.com/farion1231/cc-switch/releases

CC Switch 完整使用指南：Claude Code / Codex / Gemini CLI 多供应商配置管理

CC Switch 完整使用指南：Claude Code / Codex / Gemini CLI 多供应商配置管理

视频演示

一、CC Switch 是什么？

二、安装指南

⚠️ 官方渠道（重要）

前置要求：Node.js

安装受管 CLI 工具（示例）

CC Switch 本体安装

验证安装

三、快速上手（5 分钟）

第一步：添加供应商

第二步：切换供应商

第三步：生效方式（关键差异）

第四步：验证配置

四、供应商管理进阶

应用专属供应商 vs 统一供应商

自动获取模型列表

自定义配置格式

切换时修改的配置文件

五、扩展功能

六、代理与高可用

七、常见问题 FAQ（精选）

切换后不生效？

启用后还是走官方账号？

API Key 无效？

提示模型名错误？

切换后插件配置不见了？

为什么总有一个激活中的供应商无法删除？

配置丢失？

故障转移没触发？

Linux (Wayland + NVIDIA) 点击无响应 / 黑屏？

八、安全提示

参考链接

加微信群

完整免责声明

一、平台性质

二、内容来源与真实性

三、使用风险与责任

四、第三方服务与链接

五、合规使用与禁止用途

六、知识产权与侵权处理

七、数据与安全

八、服务变更与中断

九、法律适用与争议解决

十、联系与反馈