1. CC-Switch 是什么三端安装前先搞清楚这件事CC-Switch 是一个开源的模型服务商切换工具核心作用是帮你在 Claude Code、Codex 这类命令行编码工具里快速切换不同的 API 服务商和模型映射。它本身不提供模型也不替代编辑器只是一个本地运行的配置管理面板。适合谁用如果你手上有多个 API Key或者需要在 DeepSeek、智谱 GLM、通义千问之间来回切换手动改配置文件容易出错CC-Switch 就是来解决这个问题的。我在 Windows 和 macOS 上都装过实测下来最省事的路径是 macOS 走 brewWindows 走 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。你需要在 TaoToken 的控制台创建一个 API Key然后拿到对应的 Base URL 和 Model ID。具体操作路径打开官网进入控制台找到 API Keys 页面创建一个新的 Key。创建完成后复制保存这个 Key 只会显示一次。然后确认 Base URLTaoToken 的 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 macOSbrew 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 WindowsMSI 安装与解除锁定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 Linuxdeb、rpm 与 AppImageUbuntu/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安装。通用免依赖方案是 AppImagechmod 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/apiAPI Key 填你在控制台创建的那个Model ID 根据实际模型填。模型映射把 Sonnet、Opus、Haiku 绑定到对应模型重启终端即可调用。如果你用的是 Codex配置文件在~/.codex/auth.jsonCC-Switch 会自动管理这个文件。Cline MCP 的配置也在 CC-Switch 里统一管理不需要手动改。4. 验证请求确认 CC-Switch 正常启动并生效装完配置完怎么确认 CC-Switch 真的在工作分三步验证。第一步检查 CC-Switch 进程是否在运行。macOS 和 Linux 用ps aux | grep cc-switchWindows 在任务管理器里看。如果进程不在说明软件没启动成功回到安装步骤排查。第二步检查路由开关是否生效。打开 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 UnauthorizedAPI Key 无效或过期。检查 CC-Switch 里填的 Key 是否和 TaoToken 控制台里的一致注意不要有多余空格。如果 Key 刚创建等几秒再试。TaoToken 的 Key 在控制台 API Keys 页面管理确认没有删除或禁用。local proxy failedCC-Switch 的本地代理没启动。检查端口是否被占用默认端口在设置里能看到。如果端口冲突改一个端口重启软件。另外确认防火墙没有拦截 CC-Switch 的本地监听。reading choices 报错通常是模型返回格式不匹配。检查 Model ID 是否填对比如 claude-sonnet-4-20250514 不要写成 claude-sonnet-4。如果 Model ID 正确检查 Base URL 结尾是否需要加 /v1TaoToken 的地址是 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 和查看用量接入文档里有各端的配置示例遇到问题先看文档再排查。