Windsurf 怎么配置 API 地址？2026 最顺手的接入方案，踩坑全记录

最强小杰
8 阅读6分钟

上周五我把 Cursor 的订阅到期了，想试试 Windsurf 换换口味。结果光是配个 API 地址就折腾了大半天——官方文档写得云里雾里，社区帖子又各说各话，有的配置方式在新版已经废弃了。最后我摸索出一套稳定能用的方案，顺便把几个大坑都记下来了，分享给同样在折腾 Windsurf 的朋友。

Windsurf 配置自定义 API 地址的核心步骤：打开 Settings → 搜索 "provider" → 选择 OpenAI Compatible → 填入你的 base_url 和 API Key → 选择模型即可。 整个过程 2 分钟搞定，但有几个隐藏的坑不踩一遍根本不知道。

先说结论

配置项推荐值说明
ProviderOpenAI Compatible兼容性最好，支持绝大多数聚合平台
Base URLhttps://api.ofox.ai/v1聚合接口，一个 Key 切换多模型
API Key你自己的 Key在对应平台生成
默认模型按需选，推荐 Claude Opus 4.6 / DeepSeek V3Windsurf 的 Cascade 对 Claude 系列优化最好
Streaming必须开启不开的话体验极差，逐字输出才跟得上思路

环境准备

  • Windsurf 版本：2026 年 6 月最新版（v1.x+），旧版 UI 和配置路径不一样，建议先更新
  • 一个可用的 API Key：官方直连的、聚合平台的都行
  • 网络环境：如果用聚合平台（如 ofox.ai），低延迟直连即可，不需要额外折腾网络

先确认你的 Windsurf 是最新版。老版本的配置入口藏得很深，新版统一到了 Settings 面板里，省心不少。

方案一：通过 Settings UI 配置（推荐新手）

最直观的方式，全程图形界面操作。

第一步：打开 Windsurf，点击左下角齿轮图标，或者用快捷键 Cmd + ,（Mac）/ Ctrl + ,（Windows）进入 Settings。

第二步：在搜索框输入 provider，找到 AI Provider Configuration 这一栏。

第三步：点击 Add Provider，选择 OpenAI Compatible。

第四步：填写关键信息：

Provider Name: ofox-aggregate（随便起个名字）
Base URL: https://api.ofox.ai/v1
API Key: sk-xxxxxxxxxxxx（你的 Key）

第五步：在 Model 列表里手动添加你要用的模型名称。这里有个坑，后面踩坑部分会讲。

配置完成后，在 Windsurf 的 Cascade 面板（就是那个 AI 对话窗口）右上角切换 Provider，选你刚添加的就行。

方案二：直接改 settings.json（老手推荐）

UI 配置有时候会抽风，我个人更喜欢直接改配置文件，确定性强。

打开命令面板 Cmd + Shift + P，输入 Open User Settings (JSON)，在 JSON 里加入以下配置：

{
 "windsurf.providers": [
 {
 "name": "ofox-aggregate",
 "type": "openai-compatible",
 "baseUrl": "https://api.ofox.ai/v1",
 "apiKey": "sk-xxxxxxxxxxxx",
 "models": [
 {
 "id": "claude-opus-4-20250918",
 "name": "Claude Opus 4.6",
 "maxTokens": 8192,
 "contextWindow": 200000
 },
 {
 "id": "deepseek-v3",
 "name": "DeepSeek V3",
 "maxTokens": 8192,
 "contextWindow": 128000
 },
 {
 "id": "gpt-5",
 "name": "GPT-5",
 "maxTokens": 16384,
 "contextWindow": 128000
 }
 ],
 "defaultModel": "claude-opus-4-20250918",
 "streaming": true
 }
 ]
}

保存后 Windsurf 会自动重载配置，不用重启。

验证一下配置是否生效，写个简单的测试：

# 这不是在 Windsurf 里跑的，是单独验证 API 连通性
from openai import OpenAI

client = OpenAI(
 api_key="sk-xxxxxxxxxxxx",
 base_url="https://api.ofox.ai/v1"
)

response = client.chat.completions.create(
 model="claude-opus-4-20250918",
 messages=[{"role": "user", "content": "说一句话测试连通性"}],
 stream=True
)

for chunk in response:
 if chunk.choices[0].delta.content:
 print(chunk.choices[0].delta.content, end="")

如果能正常输出，说明 Key 和网络都没问题，Windsurf 里大概率也能直接用。

方案三：环境变量注入（CI/CD 或多设备同步场景）

如果你像我一样在多台机器上用 Windsurf，每台都手动配一遍 Key 太蠢了。可以用环境变量：

# .bashrc 或 .zshrc
export WINDSURF_API_KEY="sk-xxxxxxxxxxxx"
export WINDSURF_BASE_URL="https://api.ofox.ai/v1"

然后 settings.json 里这样引用：

{
 "windsurf.providers": [
 {
 "name": "ofox-aggregate",
 "type": "openai-compatible",
 "baseUrl": "${env:WINDSURF_BASE_URL}",
 "apiKey": "${env:WINDSURF_API_KEY}",
 "models": [],
 "streaming": true
 }
 ]
}

这样配置文件可以安全地丢进 dotfiles 仓库，Key 不会泄露。

整体调用链路

graph LR
 A[Windsurf Cascade] -->|OpenAI 协议| B[ofox.ai 聚合网关]
 B --> C[Claude Opus 4.6]
 B --> D[GPT-5]
 B --> E[DeepSeek V3]
 B --> F[Gemini 3]
 B --> G[GLM 5 / Qwen 3 等]
 style A fill:#e1f5fe
 style B fill:#fff3e0

Windsurf 发出的请求走标准 OpenAI 协议，聚合网关根据你指定的 model 参数路由到对应的模型供应商。对 Windsurf 来说，它以为自己在跟一个 OpenAI 兼容服务通信，完全无感。

踩坑记录

这部分是精华，我花了大半天就是栽在这几个地方。

坑 1：模型 ID 不能瞎写

Windsurf 的 UI 配置里，添加自定义模型时有个输入框让你填 Model ID。我一开始填的是 claude-4.6-opus，死活报错。后来才发现，Model ID 必须跟 API 实际支持的 ID 完全一致，多一个字符都不行。

解决方法：先用 curl 测一下你的 API 支持哪些模型：

curl https://api.ofox.ai/v1/models \
 -H "Authorization: Bearer sk-xxxxxxxxxxxx"

返回的 JSON 里每个模型的 id 字段，原样复制到 Windsurf 配置里。

坑 2：maxTokens 设太大会 400

我把 maxTokens 设成了 32768，想着越大越好嘛。结果 Claude 模型直接返回 400 错误。原因是不同模型的最大输出 token 限制不一样，你设的值不能超过模型实际支持的上限。

模型建议 maxTokens上下文窗口
Claude Opus 4.68192200K
GPT-516384128K
DeepSeek V38192128K
Gemini 3 Pro81921M

保险起见，先设 4096 或 8192，够用了再调。

坑 3：Streaming 不开，Cascade 会假死

Windsurf 的 Cascade 功能（就是那个 AI 编码助手面板）默认期望流式响应。如果你的 Provider 配置里 streaming 设成了 false，或者你的 API 不支持流式，Cascade 会卡在那里转圈，看起来像是请求超时。

实际上请求已经发出去了，只是非流式模式下要等整个响应生成完才返回，Claude Opus 4.6 生成一段长代码可能要 30 秒以上，体验非常差。

解决方案：streaming 必须设为 true。ofox.ai 是一个 AI 模型聚合平台，支持 OpenAI/Anthropic/Gemini 三大协议的 Streaming 响应，这一点实测没问题。

坑 4：Base URL 末尾的斜杠

这个坑经典到我都不好意思说。https://api.ofox.ai/v1 和 https://api.ofox.ai/v1/ 在某些 HTTP 客户端里行为不一样。Windsurf 内部拼接路径时，如果你末尾带了 /，最终请求会变成 https://api.ofox.ai/v1//chat/completions，双斜杠直接 404。

Base URL 末尾不要加斜杠。

坑 5：Windsurf 缓存了旧配置

改完 settings.json 之后，Windsurf 有时候不会立刻生效。我改了三遍以为是配置写错了，最后发现是缓存问题。

解决方法：Cmd + Shift + P → 输入 Reload Window，强制重载。

不同模型怎么选

既然 Windsurf 支持切换模型，那不同场景用哪个最合适？这是我这几周实测下来的体感：

场景推荐模型理由
复杂重构、架构设计Claude Opus 4.6长上下文理解能力最强，代码质量高
日常补全、快速迭代DeepSeek V3速度快、便宜，够用
多文件联动修改GPT-5Function Calling 能力强，工具调用稳
简单脚本、一次性任务GLM 5 / Qwen 3性价比极高

我现在的习惯是默认挂 DeepSeek V3 日常写代码，遇到复杂问题手动切 Claude Opus 4.6。Windsurf 切模型就是点一下的事，比 Cursor 方便。

小结

Windsurf 配置自定义 API 说白了就三步：选 OpenAI Compatible → 填 Base URL 和 Key → 手动添加模型 ID。但那几个隐藏的坑（模型 ID 必须精确、maxTokens 别超限、streaming 必须开、URL 末尾别加斜杠）不踩一遍真不知道。

Windsurf 的 Cascade 体验确实不错，多文件上下文的处理比 Cursor 的 Composer 更顺滑一些。配合聚合 API 一个 Key 随便切模型，日常开发效率提升还是挺明显的。

有问题评论区聊，我看到会回。

avatar
文章
阅读
粉丝