最近后台好多人在问同一个问题CC Switch 在 Windows 上到底怎么下载、怎么装、怎么配尤其是想把它接到 Codex CLI、OpenCode 上跑 DeepSeek、GLM、百炼这类模型结果过程中不是报 400 就是报 502还有一堆人卡在“cc switch local proxy failed while handling codex endpoint”这行错误上死活出不来。我干脆抽了个周末从零开始把 Windows 版的完整流程走了一遍从拿安装包到跑通第一个请求再到把所有高频报错都复现了一遍。这篇就把整个过程、配置思路和踩过的坑一次性写清楚不管是刚接触的小白还是已经折腾过一阵的老手应该都能从里面捞到点能直接用的东西。1. CC Switch 到底是什么为什么现在这么多人用1.1 它解决的是“模型切换”这个麻烦事先别急着下载搞清楚 CC Switch 定位很重要。它本质上是一个本地模型路由工具你在它里面配置好各家模型供应商的 API Key、Base URL、模型列表它会把这些配置统一打包成 OpenAI 兼容的本地接口再提供给 Codex CLI、OpenCode、Claude Desktop 这类的 AI 编程工具调用。打个比方你手上有 DeepSeek、智谱 GLM、阿里百炼、Kimi 好几个平台的账号每个平台的接口格式、模型名都不一样。今天想让 Codex CLI 用 DeepSeek明天又切到 GLM如果没有 CC Switch你得反复改环境变量、改配置文件、记一堆乱七八糟的 Base URL。有了它之后只需要在图形界面里点一下切换本地接口地址保持不变所有工具自动跟着切。这就是它名字里“Switch”的含义不是某个模型的专用客户端而是模型供应体系里的一个“总开关”。1.2 本地代理是怎么“骗过”Codex 的这里有个核心机制得先讲明白不然后面排错你会很痛苦。OpenAI 官方出的 Codex CLI 默认只认 OpenAI 的接口协议它启动时会向固定的地址发请求。CC Switch 做的事情是在你本机起一个 HTTP 服务监听类似127.0.0.1:15783这样的端口然后把 Codex 的请求“接住”再按你预设的供应商配置转发到真正的上游去。转发过程不是简单透传它要做三件事把请求头里的鉴权信息替换成目标供应商的 API Key把请求体里的模型名称映射成供应商实际支持的模型名把上游返回的数据结构转换成 Codex 能识别的格式所以你在日志里看到的cc switch local proxy failed while handling codex endpoint /responses翻译成人话就是本地代理已经收到了 Codex 发来的/responses请求但是在转发给上游比如 DeepSeek的过程中上游返回了错误状态导致整个链路失败。问题不一定出在 CC Switch 自己身上很可能是上游拒绝了也可能是中间的格式转换出了岔子。这个思路理顺了后面排查 Raised 各种 HTTP 报错你就知道往哪个方向查。1.3 智能模式、Config Provider、Generator 这些名词先混个脸熟CC Switch 里几个高频概念我一并说清楚因为后面配置的时候都会碰到供应商Provider指 DeepSeek、智谱、百炼、OpenAI 这些实际提供模型服务的平台。每个供应商需要配置 Base URL、API Key、支持的模型列表。生成器GeneratorCC Switch 会根据不同工具Codex、OpenCode、Claude Desktop生成对应的配置产物这个产物会以本地接口的形式暴露出来。比如/generators/v1/codex就是专门给 Codex 用的入口。智能模式Smart Mode开启后 CC Switch 不指定具体模型名而是让上游自动选择默认模型。这个模式对新手很友好能减少“模型名不存在”这类低级错误后面我会单独讲。Config Provider有些工具吃的是环境变量或者配置文件CC Switch 可以把多个供应商配置打包成一个“Config Provider”切换时一次性把所有环境变量都替换掉。这些概念不要求你现在就全记住但有了这个底子后面看配置界面和文档会顺畅很多。2. Windows 下载与安装两种主流方式都走一遍2.1 下载前的环境确认在动手之前先确认你的 Windows 环境符合要求。CC Switch 桌面版是跨平台方案Windows 10 1809 以上、Windows 11 都没问题理论上只要是 64 位系统都能跑。内存方面它本身占的资源不多但你要同时跑 Codex CLI 再加上各种 Node 服务建议至少 8GB 内存16GB 会更舒服。磁盘空间预留 2GB 左右就够主要是 Node 运行时和日志文件会占一些空间。另外两个容易被忽略的点我每次装机都会提前查确认系统是 64 位。现在基本没有 32 位系统了但如果你是老机器右键“此电脑—属性”看一眼处理器架构别下错包。如果本机已经装了 360、腾讯管家这类安全软件安装时可能会弹窗拦截本地服务记得选择“允许”。CC Switch 要监听本地端口这在安全软件眼里属于敏感行为。2.2 桌面版安装步骤拿到安装包之后怎么走安装包这块市面上流通的中文版安装包一般分两种形态一种是 exe 安装程序双击后走向导另一种是绿色版压缩包解压即用。不管哪种核心安装逻辑是一致的。以 exe 安装向导为例完整流程如下双击安装包如果出现用户账户控制UAC弹窗点“是”允许运行。安装语言选择界面有“简体中文”就选它没有的话选 English 也不影响使用后面可以在设置里改界面语言。选择安装目录。我个人的习惯是装到D:\Tools\CCSwitch这类非系统盘路径尽量避免装到C:\Program Files下因为有些版本的 Node 服务对带空格的路径处理不当虽然现在的版本已经很少出这个问题但规避掉总没坏处。选择组件时如果碰到“创建桌面快捷方式”“开机自启动”这类选项按需勾选就行。我建议把“开机自启动”关掉本地代理服务没必要常驻后台要用的时候手动开能省一点资源和很多困惑——不然哪天端口被占了你都想不到是它在后台偷偷跑。安装完成后首次启动软件会询问“选择工作模式”常见的是“智能模式”和“OpenCode 模式”。这一步不用太纠结我通常建议直接选智能模式后面需要再改也来得及。2.3 验证安装是否成功安装完别着急配模型先确认服务真的跑起来了。CC Switch 桌面版启动后会在系统托盘显示一个图标同时本地会监听一个端口。默认情况下地址是http://127.0.0.1:15783。验证方法很简单打开浏览器访问http://127.0.0.1:15783如果能看到 CC Switch 的界面或者 API 文档页面说明服务正常。如果页面打不开优先检查两件事一是托盘图标是否在运行二是防火墙有没有拦截本地端口。注意默认端口 15783 不是绝对的如果你在安装或后续配置时改过端口以实际为准。另外如果本机同时装有 Docker Desktop、MySQL 这类也会占用端口的软件15783 被占用的概率不大但碰到了就换一个高位端口比如 18080。2.4 想用命令行源码安装方式也不复杂如果你平时更喜欢命令行操作或者你是开发者想顺便读读源码CC Switch 也支持通过 Node.js 直接跑。这个过程对懂一点技术的人其实更清爽核心就几步先去 Node.js 官网装一个 LTS 版本建议 18 以上20 更好。命令行里执行node -v确认版本号。把项目克隆到本地进入项目目录。执行npm install安装依赖这一步如果网络慢可以换用国内镜像源。执行npm run dev启动开发模式看到类似listening on 15783的日志就说明起来了。源码方式的好处是你能直接看到日志输出排查问题比图形界面直观。坏处是需要自己管理 Node 环境和依赖不适合纯小白。我的建议是如果你之前没碰过 Node.js老老实实用桌面版就行没必要为了“显得专业”去折腾命令行。3. 核心配置实操把 DeepSeek、GLM、百炼接进来3.1 配置入口和文件结构CC Switch 的配置入口有两个图形界面和配置文件。图形界面在左下角设置区域能找到“供应商管理”之类的入口适合日常操作配置文件是config.json里面存着所有供应商信息和工具映射关系适合批量修改和备份。如果你拿到的是绿色版解压后目录里通常会有config.json或generators.json这样的文件。用编辑器打开后会发现结构其实很清晰一个providers数组列出所有供应商每个供应商包含id、name、baseUrl、apiKey、models等字段还有一个部分定义“如何把这些供应商暴露给不同工具”。理解了这个结构你在界面上点的每一处配置本质上都是在改这个 JSON。3.2 以 DeepSeek 为例完整配置一遍我拿 DeepSeek 当例子因为这是目前呼声最高的国产模型供应商配置它也最有代表性。首先你需要去 DeepSeek 开放平台注册账号创建一个 API Key。这个 Key 在 CC Switch 里属于高敏感信息只存在本地配置里不会回传。然后在 CC Switch 界面中点击“新增供应商”填写以下关键信息供应商名称随便起比如deepseekBase URLhttps://api.deepseek.com/v1API Key粘贴刚才创建好的 Key模型列表至少填deepseek-chat和deepseek-reasoner这两个这里有个容易踩坑的地方Base URL 不要写成https://api.deepseek.com很多复制粘贴党直接少了/v1导致后面请求 404。DeepSeek 的 OpenAI 兼容接口路径一定要带/v1。填完之后保存然后到“工具配置”或“生成器”页面选择 Codex CLI 作为目标工具把当前活动供应商指定为deepseek。做完这一步CC Switch 就会在本地生成一个针对 Codex 的配置入口这个入口的地址格式一般是http://127.0.0.1:15783/generators/v1/codex。3.3 智谱 GLM 和阿里百炼的差异点智谱 GLM 和阿里百炼的接入逻辑和 DeepSeek 完全一样无非是 Base URL 和模型名不同。智谱的 OpenAI 兼容地址是https://open.bigmodel.cn/api/paas/v4模型名一般是glm-4-plus、glm-4-flash这类。注意智谱和 DeepSeek 有个明显区别智谱不同模型的计价、上下文长度差异很大建议你把模型列表写全后面切换时才不容易选错。阿里百炼DashScope的兼容地址是https://dashscope.aliyuncs.com/compatible-mode/v1模型名如qwen-plus、qwen-max。百炼的 API Key 获取路径是阿里云控制台的百炼页面开通服务后创建。之前有热搜词提到“cc switch 怎么配置百炼 token plan”这里顺带说一句百炼平台有“Token 计划”的概念某些套餐会对模型调用做限制。正常接入 CC Switch 只需要 API Key 就行不需要单独配置 Token Plan 字段如果你在 CC Switch 里压根没找到这个选项不是你的问题是这个版本就没有这个功能。下面这张表把三家关键参数列出来方便你对照填写供应商Base URL常用模型名备注DeepSeekhttps://api.deepseek.com/v1deepseek-chat、deepseek-reasoner/v1必须带智谱 GLMhttps://open.bigmodel.cn/api/paas/v4glm-4-plus、glm-4-flash模型名区分大小写阿里百炼https://dashscope.aliyuncs.com/compatible-mode/v1qwen-plus、qwen-max需先在控制台开通服务3.4 为什么我推荐你开启智能模式配置过程中软件会问你要不要启用智能模式。我的建议是新手全程开着老手看场景切换。智能模式的本质是CC Switch 在转发请求时不指定具体的 model 参数让上游按默认策略选模型。它的好处有两个第一省去你记忆模型名的负担不用管glm-4-flash还是glm-4-flash-250408这种冷门差异第二规避了“模型名写错导致 404”的高频问题。那它有没有缺点也有。如果你同一家供应商有多个模型而你又想刻意用某个特定模型比如 DeepSeek 的推理模型智能模式可能选到你不想要的。所以我现在的习惯是快速试通链路时开智能模式确认没问题后再关掉智能模式精确指定模型。4. 接入主流工具Codex CLI、OpenCode、Claude Desktop4.1 Codex CLI 接入最常见的场景Codex CLI 是 OpenAI 出的开源命令行编程工具可以通过 npm 安装。Windows 上的安装命令是npm install -g openai/codex装完执行codex --version验证。但很多人在这一步就卡住了报“安装未完成”或者“找不到命令”大概率是 Node.js 环境变量没配好或者 npm 全局目录不在 PATH 里。Codex CLI 默认连的是 OpenAI 官方服务想让走 CC Switch 本地代理需要告诉它“别去 OpenAI去本地”。具体做法是修改 Codex 的配置文件位置一般在用户目录下的.codex/config.toml。关键配置如下model_provider ccswitch model deepseek-chat [model_providers.ccswitch] name CC Switch base_url http://127.0.0.1:15783/generators/v1/codex wire_api responses env_key CCSWITCH_API_KEY需要解释几个参数model_provider指定使用哪个供应商配置块这里命名成ccswitchbase_url是 CC Switch 暴露的本地接口地址注意路径要带/generators/v1/codexwire_api是通信协议保留responses即可因为 CC Switch 已经帮你转成 Codex 能识别的格式env_key对应一个环境变量名CC Switch 会自动把选中的 API Key 注入到这个变量里配置完成后在命令行里设置环境变量$env:CCSWITCH_API_KEY任意占位符或者从CC Switch复制这里有个比较关键的点CC Switch 在处理 Codex 请求时会用自己的供应商 Key 替换请求头里的鉴权信息。所以env_key对应的环境变量值不一定要真实有效——你填一个占位符都行真正的 Key 由 CC Switch 注入。这在官方文档里其实写得很清楚但很多人不知道以为一定要填真实 Key结果填了反而出问题。然后启动 Codexcodex。首次使用会要求登录直接输入n跳过 ChatGPT 登录因为你走的是第三方接入。如果 Codex 还是尝试连接官方服务器、报签名错误优先检查config.toml里的base_url是不是写对了以及 CC Switch 是不是在运行状态。4.2 OpenCode 接入参数大同小异OpenCode 是另一款热门的开源 AI 编程 CLI和 Codex 相比它对第三方的兼容性做得更好。接入 CC Switch 的方式几乎一样区别在于 OpenCode 自己有一套配置文件通常位于用户目录下的.opencode/config.json。在 OpenCode 里你需要定义一个自定义 Provider指向 CC Switch 的本地地址{ provider: { ccswitch: { npm: ai-sdk/openai-compatible, name: CC Switch, options: { baseURL: http://127.0.0.1:15783/generators/v1/opencode }, models: { deepseek-chat: { name: DeepSeek Chat } } } } }注意baseURL里的路径换成了/generators/v1/opencode说明这是给 OpenCode 用的独立入口。CC Switch 的不同生成器入口互不干扰你完全可以同时给 Codex 和 OpenCode 供给不同的模型配置这也是它比单纯设置环境变量优雅的地方。4.3 Claude Desktop 接入的特别之处Claude Desktop 专门用 Claude 家的模型正常情况下不会接入第三方供应商但如果你用的是 Claude Code 这类工具或者想通过 CC Switch 统一管理所有工具的 API 配置也可以把它的网关指向本地。这部分的配置逻辑跟 Codex 完全一致。很多人在配置 Claude Desktop 时遇到 “couldn‘t sign in to gateway” 的报错排查下来八成是网关地址写错或者 CC Switch 没把对应的生成器入口打开。去界面里检查一下是不是只启用了 Codex 生成器而没启用 Claude 生成器。这个按钮通常是一排开关不同工具各对应一个漏掉很容易。注意Claude 家的网关鉴权机制比较敏感如果你发现什么配置都对但就是登录不了试试把供应商的模型列表清空让它走智能模式。这个问题我后面还会在排错章节再展开。5. 高频报错排查实录400/401/403/404/502/503 逐个过5.1 HTTP 400reasoning_content必须回传这是最近出现频率最高的问题就是热搜里那个长长的错误cc switch local proxy failed while handling codex endpoint /responses. provider: deepseek; model: deepseek-v4-flash; upstream_status: http 400; cause: the reasoning_content in the thinking mode must be passed back to the api.我直接说人话。reasoning_content是 DeepSeek 推理模型比如deepseek-reasoner特有字段表示模型在给出正式回答前的思考过程。OpenAI 的协议里没有这个字段而 DeepSeek 官方接口的要求是如果你在对话上下文里带了思考模式的内容后续请求必须原样回传否则就报 400。问题的根源在于Codex CLI 这类工具本身不认识reasoning_content它只会把这个字段当作普通消息的一部分可能在处理过程中丢弃或者截断导致请求发到 DeepSeek 时上下文里的思维链内容不完整上游就拒绝了。针对这个问题我实测有效的处理方式有几种最简单粗暴把模型从推理模型换成非推理模型。DeepSeek 就换到deepseek-chat直接绕开思维链机制。确认 CC Switch 版本是否过旧。这个问题在新版里已经做过兼容处理更新后会好很多。手动清理 Codex 的对话上下文重新开一轮对话排除历史消息里的脏数据。顺带说一句错误信息里的模型名deepseek-v4-flash看着就不像 DeepSeek 官方的标准模型名。如果你是在某些第三方渠道拿到的模型名建议自己确认一下这个名字到底存不存在很多时候 400 就是模型名压根写错了。5.2 HTTP 401 Unauthorized鉴权失败401 的含义非常明确API Key 无效。但“无效”分几种情况API Key 复制不完整多了一个空格或者少了几位API Key 已经被删除、禁用或者余额耗尽请求头里的 Authorization 字段被替换成了错误的值排查步骤我建议按顺序来到 CC Switch 的供应商配置页面重新复制一次 API Key注意首尾不要有多余换行。去上游平台的控制台确认 Key 是否有效DeepSeek、智谱、百炼都有额度查询页面。用 curl 直接测上游接口跳过 CC Switch 看原始服务是否正常。curl 测试命令如下把 key 和模型替换成你自己的curl -X POST https://api.deepseek.com/v1/chat/completions -H Content-Type: application/json -H Authorization: Bearer sk-你的key -d {\model\:\deepseek-chat\,\messages\:[{\role\:\user\,\content\:\hi\}]}如果 curl 能正常返回说明上游没问题问题就出在 CC Switch 到上游之间的配置上如果 curl 也报 401那就去上游平台查 Key 的有效性。5.3 HTTP 404 Not Found地址或模型名不对404 的报错在本地代理场景下通常有两种来源。一是本地路径 404比如你访问了/generators/v1/xxx这个不存在的入口那说明生成器没配对二是上游返回 404最常见的就是模型名不存在。判断方法也很简单看日志里provider字段标记的上游返回状态。如果是上游 404去供应商官网查一下模型现在的准确名称特别注意大小写和版本后缀。比如百炼的qwen-max在某个时间点之后可能改名成qwen-max-latest如果还拿旧名字请求404 是必然的。我记得有一次排查一个 404折腾了半小时最后发现是配置里多了一个不可见字符——从网页复制模型名时带了个零宽空格。这种问题在编辑器里根本看不见用curl或者 Python 打印出字符串长度才暴露出来。5.4 HTTP 403/502/503供应商侧问题的三种形态这几个状态码本质上都是上游拒绝了请求但原因各不相同放在一起对比更好记状态码含义常见原因处理建议403禁止访问模型权限不足、账号被限制、供应商地域策略拦截检查账号权限联系供应商客服确认模型是否白名单开放502网关错误上游服务短暂故障、请求超时等几分钟重试或者切到另一家供应商503服务不可用上游过载、触发限流降低请求频率检查套餐并发限制这几个问题里502 和 503 大概率不是你的配置问题是供应商的服务器在“抽风”。我遇到过好几次明明上午还能用下午突然就 502 了日志显示上游网关超时这种属于不可控因素老老实实等着恢复或者临时切换到其他供应商。403 则不一样它通常意味着账号级问题。如果你用的是免费额度可能额度已经用完也可能是供应商某个模型只对特定区域开放你的请求 IP 不在允许范围内。这种时候别硬调配置去上游平台查清楚账号状态最实际。5.5 先分清是本地问题还是上游问题排错这么多年我最深的体会是大部分人报错排查半天是因为没先分清“本地代理的问题”和“上游接口的问题”。这两类问题的处理方法完全不一样混淆了就会一直在错误的方向上打转。一个高效的排查顺序是这样的看 CC Switch 的日志窗口确认报错文案里upstream_status字段是什么状态码。如果上游状态码正常200但 Codex 依然报错说明问题在 CC Switch 与 Codex 之间的格式转换优先升级 CC Switch、检查生成器配置。如果上游状态码就是 4xx/5xx直接按上面表格对应的方向处理。如果日志什么都没输出检查 CC Switch 服务是否运行、端口是否被占用。这个思路一次能解决 80% 的问题。别一上来就怀疑供应商、怀疑工具先按日志说话。6. 实操心得一些值得分享的配置习惯和绕坑技巧6.1 我把配置拆成“常用”和“备用”两套我自己的机器上CC Switch 里常驻两套供应商配置。一套是日常主力比如 DeepSeek 的deepseek-chat响应快、成本低适合日常问答和代码补全。另一套是备用比如智谱 GLM 或者百炼的qwen-max当主力供应商出现 502/503 时一键切过去不用中断工作流。这个习惯帮我省了很多事。有一次 DeepSeek 官方故障我切到百炼继续干活整个切换过程不到十秒Codex 会话都没断。如果只配了一家供应商遇到上游故障就只能干等。6.2 给你的常用工具写一个一键启动脚本Windows 上每次都要手动开 CC Switch、然后再开 Codex有点烦。我写了一个start.bat脚本放在桌面双击一下就把该启动的进程全拉起来echo off start C:\Tools\CCSwitch\CCSwitch.exe timeout /t 3 /nobreak nul set OPENAI_BASE_URLhttp://127.0.0.1:15783/generators/v1/codex codex解释一下第一行启动 CC Switch第二行等待 3 秒确保服务就绪第三行设置 Codex 需要的环境变量第四行启动 Codex。这里有个小坑set设置的环境变量只对当前命令行窗口有效所以必须把codex命令和set放在同一个 bat 文件里如果你另外开一个窗口运行 Codex环境变量是继承不到的。6.3 配置文件的备份比你想的更重要CC Switch 的配置文件里存着所有供应商的 API Key 和模型映射一旦丢了要全部重新录入非常麻烦。我每个月都会把config.json备份一次放在网盘或 Git 私有仓库里。注意一点文件里有真实 API Key不要放到公开仓库万一泄露被人拿去刷额度损失的是你的钱包。6.4 后续还能怎么扩展CC Switch 的价值不止于连接 Codex 和 DeepSeek。你可以把它理解成一个 API 网关所有走 OpenAI 兼容协议的工具都能接进来。比如你自己写了个脚本要调用多家大模型做对比测试以前要写一堆适配代码现在只要调 CC Switch 的本地接口它能自动帮你路由到不同供应商。我最近就在做一个简单的模型对比实验同一个 Prompt 分别发给 DeepSeek、GLM、Qwen看哪个回答质量更好。这个脚本本身只有几十行核心逻辑就是调 CC Switch 的本地代理验证不同模型效果。这种用法也许不在 CC Switch 设计者的预期里但确实能省掉很多重复工作。我个人的体会是CC Switch 这类的本地路由工具它的价值不在功能有多炫而在于把模型切换这种原本繁琐、极易出错的事情变得像切换输入法一样简单。你现在可能只用来接 Codex、跑 DeepSeek但以后如果上了更多模型、更多工具它的优势会越来越明显。
