企业官网建设流程全解析

上个月我把 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" } ] } } }

各字段的含义：

• providers：provider 集合的根节点，里面的键名（这里是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 配置。下面是一份典型的旧到新对照：

关于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。

处理办法：

1. 到网关后台确认新模型使用的密钥，或者确认旧密钥是否已自动获得新模型的权限。
2. 在环境变量里新增对应的变量名。比如原来配置里写apiKeyEnv: "GPT6_SOL_API_KEY"，新配置就写apiKeyEnv: "GPT61_SOL_API_KEY"，然后在 shell 配置文件（~/.zshrc或~/.bashrc）里导出这个变量：

export GPT61_SOL_API_KEY="sk-your-new-key"

3. 让环境变量生效：source ~/.zshrc，然后完全退出并重启 Windsurf。注意，Windsurf 通常只会读取启动进程时的环境变量，中途 export 不会影响已经运行的实例。

如果你用的是 IDE 内置终端，它可能继承的是 GUI 应用的环境变量，这个来源跟终端 shell 不完全一致。最稳妥的做法是退出 Windsurf，从终端启动，或者在启动脚本里显式声明环境变量后再打开应用。

3.4 第四步：用一次简单对话做端到端验证

配置一切都改完后，不要直接开始写业务代码，先用最小验证跑通链路。我的习惯是：

1. 重启 Windsurf 后，在 Cascade 对话框选择gpt-6.1-sol模型。
2. 发送一个最简单的请求："请回复我 OK"。
3. 观察 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。

排查顺序建议如下：

1. 打开配置文件，确认apiKeyEnv字段的拼写，注意是不是多了空格或下划线。比如SOL_GATEWAY_API_KEY和SOL_GATEWAYKEY就差一个字符，但系统不帮你纠错。
2. 在终端里执行echo $SOL_GATEWAY_API_KEY，确认环境变量在当前 shell 里存在。
3. 检查你的 shell 配置文件。如果你用的是 macOS 的 zsh，而 Windsurf 是从 Finder 启动的，它读不到~/.zshrc里的 export，因为 GUI 应用不经过终端登录流程。
4. 如果你把 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 不会配"，而是"模型名、路由名、密钥名这三层之间没有形成闭环"。每次报错都值得把这些名称逐个核对一遍，而不是盯着错误信息看半天。如果你正卡在某一步，不妨按这篇的顺序重新走一遍，大概率能定位到问题所在。