Windsurf 接入与兼容性说明

Windsurf 的 BYOK 功能只面向官方界面列出的 Provider 和模型。当前官方设置没有提供通用的 OpenAI Compatible / Custom Provider Base URL，因此不能把 Zivv 直连写成稳定支持方案。

最近核验：2026-07-24。如果后续 Windsurf 官方新增 Custom Provider，本页会在复核后更新。

当前结论

配置方式	状态
使用 Windsurf 内置模型	官方支持
为官方列出的 Provider 填写其原生 Key	官方 BYOK 支持范围内
填写任意 OpenAI Compatible Base URL	当前未提供稳定官方入口
使用 Zivv Key 冒充 OpenAI 官方 Key	不推荐，验证和功能可能失败

因此，当前不提供“在 Windsurf 中填写 https://zivv.pro/v1 即可直连”的确定性教程。

推荐替代方案

需要通过 Zivv 使用 AI 编程助手时，选择官方明确支持自定义网关的工具：

1. Claude Code — 使用 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN
2. Codex CLI — 使用 model_providers 和 Responses API
3. Codex 桌面端 — 与 Codex CLI 共享 Provider 配置
4. OpenAI SDK — 直接控制 Base URL、模型和请求格式

如果未来出现 Custom Provider

只有当 Windsurf 官方文档或当前设置页明确提供以下字段时，才进行兼容性测试：

Base URL: https://zivv.pro/v1
API Key:  sk-你的Key
Model:    模型广场中的模型 ID

测试顺序：

1. 先用普通 Chat 发送“只回复 pong”。
2. 在 用量日志 检查实际请求路径和模型。
3. 再测试流式输出和工具调用。
4. 最后测试 Cascade、索引和后台任务。

即使普通 Chat 可用，也不能推断 Cascade、Tab Completion、索引和后台代理都使用自定义 Provider。

常见误区

在 Windsurf 的 OpenAI Key 输入框粘贴 Zivv Key

BYOK 输入框通常按对应官方 Provider 验证，Zivv Key 不是 OpenAI 官方 Key，可能直接验证失败。

从旧教程寻找隐藏的 Base URL 设置

旧版本截图、实验开关或修改内部配置的方法都可能随更新失效，也可能绕过客户端安全机制。本页不推荐此类方案。

把普通 Chat 成功当成全功能兼容

Windsurf 的 Cascade、自动补全、检索和后台能力可能依赖自有服务及特定模型，不能用一次对话成功证明完整兼容。

官方资料

• Windsurf AI Models
• Windsurf Cascade Models
• 文档版本维护策略