CC Switch v3.10.3 - 安装与使用详细教程

蓝桉_T
0 阅读8分钟

CC Switch 是一款跨平台桌面 All-in-One 助手工具，支持统一管理 Claude Code、Codex、OpenCode 和 Gemini CLI 的 API Provider、MCP 服务、Skills 扩展等配置。

GitHub：github.com/farion1231/…

目录

  1. 软件简介
  2. Windows 安装
  3. macOS 安装
  4. Linux 安装
  5. 首次启动与界面说明
  6. Provider 管理（核心功能）
  7. 本地 API 代理（Proxy）
  8. MCP 服务器管理
  9. Skills 技能扩展管理
  10. 自动故障转移（Auto Failover）
  11. 全局代理设置
  12. Claude Rectifier（思考签名修复）
  13. 常见问题排查
  14. 版本说明（v3.10.3）

软件简介

CC Switch 的核心价值在于：无需手动修改各 CLI 工具的配置文件，只需在图形界面中点击切换，即可将 Claude Code、Codex、OpenCode、Gemini CLI 的 API 请求路由到不同的 Provider（官方、第三方中转、自建服务等）。

主要功能一览：

功能说明
Provider 管理添加、编辑、切换、删除 API Provider，支持预设模板
本地 API 代理内置高性能本地 HTTP 代理，自动接管 CLI 配置
Auto Failover自动检测 Provider 故障并切换到备用节点
MCP 服务管理统一管理 Claude/Codex/Gemini 的 MCP 服务器
Skills 管理安装/卸载/同步社区 Skills 扩展
多语言支持中文 / English / 日本語
请求日志记录代理请求与使用统计，方便调试和成本追踪

Windows 安装

方式一：MSI 安装包（推荐）

下载地址（本教程版本）：

https://github.com/farion1231/cc-switch/releases/download/v3.10.3/CC-Switch-v3.10.3-Windows.msi

安装步骤：

  1. 下载 CC-Switch-v3.10.3-Windows.msi 文件。
  2. 双击运行安装包，按照向导完成安装。
  3. 安装完成后，在开始菜单或桌面找到 CC Switch 并启动。

⚠️ 注意（v3.10.3 重要修复）： 本版本修复了从 v3.10.2 升级到 v3.10.3 后，当系统 HOME 路径与实际用户目录不一致时，Provider 和设置数据"消失"的问题。如果你从旧版本升级，请确保使用 v3.10.3 的安装包重新安装。

方式二：便携版（绿色免安装）

在 Releases 页面下载 CC-Switch-v3.10.3-Windows-Portable.zip，解压后直接运行 CC Switch.exe，无需安装，不写入注册表。

macOS 安装

方式一：Homebrew（推荐）

brew tap farion1231/ccswitch
brew install --cask cc-switch

方式二：手动安装

  1. 在 Releases 页面下载 CC-Switch-vX.X.X-macOS.zip。

  2. 解压后将 CC Switch.app 拖入 /Applications 文件夹。

  3. 首次启动时若提示"无法验证开发者"：

    • 关闭弹窗
    • 进入「系统设置」→「隐私与安全性」→ 点击「仍要打开」

  4. 若提示"文件已损坏"，在终端执行：

    xattr -cr "/Applications/CC Switch.app"

Linux 安装

Debian / Ubuntu（.deb 包）：

# 下载并安装
sudo dpkg -i CC-Switch-vX.X.X-Linux.deb

AppImage（通用）：

chmod +x CC-Switch-vX.X.X-Linux.AppImage
./CC-Switch-vX.X.X-Linux.AppImage

Flatpak 环境：v3.9.0 起已内置 libayatana-appindicator，支持系统托盘图标。

首次启动与界面说明

启动后，CC Switch 主界面分为以下几个区域：

┌─────────────────────────────────────────────────────┐
│  标题栏：CC Switch                      [MCP] [设置] │
├──────────┬──────────────────────────────────────────┤
│          │                                          │
│  应用选择  │         Provider 列表区域                │
│  Claude  │   [Provider 1]  当前激活  ✓              │
│  Codex   │   [Provider 2]  备用节点                  │
│  OpenCode│   [Add Provider]                         │
│  Gemini  │                                          │
│          │         [Proxy 状态栏]                   │
└──────────┴──────────────────────────────────────────┘
  • 左侧：选择要管理的 CLI 工具（Claude Code / Codex / OpenCode / Gemini CLI）
  • 右侧上方：该工具的 Provider 列表，可切换激活项
  • 右上角：MCP 管理入口、全局设置
  • 底部：本地代理状态

Provider 管理（核心功能）

Provider 即 API 接入节点，可以是官方 API、第三方中转站或自建服务。

添加 Provider

  1. 在主界面点击 「Add Provider」。

  2. 选择预设模板（内置了 PackyCode、AIGoCode、AICodeMirror、Cubence、DMXAPI、RightCode 等常用中转预设），或选择「Custom」自定义。

  3. 填写以下字段：

    字段说明
    NameProvider 名称（自定义，方便识别）
    API Base URLAPI 端点地址，如 https://api.anthropic.com
    API Key对应服务的密钥
    Model模型名称（可选，覆盖默认值）
    API FormatAPI 格式选择器（Anthropic / OpenRouter 等）

  4. 点击「Save」保存。

切换 Provider

  • 点击列表中任意 Provider 的激活按钮，CC Switch 会立即将对应 CLI 工具的配置重定向至该 Provider。
  • 切换生效后，重启或新建一个 Claude Code / Codex / Gemini CLI 会话即可使用新的 Provider。

恢复官方设置

  • Claude Code / Codex：选择「Official Login」预设，重启对应 CLI 并重新登录。
  • Gemini CLI：选择「Google Official」预设，重启并完成 OAuth 认证。

每个应用独立配置

v3.10.x 起支持「Per-provider configuration」，每个应用（Claude/Codex/Gemini/OpenCode）可以独立管理各自的 Provider 列表，互不干扰。

本地 API 代理（Proxy）

这是 v3.9.0 引入的核心功能，基于 Axum 框架构建，性能高效。

工作原理

CC Switch 在本地启动一个 HTTP 代理服务器，并接管各 CLI 工具的配置文件（自动备份原始配置），将所有 API 请求通过本地代理转发，再由代理路由到指定 Provider。

启用代理

  1. 在主界面底部或设置中找到 Proxy 开关。

  2. 点击开启（默认关闭，v3.10.3 中 Rectifier 修复了默认状态稳定性问题）。

  3. 开启后，可为每个应用单独设置「Takeover」（接管）：

    • Per-App Takeover：仅接管已开启 Takeover 的应用，其他应用保持原配置不变。

请求日志与统计

代理开启后，可在日志面板查看：

  • 每条请求的时间、Provider、状态
  • 失败请求的详细错误信息（便于调试）
  • 用量统计（用于成本追踪）

MCP 服务器管理

MCP（Model Context Protocol）服务器可以为 Claude Code 等工具提供额外的上下文能力。

进入 MCP 管理

点击主界面右上角的 「MCP」 按钮。

主要操作

  • 添加 MCP Server：手动填写服务器配置（名称、命令、参数、环境变量）
  • 导入已有配置：从 Claude / Codex / Gemini 的现有配置文件一键导入
  • 统一架构：同一个 MCP 配置可以同步到多个 CLI 工具
  • 导出备份：将 MCP 配置导出为标准 JSON 格式

⚠️ v3.10.3 对 SQL 导入做了安全限制：仅允许导入 CC Switch 自身导出的备份文件。

Skills 技能扩展管理

Skills 是 Claude Code 的 ~/.claude/skills/ 目录下的扩展脚本，CC Switch 提供了可视化管理界面。

主要操作

安装 Skill → 启用/禁用（按应用单独控制） → 同步到 CLI 目录
  • 搜索安装：从内置的社区仓库（包含 3 个精选仓库）搜索并安装 Skills
  • 添加自定义仓库：支持 owner/repo[@branch] 或 GitHub URL 格式
  • 多应用支持：同一个 Skill 可以分别为 Claude / Codex / OpenCode 启用或禁用
  • 同步方式：支持符号链接（symlink）或文件复制（copy）两种同步方式

自动故障转移（Auto Failover）

在 Proxy 开启的前提下，CC Switch 内置了熔断器（Circuit Breaker）机制：

  1. 健康检测：定期检测每个 Provider 的可用性
  2. 自动切换：当前 Provider 失败时，自动切换到备用 Provider
  3. 独立队列：每个应用有独立的 Provider 队列，互不影响
  4. 恢复检测：主 Provider 恢复后，自动切回

配置方法：

在 Provider 列表中，将多个 Provider 设置为同一应用的候选节点，CC Switch 会按优先级自动管理故障转移。

全局代理设置

v3.10.0 起，CC Switch 支持为所有出站网络请求配置统一代理（HTTP/HTTPS/SOCKS5）。

设置路径： 右上角「设置」→「Network」→「Global Proxy」

填写代理地址，例如：

http://127.0.0.1:7890

Claude Rectifier（思考签名修复）

Rectifier 是 v3.10.0 引入的特殊功能，用于修复部分第三方 Provider 在返回 Claude 思考（Thinking）功能响应时，签名字段格式不兼容的问题。

  • 入口：设置 → Rectifier（默认关闭，v3.10.3 修复了默认状态异常问题）
  • 适用场景：当你使用第三方 Provider 且 Claude Code 在使用扩展思考模式时报错，可尝试开启此功能

常见问题排查

切换 Provider 后 CLI 没有生效

  1. 确认已重启对应的 CLI 工具（Claude Code / Codex / Gemini CLI）。
  2. 检查系统环境变量中是否有 ANTHROPIC_API_KEY、OPENAI_API_KEY 等直接设置的密钥——这些环境变量优先级高于 CC Switch 的配置，会覆盖生效。解决方法：编辑 ~/.zshrc 或 ~/.bashrc，删除或注释掉相关行，然后 source ~/.zshrc。

WSL 环境下检测工具版本失败

v3.9.x 起已支持 WSL 环境下的工具版本检测，并加入了安全加固防止命令注入。如仍有问题，确认 WSL 内已正常安装目标 CLI 工具。

Windows 升级后数据丢失

v3.10.3 已修复从 v3.10.2 升级时，HOME 路径不一致导致的数据库路径识别错误问题。请使用 v3.10.3 重新安装，软件会自动检测旧版数据库位置并恢复。

应用图标显示异常 / 窗口布局问题

v3.10.1 调整了图标折叠阈值（从 3 个提高到 4 个），并修复了 Windows/Linux 上标题栏下多余空白的问题。确保使用 v3.10.1 及以上版本。

版本说明（v3.10.3）

v3.10.3 是一个针对 Windows 平台的维护版本，主要修复内容：

修复项说明
Windows 数据回归修复修复 HOME 路径不一致导致的 Provider/Settings 丢失问题
Provider 图标更新更新 RightCode Provider 图标
Rectifier 默认状态修改 Rectifier 默认为禁用，提升稳定性
窗口设置优化调整窗口设置顺序和默认值
UI 布局图标折叠阈值从 3 调整为 4

附录：快速上手流程

1. 安装 CC Switch
       ↓
2. 启动软件，在左侧选择 Claude Code
       ↓
3. 点击 Add Provider，选择预设或填写自定义 API Base URL + API Key
       ↓
4. 点击该 Provider 的激活按钮
       ↓
5. 重启 Claude Code，即可使用新的 Provider
       ↓
（可选）6. 开启 Proxy + Takeover，享受自动故障转移和请求日志功能
avatar
文章
阅读
粉丝