CC Switch 安装与使用教程：管理 Claude Code / Codex 中转配置

发布于 2026-05-07

CC Switch 和 cc-switch-cli 安装教程：选择桌面版或命令行版，配置 Claude Code、Codex、Gemini CLI 的 provider、Base URL、API Key 和常用切换命令。

先分清两个版本

搜索 cc switch 安装 时最容易混淆的是：网上同时有人在讲 CC Switch 桌面版 和 cc-switch-cli 命令行版。它们都叫 cc-switch，但适合的场景不一样。

版本	适合谁	入口
CC Switch 桌面版	日常在本机用图形界面管理多个 provider	farion1231/cc-switch Releases
cc-switch-cli	服务器、SSH、自动化脚本、喜欢终端 TUI 的用户	SaladDay/cc-switch-cli Releases

如果你只是想在 macOS / Windows 上点选 provider，先装桌面版。如果你要在远程机器、CI、纯终端环境里管理 Claude Code、Codex、Gemini CLI，就装 cc-switch-cli。

不要把它们当成“中转站本身”。CC Switch 负责管理本地配置，真正能不能跑通，还是取决于服务商的 Base URL、API Key、模型名、协议兼容和流式响应。

桌面版 CC Switch 安装

桌面版适合第一次上手。它可以从 GitHub Releases 下载 Windows、macOS、Linux 安装包。

macOS 如果使用 Homebrew，官方 release 页给出的安装方式是：

brew install --cask cc-switch

更新时使用：

brew upgrade --cask cc-switch

Windows 用户优先选择 .msi 安装包；Linux 用户按发行版选择 .deb、.rpm 或 AppImage。安装完成后再打开应用，新建 provider，填入服务商给你的 Base URL、API Key 和模型名。

cc-switch-cli 安装

命令行版适合服务器、SSH、自动化和终端重度用户。macOS / Linux 可以用官方一键脚本：

curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash

默认会安装到 ~/.local/bin。如果你想改安装目录，可以在执行脚本前设置 CC_SWITCH_INSTALL_DIR。如果终端提示找不到 cc-switch，先检查 PATH：

echo $PATH
ls ~/.local/bin/cc-switch

临时加入 PATH 可以这样做：

export PATH="$HOME/.local/bin:$PATH"

确认能启动：

cc-switch --help
cc-switch

如果你使用 Homebrew，也可以安装 CLI 版本：

brew install cc-switch-cli

注意：桌面版的 Homebrew 包是 --cask cc-switch，CLI 版是 cc-switch-cli。这两个名字很像，装错了就会出现“教程里的命令找不到”这种低级但很耗时间的问题。

配置前准备

先确认你要管理的目标 CLI 已经能启动。不要一上来就把所有配置塞进 CC Switch，否则排障时会分不清是工具问题、服务商问题，还是目标 CLI 自己没安装好。

claude --help
codex --help
gemini --help

如果你使用 cc-switch-cli，可以让它检查本地工具：

cc-switch env tools
cc-switch env check

然后准备好三类信息：

Base URL：服务商给出的 OpenAI / Anthropic 兼容地址，尤其注意是否需要 /v1。
API Key / Token：不同工具可能需要不同分组的令牌，不要把 Claude Code、Codex、Gemini 的 token 混用。
模型名：不要默认以为 claude-sonnet、gpt-5、gemini-pro 这类别名都可用，先按服务商文档填。

用桌面版配置 provider

桌面版的核心步骤是：

打开 CC Switch。
新增 provider，给它一个能识别来源和协议的名字，例如 某某服务商 - Claude。
填入 Base URL、API Key / Token、模型名。
选择这个 provider 作用到 Claude Code、Codex、Gemini CLI 或其他支持的工具。
保存并切换。
重启目标 CLI 或重新打开终端会话。

配置时尤其要看这几个字段：

Provider 名称：给自己看的，建议写清楚服务商和协议。
Base URL：严格按服务商文档填写，尤其注意 /v1。
API Key / Token：区分 OpenAI Key、Anthropic Key 和 Bearer Token。
模型名：不要默认以为某个模型别名一定可用。
作用工具：同一个 provider 可能只适合 Claude Code，不一定适合 Codex。

用 cc-switch-cli 配置和切换

第一次配置可以直接进入 TUI：

cc-switch

如果要直接管理某个应用，用 --app 指定：

cc-switch --app claude
cc-switch --app codex
cc-switch --app gemini

常用命令：

cc-switch provider list
cc-switch provider current
cc-switch provider switch <id>
cc-switch use <id>
cc-switch provider stream-check <id>
cc-switch provider fetch-models <id>
cc-switch env tools
cc-switch env check

管理 Codex 或 Gemini 时：

cc-switch --app codex provider list
cc-switch --app codex provider current
cc-switch --app codex provider switch <id>

cc-switch --app gemini provider list
cc-switch --app gemini provider current

claude 是默认应用，所以不写 --app 时通常是在管理 Claude Code。这个默认值很方便，也很危险：如果你明明想切 Codex，却忘了加 --app codex，你只是在改 Claude Code 的 provider。

切换后没有生效怎么办

按这个顺序排查，不要乱改：

先重启目标 CLI 或重新打开终端。
用 cc-switch provider current 或对应 --app 命令确认当前 provider。
用 cc-switch env check 看是否有环境变量覆盖了工具写入的配置。
临时绕过 CC Switch，手动用 Base URL 和 API Key 跑一次最小配置。
如果手动配置也不通，问题大概率在服务商接口、模型名、token 分组或协议兼容。

常见误判是：切换工具没问题，但当前 shell 里还残留 OPENAI_BASE_URL、OPENAI_API_KEY、ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 等环境变量。环境变量优先级一旦盖过配置文件，你在 CC Switch 里怎么切都像“没生效”。

适合什么场景

CC Switch 值得用在这些场景：

你同时使用 Claude Code、Codex、Gemini CLI、OpenCode 或类似工具。
你经常在官方 API、OpenAI 兼容中转站和本地模型接口之间切换。
你不想每次切换 provider 都手动改 shell 配置、settings.json 或 config.toml。
你需要 MCP、prompts、skills、provider、用量和备份集中管理。

如果你只接一个服务商，而且手动配置已经很稳定，先别急着上管理工具。多一层工具就多一层状态，多一层状态就多一类排障成本。

一个实用原则

CC Switch 负责“管理配置”，不负责“保证接口兼容”。真正决定能不能跑通的，还是服务商是否支持对应 CLI 需要的协议、模型和流式能力。

如果你是为了接中转站，顺序一定是：先手动跑通，再交给 CC Switch 管理。反过来做，就是把一个未知问题包进另一个未知问题里，最后只会得到一团看起来像玄学的配置故障。

CC Switch cc-switch-cli Claude Code Codex Provider