Windsurf配置的API URL中包含路径参数,如何正确设置?

文章导读
配置 Windsurf 时,遇到 API URL 里带 {model} 这类占位符,最常见的问题是“该不该保留”。直接删掉可能会 404,写死成某个模型名又可能导致模型列表失效。下文按我通常的处理顺序走一遍,你可以对照自己拿到的是哪种 URL。
📋 目录
  1. 一 先判断它是不是路径参数
  2. 二 先原样填占位符试一次
  3. 三 用日志或代理看最终请求地址
  4. 四 两个容易被忽略的绕行坑
  5. 五 改之前留一条后路
A A

配置 Windsurf 时,遇到 API URL 里带 {model} 这类占位符,最常见的问题是“该不该保留”。直接删掉可能会 404,写死成某个模型名又可能导致模型列表失效。下文按我通常的处理顺序走一遍,你可以对照自己拿到的是哪种 URL。

先判断它是不是路径参数

先看提供方文档里的请求示例。如果示例地址是 https://api.xxx.com/v1/chat/completions/{model},而且大括号里是每次请求必须不同的值,就说明这是一个路径参数。Windsurf 的 API URL 填写框对应的是实际请求路径,不是站点根域名。若你把占位符删掉,服务端会认为你在访问另一个资源,经常返回 404 或路由错误,而不是认证失败。判断时可以把 URL 粘贴到普通浏览器里,如果只差模型名就报 404,基本可以确定路径参数不可省略。

这个方法适用的是文档里能直接看到请求示例的情况。把地址粘到浏览器时,要注意浏览器可能会先弹认证框,如果页面提示 401 而不是 404,说明路径本身能访问,问题出在没带凭证,不能据此判断路径参数可省略。另外,有的服务端会把缺省路径自动重定向到默认模型,这时删掉占位符也可能返回 200,所以“只差模型名就报 404”是一个很强的信号,但不是唯一标准。拿不太准时,可以再看服务端对错误消息的说明,有些 404 返回体里会带具体的路由提示。

先原样填占位符试一次

正确做法是先把带占位符的路径原样填进 API URL 栏,占位符写法跟随提供方,常见的有 {model} 和 :model。先不要手动把大括号替换成模型名,因为 Windsurf 可能会在请求时再追加模型名,或者从模型列表取用,手动固定容易造成路径重复。填完后保存,然后发送一条最简测试请求。如果返回 404,再把占位符改成实际模型名对照一次。两个结果不同,就说明 Windsurf 最终拼出的 URL 需要你保留占位符。

Windsurf配置的API URL中包含路径参数,如何正确设置?

这里的关键是把“先保留”当成基准状态。很多配置界面比我们预想的聪明,它会自动识别 {model} 并从模型列表取值,但有的版本只会把模型名追加到 URL 末尾。先保留占位符,再发一条最简测试,对比返回 404 还是 200,就能大致猜出 Windsurf 的拼接行为。如果返回 404,再把占位符改成真实模型名对照,这一组对比的差异会直接告诉你该不该保留。注意测试请求本身要简单,最好不带额外参数,否则报错原因可能混在一起。

用日志或代理看最终请求地址

检查方法是抓取 Windsurf 实际发出的请求地址。可以查看日志目录里的模型请求记录,或用 mitmproxy 这类代理工具拦截。正常的最终 URL 应该只包含一个模型名,且路径参数位置与文档一致。如果看到 URL 里出现两个模型名,或者占位符仍然是大括号,说明配置中混入了多余内容。对比 curl 手动请求:curl -v 'https://api.xxx.com/v1/chat/completions/{model}' 换成真实模型名后能通,而 Windsurf 内不通,就重点查它的拼接逻辑。

日志目录的位置和命名在不同系统上不一样,但思路是一致的:搜包含 chat/completions 的 URL。如果用 mitmproxy,记得先安装并信任证书,然后按 Host 过滤,只看 windsurf 发出去的请求。正常来说,最终 URL 里模型名只会出现一次。如果出现两个,比如路径里既有你填的 gpt-4,Windsurf 又追加了 gpt-4,那就是配置里混入重复内容。另一种情况是占位符仍然是大括号,说明 Windsurf 没有做变量替换,把它当成了普通字符。这时候再看配置界面里有没有单独的“模型名”输入框,如果有,就填在那里。

Windsurf配置的API URL中包含路径参数,如何正确设置?

两个容易被忽略的绕行坑

不要为了省事把所有请求的 URL 都固定成一个模型名。有些代理网关严格按路径里的模型名路由,比如你在 URL 里写了 model-1,即使 Windsurf 模型列表选择的是 model-2,实际请求仍会打到 model-1,很容易出现错卡或配额统计混乱。同样,把模型名挪到查询字符串里(例如 ?model=model-2)通常没有用,因为服务端解析路由时不会去读这个参数,经常直接返回 400 或 422。另外,如果保存配置时被拦截,先检查是否有全角花括号或多余空格,输入法自动转换是很常见的原因。

改之前留一条后路

不管最终选保留占位符还是替换成实际模型名,每次改动前先把当前能用的配置保存在文本文件里。路径参数相关的报错大多可以通过“换一种写法”来回滚,但如果你同时改了多个字段,出问题时就难以确认是哪一处导致。记录好 URL、模型列表名称、请求头这些关键项,出了问题先恢复原样,再试另一种方案。Windsurf 的模型配置可以多份并存,单独新建一个配置来测路径参数,等确认无误再切过去,也是一个省事的做法。

处理路径参数,核心动作就是先原样填占位符测,不行再换真实模型名。日志和 curl 用来确认问题出在配置界面还是拼接环节。由于不同提供方的路径要求不一样,Windsurf 各版本对占位符的处理也有差异,最终配置以你本机上的实测结果为准。