CC-Switch使用指南

一直会游泳的小猫2026-03-21 12:15

CC Switch 使用指南

Claude Code、Codex、Gemini CLI、OpenCode 和 OpenClaw 的全方位管理工具

目录

  • [1. 简介](#1. 简介)
  • [2. 安装指南](#2. 安装指南)
  • [3. 环境检查](#3. 环境检查)
  • [4. 快速开始](#4. 快速开始)
  • [5. 各工具详细配置](#5. 各工具详细配置)
  • [6. 供应商管理](#6. 供应商管理)
  • [7. 扩展功能](#7. 扩展功能)
  • [8. 代理与高可用](#8. 代理与高可用)
  • [9. CC-Switch CLI 命令行工具](#9. CC-Switch CLI 命令行工具)
  • [10. 常见问题](#10. 常见问题)

1. 简介

1.1 什么是 CC Switch？

CC Switch 是一款桌面应用程序，用于统一管理五个主流 AI 编程 CLI 工具：

工具 说明
Claude Code Anthropic 官方 AI 编程助手
Codex OpenAI Codex CLI
Gemini CLI Google Gemini 命令行工具
OpenCode 开源代码助手
OpenClaw 开源 AI 编程工具

1.2 为什么需要 CC Switch？

传统的 AI 编程工具配置存在以下痛点：

  • 每个工具使用不同的配置格式（JSON、TOML、.env）
  • 切换 API 供应商需要手动编辑配置文件
  • 缺乏统一的 MCP 和 Skills 管理方式
  • 配置文件容易损坏或丢失

CC Switch 解决方案：

  • 一键导入 50+ 预设供应商
  • 可视化界面管理所有工具配置
  • 统一的 MCP/Prompts/Skills 管理
  • 系统托盘快速切换
  • SQLite 数据库 + 原子写入保护配置

1.3 核心特性

  • 一个应用，五个 CLI 工具 --- 单一界面统一管理
  • 50+ 供应商预设 --- 包括 AWS Bedrock、NVIDIA NIM 和社区中转
  • 通用供应商 --- 一份配置同步到多个应用
  • 系统托盘快速切换 --- 无需打开完整应用
  • 云同步 --- 支持 Dropbox、OneDrive、iCloud、WebDAV
  • 跨平台 --- Windows、macOS、Linux 原生支持
  • 内置 PackyAPI 模板 --- 预设了常用中转服务的配置模板

2. 安装指南

2.1 系统要求

平台 最低版本
Windows Windows 10 及以上
macOS macOS 12 (Monterey) 及以上
Linux Ubuntu 22.04+ / Debian 11+ / Fedora 34+

2.2 Windows 安装

从 Releases 页面下载：

  • CC-Switch-v{版本号}-Windows.msi --- 安装包（推荐）
  • CC-Switch-v{版本号}-Windows-Portable.zip --- 绿色便携版

安装步骤：

  1. 下载 .msi 安装包
  2. 双击运行安装程序
  3. 按照向导完成安装
  4. 启动 CC Switch

2.3 macOS 安装

方式一：Homebrew（推荐）

bash 复制代码 
# 添加 Tap 源
brew tap farion1231/ccswitch

# 安装
brew install --cask cc-switch

# 更新
brew upgrade --cask cc-switch

方式二：手动下载

下载 CC-Switch-v{版本号}-macOS.zip 解压使用。

注意 ：首次打开可能提示"未知开发者"，请前往 系统设置 → 隐私与安全性 → 仍要打开。

2.4 Linux 安装

Arch Linux（推荐）

bash 复制代码 
paru -S cc-switch-bin

Debian/Ubuntu

bash 复制代码 
# 下载 .deb 包
wget https://github.com/farion1231/cc-switch/releases/latest/download/cc-switch_x.x.x_amd64.deb

# 安装
sudo dpkg -i cc-switch_x.x.x_amd64.deb

Fedora/RHEL

bash 复制代码 
sudo rpm -i CC-Switch-v{版本号}-Linux.rpm

Flatpak

bash 复制代码 
flatpak install --user ./CC-Switch-v{版本号}-Linux.flatpak
flatpak run com.ccswitch.desktop

3. 环境检查

重要提示：建议在进行 CC Switch 配置前完成环境检查！

3.1 检查 Node.js 环境

确保已安装 Node.js 18+：

bash 复制代码 
node -v
npm -v

3.2 检查 CLI 工具安装

bash 复制代码 
# 检查 Claude Code
claude --version

# 检查 Codex
codex --version

# 检查 Gemini CLI
gemini --version

3.3 检查配置目录

确保配置目录存在：

工具 配置目录
Claude Code ~/.claude/
Codex ~/.codex/
Gemini CLI ~/.gemini/

如果目录不存在，请先运行一次对应的 CLI 工具，让其自动创建配置目录。

3.4 检查环境变量冲突

检查是否存在冲突的环境变量：

bash 复制代码 
# 检查 Claude 相关环境变量
env | grep -i claude

# 检查 Codex 相关环境变量
env | grep -i codex

# 检查 Gemini 相关环境变量
env | grep -i gemini

如果存在冲突的环境变量，建议在 shell 配置文件（.bashrc、.zshrc）中注释掉或删除相关配置。

4. 快速开始

4.1 首次启动

  1. 启动 CC Switch
  2. 选择要管理的 CLI 工具
  3. 可选择导入现有配置作为默认供应商

4.2 基本使用流程

复制代码 
添加供应商 → 切换供应商 → 重启终端 → 开始使用
步骤 1：添加供应商
  1. 点击 "添加供应商" 按钮
  2. 选择预设供应商或创建自定义配置
  3. 填写 API Key 和相关配置
  4. 保存
步骤 2：切换供应商

主界面切换：

  • 选择供应商 → 点击 "启用"

系统托盘切换：

  • 点击托盘图标 → 直接点击供应商名称（立即生效）
步骤 3：生效
工具 是否需要重启
Claude Code 无需重启，支持热切换
Codex 需要重启终端
Gemini CLI 需要重启终端
OpenCode 需要重启终端
OpenClaw 需要重启终端

4.3 重要设置

首次使用 Claude Code 请务必勾选：

  1. 点击左上角 "设置" 按钮
  2. 在通用页面下拉找到 "跳过 Claude Code 初次安装确认"
  3. 勾选此选项

4.4 恢复官方登录

  1. 在预设中添加 "官方登录" 供应商
  2. 切换到该供应商
  3. 重启 CLI 工具
  4. 按照登录/OAuth 流程操作

5. 各工具详细配置

5.1 Claude Code 配置

步骤 1：选择分组
  1. 打开 CC Switch 软件
  2. 在分组条中选择 "Claude"
步骤 2：添加供应商
  1. 在供应商分组中选择 "PackyCode"（或其他预设）
  2. 填入 API Key
  3. 点击 "添加" 按钮
步骤 3：启用配置
  1. 在主界面找到刚配置的供应商
  2. 点击右侧 "启用" 按钮
  3. 显示 "使用中" 表示配置成功
步骤 4：验证

在终端运行：

bash 复制代码 
claude

看到对话界面并能正常回复即表示配置完成。

5.2 Codex 配置

步骤 1：选择分组
  1. 打开 CC Switch 软件
  2. 在分组条中选择 "Codex"
步骤 2：添加供应商
  1. 在供应商分组中选择 "PackyCode"（或其他预设）
  2. 填入 API Key

Codex 包月用户注意：

  • 从 包月 Codex 控制台 获取 API Key
  • API 请求地址 需要更换为 https://codex-api.packycode.com/v1
  1. 点击 "添加" 按钮
步骤 3：启用配置
  1. 在主界面找到刚配置的供应商
  2. 点击右侧 "启用" 按钮
  3. 重启终端
步骤 4：验证

在终端运行：

bash 复制代码 
codex

看到对话界面并能正常回复即表示配置完成。

5.3 Gemini CLI 配置

步骤 1：选择分组
  1. 打开 CC Switch 软件
  2. 在分组条中选择 "Gemini"
步骤 2：添加供应商
  1. 在供应商分组中选择 "PackyCode"（或其他预设）
  2. 填入 API Key
  3. 点击 "添加" 按钮
步骤 3：启用配置
  1. 在主界面找到刚配置的供应商
  2. 点击右侧 "启用" 按钮
  3. 重启终端
步骤 4：验证

在终端运行：

bash 复制代码 
gemini

看到对话界面并能正常回复即表示配置完成。

6. 供应商管理

6.1 添加供应商

使用预设（推荐）

CC Switch 内置 50+ 供应商预设：

  1. 点击 "添加供应商"
  2. 选择 "从预设创建"
  3. 选择供应商类型（如 PackyCode、AICodeMirror 等）
  4. 粘贴 API Key
  5. 保存
自定义配置
  1. 点击 "添加供应商"
  2. 选择 "自定义配置"
  3. 填写以下信息：
    • 供应商名称
    • API 端点地址
    • API Key
    • 其他配置项
通用供应商

通用供应商可以将一份配置同步到多个应用：

  • 适用于 OpenCode 和 OpenClaw
  • 一次配置，多处生效

6.2 编辑供应商

  1. 点击供应商卡片的 "编辑" 按钮
  2. 修改配置项
  3. 保存

通用配置面板：

  • 从当前供应商提取 --- 将插件等通用数据提取到共享配置
  • 写入通用配置 --- 新建供应商时自动写入插件数据

6.3 排序与复制

  • 拖拽排序 --- 在列表中拖拽调整供应商顺序
  • 复制供应商 --- 快速创建相似配置
  • 删除供应商 --- 当前激活的供应商无法删除

6.4 用量查询

  • 查看账户余额
  • 追踪请求数和 Token 用量
  • 趋势图表分析
  • 自定义模型定价

7. 扩展功能

7.1 MCP 服务器管理

MCP (Model Context Protocol) 用于扩展 AI 工具的能力。

添加 MCP 服务器
  1. 点击 "MCP" 按钮
  2. 选择 "添加服务器"
  3. 选择模板或自定义配置
  4. 切换各应用的同步开关
配置示例
json 复制代码 
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

支持通过 URL 快速导入 MCP 配置：

复制代码 
ccswitch://mcp?config=...

7.2 Prompts 管理

管理各工具的提示词文件：

工具 文件
Claude Code CLAUDE.md
Codex AGENTS.md
Gemini CLI GEMINI.md
使用方法
  1. 点击 "Prompts" 按钮
  2. 使用 Markdown 编辑器创建预设
  3. 激活后自动同步到对应文件
  4. 支持智能回填保护

7.3 Skills 管理

Skills 是可复用的功能模块。

安装 Skills
  1. 点击 "Skills" 按钮
  2. 浏览 GitHub 仓库
  3. 一键安装到全部应用
  4. 支持从 ZIP 文件安装
管理
  • 查看已安装的 Skills
  • 卸载不需要的 Skills
  • 自定义仓库管理
  • 支持软链接和文件复制模式

8. 代理与高可用

8.1 本地代理服务

CC Switch 提供本地代理模式，支持：

  • 格式转换 --- 自动转换不同 API 格式
  • 热切换 --- 无需重启即可切换供应商
  • 熔断器 --- 自动熔断异常供应商
  • 健康监控 --- 实时监控供应商状态
启动代理
  1. 进入 "代理" 面板
  2. 配置代理端口
  3. 点击 "启动服务"
  4. 将 CLI 工具的 API 端点设置为代理地址

8.2 应用级接管

独立为各个应用配置代理：

  • Claude Code 代理
  • Codex 代理
  • Gemini CLI 代理

可具体到单个供应商级别。

8.3 故障转移

配置故障转移队列：

  1. 设置供应商优先级
  2. 配置故障转移规则
  3. 启用自动故障转移
  4. 监控健康状态

8.4 用量统计

  • 跨供应商追踪支出
  • 请求数和 Token 统计
  • 趋势图表
  • 详细请求日志
  • 自定义模型定价

9. CC-Switch CLI 命令行工具

推荐在服务器环境或 macOS 系统下使用 CC-Switch CLI

CC-Switch CLI 是 CC Switch 的命令行版本，使用 Rust 编写，适合无图形界面的服务器环境。

9.1 下载与安装

macOS
bash 复制代码 
# 下载 Universal Binary（推荐，支持 Apple Silicon + Intel）
curl -LO https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-darwin-universal.tar.gz

# 解压
tar -xzf cc-switch-cli-darwin-universal.tar.gz

# 添加执行权限
chmod +x cc-switch

# 移动到 PATH
sudo mv cc-switch /usr/local/bin/

# 如遇 "无法验证开发者" 提示
xattr -cr /usr/local/bin/cc-switch
Linux (x64)
bash 复制代码 
# 下载
curl -LO https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-linux-x64-musl.tar.gz

# 解压
tar -xzf cc-switch-cli-linux-x64-musl.tar.gz

# 添加执行权限
chmod +x cc-switch

# 移动到 PATH
sudo mv cc-switch /usr/local/bin/
Linux (ARM64)
bash 复制代码 
# 适用于树莓派或 ARM 服务器
curl -LO https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-linux-arm64-musl.tar.gz
tar -xzf cc-switch-cli-linux-arm64-musl.tar.gz
chmod +x cc-switch
sudo mv cc-switch /usr/local/bin/
Windows
powershell 复制代码 
# 下载 zip 文件
# https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-windows-x64.zip

# 解压后将 cc-switch.exe 移动到 PATH 目录
move cc-switch.exe C:\Windows\System32\

# 或者直接运行
.\cc-switch.exe

9.2 命令列表

常用命令
bash 复制代码 
cc-switch provider list              # 列出供应商
cc-switch provider switch <id>       # 切换供应商
cc-switch mcp sync                   # 同步 MCP 服务器

# 使用全局 `--app` 参数来指定目标应用
cc-switch --app claude provider list    # 管理 Claude 供应商
cc-switch --app codex mcp sync          # 同步 Codex MCP 服务器
cc-switch --app gemini prompts list     # 列出 Gemini 提示词

# 支持的应用：`claude`（默认）、`codex`、`gemini`
供应商管理
bash 复制代码 
cc-switch provider list              # 列出所有供应商
cc-switch provider current           # 显示当前供应商
cc-switch provider switch <id>       # 切换供应商
cc-switch provider add               # 添加新供应商
cc-switch provider edit <id>         # 编辑现有供应商
cc-switch provider duplicate <id>    # 复制供应商
cc-switch provider delete <id>       # 删除供应商
cc-switch provider speedtest <id>    # 测试 API 延迟
MCP 服务器管理
bash 复制代码 
cc-switch mcp list                   # 列出所有 MCP 服务器
cc-switch mcp add                    # 添加新 MCP 服务器（交互式）
cc-switch mcp edit <id>              # 编辑 MCP 服务器
cc-switch mcp delete <id>            # 删除 MCP 服务器
cc-switch mcp enable <id> --app claude   # 为特定应用启用
cc-switch mcp disable <id> --app claude  # 为特定应用禁用
cc-switch mcp validate <command>     # 验证命令在 PATH 中
cc-switch mcp sync                   # 同步到实时文件
cc-switch mcp import --app claude    # 从实时配置导入
Prompts 管理
bash 复制代码 
cc-switch prompts list               # 列出提示词预设
cc-switch prompts current            # 显示当前活动提示词
cc-switch prompts activate <id>      # 激活提示词
cc-switch prompts deactivate         # 停用当前激活的提示词
cc-switch prompts create             # 创建新提示词预设
cc-switch prompts edit <id>          # 编辑提示词预设
cc-switch prompts show <id>          # 显示完整内容
cc-switch prompts delete <id>        # 删除提示词
Skills 管理
bash 复制代码 
cc-switch skills list                # 列出已安装技能
cc-switch skills search <query>      # 搜索可用技能
cc-switch skills install <name>      # 安装技能
cc-switch skills uninstall <name>    # 卸载技能
cc-switch skills enable <name>       # 为当前应用启用
cc-switch skills disable <name>      # 为当前应用禁用
cc-switch skills info <name>         # 显示技能信息
cc-switch skills sync                # 同步已启用技能到应用目录
cc-switch skills sync-method [m]     # 查看/设置同步方式
cc-switch skills scan-unmanaged      # 扫描未管理技能
cc-switch skills import-from-apps    # 导入未管理技能

# 仓库管理
cc-switch skills repos list          # 查看仓库列表
cc-switch skills repos add <repo>    # 添加仓库
cc-switch skills repos remove <repo> # 移除仓库
配置管理
bash 复制代码 
cc-switch config show                # 显示配置
cc-switch config path                # 显示配置文件路径
cc-switch config validate            # 验证配置文件

# 通用配置片段
cc-switch --app claude config common show
cc-switch --app claude config common set --json '{"env":{...}}' --apply
cc-switch --app claude config common clear --apply

# 备份
cc-switch config backup              # 创建备份
cc-switch config backup --name my-backup  # 自定义名称备份

# 恢复
cc-switch config restore             # 交互式选择恢复
cc-switch config restore --backup <id>    # 通过 ID 恢复
cc-switch config restore --file <path>    # 从外部文件恢复

# 导入/导出
cc-switch config export <path>       # 导出
cc-switch config import <path>       # 导入

cc-switch config reset               # 重置为默认配置

9.3 CC-Switch CLI 配置 PackyAPI

进入 TUI 界面
bash 复制代码 
cc-switch
添加供应商
  1. 在左侧选择 Providers，回车选中
  2. 按 a 键，进入供应商添加页面
  3. 在上方模板中选择 PackyCode
  4. 在 Api Key 处填写你的 API Key，回车
  5. 按 Ctrl+S 保存
  6. 确保选中的是刚配置的 Provider
  7. 退出 CC Switch CLI

10. 常见问题

10.1 配置文件位置

数据类型 路径
数据库 ~/.cc-switch/cc-switch.db
本地设置 ~/.cc-switch/settings.json
备份 ~/.cc-switch/backups/
Skills ~/.cc-switch/skills/
Skills 备份 ~/.cc-switch/skill-backups/

10.2 切换供应商后插件配置丢失？

CC Switch 使用 "通用配置片段" 功能保留插件数据：

  1. 进入 "编辑供应商" → "通用配置面板"
  2. 点击 "从当前供应商提取"
  3. 新建供应商时勾选 "写入通用配置"（默认勾选）

10.3 macOS 提示"未知开发者"？

  1. 关闭警告弹窗
  2. 前往 系统设置 → 隐私与安全性
  3. 点击 "仍要打开"
  4. 之后可正常打开

10.4 为什么无法删除当前供应商？

CC Switch 遵循 "最小侵入性" 设计原则：

  • 系统始终保留一个激活配置
  • 确保卸载软件后 CLI 工具仍能正常工作
  • 不常用的工具可在设置中隐藏

10.5 如何切换回官方登录？

  1. 在预设中添加 "官方登录" 供应商
  2. 切换到该供应商
  3. 重启 CLI 工具
  4. 执行登录/OAuth 流程
  5. 之后可自由切换官方和第三方供应商

10.6 环境变量冲突

如果系统环境变量与 CC Switch 配置冲突：

  1. 检查 .env 文件
  2. 检查 shell 配置文件（.bashrc, .zshrc）
  3. 使用 CC Switch 的环境变量管理功能

CC Switch 支持 ccswitch:// 协议快速导入配置：

11.1 导入供应商

复制代码 
ccswitch://provider?name=xxx&api_key=xxx&base_url=xxx

11.2 导入 MCP 服务器

复制代码 
ccswitch://mcp?config=...

11.3 导入 Prompts

复制代码 
ccswitch://prompt?content=...

11.4 导入 Skills

复制代码 
ccswitch://skill?url=...

12. 设置与个性化

12.1 外观设置

  • 主题：深色 / 浅色 / 跟随系统
  • 语言：中文 / English / 日本語

12.2 功能设置

  • 开机自启：系统启动时自动运行
  • 自动更新：自动检查并安装更新
  • 自动备份：定期备份配置

12.3 云同步

支持多种云同步方式：

方式 说明
Dropbox 同步到 Dropbox 目录
OneDrive 同步到 OneDrive 目录
iCloud 同步到 iCloud 目录
WebDAV 自定义 WebDAV 服务器

13. 推荐供应商

以下是 CC Switch 用户常用的 API 中转服务：

服务商 特点 优惠
PackyCode 多模型中转 首充 9 折
AICodeMirror 企业级稳定 首充 8 折
SiliconFlow 多模态支持 ¥20 奖励金
AIGoCode 国内直连 首充 10% 奖励
DMXAPI 全球大模型 6.8 折
RightCode 额度转结 25% 按量额度

版本信息

  • 文档版本：v3.12.3
  • 最后更新：2026-03-20
  • 适用版本：CC Switch v3.12.0+

相关链接

相关推荐
weixin_449290012 小时前
端到端智能对话系统架构文档
ai
夏白分享社2 小时前
OpenClaw 本地模型终极实战：vLLM 部署优化完整教程！
ai·开源软件·openclaw
鸡吃丸子2 小时前
如何编写一个高质量的AI Skill
前端·ai
夏星印2 小时前
学习吴恩达课程机器学习笔记
人工智能·笔记·学习·机器学习·ai
智算菩萨3 小时前
AGI神话：人工通用智能的幻象如何扭曲与分散数字治理的注意力
论文阅读·人工智能·深度学习·ai·agi
MadPrinter3 小时前
Attention Residuals 代码实现：从原理到 PyTorch 实战（第 2 篇）
人工智能·pytorch·python·ai·自动化·openclaw
supersolon3 小时前
OpenClaw的引导配置（onboard）流程
ai·ai助理·openclaw·龙虾·onboard
Agent产品评测局4 小时前
中国龙虾ai软件有哪些选择？2026自动化选型指南
运维·人工智能·ai·chatgpt·自动化
前端摸鱼匠4 小时前
面试题3：自注意力机制（Self-Attention）的计算流程是什么？
人工智能·ai·面试·职场和发展
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03Labelme从安装到标注：零基础完整指南04OpenClaw 使用和管理 MCP 完全指南05小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）06AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南07UV安装并设置国内源08OpenClaw Control UI安全上下文访问配置09班级宠物园部署指南10Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services