cc-switch/docs/user-manual/zh/1-getting-started/1.2-installation.md

1.2 安装指南

前置要求

安装 Node.js

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

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

Windows

1. 访问 Node.js 官网

2. 下载 LTS 版本安装包

3. 运行安装程序，按提示完成安装

4. 验证安装：

node --version
npm --version

macOS

# 使用 Homebrew 安装
brew install node

# 或使用 nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

Linux

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

# 或使用 nvm
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

安装包方式

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

绿色版（免安装）

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

macOS

方式一：Homebrew（推荐）

# 添加 tap
brew tap farion1231/ccswitch

# 安装
brew install --cask cc-switch

更新到最新版本：

brew upgrade --cask cc-switch

方式二：手动下载

1. 下载 CC-Switch-v{版本号}-macOS.zip
2. 解压得到 CC Switch.app
3. 拖动到「应用程序」文件夹

首次打开提示

由于开发者没有 Apple 开发者账号，首次打开可能出现「未知开发者」警告：

推荐解决方法： 打开终端执行以下命令：

sudo xattr -dr com.apple.quarantine /Applications/CC\ Switch.app/

备选解决方法（通过系统设置）：

1. 关闭警告弹窗
2. 打开「系统设置」→「隐私与安全性」
3. 找到 CC Switch 相关提示，点击「仍要打开」
4. 再次打开应用即可正常使用

Linux

ArchLinux

使用 AUR 助手安装：

# 使用 paru
paru -S cc-switch-bin

# 或使用 yay
yay -S cc-switch-bin

Debian / Ubuntu

1. 下载 CC-Switch-v{版本号}-Linux.deb
2. 安装：

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

# 如果有依赖问题
sudo apt-get install -f

AppImage（通用）

1. 下载 CC-Switch-v{版本号}-Linux.AppImage
2. 添加执行权限：

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

3. 运行：

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

验证安装

安装完成后，启动 CC Switch：

1. 应用窗口正常显示
2. 系统托盘出现 CC Switch 图标
3. 能够切换 Claude / Codex / Gemini 三个应用

自动更新

CC Switch 内置自动更新功能：

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

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

卸载

Windows

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

macOS

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

Linux

# Debian/Ubuntu
sudo apt remove cc-switch

# ArchLinux
paru -R cc-switch-bin