来源：https://www.ccswitch.io/zh/docs?section=getting-started

CC Switch 快速入门

文档说明

本文整理自 CC Switch「快速入门」文档，包含以下子项：

章节	内容
1.1 软件介绍	产品定位、核心能力、支持平台
1.2 安装指南	Windows / macOS / Linux 安装方式
1.3 界面概览	主界面、供应商卡片、托盘、设置页
1.4 快速上手	首次添加供应商并验证配置
1.5 个性化配置	语言、主题、目录、代理、备份、同步等设置

1.1 软件介绍

什么是 CC Switch

CC Switch 是一款跨平台桌面应用，用于统一管理多个 AI 编程工具的配置。

支持管理的工具包括：

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

主要解决的问题

问题	CC Switch 的作用
多供应商切换麻烦	通过界面一键切换 API 供应商
配置分散	统一管理不同 CLI 工具的配置文件
用量不可见	提供用量查询、余额展示、Token 统计
服务不稳定	支持代理、故障转移和熔断机制

核心功能

供应商管理

添加、编辑、删除 API 供应商

使用预设模板快速配置常见供应商

支持统一供应商，跨应用复用配置

支持 Claude Desktop 第三方供应商与模型映射

支持用量查询、余额显示、端点测速

扩展能力

MCP 服务器管理

Prompts 系统提示词管理

Skills 技能安装与管理

会话管理

工作区文件与每日记忆管理

代理与高可用

本地代理服务

请求日志记录

Token 用量统计

自动故障转移

熔断器机制

成本估算

支持平台

系统	最低版本	架构
Windows	Windows 10 及以上	x64
macOS	macOS 12 Monterey 及以上	Intel x64 / Apple Silicon arm64
Linux	Ubuntu 22.04+ / Debian 11+ / Fedora 34+	x64 / ARM64

技术架构

模块	技术
前端	React 18、TypeScript、Tailwind CSS
后端	Tauri 2、Rust
数据存储	SQLite、JSON

1.2 安装指南

官方下载渠道

请仅从以下官方渠道获取 CC Switch：

渠道	地址
官方网站	https://ccswitch.io
GitHub Releases	https://github.com/farion1231/cc-switch/releases
源码仓库	https://github.com/farion1231/cc-switch

注意：任何要求付费、充值或索取登录凭据的“CC Switch”网站或客户端，都不是官方渠道。

前置要求

CC Switch 管理的 CLI 工具通常需要 Node.js 环境。

推荐版本：

安装 Node.js

Windows

访问 Node.js 官网：https://nodejs.org/

下载 LTS 版本安装包

运行安装程序

验证安装：

macOS

也可以使用 nvm：

Linux

Ubuntu / Debian：

或使用 nvm：

安装 CLI 工具

Claude Code

或：

国内网络较慢时：

Codex

或：

国内网络较慢时：

Gemini CLI

或：

国内网络较慢时：

设置 npm 镜像源

Windows 安装

安装包方式

打开 Releases 页面：https://github.com/farion1231/cc-switch/releases

下载 Windows 安装包：

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

双击运行安装程序

按提示完成安装

如果安装程序没有反应：

右键安装包

打开“属性”

在“常规”页找到“安全”

勾选“解除锁定”

再次运行安装包

绿色版

下载：

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

解压到任意目录

运行：

CC-Switch.exe

macOS 安装

Homebrew 安装

更新：

手动安装

下载以下任一文件：

CC-Switch-v{版本号}-macOS.dmg
CC-Switch-v{版本号}-macOS.zip

打开 DMG，或解压 zip 得到 CC Switch.app

拖动到“应用程序”文件夹

Linux 安装

Arch Linux

或：

Debian / Ubuntu

下载对应架构的安装包：

CC-Switch-v{版本号}-Linux-x86_64.deb
CC-Switch-v{版本号}-Linux-arm64.deb

安装：

修复依赖：

AppImage

下载对应架构：

CC-Switch-v{版本号}-Linux-x86_64.AppImage
CC-Switch-v{版本号}-Linux-arm64.AppImage

添加执行权限：

运行：

验证安装

安装完成后启动 CC Switch，检查以下内容：

检查项	预期结果
应用窗口	可以正常打开
系统托盘	出现 CC Switch 图标
应用切换器	可以看到已启用的受管应用
应用面板	可以切换到目标应用

自动更新

CC Switch 支持自动更新：

启动时检查新版本

有新版本时显示更新提示

可点击下载并安装

可在“设置 → 关于”中手动检查更新

卸载

Windows

在“设置 → 应用”中卸载

或运行安装目录中的卸载程序

macOS

将 CC Switch.app 移到废纸篓

可选删除配置目录：

Linux

Debian / Ubuntu：

Arch Linux：

1.3 界面概览

主界面

主界面包含顶部导航、应用切换器、功能入口、供应商列表和操作按钮。

主界面示意图：

顶部导航栏

元素	功能
Logo	点击访问 GitHub 项目页
设置按钮	打开设置页面，快捷键 `Cmd/Ctrl + ,`
代理开关	启动或停止本地代理服务
应用切换器	切换 Claude、Claude Desktop、Codex、Gemini、OpenCode、OpenClaw、Hermes
功能区	显示当前应用支持的功能入口
添加按钮	添加新的供应商

应用切换器

可切换管理以下应用：

应用	管理内容
Claude	Claude Code 配置
Claude Desktop	Claude Desktop 官方模式与第三方供应商
Codex	Codex 配置
Gemini	Gemini CLI 配置
OpenCode	OpenCode 配置
OpenClaw	OpenClaw 配置
Hermes	Hermes Agent 供应商与 Memory

功能区按钮

按钮	功能	可见条件
Skills	技能扩展管理	Claude / Codex / Gemini / OpenCode / Hermes
Prompts	系统提示词管理	Claude / Codex / Gemini / OpenCode
MCP	MCP 服务器管理	Claude / Codex / Gemini / OpenCode / Hermes

供应商卡片

每个供应商以卡片形式展示，常见元素包括：

元素	功能
拖拽手柄	调整供应商顺序
供应商图标	显示品牌图标，可自定义颜色
供应商信息	显示名称、备注、端点地址
用量信息	显示余额、额度或套餐信息
启用按钮	切换为当前供应商
编辑按钮	修改供应商配置
复制按钮	创建供应商副本
测速按钮	测试模型可用性和响应速度
用量查询	配置用量查询脚本
删除按钮	删除供应商

操作按钮通常在鼠标悬停时显示，以保持界面简洁。

供应商卡片状态

状态	表现	说明
当前启用	蓝色边框	当前正在使用
代理活跃	绿色边框	代理接管模式下实际使用
普通状态	默认边框	未启用
故障转移中	显示优先级	例如 P1、P2

健康状态

代理模式下，故障转移队列中的供应商会显示健康状态：

状态	说明
健康	连续失败 0 次
警告	连续失败 1-2 次
不健康	连续失败 3 次及以上，可能触发熔断

系统托盘

系统托盘提供快速操作入口。

托盘菜单示意图：

托盘菜单功能

菜单项	功能
打开主界面	显示并聚焦主窗口
应用子菜单	按 Claude / Codex / Gemini 分组
供应商列表	点击切换供应商
轻量模式	进入或退出仅托盘运行模式
退出	完全退出应用

轻量模式

启用轻量模式后：

主窗口会被销毁以释放资源

应用仅保留在系统托盘中运行

仍可通过托盘菜单切换供应商

macOS 上 Dock 图标会隐藏

退出轻量模式：

点击托盘菜单中的“打开主界面”

或通过深链接 / 再次启动 CC Switch

设置页面

Tab	功能
通用	语言、主题、窗口行为、应用可见性
高级	配置目录、代理配置、故障转移、导入导出
用量	请求统计、趋势图表、请求日志
关于	版本信息、更新检查、开源协议

快捷键

快捷键	功能
`Cmd/Ctrl + ,`	打开设置
`Cmd/Ctrl + F`	搜索供应商
`Esc`	关闭弹窗或搜索

1.4 快速上手

第一步：添加供应商

点击主界面右上角的 + 按钮

在“预设”下拉框中选择供应商

填写 API Key

点击“添加”

常见预设包括：

智谱 GLM

MiniMax

DeepSeek

Kimi

PackyCode

自定义供应商

添加供应商示意图：

选择预设后，端点地址通常会自动填充，只需要补充 API Key。

第二步：切换供应商

主界面切换

在供应商卡片中点击“启用”。

托盘切换

右键系统托盘图标

在对应应用菜单中选择供应商

第三步：确认生效方式

不同 CLI 工具的配置生效方式不同：

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

Claude Code 首次安装提示

如果 Claude Code 首次启动时提示登录或初始化引导，可以开启跳过引导选项：

打开“设置 → 通用”

开启“跳过 Claude Code 初次安装确认”

重新启动 Claude Code

验证配置

启动对应 CLI 工具并输入简单问题测试。

Claude Code

你好，请简单介绍一下自己

Codex

你好，请简单介绍一下自己

Gemini

你好，请简单介绍一下自己

OpenCode

你好，请简单介绍一下自己

OpenClaw

你好，请简单介绍一下自己

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

下一步

目标	建议操作
添加更多供应商	进入供应商管理，添加多个配置
扩展能力	配置 MCP 服务器
自定义行为	设置系统提示词
监控与高可用	开启代理服务和故障转移

常见问题

切换后不生效怎么办？

请关闭并重新打开终端或 CLI 工具。部分工具不会自动重新加载已修改的配置文件。

找不到供应商预设怎么办？

选择“自定义”，手动填写端点、模型和 API Key。

如何恢复官方登录？

选择官方预设并重启客户端：

应用	预设
Claude / Codex	官方登录
Gemini	Google 官方

1.5 个性化配置

打开设置

可通过以下方式进入设置页：

点击左上角设置按钮

使用快捷键 Cmd/Ctrl + ,

语言设置

语言	说明
简体中文	默认中文界面
繁體中文	繁体中文界面
English	英文界面
日本語	日文界面

语言切换后立即生效，无需重启。

主题设置

选项	说明
跟随系统	自动匹配系统深色 / 浅色模式
浅色	始终使用浅色主题
深色	始终使用深色主题

窗口行为

开机自启

开启后，系统启动时自动运行 CC Switch。

系统	实现方式
Windows	注册表
macOS	LaunchAgent
Linux	XDG autostart

关闭行为

选项	说明
最小化到托盘	点击关闭按钮时隐藏到托盘
直接退出	点击关闭按钮时退出应用

推荐使用“最小化到托盘”，便于后台运行和快速切换供应商。

轻量模式

轻量模式是一种仅托盘运行状态，适合长时间后台使用。

对比项	最小化到托盘	轻量模式
主窗口	保留在内存中	销毁并按需重建
空闲资源占用	与正常运行接近	更低
再次打开速度	更快	略慢
托盘切换	支持	支持
深链接唤起	支持	支持

Claude 插件集成

开启后，CC Switch 在切换供应商时会同步配置到 VS Code 的 Claude Code 插件。

写入位置：

跳过 Claude 引导

开启后会跳过 Claude Code 的新手引导流程。

写入位置：

应用可见性

可配置哪些应用显示在应用切换器中。

支持控制的应用：

Claude

Claude Desktop

Codex

Gemini

OpenCode

OpenClaw

Hermes

至少需要保留一个可见应用。

Skills 同步方式

方式	说明
软链接 Symlink	指向技能源文件，占用空间小，更新同步快
复制 Copy	将技能文件完整复制到目标目录

默认推荐使用软链接。如果遇到权限问题，可以切换为复制。

终端设置

可选择 CC Switch 打开终端时使用的终端程序。

平台	终端选项
macOS	Terminal、iTerm2、Alacritty、Kitty、Ghostty、WezTerm
Windows	CMD、PowerShell、Windows Terminal
Linux	GNOME Terminal、Konsole、Xfce4 Terminal、Alacritty、Kitty、Ghostty

目录配置

应用配置目录

CC Switch 自身数据默认存储在：

CLI 工具目录

配置项	默认目录
Claude	`~/.claude/`
Codex	`~/.codex/`
Gemini	`~/.gemini/`
OpenCode	`~/.config/opencode/`
OpenClaw	`~/.openclaw/`
Hermes	`~/.hermes/`

修改目录后需要重启 CC Switch，对应 CLI 工具也需要使用相同目录。

数据管理

导出配置

导出内容包括：

供应商配置

MCP 服务器配置

Prompts 预设

用量日志

应用设置

导出文件名格式：

cc-switch-export-{timestamp}.sql

导入配置

点击“选择文件”

选择之前导出的 SQL 备份文件

点击“导入”

确认覆盖现有配置

导入会覆盖当前配置，建议导入前先导出备份。

代理设置

代理设置位于：

设置 → 代理

功能	说明
本地代理	启动 / 停止代理服务，配置监听地址和端口
故障转移	按应用配置供应商队列和自动切换策略
定价矫正器	校准模型计费统计
全局出站代理	配置 HTTP / HTTPS 出站代理

高级设置

高级设置位于：

设置 → 高级

包含：

配置目录

数据导入导出

备份与恢复

云同步 WebDAV

日志配置

备份与恢复

自动备份

配置	选项	默认值
备份间隔	禁用、6h、12h、24h、48h、7d	24 小时
保留数量	3、5、10、15、20、30、50	10 个备份

备份操作

操作	说明
立即备份	立刻创建数据库备份
恢复	从选定备份恢复数据库
重命名	修改备份显示名称
删除	删除指定备份

恢复备份会覆盖当前数据库。恢复前会自动创建安全备份。

云同步 WebDAV

通过 WebDAV 在多台设备间同步配置。

配置项	说明
服务预设	坚果云、Nextcloud、群晖、自定义
服务地址	WebDAV 服务器 URL
用户名	登录用户名
密码	登录密码或应用专用密码
远程目录	远程存储路径，默认 `cc-switch-sync`
配置名称	设备配置文件名，默认 `default`
自动同步	开启后按间隔自动同步

WebDAV 操作

操作	说明
测试连接	验证 WebDAV 配置
上传	将本地数据库上传到远程
下载	从远程下载数据库并覆盖本地

上传会覆盖远程数据，下载会覆盖本地数据。下载前会自动创建安全备份。

日志配置

配置项	说明
启用日志	开启或关闭应用日志
日志级别	error / warn / info / debug / trace

日志级别说明：

级别	说明
error	仅记录错误
warn	记录警告和错误
info	记录一般信息，推荐
debug	记录调试信息
trace	记录详细信息

OAuth 认证中心 Beta

位置：

设置 → OAuth 认证中心

支持的账号类型：

账号类型	用途
GitHub Copilot	配合 Copilot 反向代理
ChatGPT / Codex OAuth	配合 Codex OAuth 反向代理
xAI / Grok OAuth	配合 xAI Responses API 反向代理

可执行操作：

通过 Device Code 登录账号

查看账号列表和认证状态

设置默认账号

移除单个账号

一键注销所有账号

xAI OAuth 网络依赖

依赖	地址
OpenID discovery	`https://auth.x.ai/.well-known/openid-configuration`
设备授权	`https://auth.x.ai/oauth2/device/code`
Token 交换 / 刷新	`https://auth.x.ai/oauth2/token`
推理接口	`https://api.x.ai/v1/responses`
模型发现	`https://api.x.ai/v1/models`

风险提示：账号型反向代理可能涉及账号与服务条款风险，使用前应自行确认对应服务商条款。

关于页面

位置：

设置 → 关于

版本信息

可查看：

当前 CC Switch 版本

发布说明

更新检查

新版本下载与安装

本地环境检查

可检测以下 CLI 工具版本：

工具	检测内容
Claude	当前版本、最新版本
Codex	当前版本、最新版本
Gemini	当前版本、最新版本
OpenCode	当前版本、最新版本
OpenClaw	当前版本、最新版本
Hermes	当前版本、最新版本

检测到新版后，可以单独升级，也可以全部升级。

名称	地址
官方网站	https://ccswitch.io
快速入门文档	https://www.ccswitch.io/zh/docs?section=getting-started
GitHub 仓库	https://github.com/farion1231/cc-switch
Releases 下载页	https://github.com/farion1231/cc-switch/releases **

CC Switch 教程

CC Switch 快速入门#

文档说明#

1.1 软件介绍#

什么是 CC Switch#

主要解决的问题#

核心功能#

供应商管理#

扩展能力#

代理与高可用#

支持平台#

技术架构#

1.2 安装指南#

官方下载渠道#

前置要求#

安装 Node.js#

Windows#

macOS#

Linux#

安装 CLI 工具#

Claude Code#

Codex#

Gemini CLI#

设置 npm 镜像源#

Windows 安装#

安装包方式#

绿色版#

macOS 安装#

Homebrew 安装#

手动安装#

Linux 安装#

Arch Linux#

Debian / Ubuntu#

AppImage#

验证安装#

自动更新#

卸载#

Windows#

macOS#

Linux#

1.3 界面概览#

主界面#

顶部导航栏#

应用切换器#

功能区按钮#

供应商卡片#

供应商卡片状态#

健康状态#

系统托盘#

托盘菜单功能#

轻量模式#

设置页面#

快捷键#

1.4 快速上手#

第一步：添加供应商#

第二步：切换供应商#

主界面切换#

托盘切换#

第三步：确认生效方式#

Claude Code 首次安装提示#

验证配置#

Claude Code#

Codex#

Gemini#

OpenCode#

OpenClaw#

下一步#

常见问题#

切换后不生效怎么办？#

找不到供应商预设怎么办？#

如何恢复官方登录？#

1.5 个性化配置#

打开设置#

语言设置#

主题设置#

窗口行为#

开机自启#

关闭行为#

轻量模式#

Claude 插件集成#

CC Switch 快速入门

文档说明

1.1 软件介绍

什么是 CC Switch

主要解决的问题

核心功能

供应商管理

扩展能力

代理与高可用

支持平台

技术架构

1.2 安装指南

官方下载渠道

前置要求

安装 Node.js

Windows

macOS

Linux

安装 CLI 工具

Claude Code

Codex

Gemini CLI

设置 npm 镜像源

Windows 安装

安装包方式

绿色版

macOS 安装

Homebrew 安装

手动安装

Linux 安装

Arch Linux

Debian / Ubuntu

AppImage

验证安装

自动更新

卸载

Windows

macOS

Linux

1.3 界面概览

主界面

顶部导航栏

应用切换器

功能区按钮

供应商卡片

供应商卡片状态

健康状态

系统托盘

托盘菜单功能

轻量模式

设置页面

快捷键

1.4 快速上手

第一步：添加供应商

第二步：切换供应商

主界面切换

托盘切换

第三步：确认生效方式

Claude Code 首次安装提示

验证配置

Claude Code

Codex

Gemini

OpenCode

OpenClaw

下一步

常见问题

切换后不生效怎么办？

找不到供应商预设怎么办？

如何恢复官方登录？

1.5 个性化配置

打开设置

语言设置

主题设置

窗口行为

开机自启

关闭行为

轻量模式

Claude 插件集成

跳过 Claude 引导