Claude Code 中文教程网

外观

2.4 使用 CC-Switch 工具

约 2230 字大约 7 分钟

CC-Switch 是什么？为什么需要它

CC-Switch 是一款开源的跨平台桌面应用，专门用于统一管理 AI 编程助手的配置。它由开发者 farion1231 创建并开源在 GitHub 上。 alt text

CC-Switch 核心定位

简单来说，CC-Switch 是 AI 编程工具的「配置管理中心」：

传统方式CC-Switch 方式
手动编辑 ~/.claude/settings.json可视化界面一键配置
不同工具配置文件分散统一管理 4 款 CLI 工具
切换 Provider 需重启+改文件一键切换，自动生效
无法测速，不知道哪个快内置延迟测试，直观显示
配置丢失难恢复自动备份，支持云同步

CC-Switch 支持的 4 大 AI 编程工具

工具说明配置文件位置
Claude CodeAnthropic 官方终端 AI 助手~/.claude/settings.json
CodexOpenAI 的 CLI 编程工具~/.codex/config.toml
OpenCode开源终端 AI 助手~/.config/opencode/
Gemini CLIGoogle 的终端 AI 工具~/.gemini/.env

CC-Switch 核心功能详解

CC-Switch 不仅仅是配置切换器，它是一个功能完整的 AI 工具管理平台：

alt text

功能一：Provider 管理（核心功能）

这是 CC-Switch 最常用的功能，支持：

功能说明
添加 Provider配置 API 地址、密钥、模型映射
一键切换在多个 Provider 间快速切换
速度测试测量各 Provider 的 API 延迟
共享配置一个 Provider 同步到多个工具
官方回退一键恢复官方登录状态

Provider 配置示例：

{
  "name": "openRouter",
  "baseUrl": "https://openrouter.ai/api/v1",
  "apiKey": "sk-your-apiyi-key",
  "models": {
    "claude-sonnet-4-20250514": "claude-sonnet-4-20250514",
    "claude-opus-4-20250514": "claude-opus-4-20250514"
  }
}

功能二：MCP 服务器管理

MCP (Model Context Protocol) 是 Claude Code 的扩展协议。CC-Switch 提供统一的 MCP 管理界面：

  • 支持 stdio / http / sse 三种传输类型
  • 跨应用统一配置 (Claude/Codex/Gemini)
  • 可视化添加、编辑、删除 MCP 服务器

功能三：Skills 技能管理

CC-Switch 可以自动发现和安装 Claude Skills：

  • 自动扫描 GitHub 仓库中的 Skills
  • 一键安装到 ~/.claude/skills/ 目录
  • 支持递归扫描嵌套目录

功能四：System Prompts 管理

为不同场景创建系统提示词预设：

  • 无限数量的提示词预设
  • 支持 CLAUDE.md、AGENTS.md、GEMINI.md
  • 快速切换不同工作模式

功能五：本地 API 代理 (v3.9.0+)

CC-Switch 内置本地代理服务器，提供高级功能：

功能说明
请求拦截自动将 CLI 请求转发到配置的 Provider
自动故障转移当前 Provider 不可用时自动切换备用
请求日志记录所有 API 请求，便于调试
用量统计追踪 Token 消耗和成本
熔断保护检测 Provider 故障，自动隔离

CC-Switch 安装指南

CC-Switch 支持 Windows、macOS、Linux 三大平台，提供多种安装方式。

Windows 安装

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

从 GitHub Releases 下载 .msi 文件，双击安装即可。

方式二：便携版

下载 .zip 便携版，解压后直接运行，无需安装。

macOS 安装

方式一：Homebrew（推荐）

brew install --cask cc-switch

方式二：手动安装

下载 .dmg 或 .zip 文件，拖入 Applications 文件夹。

注意：首次启动可能遇到 Gatekeeper 警告，需要在「系统偏好设置 → 安全性与隐私」中允许运行。

Linux 安装

CC-Switch 为 Linux 提供多种包格式：

发行版安装方式
Ubuntu/Debian下载 .deb 包，sudo dpkg -i cc-switch.deb
Fedora/RHEL下载 .rpm 包，sudo rpm -i cc-switch.rpm
Arch Linuxparu -S cc-switch-bin
通用下载 AppImage，添加执行权限后运行

验证安装

安装完成后，启动 CC-Switch，你应该看到主界面显示已检测到的 CLI 工具状态。

CC-Switch 快速上手配置

第一步：添加 大模型API供应商 Provider

  1. 点击主界面的「Add Provider」按钮
  2. 选择「Custom」自定义配置
  3. 填写以下信息：
    • 名称：OpenRouter # 此处填写自定义名称
    • Base URL
    • API Key：sk-your-apiyi-key # 从 大模型API供应商获得
  4. 配置模型映射（可选）：
{
  "claude-sonnet-4-20250514": "claude-sonnet-4-20250514",
  "claude-opus-4-20250514": "claude-opus-4-20250514",
  "gpt-4o": "gpt-4o"
}
  1. 点击「Save」保存配置

第二步：切换 Provider

配置保存后，在主界面的 Provider 列表中：

  1. 找到刚添加的「OpenRouter」Provider
  2. 点击「Switch」或直接点击该 Provider
  3. CC-Switch 会自动修改对应工具的配置文件
  4. 重启 Claude Code 等 CLI 工具使配置生效

第三步：测试连接

使用 CC-Switch 的速度测试功能验证配置：

  1. 点击 Provider 旁边的「Test」按钮
  2. 等待延迟测试完成
  3. 查看响应时间和状态指示

测试通过后，打开终端运行 Claude Code：

claude

如果能正常对话，说明配置成功。

CC-Switch 进阶功能

多 Provider 管理策略

CC-Switch 支持配置多个 Provider，实现灵活的使用策略：

┌─────────────────────────────────────────────────┐
│              CC-Switch Provider 列表              │
├─────────────────────────────────────────────────┤
│  📦 OpenRouter (备用)   延迟: 280ms   ✓ 健康    │
│  🏢 官方 Claude (保底)  延迟: 350ms   ✓ 健康    │
└─────────────────────────────────────────────────┘

推荐配置：

  • 备用：OpenRouter – 模型丰富，海外稳定
  • 保底：官方登录 – 确保始终可用

云同步配置

CC-Switch 支持将配置同步到云存储：

  1. 打开 Settings → Storage
  2. 选择云同步文件夹 (Dropbox、OneDrive、iCloud Drive)
  3. CC-Switch 会自动同步 Provider 配置

这样你可以在多台设备间共享相同的 API 配置。

本地代理高级配置

启用本地代理后，CC-Switch 会：

  1. 在本地启动代理服务器
  2. 自动修改 CLI 配置指向本地代理
  3. 代理服务器转发请求到实际 Provider

优势：

  • 所有请求经过统一入口，便于监控
  • 自动故障转移，Provider 挂了自动切换
  • 请求日志记录，方便排查问题

Claude Rectifier 功能

v3.10.0 新增的 Claude Rectifier 功能，用于修复第三方 API 的兼容性问题：

  • 自动修复 thinking signature 格式
  • 提高与非官方 API 的兼容性
  • 减少「格式错误」类报错

CC-Switch 常见问题

Q1：CC-Switch 支持哪些操作系统？

CC-Switch 支持以下平台：

  • Windows 10 及以上
  • macOS 10.15 (Catalina) 及以上
  • Linux：Ubuntu 22.04+、Debian 11+、Fedora 34+、Arch Linux

技术栈：Tauri 2.8 + Rust (后端) + React 18 + TypeScript (前端)

Q2：切换 Provider 后 Claude Code 没生效？

CC-Switch 修改配置文件后，需要重启 CLI 工具才能生效：

# 方法一：关闭当前终端，重新打开
# 方法二：在 Claude Code 中输入 /exit 退出后重新启动
claude  # 重新启动

如果仍不生效，检查：

  • CC-Switch 中 Provider 状态是否为「Active」
  • API Key 是否正确填写
  • 使用 CC-Switch 的测试功能验证连接

Q3：如何恢复官方 Claude 登录？

CC-Switch 提供一键恢复功能：

  1. 在 Provider 列表中找到「Official Login」预设
  2. 点击切换到官方模式
  3. CC-Switch 会自动恢复原始配置

或者使用命令行：

# 删除自定义配置，恢复官方
rm ~/.claude/settings.json
claude  # 重新登录官方账号

Q4：CC-Switch 的配置存储在哪里？

CC-Switch v3.8.0+ 采用 SQLite + JSON 双层存储：

数据类型存储位置
Provider/MCP/Skills~/.cc-switch/cc-switch.db (SQLite)
设备设置~/.cc-switch/settings.json (JSON)
备份文件~/.cc-switch/backups/ (自动保留最近 10 个)

CC-Switch vs 手动配置对比

alt text

对比维度CC-Switch手动编辑配置文件
学习成本低，可视化操作高，需了解配置格式
切换效率一键切换需编辑文件+重启
多工具支持统一管理 4 款工具每个工具单独配置
备份恢复自动备份，一键恢复手动备份
速度测试内置测速功能无
故障转移自动切换备用 Provider无
配置同步支持云同步手动同步
适合人群新手+进阶用户熟悉命令行的用户

🎯 选择建议：如果你经常需要在多个 API Provider 间切换，或者同时使用多款 AI 编程工具，CC-Switch 能大幅提升效率。

CC-Switch 相关工具对比

除了 CC-Switch，还有一些类似工具：

工具类型特点适用场景
CC-Switch桌面应用全功能，支持 4 款 CLI需要完整管理功能
CC-Switch-CLI命令行CC-Switch 的 CLI 版本偏好命令行操作
Claude-Code-Router代理服务动态路由，多模型协作复杂路由需求
CCS混合工具OAuth 支持，可视化面板需要 OAuth 登录

参考资料

资料链接说明
CC-Switch GitHubgithub.com/farion1231/cc-switch源码和 Issue
CC-Switch Releasesgithub.com/farion1231/cc-switch/releases下载最新版本
CC-Switch-CLIgithub.com/SaladDay/cc-switch-cli命令行版本

总结

CC-Switch 是管理 AI 编程助手配置的利器，它解决了以下痛点：

  • 配置繁琐：可视化界面替代手动编辑 JSON
  • 切换麻烦：一键切换多个 Provider
  • 多工具分散：统一管理 Claude Code、Codex、OpenCode、Gemini CLI
  • 无法测速：内置延迟测试，选择最快的 Provider
  • 配置丢失：自动备份+云同步，配置永不丢失
公众号
小红书