1. CC-Switch 是什么，三端安装前先搞清楚这件事
CC-Switch 是一个开源的模型服务商切换工具，核心作用是帮你在 Claude Code、Codex 这类命令行编码工具里，快速切换不同的 API 服务商和模型映射。它本身不提供模型，也不替代编辑器，只是一个本地运行的配置管理面板。适合谁用？如果你手上有多个 API Key，或者需要在 DeepSeek、智谱 GLM、通义千问之间来回切换，手动改配置文件容易出错，CC-Switch 就是来解决这个问题的。
我在 Windows 和 macOS 上都装过，实测下来最省事的路径是 macOS 走 brew，Windows 走 MSI 安装包，Linux 用 AppImage 或 deb 包。三端的安装逻辑不一样，踩的坑也不一样。这篇文章会把三端的官方下载渠道、可复制的安装命令、brew 源配置片段，以及安装后怎么验证 CC-Switch 是否正常启动，全部拆开讲清楚。
先明确一个前提：CC-Switch 的所有 API 密钥仅本地加密存储，不上传服务器。这一点在你配置服务商的时候可以放心。安装完成后需要彻底重启软件，再进行 API 路由配置，否则路由开关可能不生效。
另外，CC-Switch 的版本更新比较频繁，2026 年 8 月这个时间点，v3.15.x 和 v3.16.x 都在流通。下载时认准 Releases 页面的 Assets 附件区，根据自己的系统选对应文件。不要从来路不明的第三方站点下载，避免拿到被篡改的安装包。
下面按平台拆解。macOS 用户重点看 brew 部分，因为 brew 安装涉及 tap 源配置，报错也集中在这里。Windows 用户注意 MSI 的解除锁定操作。Linux 用户根据发行版选 deb、rpm 或 AppImage。
2. TaoToken 前置准备：Base URL、Key 和 Model ID 三件套
在装 CC-Switch 之前，你需要先准备好要接入的服务商信息。不管你用哪家，本质上都是三件套：Base URL、API Key、Model ID。CC-Switch 的作用就是帮你管理这三件套的切换。
以 TaoToken 为例，它的 API 地址是 https://taotoken.net/api，官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=。你需要在 TaoToken 的控制台创建一个 API Key，然后拿到对应的 Base URL 和 Model ID。
具体操作路径：打开官网，进入控制台，找到 API Keys 页面，创建一个新的 Key。创建完成后复制保存，这个 Key 只会显示一次。然后确认 Base URL，TaoToken 的 API 入口是 https://taotoken.net/api，注意结尾不要多加斜杠。Model ID 根据你要用的模型来定，比如 claude-sonnet-4-20250514 这类。
如果你还没决定用哪个模型，可以先到模型对话页面测试一下，确认模型能正常响应，再回到 CC-Switch 里配置。模型对话的入口在官网导航里能找到。
这里有个关键点：CC-Switch 里配置服务商时，Base URL 的结尾是否需要加 /v1，取决于服务商的要求。TaoToken 的 API 地址是 https://taotoken.net/api，你在 CC-Switch 里填的时候，按照服务商文档的说明来。如果不确定，先不加 /v1，测试不通再加。
准备好三件套之后，再开始装 CC-Switch。顺序不要反，否则装完软件发现没东西可配，还得回头找 Key。
3. 三端可复制安装配置：brew 源、MSI 和 AppImage 全流程
这一节是核心操作部分，按平台给出可复制的命令和配置片段。
3.1 macOS：brew tap 与 cask 安装
macOS 推荐用 brew 安装，后续升级方便。打开终端，依次执行：
brew tap farion1231/ccswitch brew install --cask cc-switch第一行是添加第三方 tap 源，第二行是安装 cask 包。如果你的 brew 没有配置国内镜像，tap 和 install 可能会比较慢，耐心等或者配置镜像源。
升级命令：
brew upgrade --cask cc-switch如果 brew 安装报错Error: Cask 'cc-switch' is unavailable，说明 tap 源没添加成功，重新执行brew tap farion1231/ccswitch，确认没有报错再 install。
如果报错Error: Failure while executing; git clone ...，通常是网络问题导致 tap 源拉取失败。可以尝试brew update后重试，或者检查 brew 的 git 配置。
安装完成后，CC-Switch 会出现在「应用程序」文件夹里。首次打开如果提示「无法验证开发者」，去系统设置 → 隐私与安全性 → 下拉找到「仍要打开」，点击放行。
3.2 Windows：MSI 安装与解除锁定
Windows 用户从 Releases 页面下载CC-Switch-v3.15.0-Windows.msi。如果双击 MSI 没反应，右键文件 → 属性 → 常规 → 勾选「解除锁定」再安装。这是 Windows 对下载文件的保护机制，不解除锁定安装程序可能被拦截。
绿色便携版是CC-Switch-v3.15.0-Windows-Portable.zip，解压路径必须纯英文，不能带中文或空格，否则可能启动失败。
安装完成后，在开始菜单找到 CC-Switch 启动。如果启动后界面空白，检查是否被杀毒软件拦截，把 CC-Switch 加入白名单。
3.3 Linux：deb、rpm 与 AppImage
Ubuntu/Debian 用户下载cc-switch_3.15.0_amd64.deb，安装命令：
sudo dpkg -i cc-switch_3.15.0_amd64.deb && sudo apt -f installapt -f install是用来修复依赖的，如果 dpkg 报依赖错误，这条命令会自动补上。
Fedora/RHEL 用户下载.rpm后缀的安装包，用sudo rpm -ivh 包名.rpm安装。
通用免依赖方案是 AppImage：
chmod +x CC-Switch-3.15.0.AppImage ./CC-Switch-3.15.0.AppImage赋予执行权限后直接运行。AppImage 不需要安装，适合不想动系统包管理的用户。
3.4 CC-Switch 配置片段
安装完成后，打开 CC-Switch，进入设置，开启路由总开关和 Claude 接管。然后添加服务商，以 TaoToken 为例，配置如下：
{ "provider": "taotoken", "baseUrl": "https://taotoken.net/api", "apiKey": "你的_API_Key", "modelMapping": { "sonnet": "claude-sonnet-4-20250514", "opus": "claude-opus-4-20250514", "haiku": "claude-haiku-4-20250514" } }Base URL 填https://taotoken.net/api，API Key 填你在控制台创建的那个，Model ID 根据实际模型填。模型映射把 Sonnet、Opus、Haiku 绑定到对应模型，重启终端即可调用。
如果你用的是 Codex，配置文件在~/.codex/auth.json，CC-Switch 会自动管理这个文件。Cline MCP 的配置也在 CC-Switch 里统一管理，不需要手动改。
4. 验证请求：确认 CC-Switch 正常启动并生效
装完配置完，怎么确认 CC-Switch 真的在工作？分三步验证。
第一步，检查 CC-Switch 进程是否在运行。macOS 和 Linux 用ps aux | grep cc-switch，Windows 在任务管理器里看。如果进程不在，说明软件没启动成功，回到安装步骤排查。
第二步，检查路由开关是否生效。打开 CC-Switch 界面，确认「路由总开关」和「Claude 接管」都是开启状态。如果开关是灰的，说明配置没保存，重新点一次保存。
第三步，发一个实际请求。打开终端，用 Claude Code 发一条测试消息：
claude "你好，请回复当前使用的模型名称"如果返回正常，说明 CC-Switch 的路由生效了。如果报错，看下面的排查部分。
你也可以直接在 CC-Switch 里点「测试连接」，它会向配置的 Base URL 发一个请求，返回 200 就说明连通。TaoToken 的 API 地址是 https://taotoken.net/api，测试连接时确认这个地址没有拼错。
验证通过后，你可以在 CC-Switch 里切换不同的服务商，观察终端里的模型响应是否跟着变。如果切换后没变化，说明路由没接管成功，检查「Claude 接管」开关。
5. 常见报错排查：401、local proxy failed 与 OAuth 问题
这一节对照真实报错，给出排查路径。
401 Unauthorized：API Key 无效或过期。检查 CC-Switch 里填的 Key 是否和 TaoToken 控制台里的一致，注意不要有多余空格。如果 Key 刚创建，等几秒再试。TaoToken 的 Key 在控制台 API Keys 页面管理，确认没有删除或禁用。
local proxy failed：CC-Switch 的本地代理没启动。检查端口是否被占用，默认端口在设置里能看到。如果端口冲突，改一个端口重启软件。另外确认防火墙没有拦截 CC-Switch 的本地监听。
reading choices 报错：通常是模型返回格式不匹配。检查 Model ID 是否填对，比如 claude-sonnet-4-20250514 不要写成 claude-sonnet-4。如果 Model ID 正确，检查 Base URL 结尾是否需要加 /v1，TaoToken 的地址是 https://taotoken.net/api，按文档要求填。
OAuth 相关报错：如果你用的是需要 OAuth 的服务商，检查 CC-Switch 里的 OAuth 配置是否完整。Codex 的 auth.json 路径是~/.codex/auth.json，确认 CC-Switch 有权限读写这个文件。如果报权限错误，手动改一下文件权限。
brew 安装后找不到命令：cask 安装的是 GUI 应用，不是命令行工具，所以which cc-switch找不到是正常的。去「应用程序」文件夹里找 CC-Switch.app。
Windows 安装后启动闪退：检查解压路径是否纯英文，检查杀毒软件是否拦截。把 CC-Switch 加入白名单后重试。
如果以上都排查完还是不通，到 TaoToken 的接入文档页面看最新的配置说明，或者到 API Keys 页面重新生成一个 Key 试试。
6. 装完之后：把 CC-Switch 用起来的几个实际建议
CC-Switch 装好只是第一步，真正省事的是把它和你的日常编码流程结合起来。我的习惯是：在 CC-Switch 里配好两到三个服务商，一个主力一个备用，主力不通的时候一键切换，不用手动改配置文件。
如果你长期用 Claude Code 做编码，可以考虑 Coding Plan，把常用的模型映射固定下来，减少每次配置的时间。Coding Plan 的入口在官网导航里。
另外，CC-Switch 的配置文件建议备份一份。虽然它本地加密存储，但换机器的时候重新配一遍还是麻烦。备份路径在设置里能看到，复制出来存好。
最后提醒一点：CC-Switch 是配置管理工具，不是模型服务本身。它的作用是帮你把 Base URL、Key、Model ID 这三件套管好，真正干活的是背后的模型服务。所以选一个稳定的服务商比频繁换工具更重要。TaoToken 的 API 地址是 https://taotoken.net/api，控制台里可以管理 Key 和查看用量，接入文档里有各端的配置示例，遇到问题先看文档再排查。
