CC Switch配置Claude&Codex完整教程

CC Switch 配置Claude & Codex完整教程

CC Switch 是一款强大的跨平台图形化配置管理工具，支持一键切换并管理 Claude Code CLI、Claude Desktop 桌面端、Codex CLI 以及 Codex 客户端/App 等多款 AI 编程工具的 API 供应商（如原生官方、DeepSeek、QCode、SiliconFlow 等）、Base URL、Token 与模型映射。

1. 准备工作

1.1 官方渠道与系统要求

⚠️ 安全提示
请只从 ccswitch.io、GitHub Releases 或项目官方源码仓库获取 CC Switch。任何要求付费、充值或索取登录凭据的“CC Switch”网站或客户端都不是官方渠道。

系统 最低版本要求 支持架构
Windows Windows 10 及以上 x64 / ARM64
macOS macOS 12 (Monterey) 及以上 Intel (x64) / Apple Silicon (arm64)
Linux glibc 2.35+ 和 WebKitGTK 4.1 x64 / ARM64

注：安装包可以从官网的下载页或 GitHub Releases 获取，两处文件完全相同。

1.2 可选：安装要管理的工具

CC Switch 本身不需要 Node.js 或其他运行环境。它管理的是你已经安装的 Claude Code、Codex 等工具；若尚未安装，可以先装好 CC Switch，再用以下任一方式安装工具：

方式一：在 CC Switch 内一键安装（推荐）

打开 「设置 → 关于」，工具列表会显示每个工具的当前版本和最新版本：

  • 未安装的工具旁提供 安装 按钮。
  • 已安装的工具可以单独升级或选择 「全部升级」。
  • 支持工具：Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi。（详见 1.5 个性化配置 → 关于页面）

方式二：按各工具官方方式安装

工具 安装命令（macOS / Linux）
Claude Code curl -fsSL https://claude.ai/install.sh | bash 或 npm i -g @anthropic-ai/claude-code
Codex npm i -g @openai/codex 或 brew install --cask codex
Gemini CLI npm i -g @google/gemini-cli
Grok Build curl -fsSL https://x.ai/cli/install.sh | bash 或 npm i -g @xai-official/grok
OpenCode curl -fsSL https://opencode.ai/install | bash 或 npm i -g opencode-ai
OpenClaw npm i -g openclaw
Hermes curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Pi npm i -g @earendil-works/pi-coding-agent

ℹ️ 说明

  • Claude Desktop、MiniMax Code 以及 Windows 上的安装方式，请参考各工具的官方文档。
  • 用 npm 安装需要先装好 Node.js。各工具要求的版本不同（例如 Claude Code 需要 22 及以上，OpenClaw 需要 24.16+ 或 26.1+），建议安装当前的 LTS 版本；版本不满足时 npm 会给出提示。

💡 镜像加速提示
国内用户如果 npm 下载较慢，可以在命令后加上 --registry=https://registry.npmmirror.com，或全局设置镜像源：

1
npm config set registry https://registry.npmmirror.com

镜像同步偶尔可能会有滞后，若安装到的版本比官方旧，可临时改回官方源：https://registry.npmjs.org。

1.3 CC Switch 安装指南

💻 Windows

1. 安装包方式
  1. 在下载页或 Releases 页面下载 CC-Switch-v{版本号}-Windows.msi（ARM 版 Windows 请下载 CC-Switch-v{版本号}-Windows-arm64.msi）。
  2. 双击运行安装程序。
  3. 按界面提示完成安装。

📌 常见问题：运行安装程序后如果没有任何反应，可右键点击该文件选 属性，在 常规 标签页底部勾选 解除锁定 即可。

2. 绿色版（免安装）
  1. 下载 CC-Switch-v{版本号}-Windows-Portable.zip（ARM 版为 CC-Switch-v{版本号}-Windows-arm64-Portable.zip）。
  2. 解压到任意目录。
  3. 直接运行 CC-Switch.exe。

🍎 macOS

方式一：Homebrew 安装（推荐）
1
2
3
4
5
# 安装
brew install --cask cc-switch

# 更新到最新版本
brew upgrade --cask cc-switch
方式二：手动下载安装
  1. 下载 CC-Switch-v{版本号}-macOS.dmg（推荐）或 CC-Switch-v{版本号}-macOS.zip。（此为 Universal 通用包，Apple Silicon 和 Intel Mac 均可原生运行）
  2. 打开 DMG，或解压 zip 获得 CC Switch.app。
  3. 将图标拖动到 「应用程序 (Applications)」 文件夹。

🛡️ 安全认证：CC Switch macOS 版本已通过 Apple 代码签名和公证，安装后可直接打开，无需额外信任设置。

🐧 Linux

⚠️ 系统要求：CC Switch Linux 版需要 glibc 2.35+ 和 WebKitGTK 4.1（例如 Ubuntu 22.04+、Debian 12+ 及较新的 Fedora）。RHEL / Rocky / Alma 8–9 的系统库版本不够，暂不支持。

Arch Linux

使用 AUR 助手进行安装：

1
2
3
4
5
# 使用 paru
paru -S cc-switch-bin

# 或使用 yay
yay -S cc-switch-bin
Debian / Ubuntu
  1. 根据架构下载 CC-Switch-v{版本号}-Linux-x86_64.deb 或 CC-Switch-v{版本号}-Linux-arm64.deb。
  2. 执行安装命令：
    1
    2
    3
    4
    sudo dpkg -i CC-Switch-v{版本号}-Linux-*.deb

    # 如果遇到依赖问题，运行以下命令修复：
    sudo apt-get install -f
Fedora 等 RPM 发行版
  1. 根据架构下载 CC-Switch-v{版本号}-Linux-x86_64.rpm 或 CC-Switch-v{版本号}-Linux-arm64.rpm。
  2. 执行安装命令：
    1
    sudo dnf install ./CC-Switch-v{版本号}-Linux-*.rpm
AppImage

适用于满足系统要求但没有对应安装包的发行版：

  1. 下载对应的 CC-Switch-v{版本号}-Linux-x86_64.AppImage 或 CC-Switch-v{版本号}-Linux-arm64.AppImage。
  2. 添加执行权限并运行：
    1
    2
    chmod +x CC-Switch-v{版本号}-Linux-*.AppImage
    ./CC-Switch-v{版本号}-Linux-*.AppImage
Flatpak

官方 Release 暂不包含 Flatpak 包。如需使用，可以从 .deb 自行构建，详见仓库中的 flatpak/README.md。

1.4 验证安装

安装完成后启动 CC Switch，确认以下事项：

  • 应用窗口正常显示。
  • 系统托盘区域出现 CC Switch 图标。
  • 在应用切换器中能看到已启用的受管应用，并能流畅切换到目标应用面板。

1.5 自动更新

CC Switch 内置自动更新功能：

  1. 自动检查：启动时会自动检查是否有新版本。
  2. 更新提示：存在新版本时会在界面弹出提示。
  3. 一键升级：点击提示即可自动下载并完成安装。

注：您也可以随时在 「设置 → 关于」 中手动检查更新。

1.6 卸载说明

  • Windows：
    • 通过 「设置 → 应用 → 安装的应用」 进行卸载。
    • 或运行安装目录下的卸载程序。
  • macOS：
    • Homebrew 安装：执行 brew uninstall --cask cc-switch（若要清除配置数据请加上 --zap 参数）。
    • 手动安装：直接将 CC Switch.app 移入废纸篓。
    • 可选：彻底清理配置目录可以删除 ~/.cc-switch/。
  • Linux：
    1
    2
    3
    4
    5
    6
    7
    8
    # Debian / Ubuntu
    sudo apt remove cc-switch

    # Fedora 等 RPM 发行版
    sudo dnf remove cc-switch

    # Arch Linux
    paru -R cc-switch-bin
  1. 准备 API 凭证：
    • 准备好你想接入的 API 供应商的 API Key 和对应的 Base URL。
    • 协议区分：
      • Claude 生态（Claude Code / Desktop）：通常使用 Anthropic 协议端点（例如 https://api.qcode.cc/api 或 https://api.anthropic.com）。
      • Codex 生态（Codex CLI / App）：通常使用 OpenAI 协议端点（例如 https://api.qcode.cc/openai 或 https://api.openai.com/v1）。

2. 配置 Claude 体系 (Claude Code CLI 与 Desktop)

2.1 配置 Claude Code CLI

CCSwitch 会将配置直接写入全局配置文件 ~/.claude/settings.json。

  1. 添加供应商：
    在本站API密钥页面，直接点击“导入CCS”按钮，即可自动帮你完成配置，无需手动设置。

  2. 启用配置：

    • 保存后，在供应商卡片上点击 「启用」 (使用)。

  3. 终端验证：

    • 打开新的命令行终端，运行：
      1
      claude
    • 首次启动若提示登录可按 Esc 跳过网页授权。

2.2 配置 Claude Desktop 桌面客户端

Claude Desktop 需要配合 CCSwitch 的 本地代理 (Local Proxy) 与 第三方网关 (3P Gateway) 使用。

  1. 开启 CCSwitch 本地代理与模型映射：
    • 在 CCSwitch 中切换至 Claude Desktop 面板，开启 本地路由 开关。
    • image
    • 配置模型映射：Claude Desktop 仅识别官方模型名称，如果使用第三方非原生模型（如 Kimi、DeepSeek 等），需在供应商设置中勾选 “需要模型映射”，将目标模型映射为 Sonnet 或 Opus 角色。
  2. 配置 Claude Desktop 客户端 Gateway：
    • 打开 Claude Desktop -> 点击左上角汉堡菜单 -> Help -> Troubleshooting -> Enable Developer mode。
    • 再次点击菜单 -> Developer -> Configure third-party inference。
    • Connection 标签选 Gateway。
    • Gateway base URL：填入本地代理地址（如 http://127.0.0.1:15721）。
    • Gateway API key：固定填写 PROXY_MANAGED（必须严格一致）。
    • Gateway auth scheme：填写 bearer。
  3. 重启验证：完全退出 Claude Desktop（从系统托盘右键退出）后重新启动。

3. 配置 Codex 体系 (Codex CLI 与 Desktop 客户端)

Codex 是基于 OpenAI 协议的终端助手与桌面客户端，CCSwitch 会将配置自动写入全局配置文件 ~/.codex/config.toml 中。

3.1 配置 Codex CLI

  1. 添加 Codex 供应商：
    在本站API密钥页面，直接点击“导入CCS”按钮，即可自动帮你完成配置，无需手动设置。
    • 注意：界面上的 「需要本地路由映射」 开关只在目标上游仅支持旧版 Chat Completions、需要本地代理转换为 Responses 协议时开启。若接入的服务已原生支持 OpenAI/Responses 协议（如 QCode、OpenAI 原生或专业网关），请保持关闭。
  2. 启用配置：
    • 保存配置后，点击对应供应商卡片上的 「启用」 (Use) 按钮。
  3. 终端验证：
    • 打开新的终端，输入并运行：
      1
      codex
    • 在终端中发送命令或问题测试请求是否正常返回。

3.2 配置 Codex Desktop 客户端 / Codex App

  1. 配置文件共享机制：
    • Codex 桌面客户端 (Codex App) 默认直接读取 ~/.codex/config.toml 或当前环境变量。
  2. 配置生效步骤：
    • 在 CCSwitch 中选择并启用所需的 Codex 供应商。
    • 启动或重启 Codex App（运行 codex app 或从系统程序菜单中打开）。
    • App 会自动使用当前的全局配置进行 API 请求。

4. 版本检查与升级指南

为了保持功能兼容性并修复已知 Bug，建议定期检查并升级各项 CLI 及客户端工具。

4.1 Claude 体系检查与升级

工具 / 客户端 检查版本方法 升级命令 / 步骤
Claude Code CLI 终端运行：
claude --version		 npm 全局升级：
npm install -g @anthropic-ai/claude-code@latest
或运行内置更新命令：claude update
Claude Desktop 桌面端 点击菜单 -> Help -> About Claude macOS (Homebrew):
brew upgrade --cask claude
通用方式：收到客户端应用内升级提示后确认更新，或前往官网下载最新安装包覆盖

4.2 Codex 体系检查与升级

工具 / 客户端 检查版本方法 升级命令 / 步骤
Codex CLI 终端运行：
codex --version		 npm 全局升级：
npm install -g @openai/codex@latest
macOS (Homebrew):
brew upgrade --cask codex
包管理器更新命令：codex upgrade
Codex Desktop / App 打开 App -> 进入 Settings -> About macOS (Homebrew):
brew upgrade --cask codex
通用方式：在软件设置中检测升级，或前往官方 Releases 重新下载安装包覆盖

4.3 CCSwitch 管理工具升级

安装方式 检查与升级步骤
macOS (Homebrew) 终端运行：brew upgrade --cask cc-switch
安装包安装 (Win/Mac/Linux) 打开 CCSwitch 设置页面点击“检查更新”，或前往 GitHub Release 页面下载最新安装包覆盖安装。

5. 常见问题排查 (FAQ)

  1. 切换供应商后 CLI 依然请求旧服务节点：
    • 已打开的命令行进程不会实时重载配置。请关闭当前终端标签页，重新打开终端再运行 claude 或 codex。
  2. Claude Desktop 提示认证或连接 401 报错：
    • 检查 CCSwitch 的“本地代理”是否保持开启状态。
    • 确认 Claude Desktop 开发者设置中的 Gateway API key 是否严格为 PROXY_MANAGED 字符串。
  3. Codex CLI 启动后卡住或提示 URL 错误：
    • 检查 Base URL 后缀格式（如 OpenAI 规范协议通常以 /openai 或 /v1 结尾）。
    • 若非必要，请确认已关闭 Codex 供应商卡片中的“需要本地路由映射”选项。
  4. 能否同时配置并使用 Claude 与 Codex？：
    • 可以完全并行使用。CCSwitch 分别维护 ~/.claude/settings.json 与 ~/.codex/config.toml，两者互不影响。