Windsurf 后端把模型从 gpt-6-sol 升级到 gpt-6.1-sol 之后最折磨人的往往不是模型本身而是 Cascade 里那些对不上的 provider 路由。你明明把模型名改成了 gpt-6.1-solCascade 却照样报“模型不支持”、路由找不到 API key甚至整个对话直接断掉。这篇就当一次完整的迁移笔记把从 gpt-6-sol 切到 gpt-6.1-sol 过程中Windsurf 的 Cascade 自定义 provider 到底要怎么改、路由变更影响哪些配置、迁移后哪些报错要重点排查一条条讲清楚。适合正在用 Windsurf 做 AI 编程、需要把 Cascade 指向自建网关或第三方聚合模型服务的开发者和运维。1. 迁移之前先理解 Cascade 的 provider 路由1.1 provider 路由的实质三个字段的绑定关系很多人以为换模型就是改一个名字实际上 Cascade 的自定义 provider 路由本质是三个字段的绑定关系provider 标识也就是路由名、Base URL、模型名。这三者不是互相独立的。Windsurf 拿到你的对话请求后会根据你选择的模型去匹配配置里对应的 provider 路由再通过这条路由把请求转发给后端服务。从 gpt-6-sol 迁到 gpt-6.1-sol 的时候最容易忽视的是第一个字段。很多聚合网关会把模型的“对外调用名”和“路由前缀”绑在一起比如旧的 gpt-6-sol 走的是/v1/sol/legacy这一条路径新的 gpt-6.1-sol 换到了/v1/sol/stable。这时候你只改模型名、不动 Base URL请求就会打到一条已经不存在的路由上轻则 404重则被网关判定为非法调用。我之前迁移时先列了一张变更清单把三个字段逐项对照改完一项勾一项后面排查省了很多事变更项迁移前gpt-6-sol迁移后gpt-6.1-sol影响范围模型名gpt-6-solgpt-6.1-solCascade 对话请求体Base URL 路径/v1/sol/v1/sol/stable请求转发路由默认上下文窗口128K200K对话历史裁剪策略API Key 作用域全部模型共用按新路由重新校验鉴权与计费1.2 为什么这次不是“改个名”就能收工模型名从 6-sol 变到 6.1-sol通常不只是小版本号变化。从服务端的角度看这次迁移至少碰了四层东西路由、鉴权、参数协议、上下文窗口。路由变了新模型往往挂在新网关路径下旧路径可能在某个时间点直接下线而不是继续做兼容。鉴权可能变新路由有可能要求新的 API Key 前缀或者要求额外带一个X-Route-Version之类的请求头旧的 Key 在旧路由上有效在新路由上直接 401。参数协议变了gpt-6.1-sol 如果调整了temperature的合法范围或者加入了新的reasoning_effort参数你在 Cascade 里旧的参数模板就要跟着改。上下文窗口放大了从 128K 到 200K 这种变化会让 Cascade 的自动裁剪策略失效。如果配置里还写死 128K等于白白浪费新模型的上下文能力还有可能在长会话中途触发异常截断。所以迁移的核心不是“知道新模型叫什么”而是搞清楚新模型对应的完整路由长什么样。我在动手前会先给网关管理员发个消息或者翻一下网关的接口文档确认这三个关键信息新模型的模型名、Base URL、是否要求新的鉴权头。这一步不做后面配置得再漂亮都是空中楼阁。2. Windsurf 里自定义 provider 的两种配置路径2.1 界面配置适合快速验证路由是否通Windsurf 的模型设置入口在 Settings快捷键Cmd,或Ctrl,里搜索“Language Models”可以看到模型管理区域。想接自定义 provider 时选择添加自定义模型或自定义 Provider然后填三个东西Provider 名称这个只做展示用可以填“Sol Gateway”这种便于识别的名字。Base URL网关的地址注意要填到 OpenAI 兼容接口那一层比如https://your-gateway.example.com/v1不要直接填到域名根路径。模型名这里填的是网关对外公布的模型名也就是gpt-6.1-sol不是你在服务端内部叫的名字。界面配置适合第一次验证。我迁移时习惯先走界面填好之后立刻开一个新的 Cascade 对话让它执行一个最简单的任务比如“用一句话解释这个项目结构”。如果响应正常说明 Base URL、模型名、鉴权这三个核心要素已经对齐如果报错再往下排查。界面配的好处是即时反馈省得反复改配置文件还得重启。2.2 直接改配置文件适合批量部署和版本管理界面配好之后Windsurf 会把配置落到本地的settings.json里。不同系统的路径不一样Windows%APPDATA%\Codeium\Windsurf\settings.jsonmacOS~/Library/Application Support/Codeium/Windsurf/settings.jsonLinux~/.config/Codeium/Windsurf/settings.json打开这个文件你会看到 Language Models 相关的配置段。迁移后的配置大概长这样{ languageModels: { enabled: true, providers: [ { id: sol-gateway, displayName: Sol 模型网关, baseUrl: https://your-gateway.example.com/v1/sol/stable, apiKey: sk-yOUR-NEW-ROUTE-KEY, models: [ { name: gpt-6.1-sol, contextWindow: 200000, supportsReasoning: true } ] } ] } }注意不同版本的 Windsurf 对配置字段的命名有细微差异有的版本用providers有的用customProviders更新前最好先看一眼当前版本的 schema。真正关键的是baseUrl、apiKey、models[].name这三个字段它们对应的就是前面说的路由三要素。直接用配置文件的好处是可控。我会把旧的 gpt-6-sol 配置也保留在同一个 providers 数组里只是把路由指向一个备用地址这样一旦新模型出问题切回去只是一行配置的事。2.3 API Key 的存放方式别踩坑在配置文件里直接写明文 API Key 是最省事的方式但也是最危险的方式。如果你的settings.json会同步到公司仓库或者放进 dotfiles 管理那这个 Key 基本等于公开了。我的做法是用环境变量占位符{ apiKey: ${SOL_ROUTE_API_KEY} }然后在 Windsurf 启动前把它注入到系统环境变量里。macOS / Linux 可以在~/.zshrc里加一行export SOL_ROUTE_API_KEYsk-xxxWindows 可以用setx SOL_ROUTE_API_KEY sk-xxx。这样配置仓库只留一个占位符真实 Key 隔离在本地环境。还有个细节Windsurf 启动时如果读取不到环境变量会直接判定该 provider 没有可用的 API Key。所以不要只改配置不设环境变量否则常见报错里“no api key for provider route”就会找上门来后面第 4 节会专门展开。3. 从前到后的迁移实操步骤3.1 第一步备份并盘点现有配置动手前先备份。把settings.json复制一份到旁边命名成settings.json.bak-gpt6sol这是个成本几乎为零但收益很大的习惯。然后打开当前配置把所有跟 gpt-6-sol 有关的字段记下来Base URL、模型名、上下文窗口设置、请求头里有哪几个自定义字段。为什么要先盘点因为迁移之后如果 Cascade 的行为变了你得能区分是模型本身的行为差异还是配置迁移过程中丢了某个参数。没有基线对比排查起来全靠猜。3.2 第二步确认新模型的路由信息这一步决定了迁移的成败。拿出网关侧给出的接入文档确认以下信息并记到便签上新模型完整名称gpt-6.1-sol新 Base URL 完整路径注意区分/v1还是/v1/sol/stable这种子路径API Key 是否沿用旧 Key还是需要重新申请是否需要额外的请求头比如X-Provider-Route: gpt-6.1-sol这一步我看着像废话但实际上很多人跳过它直接填配置然后去问网关管理员为什么报错。新模型如果要求加一个路由请求头而你没加网关会返回 401 或者“model not supported”之类的错误。你把时间花在排查 Windsurf 配置上就完全跑偏了。3.3 第三步修改配置并做最小化验证界面配置或者改配置文件都行改完之后重启 Windsurf。打开 Cascade 面板确认模型选择器里已经能显示gpt-6.1-sol。新建一个会话先跑一句简单的自然语言指令比如“列出当前文件里的所有 TODO”。观察响应是否正常以及请求的延迟和返回格式。这里特别提醒第一次验证不要开长文档不要让它分析整个仓库。最小化验证的目的是把配置问题暴露在最短链路里。如果最简单的指令都不通说明问题在模型名或鉴权上如果简单指令通了、长任务挂了再往上下文窗口或参数协议方向排查。我迁移时第一次验证就是让它“告诉我今天的日期”一条消息往返干净利落。3.4 第四步保留旧路由作为回滚通道新模型稳定跑两三天之前不建议直接删除 gpt-6-sol 的配置。我在配置里保留了旧 provider只是把它的模型语义改成“legacy”并且把旧路由的 Base URL 指向网关的兼容端点。这样做的好处是一旦 gpt-6.1-sol 在长会话中出现不稳定比如频繁超时、响应截断我可以只用两步切回旧模型Cascade 模型选择器里选回 gpt-6-sol然后继续正常干活。等新模型跑稳了再清理旧路由也不迟。4. 迁移过程里最容易踩的三个坑4.1 “model is not supported” 到底在说谁不支持迁移替换模型名之后最常见的报错是类似于the gpt-6.1-sol model is not supported when using codex with a...这种信息。很多人看到“codex”就懵了心想我又没用 codex。其实这里的关键在于你的网关可能同时对接多种客户端协议Windsurf 的 Cascade 也是通过一套协议去调后端的网关需要把“模型名 客户端场景”映射到具体路由。当它返回“model is not supported”通常有两种可能你填的模型名和网关公布的完全不一致多一个空格、少一个后缀都不行。该模型名在当前调用协议下被网关禁用了比如只允许通过浏览器端 UI 调用不允许通过 API 直连。排查方法是直接到网关的文档里搜模型名看看有没有标注“支持协议/场景”再对比 Windsurf 里填的字符串。还有一个野路子用 curl 直接手动打一次网关接口把 Cascade 的请求体复刻一遍看网关返回什么。如果 curl 能通、Windsurf 不通问题就在 Windsurf 侧的路由配置如果 curl 都不通那就要找网关管理员确认模型名和调用权限。4.2 “no api key for provider route” 的根因通常在环境变量报错信息里带类似no api key for provider route deepseek-official这种字样指的是某条 provider 路由没有配置 API Key。这里有个容易混淆的点报错里出现的路由名不一定是你在 Windnsurf 里配的那条。如果你同时配置了多个 provider比如 Sol 网关出于兼容还挂了一个 DeepSeek 官方模型而你在环境变量里只给 Sol 网关配了 Key没给 DeepSeek 那条路由配Cascade 在做模型列表预检时就会整体报“no api key”。解决思路分两步走。先看 Windsurf 模型选择器里是否已经存在不可用的 provider把这些不可用的 provider 临时禁用或干脆删除然后检查环境变量名称是否和配置里的占位符完全一致。占位符是${SOL_ROUTE_API_KEY}环境变量就别设成SOL_API_KEY少一个词的差异都读不到。4.3 免费层限制的报错先确认 Key 的授权范围迁移后如果在别的工具里测试同一个 Key可能会碰到类似error from provider (console): opencodes free tier can only be used from wi...的报错。这种提示的意思是网关对免费层流量做了来源限制你的 Key 虽然有效但只能在特定客户端或特定来源里使用。这其实不是 Windsurf 的配置问题而是 Key 的授权策略在起作用。遇到这种报错正确动作是回到网关控制台查一下这个 Key 的授权来源绑定情况看看是不是只允许从特定域名或特定应用调用。如果 Key 要同时给 Windsurf 和别的工具用通常需要在网关里申请更高级别的访问凭证或者手动把目标来源加入白名单。这里特别提醒不要在免费的公共 Key 上折腾太久该升级升级跟着报错信息走才省时间。4.4 排查速查表把迁移期间遇到过的问题整理成一张速查表方便直接对照报错现象大概率原因优先排查动作model is not supported模型名匹配失败 / 权限不足对照网关文档核对模型名用 curl 直连验证no api key for provider route环境变量未注入 / provider 不可用检查${VAR}占位符与环境变量名是否一致401 unauthorizedAPI Key 失效或需要新 Key回到网关重新生成 Key核对 Key 作用域超长会话中途断掉上下文窗口配置偏小把contextWindow调到新模型实际值比如 200K请求能通但回答明显变差参数协议没跟上检查temperature等参数是否还在合法范围是否该加supportsReasoning5. 迁移完成后值得顺手做的三件小事第一件事把 Cascade 的默认模型切到 gpt-6.1-sol 之后顺手清理一下历史会话。不是删数据而是避免 Cascade 在长上下文里把旧模型的行为模式残留带到新会话中。迁移后第一次长任务如果感觉“和之前不一样”先开一个全新会话试一次很多时候问题自己就消失了。第二件事给配置目录加上版本管理意识。我个人的习惯是在本地建一个小的 dotfiles 仓库把settings.json的模板放进去但 Key 全部用占位符替换。这样下次再遇到模型升级直接 diff 一下就知道改了什么不用靠脑子记。第三件事验证一下 gpt-6.1-sol 在 Cascade 里的代码补全和对话两条链路的延迟。这两个功能在 Windsurf 里走的可能不是同一条路由。如果对话正常、但 Tab 补全没有生效基本可以确定补全链路还指着旧模型或者旧路由需要单独再配一条 provider。根据我个人的实操体会这类模型迁移只要把“Base URL、模型名、API Key、上下文窗口”这四个变量当成一个整体来改基本不会出大乱子。最怕的就是拆开来一个字段一个字段测试那样一旦报错你会分不清到底是哪一层出了问题。一个干净利落的路由变更应该是一次重启、一个配置块、一次最小化验证就能完成的。