超详细！CC-Switch 3.16.1 全平台部署 使用指南【2026.6.12】

✅ 一、下载（v3.16.1，2026-06-01 官方版）

国内备用（高速）： https://pan.quark.cn/s/d6152047213b

各平台安装包（Assets 里找）：

• Windows（Win10+ x64）
  • 安装版（推荐，自动更新）：CC-Switch-v3.16.1-Windows.msi
  • 便携版（免安装）：CC-Switch-v3.16.1-Windows-Portable.zip
• macOS（12+，Intel/Apple Silicon）
  • 镜像：CC-Switch-v3.16.1-macOS_Universal.dmg
  • Homebrew（推荐）：

    brew tap farion1231/ccswitch brewinstall--caskcc-switch

• Linux（Ubuntu22.04+/Debian11+/Fedora34+）
  • Debian/Ubuntu：cc-switch_3.16.1_amd64.deb
  • Fedora/RHEL：CC-Switch-v3.16.1-Linux.x86_64.rpm
  • AppImage（通用）：CC-Switch-v3.16.1-Linux.AppImage

✅ 二、安装步骤

Windows（MSI 安装版）

1. 双击.msi→ 同意协议 → 建议改路径到非中文目录（如 D:\CCSwitch）。

2. 下一步 → 勾选桌面快捷方式 → 安装 → 完成后启动。

Windows（便携版）

• 解压Portable.zip到全英文无空格路径，双击CC-Switch.exe直接运行，配置保存在文件夹data目录。

macOS（DMG）

1. 双击.dmg→ 将CC Switch.app拖入「应用程序」。
2. 首次启动提示“未知开发者”：系统设置 → 隐私与安全性 → 点击「仍要打开」。

Linux

• Debian/Ubuntu：

  sudodpkg-icc-switch_3.16.1_amd64.debsudoapt-finstall-y# 依赖缺失时修复

• AppImage：

  chmod+x CC-Switch-v3.16.1-Linux.AppImage ./CC-Switch-v3.16.1-Linux.AppImage

✅ 三、首次启动基础配置（必做）

1. 启动后自动扫描已安装的 AI CLI（Claude Code、Codex、Gemini CLI 等）。

2. 左上角设置 → 通用：

   • 勾选：跳过 Claude Code 初次登录校验、自动接管本地 Claude 配置文件（~/.claude.json）。
   • 端口默认 18789，保存。

✅ 四、添加 API 供应商（核心）

1. 右上角**+Add Provider（新增服务商）**。

2. 选预设（如 Anthropic、DeepSeek、Kimi、智谱 GLM）或自定义（Custom）。

示例1：官方 Anthropic

• 名称：自定义（如 Claude 官方）
• BaseURL：https://api.anthropic.com
• API Key：官网获取的sk-密钥
• 模型：claude-sonnet-4/haiku等。

示例2：自定义第三方中转（如 ZenMux）

• 名称：ZenMux（自定义）
• BaseURL：中转地址（如https://zenmux.ai/api/anthropic）
• API Key：服务商sk-密钥
• API 格式：选 Anthropic 或 OpenAI 兼容。

3. 保存后，在列表选中 → 点击启用，自动写入对应 CLI 配置文件。

4. 健康检查：点击「健康检查」，验证 Key 与连通性。

✅ 五、切换与使用

1. 顶部切换栏选目标 CLI（如 Claude Code）。
2. 供应商列表点选 → 启用 → 终端直接运行claude/codex等命令即可生效。
3. 常用 CLI 配置文件路径：
   • Claude Code：~/.claude/settings.json
   • Codex：~/.codex/auth.json
   • Gemini CLI：~/.gemini/config.json。

✅ 六、常见问题

• Windows 安全提示：允许运行，添加信任。
• macOS 无法验证：隐私与安全性 → 仍要打开。
• Linux 托盘不显示（GNOME）：安装gnome-shell-extension-appindicator并重启。
• 报错“配置文件无权限”：右键文件夹 → 属性 → 完全控制。