上个月我把 Cascade 默认模型从 gpt-6-sol 升到 gpt-6.1-sol本来以为只是把模型名改掉的小事结果在 provider 配置上折腾了一整个下午。报错信息五花八门从 the gpt-6.1-sol model is not supported when using codex with a... 到 no api key for provider route...中间还夹杂着免费额度限制的提示。回头复盘问题几乎都出在同一个地方路由变更。这篇指南我会把这次迁移的完整过程拆开讲包括 Cascade 自定义 provider 的配置结构、从旧模型切换到新模型到底改了哪些字段、哪些报错对应什么根因以及我在实际切换过程中积累的几条经验。适合正在用 Windsurf、想把 Cascade 接到自建网关或第三方模型服务的开发者参考也适合刚从旧版本模型迁移到新版本、被路由规则卡住的人。1. 为什么 gpt-6-sol 的配置直接搬过不了迁移前后的路由模型差异1.1 旧配置能跑、新配置报错问题出在路由层而不是模型层先说一个很多人容易误判的地方模型升级通常不会破坏 OpenAI 兼容接口的基本请求格式。gpt-6-sol 到 gpt-6.1-sol本质上只是model字段里的字符串变了baseUrl、apiKey、请求体结构这些理论上完全不用动。如果你只是把配置里的模型名从gpt-6-sol改成gpt-6.1-sol最理想的情况下确实直接能用。但实测下来只要你的模型不是走官方 API而是通过某个 API 网关、中转服务或者自建代理接入情况就完全不同了。这类网关通常会把模型名当成路由键来用你请求里写的model字段决定了这个请求被转发到哪条上游通道、使用哪个密钥、计费规则是什么。有些网关做得更细还会区分用户侧模型名和内部路由名两者之间有一层映射关系。所以你会看到一种很典型的现象旧配置明明运行正常把模型名一改立刻报model not found或model is not supported。这不是因为模型本身不存在而是因为网关的路由表里根本没有gpt-6.1-sol这条新规则或者新规则对应的上游通道还没被正确激活。1.2 模型名与路由名的关系API 网关如何区分别名、版本和上游为了把这个讲清楚我用一个生活化的类比。你可以把模型名想象成快递单上的收件人姓名路由规则想象成快递分拣中心的分拣逻辑。同一个小区里住着张伟和张伟明快递单上如果只写张伟分拣员会按历史记录投递但如果你写了一个新名字张伟明分拣中心必须先确认这个人在不在系统里、门牌号是哪一户否则快递就只能滞留。网关处理模型请求也是这个逻辑模型名model alias你在客户端里填的标识通常是gpt-6.1-sol这种好记的名字。路由名route网关内部用来匹配上游服务的标识可能叫gpt61-sol-route、v3/openai/gpt61-sol或者其他任意字符串。上游端点upstream真正执行推理的服务地址。当网关收到你的请求时会先读取model字段然后到自己的路由表里查找对应配置。如果路由表里只有gpt-6-sol → upstream-A你发gpt-6.1-sol过去网关大概率返回model not found不会自动帮你把新模型名映射到旧上游。也不会因为你改了版本号就智能匹配。有些网关支持直通模式即 model 字段直接原样透传给上游这种情况下模型名和路由名完全一致升级版本只需要确认上游认这个名字。但如果你用的是那种强调路由管理的网关比如带多租户、多密钥、多上游负载均衡的网关就必须显式配置新模型对应的路由规则。1.3 升级前先确认三件事模型名、路由地址、鉴权方式根据这次迁移的教训我强烈建议在动手改配置之前先回答下面三个问题任何一个不确定都先不要动新模型在网关里的准确名称是什么注意大小写、版本号后缀、连字符。gpt-6.1-sol和gpt-61-sol是两回事。如果你是从网关文档上复制来的小心复制到不可见字符。这个新模型走的是同一个 baseUrl还是一个全新的路由地址很多网关会把新版本模型放在新路径下旧路径只能访问旧模型。比如旧地址是https://api.example.com/v1新地址可能是https://api.example.com/v1/routing/gpt-6.1-sol。新模型是否沿用旧密钥部分网关按模型路由绑定独立密钥旧密钥的权限范围只覆盖到gpt-6-sol新模型需要申请新密钥。把这三件事弄清楚后面的迁移就只剩机械操作。我当时就是跳过了第一个问题默认新版本只是后缀变化结果被网关的版本路由隔离策略卡了很久。2. Cascade 自定义 provider 的完整配置清单从入口到验证2.1 找到 Windsurf 里的 provider 设置入口Windsurf 的配置入口有几个层级容易搞混。先说结论Cascade 能使用的模型列表来自IDE 设置面板中的 Model Providers 配置不是随便在配置文件里写个 JSON 就能生效的。具体路径在不同版本里略有差异。目前我使用的是打开 Windsurf → 点击左下角设置或者通过命令面板搜Preferences: Open Settings→ 找到 AI / Model Providers 相关标签页。这里能看到当前已配置的 provider 列表以及 Cascade 默认使用的模型。如果你更习惯手工编辑配置文件也可以直接改 Windsurf 的数据目录下的配置文件。macOS 通常在~/.codeium/windsurf/下Windows 在%USERPROFILE%\.codeium\windsurf\下。文件里记录了 provider 的 JSON 片段修改后重启 IDE 生效。注意这个文件可能被 IDE 自动覆盖所以不建议在 IDE 运行时手动改。还有一个常见的误区Windsurf 的项目级配置比如.windsurfrc里也可以指定模型但那是做项目级规则限制用的和全局 provider 配置是两套体系。我在迁移的时候一开始只改了项目级配置结果 Cascade 下拉框里的模型列表完全没变化后来才发现改错了地方。2.2 配置文件的字段逐项说明下面是一个标准的 Cascade 自定义 provider 配置示例结构以 OpenAI 兼容接口为基准{ providers: { sol-gateway: { name: Sol Gateway, baseUrl: https://api.example.com/v1, apiKeyEnv: SOL_GATEWAY_API_KEY, models: [ { name: gpt-6.1-sol, routing: gpt-6.1-sol } ] } } }各字段的含义providersprovider 集合的根节点里面的键名这里是sol-gateway是 provider 的内部 ID你自己定义但建议用有意义的名称方便后续在日志里排查。name显示名称会出现在 Cascade 的模型下拉框里。baseUrl网关的 OpenAI 兼容端点地址。注意这里填的是地址根路径通常以/v1结尾不要把具体的模型路径拼进去。apiKeyEnv读取 API 密钥的环境变量名。这里填写的是环境变量的名字不是密钥本身。Windsurf 在发起请求时会从这个环境变量里取值放进Authorization头。models该 provider 下可用的模型列表。每一项至少包含name字段有些配置还需要routing字段来声明网关内部路由名。如果你用的网关要求显式指定路由名但 Windsurf 的 UI 上又没有单独路由输入框通常的变通办法就是利用models数组配置让name保持为你在 Cascade 里想看到的模型名而把routing设置成网关实际识别的名称。如果你的网关不支持这种方式就要回到网关管理界面把新模型名注册为别名。2.3 如何在 Cascade 下拉框里看到模型并选定配置写好后需要重启 Windsurf 才会重新读取 provider 列表。重启后在 Cascade 对话输入框上方的模型选择器里应该能看到名为 Sol Gateway 的 provider 以及gpt-6.1-sol模型。如果你使用的 Cascade 版本支持斜杠命令也可以直接在输入框里输入模型切换命令。我手上的版本是/model命令输入后会弹出可切换的模型列表选择即可。这里有几个我踩过的细节如果你在配置里把name和routing都写成了gpt-6.1-sol但下拉框里出现了两个同名选项说明你的 provider 配置文件中存在重复项检查一下是否旧配置和新配置同时生效。如果重启后模型列表里只有旧模型没有新模型优先检查 JSON 格式。配置文件的解析容错率很低少一个逗号或引号都会导致整个 provider 被忽略。如果新模型在下拉框里是灰色的不可选状态说明 Windsurf 认为该模型与当前 Cascade 模式不兼容。常见原因是模型在网关侧被标记为纯代码补全模型不支持 agent 式对话请求需要到网关注册页面确认模型能力类型。3. 从 gpt-6-sol 迁移到 gpt-6.1-sol四步路由变更实操3.1 第一步确认上游端点的路由兼容性不要一上来就改配置先用一个最小的请求测试网关是否认这个新模型。这一步能帮你把网关层问题和客户端配置问题区分开。我通常用 curl 直接打网关的 chat completions 接口curl -X POST https://api.example.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $SOL_GATEWAY_API_KEY \ -d { model: gpt-6.1-sol, messages: [{role: user, content: ping}], max_tokens: 10 }观察返回返回正常的choices内容说明网关侧路由没问题问题只在 Windsurf 配置。返回model not found说明网关路由表里还没有gpt-6.1-sol需要到网关管理界面创建新路由或别名映射。返回401 unauthorized或invalid api key说明当前密钥没有访问新模型的权限。返回model is not supported说明模型存在但不支持当前请求模式比如你用了chat/completions但该模型只支持补全接口。另外注意看返回头里的X-Route-Id或类似字段取决于网关实现。有些网关会把命中的路由名回显出来你可以确认新模型是否真的落到了新上游而不是被网关降级到旧模型。3.2 第二步修改 provider 配置旧 vs 新对照表网关侧确认无误后再回来改 Windsurf 的 provider 配置。下面是一份典型的旧到新对照配置项旧配置gpt-6-sol新配置gpt-6.1-sol说明models[].namegpt-6-solgpt-6.1-solCascade 下拉框显示的名称models[].routinggpt-6-solgpt-6.1-sol网关内部路由名按网关文档填写baseUrlhttps://api.example.com/v1https://api.example.com/v1如果新模型在同一端点下则不变apiKeyEnvGPT6_SOL_API_KEYGPT61_SOL_API_KEY如果网关按模型分配密钥则需变更nameprovider名sol-gatewaysol-gateway-v2建议保留旧 provider 并新建 v2便于回滚关于routing字段不同网关的叫法不同有的叫route、model_alias、upstream_model。如果你的网关文档里没有明确提到路由概念而且 baseUrl 不同那就优先确认 baseUrl 是否需要改变。比如新模型的路由变成了https://api.example.com/v1/routing/gpt-6.1-sol那baseUrl也要跟着改否则请求会打到旧路径上。3.3 第三步更新环境变量与密钥路由这一步最容易被忽略但恰恰是最容易引发诡异报错的地方。我在迁移时就遇到过配置文件全改对了模型名也是新的但是 Cascade 发送请求后网关返回no api key for provider route。原因在于网关的密钥体系往往也跟路由绑定。gpt-6-sol用的密钥可能只在该模型的路由范围内有效。你升级到gpt-6.1-sol之后如果还让 Windsurf 读取旧的GPT6_SOL_API_KEY网关查询新模型的路由权限时发现密钥不匹配于是干脆报 no api key。处理办法到网关后台确认新模型使用的密钥或者确认旧密钥是否已自动获得新模型的权限。在环境变量里新增对应的变量名。比如原来配置里写apiKeyEnv: GPT6_SOL_API_KEY新配置就写apiKeyEnv: GPT61_SOL_API_KEY然后在 shell 配置文件~/.zshrc或~/.bashrc里导出这个变量export GPT61_SOL_API_KEYsk-your-new-key让环境变量生效source ~/.zshrc然后完全退出并重启 Windsurf。注意Windsurf 通常只会读取启动进程时的环境变量中途 export 不会影响已经运行的实例。如果你用的是 IDE 内置终端它可能继承的是 GUI 应用的环境变量这个来源跟终端 shell 不完全一致。最稳妥的做法是退出 Windsurf从终端启动或者在启动脚本里显式声明环境变量后再打开应用。3.4 第四步用一次简单对话做端到端验证配置一切都改完后不要直接开始写业务代码先用最小验证跑通链路。我的习惯是重启 Windsurf 后在 Cascade 对话框选择gpt-6.1-sol模型。发送一个最简单的请求请回复我 OK。观察 Cascade 的响应速度和回复内容是否符合预期。如果这一步通过了基本可以确认路由、密钥、模型名三层都正常。如果报错再按下一节的诊断方法定位。有一个值得注意的点Cascade 是 agent 模式它会自动决定是否调用工具。哪怕你只让它回复 OK它也可能先尝试读取项目文件。因此严格来说最简单的端到端验证最好在空白目录里做避免 Cascade 因为项目上下文问题额外触发报错干扰你对 provider 配置的判断。4. 迁移过程中常见的四类报错与排查思路4.1 the gpt-6.1-sol model is not supported when using codex with a...这类报错我见过两种触发场景。第一种是你在 Windsurf 里选择了 Codex 模式的集成而网关侧没有为gpt-6.1-sol开启 Codex 协议支持。本质上这不是 Windsurf 的问题而是网关的路由规则里对新模型的协议支持范围做了限制。第二种是网关兼容层尝试把 OpenAI 格式请求转换成 Codex 格式但新模型的名字不在转换白名单里。排查思路确认 Windsurf 当前调用 Cascade 时使用的是哪种协议通道。不同版本、不同设置下可能走 OpenAI chat completions也可能走 Codex 风格接口。到网关管理后台查看新模型是否勾选了支持 Codex / Agent 请求之类的选项有些网关默认只放开 chat 模式agent 模式需要单独授权。如果你无法修改网关侧配置试试在 provider 配置里不要放两个模型共用的同一个routing。因为路由混用会导致网关无法判断该走哪个协议分支。我在实际迁移中最后是把这个模型单独分配了一条路由并从 Cascade 的模型选项中移除旧模型报错才消失。如果你也有多个模型共用 provider优先检查是不是路由名重复导致协议匹配错乱。4.2 free tier can only be used from wi...免费层使用受限这条报错一般来自网关而不是模型本身。它出现的背景通常是你用的 key 属于某个免费套餐而免费套餐绑定了一系列使用条件比如必须从特定出口 IP、特定工作区或特定账号发起请求。模型从gpt-6-sol升级到gpt-6.1-sol后网关可能把新模型划入了付费路由免费 key 自然没有访问权限。遇到这种报错不要纠结于为什么之前能白嫖。本质上是权限范围问题。对应的解法在网关后台查看该模型的计费策略确认当前 key 的套餐是否覆盖新模型。如果只是临时验证可以先申请一个试用 key 或调整 key 的模型绑定范围。如果你在 Windsurf 里同时配置了多个 provider注意检查 Cascade 实际使用的是哪个 key。有时候你以为走的是付费 key实际上因为apiKeyEnv拼写错误Windsurf 悄悄回退到了空 key然后网关把空 key 当成免费套餐处理抛出了这个错误。4.3 no api key for provider route ...这条报错信息通常长这样llm-deepseek: no api key for provider route deepseek-official或者no api key for provider route sol-gateway。虽然报错里可能出现你完全没配置过的 provider 名字但根因几乎都一样实际请求发生时Windsurf 没有从环境变量里读到 key。排查顺序建议如下打开配置文件确认apiKeyEnv字段的拼写注意是不是多了空格或下划线。比如SOL_GATEWAY_API_KEY和SOL_GATEWAYKEY就差一个字符但系统不帮你纠错。在终端里执行echo $SOL_GATEWAY_API_KEY确认环境变量在当前 shell 里存在。检查你的 shell 配置文件。如果你用的是 macOS 的 zsh而 Windsurf 是从 Finder 启动的它读不到~/.zshrc里的 export因为 GUI 应用不经过终端登录流程。如果你把 key 写进了.env文件要确认 Windsurf 是否真的会自动加载改.env。不同的启动方式行为不同最保险的方式是显式设置环境变量后再启动应用。另外有些网关的报错会把 provider 内部 ID 暴露出来比如这条报错里的sol-gateway你可以拿它去对照配置文件的providers键名确认是不是多条配置互相覆盖了。4.4 模型列表刷新不出来的处理迁移后最闹心的还不是报错而是配置明明改对了Cascade 下拉框里就是看不到新模型。我这次也遇到了后来总结出三个可能原因配置文件被 IDE 覆盖Windsurf 在某些版本里会维护一份内部缓存你手动改了配置文件IDE 在退出时不一定会把内存里的状态同步到磁盘反而可能用旧状态覆盖你的手写配置。解决办法是先退出 Windsurf再修改配置文件最后重新打开。JSON 语法错误我一度没注意到routing字段末尾多了一个逗号导致整个 provider 解析失败。Windsurf 的配置解析不会给你明显的弹窗提示只会默默忽略这个 provider。建议修改后用任意 JSON 校验工具先验证。缓存未刷新部分版本的下拉框模型列表会缓存一段时间。最直接的处理是删除 Windsurf 的缓存目录后重启。注意删除前备份配置文件避免缓存目录和配置目录重叠误删。如果你对这几点都不放心最粗暴但有效的方法新建一个 provider把新模型单独放到里面下拉框里就一定会出现新选项。这比反复折腾旧 provider 要快得多。5. 实测经验多 provider 并存、回滚预案和团队协同配置5.1 新旧 provider 并存不要删旧配置迁移的第一个原则别手贱删掉旧配置。我在这次升级中最庆幸的就是保留了sol-gateway这个旧 provider。因为新模型上线后你无法预知它在你的典型工作流里表现如何。如果 Cascade 拉取代码上下文、执行命令、修改文件的行为出现异常你需要一个能一键切回的选项而不是重新回忆旧配置长什么样。实际操作上我建议把旧配置原样保留新增一个sol-gateway-v2provider 用来放gpt-6.1-sol。两个 provider 并存在模型下拉框里随时切换。等新模型稳定使用两周以上再考虑是否清理旧 provider。5.2 回滚场景模型质量不满意如何快速切回万一新模型在某个项目里的表现不如旧模型回滚动作应该尽可能轻。这里有个小技巧不要修改配置文件直接在 Cascade 的模型选择器里切回旧 provider 下的gpt-6-sol即可。不过我建议你在切回之前先在两个模型之间跑一遍相同的任务把响应结果对照一下。比如让 Cascade 读同一个文件、做同一个重构观察它的提问方式、代码修改范围、对项目上下文的理解程度。不要只看感觉新模型变笨了或者旧模型比较稳。我用这种方式对比过几次发现很多时候是提示词上下文影响了表现跟模型升级没有直接关系。如果你同时改了系统提示词和模型那更要谨慎归因。5.3 团队共享配置时密钥独立如果你的团队把 Windsurf 配置放在 Git 仓库里共享注意一个细节永远不要把 API 密钥明文写进配置文件。正确做法是使用apiKeyEnv指向环境变量让每个人在本地单独设置自己的密钥。举个例子假设团队共有sol-gateway-v2provider配置文件里只写{ providers: { sol-gateway-v2: { name: Sol Gateway V2, baseUrl: https://api.example.com/v1, apiKeyEnv: SOL_GATEWAY_V2_API_KEY, models: [ { name: gpt-6.1-sol, routing: gpt-6.1-sol } ] } } }然后每个成员在自己的~/.zshrc里导出各自的SOL_GATEWAY_V2_API_KEY。这样即使仓库配置泄露也不会直接把密钥带出去。另外建议在 Git 里忽略.env文件如果有.env.example模板只放变量名不放真实值。团队里如果同时有人在用旧模型、有人用新模型更要把 API key 的命名跟 provider 一一对应。我见过最乱的情况是多个 provider 的apiKeyEnv指向同一个环境变量导致一人换 key 全员受影响。给每个 provider 使用独立的环境变量名是最省心的做法。5.4 Cascade 提示词配合模型版本升级时的小调整模型从gpt-6-sol升级到gpt-6.1-sol跟随变更的还有 Cascade 的系统提示词。但这里我强烈建议升级当天先保持提示词不动观察一天再决定要不要改。原因是模型版本升级往往会在指令遵循能力、工具调用频次、代码风格偏好上有细微变化。如果你同时修改了模型和一堆提示词规则出了问题你根本无法定位是模型不适应还是提示词写法不兼容。我遇到过类似情况新版本模型对只修改指定函数不要动其他部分这类指令的更严格遵守导致 Cascade 在旧规则下频繁询问确认看起来像变笨了其实是指令风格需要适配。等新模型跑顺后你可以逐步调整。比如把每次修改前先说明修改计划这类提示词从强约束改成弱约束让新模型在 agent 模式下减少不必要的确认步骤。但每改一条规则单独验证一下对终端用户的影响别一次性改一堆。最后分享一个这次迁移给我留下的最深印象大多数配置问题都不是Windsurf 不会配而是模型名、路由名、密钥名这三层之间没有形成闭环。每次报错都值得把这些名称逐个核对一遍而不是盯着错误信息看半天。如果你正卡在某一步不妨按这篇的顺序重新走一遍大概率能定位到问题所在。