最近好多人在问 CC Switch 到底怎么才能顺利用起来尤其是看到控制台里一遍遍刷local proxy failed while handling codex endpoint /responses这种报错的时候真的会让人怀疑是不是自己下载错了版本。这阵子我把 CC Switch 从下载、配置到接入 DeepSeek、Qwen、GLM 这些国产模型完整跑了一遍中间踩了不少坑也搞清楚了它的工作方式。这篇就写成一份实操向的笔记给刚接触的朋友一条能照着操作的路径也把那些反复出现的 404、503、401 错误一次说清楚。如果你还不清楚 CC Switch 是什么简单说它是一个跑在你本地的 API 代理工具。你本地的 Claude Code、Codex CLI 默认会向模型厂商的官方地址发请求而 CC Switch 会把这些请求拦截到本地端口再转发到你配置好的第三方模型服务上。这样就能用 DeepSeek、通义千问、GLM 之类的大模型来驱动这些编码工具省下官方订阅费用也让模型的选择变得灵活。适合的人群很明确想用国产模型跑 Codex / Claude Code 的开发者、觉得官方按量计费太贵的个人用户以及想在 VS Code 的 AI 插件里统一管理多个模型 API 的折腾型选手。1. 先搞清楚 CC Switch 到底解决什么问题1.1 它是一个本地代理不是插件也不是改壳我见过不少第一次用 CC Switch 的人会把它理解成一个“模型管理面板”或者“聊天客户端”其实它的核心身份是 local proxy。它的工作方式跟抓包工具有点像你本机的 CLI 工具发出 HTTPS 请求CC Switch 在 localhost 的一个端口上监听然后按你填好的规则把请求转发到真正的模型服务商那边。理解这一点特别重要因为后面遇到的所有报错几乎都跟“请求到了本地代理之后没能正确转出去”有关。比如local proxy failed while handling codex endpoint /responses这句话表面上是在说 Codex 的/responses接口处理失败实际上是因为本地代理接收到了这个请求但在转发、鉴权或模型映射环节出了问题。所以排查的时候不要盯着“failed”这个词要往前看代理有没有起来、转发地址对不对、Key 有没有填对。1.2 为什么本地代理这种方式最合适有人会问为什么不直接把 Claude Code 的 API Base 改成国产模型的地址原因是很多编码工具的前端协议是固定的比如 Codex 走的是 OpenAI 的 Responses API 格式而 DeepSeek、Qwen 提供的接口格式可能只有 Chat Completions 格式两边直接对接往往不通。CC Switch 的作用就是做协议转换。它把 OpenAI 风格的聊天补全请求转换成目标模型服务商能识别的格式再把返回结果转回给编码工具。所以它本质上干了两件事协议翻译和地址路由。理解了这一层你就知道为什么配置时必须关心“模型名映射”和“API 路径兼容”这些细节了因为代理并不知道你脑子里想用什么模型它只知道把请求发到什么地址、用什么 Key、返回什么格式。1.3 CC Switch 与官方账号是否冲突这阵子好多人问“装了 CC Switch 之后会不会影响我原来的官方账号”从我实际使用来看不冲突。它只是在本地开了一个代理服务你不启动它的时候Claude Code 或者 Codex CLI 该走官方还是走官方。即使启动了 CC Switch只要你没有在终端里设置对应的环境变量CLI 也不会主动连它。需要注意的是别把两个体系的环境变量混在一起。比如你已经在系统里设置了ANTHROPIC_API_KEY同时又想在 CC Switch 里用一个第三方模型的 Key那就要确认 CLI 读到的是 CC Switch 写的环境变量而不是之前残留的官方 Key。我自己的习惯是写一个独立的终端配置文件只在需要时加载代理相关变量避免跟日常环境冲突。这样既能保持官方账号不动又能随时切到代理模式。2. 安装与版本选择安装版、便携版、AMD/Ubuntu 的坑2.1 安装版和便携版到底选哪个CC Switch 目前有安装版和便携版两种分发方式。安装版会写入系统配置、注册开机启动项用起来像是普通的桌面应用便携版则是一个解压就能跑的目录所有配置文件都在目录里面不碰系统。对于只是偶尔用一下的人我建议便携版因为删的时候直接删文件夹就完事不会留下什么残留。不过便携版也有一个容易被忽略的问题如果操作系统升级或者杀毒软件清理了临时目录可能会把 CC Switch 运行时生成的缓存清掉导致下次启动时认为你是首次运行之前配好的模型信息全部丢失。我连续遇到两次之后学乖了每次改完配置都会手动把整个配置文件夹备份一份。表里列一下两者区别对比项安装版便携版安装方式走系统安装流程解压即用配置存储系统用户目录软件目录内清理残留要额外卸载删文件夹即可适合场景长期固定在电脑上用临时演示、多台电脑同步主要风险安装过程可能被杀软拦截配置可能被系统临时文件清理影响2.2 处理 AMD 处理器和 Ubuntu 系统的特殊情况热词里出现了“cc switch amd”和“cc switch download ubuntu”估计很多朋友在这两个环境下栽过跟头。先说 AMD如果你只是 AMD 的 CPU那完全没问题CC Switch 本质是 Node.js 或类似运行时包装的应用和 CPU 品牌无关。但如果你是 AMD 显卡的用户要明白 CC Switch 本身不负责模型推理它只做代理转发所以显卡型号对它的影响很小真正影响你的是你选择的模型服务商是否提供 GPU 推理能力。Ubuntu 环境下最容易犯的错是当成绿色软件直接双击Linux 下没有这个概念。你需要在终端里给启动文件加执行权限chmod x cc-switch然后手动运行。如果碰到缺少系统依赖的提示先用包管理器装上libgtk-3-0和libwebkit2gtk-4.0-37这类常见运行库再重新启动。很多 Ubuntu 用户觉得“怎么打开没反应”其实不是软件坏了而是图形库缺失导致窗口创建失败。2.3 升级版本前先备份配置我吃过一次大亏CC Switch 从 3.16.0 升到 3.16.1 之后之前配好的几个模型指向全部不见了。后来翻更新日志才发现新版本改了配置文件的存储结构。所以无论你是从官网还是从网盘下载的新版本升级之前一定先备份config.json或者整个配置目录。如果你用的是安装版一般配置在系统用户目录下的.cc-switch文件夹里便携版就直接复制整个软件目录。官方一般会随版本发布更新说明特别会标注“配置迁移”相关的注意事项。我的建议是不要见到新版本就升。除非更新说明里写着修复了你正在踩的那个 bug或者新增了明确需要的功能。尤其是像 3.16.1 这种小版本如果当前用的稳定完全没必要追新。3. 最关键的一步如何把模型接进来3.1 准备好一个可用的 API Key 和 Base URL很多人到这一步就乱了因为每个模型厂商的控制台入口不一样。你先别急着打开 CC Switch 乱填先准备好三样东西API Key、Base URL、模型名称。API Key 就是你在模型服务商后台创建的访问密钥Base URL 是 API 服务的根地址模型名称是厂商那边对某个模型的唯一标识比如通义千问的qwen-max、GLM 的glm-4-plusDeepSeek 的deepseek-chat。这三样东西是 CC Switch 转发的核心依据。Base URL 填错了代理就会把请求发到不存在的地址表现出来就是各种连接失败模型名填错了服务商收到请求后无法识别大概率返回 404。记住一句话本地代理不会替你猜测任何参数。3.2 以 DeepSeek、Qwen、GLM 为例的配置我以常见的三个国产模型服务商为例说下配置思路。DeepSeek 的 API 地址是https://api.deepseek.com/v1模型名deepseek-chat对应对话模型。如果你拿到的是兼容 OpenAI 格式的地址直接在 CC Switch 里填即可。通义千问这边如果你用的是阿里云百炼Base URL 一般是https://dashscope.aliyuncs.com/compatible-mode/v1模型名填qwen-max或qwen-turbo都可以。GLM 的智谱开放平台地址是https://open.bigmodel.cn/api/paas/v4模型名glm-4-plus。配置界面里通常还有一项“模型映射”需要你告诉 CC Switch当 Codex 或 Claude Code 请求某个默认模型时转出去用哪个目标模型。比如 Codex 默认请求gpt-4o你可以把gpt-4o映射成deepseek-chat这样上层工具以为自己在跟gpt-4o对话实际背后跑的是 DeepSeek。这个映射关系是整个配置里最容易出错的地方建议每一步都单独测试连通性之后再叠加。3.3 仔细说下阿里云百炼的配置热词里有“阿里云百炼api配置到cc switch当中”这个值得单独讲。阿里云百炼现在提供了兼容 OpenAI 的接口模式所以接入 CC Switch 比想象中简单。你需要先去阿里云控制台开通百炼服务然后在 API-KEY 管理页面生成一个 DashScope 的 API Key。这个 Key 形如sk-开头的一长串。接下来在 CC Switch 里新建一个 providerBase URL 填https://dashscope.aliyuncs.com/compatible-mode/v1Key 填你刚生成的字符串。模型名不要填错了百炼有很多模型编码比如qwen-plus、qwen-max、qwen-turbo还有支持百万上下文的新型号。如果你主要跑代码补全和日常问答qwen-plus的性价比通常不错要追求更强推理能力可以选qwen-max。首次配置完成之后不要急着去 Claude Code 里调用。先在 CC Switch 界面里找一个“测试连接”或者直接发一个简单请求的入口看看返回结果是否正常。这一步能帮你把“服务商问题”和“上层工具问题”隔离开来太关键了。3.4 配置完成后的连通性测试方法如果你在 CC Switch 里找不到测试入口可以用命令行手动测试。以 OpenAI 兼容格式为例在终端执行curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \ -H Authorization: Bearer 你的API-KEY \ -H Content-Type: application/json \ -d { model: qwen-plus, messages: [{role: user, content: 你好}] }如果返回了一段包含choices字段的 JSON说明服务商这边是通的。这时候再去启动 Codex 或 Claude Code如果依然报错那问题大概率出在 CC Switch 的模型映射、端口监听或者环境变量上与服务商无关。这个排查顺序能省下大量时间。4. 和 Claude Code / Codex 的联动4.1 通过环境变量让 CLI 找到本地代理Claude Code 和 Codex CLI 都支持通过环境变量来指定 API 地址和 Key。以 Codex 为例常见方式是在启动前设置好export OPENAI_API_KEYcc-switch中配置的key export OPENAI_BASE_URLhttp://127.0.0.1:1234/v1具体端口要看你在 CC Switch 里启用的代理端口是多少。Claude Code 这边则是export ANTHROPIC_BASE_URLhttp://127.0.0.1:1234 export ANTHROPIC_API_KEYcc-switch中配置的key这里的关键是环境变量里的 API Key 其实不一定要填真的因为请求已经被本地代理接管了代理会用自己的 Key 替换它。我见过有人在这里纠结要不要填官方 Key答案是不需要。你只要让 CLI 的流量进到代理端口就算成功了。要注意的是不同版本的 CLI 环境变量名可能略有差别启动前可以用printenv或echo $变量名确认是否生效。4.2 在 VS Code 里正确使用 CC Switch很多人的日常开发环境是 VS Code不是在裸终端里敲命令。我的建议是直接在 VS Code 的集成终端里跑上面的环境变量和启动命令这样你既能享受 VS Code 的编辑体验又不用切换窗口。还有一类 VS Code 插件支持自定义 OpenAI 兼容的服务地址你可以在插件设置里把 Base URL 填成http://127.0.0.1:1234/v1模型名填 CC Switch 里映射好的目标模型。有一点要提醒VS Code 的插件可能会把配置缓存在自己的设置文件里当你改了 CC Switch 的端口或者删除了某个 provider插件不会自动感知。这时候你手动重启插件或者重新选择模型不然会一直拿着旧的地址去请求。我一开始就不知道为什么插件里老报连接被拒绝后面才发现是把端口从1234改成3456之后插件设置没同步。4.3 切换模型后原对话不停跳闪的原因热词里提到“切换模型后原对话框不停跳闪”这问题我也遇到过。它一般不是 CC Switch 出 bug 了而是会话里记录的数据格式和当前模型不匹配。比如你用 A 模型跑完一轮对话直接在 UI 里切到 B 模型B 模型返回的流式输出格式跟 A 不一样前端解析器懵了就会反复尝试重绘对话内容看起来就像跳闪。最简单的解决办法是切换模型之前先开一个新会话或者清掉当前会话上下文。如果还是跳闪退出 CC Switch 进程再重新打开。我在实操中还发现跳闪经常发生在同时开多个项目、多窗口共用同一个代理端口时这种时候建议把不同的 CLI 会话分开不要同时向同一个 localhost 端口发送流式请求。5. 常见报错速查404、503、401 与 local proxy failed5.1 通用排查逻辑先分三层看到local proxy failed while handling之类的提示先别慌。把问题拆成三层第一层是本地代理有没有起来第二层是你配置的服务商地址和 Key 对不对第三层是上游服务端有没有正常返回。这三层只要有一层出问题最终都会表现为代理报错因为代理只是一个传递者它不会替你修复任何链路错误。我习惯的做法是第一次遇到报错立刻打开 CC Switch 的日志面板看它打印出的原始请求和响应状态码。日志里如果有写明转发到哪个 URL、带了什么 Authorization 头那排查起来非常快。如果日志是空的就先确认代理进程是否还在监听端口用lsof -i :端口号或者netstat -ano | findstr 端口号看。5.2 404 Not Found模型名或路径不对unexpected status 404 not found通常不是 CC Switch 问题。最常见的场景是模型名写成了官方页面上展示的“友称”而不是 API 接口里的“真实模型编码”。比如有的平台把模型叫做“通义千问-超强版”但接口内部编码是qwen-max如果你填了前者服务端自然找不到资源只能回 404。另一个常见原因是 Base URL 路径写错了。有些厂商的兼容地址是/v1结尾有些是/api/v1差一个/v1资源路径就全变了。正确做法是去服务商官方文档里复制完整的 Base URL不要手打。这里要特别提醒CC Switch 配置界面里的地址不要乱加斜杠末尾多一个/或漏掉/v1都会让转发出去的请求路径和鉴权路径不匹配表现就是 404。5.3 401 UnauthorizedKey 或鉴权头不对401 的本质是鉴权没过。通常三种情况一是你填的 API Key 本身无效、过期、或者被服务商吊销二是 Key 复制到了隐藏字符或者空格三是 CC Switch 在转发时没有把 Key 正确放到 Authorization 头里。对于第一种去服务商后台查一下 Key 的状态对于第二种用文本编辑器的“显示空白字符”功能检查一下粘贴内容。我踩过最隐蔽的坑是在 CC Switch 里配置了多个 provider但某个 provider 的 Key 填错了而当前会话恰好命中了这个 provider。表面上看整个配置都没问题因为其他模型都正常就这一个 401。所以排查 401 时要先确认当前请求走到了哪个 provider不要被全局配置骗了。5.4 503 Service Unavailable供应商过载或额度问题503 表示服务端无法处理请求。如果你是免费额度、试用额度或者按量付费余额不足部分服务商不会明确告诉你余额问题而是返回 503。另一个常见原因是目标模型的请求量过大服务商自动限流。尤其在工作日的上午推理集群繁忙的时候503 出现的概率明显增高。我的处理方式是先把模型切换到同一服务商下的其他低并发模型比如从deepseek-reasoner切到deepseek-chat看是否恢复如果恢复了说明是模型点过载。如果所有模型都 503就该去服务商控制台看余额和用量。另外CC Switch 设置的请求超时时间不宜过短否则代理可能因为上游响应慢而提前放弃本质上变成一种伪 503 问题。5.5 本地代理起不来或请求不进入代理怎么办有一种情况是本地代理直接起不来日志里只有崩溃信息。这时候先看端口占用比如你配置的端口被别的程序占用了代理就收听不了。换一个端口或者在系统里结束掉占用进程都能解决。还有一种情况是代理起来了但 CLI 请求完全不进代理说明环境变量没设置成功。我遇到过因为.bashrc和.zshrc同时存在导致只在其中一个文件里设置的变量不生效的情况。建议用绝对直观的方式验证在终端里启动 CLI 之前先跑一句curl http://127.0.0.1:你的端口/v1/models如果返回的是 CC Switch 或上游服务的模型列表说明代理在。如果连接被拒绝那问题就在代理本身。CLI 进不来请求时基本可以肯定是环境变量问题不要再去怀疑模型配置。6. 我的一些实操心得和避坑建议6.1 把常用配置整理成脚本模板我后来把常用的启动流程做成了一个 shell 脚本放在项目目录外比如~/scripts/cc-switch-dev.sh。每次准备开发前先启动 CC Switch然后执行一行脚本加载所有环境变量再启动对应的 CLI。这个方式最大的价值是减少重复输入也避免每次手敲 Key 时不小心敲漏字符。脚本里我会用注释标明每个变量是从哪个 provider 映射来的这样半个月后再看也能想起来。6.2 别忽视升级带来的配置结构变化前文提过从 3.16.0 升到 3.16.1 丢配置的事这里再补一句有些版本升级不会丢配置但可能会改变日志格式、默认端口或者模型映射的读取逻辑。如果你发现升级后原本能用的模型突然报错先看官方更新说明里有没有“模型映射 key 命名变化”。我基本已经养成习惯每次升级后先跑一个最小测试确认主线功能不受影响再去继续手头工作。6.3 把“要用什么模型”想清楚再配置最后分享一个方法论上的经验CC Switch 只是工具它的上限取决于你对模型的理解。如果你只是想让 Codex 能跑起来随便配一个便宜模型就够了不用追求最大最强的版本。要是在做复杂代码重构或长上下文分析就该选上下文窗口更大、推理能力更强的模型。配置多个 provider 没有错但别让模型切换变成日常写代码的负担我最终常用的只有一两个 provider其他都是临时测试用的。我在实际使用中发现CC Switch 真正要“顺利使用”一半在配置正确另一半在养成固定的使用节奏下载前看更新说明、配置后立刻测试、切换模型先开新会话、报错时按三层链路排查。把这几点做成肌肉记忆你会发现它远没有控制台里那一堆眼睛的报错看起来那么可怕。