Windsurf OpenAI 兼容 API 设置：通过一个密钥路由编码代理流量

如果您搜索 Windsurf OpenAI 兼容 API 设置，您可能指的是以下两种不同情况之一：

• 您想更改 Windsurf 或 Devin Desktop 在 Cascade 内部使用的模型。
• 您希望 Windsurf 帮助您构建的代码、脚本、工具或本地应用通过一个共享网关密钥发送 OpenAI 兼容的 API 流量。

这两种设置并不相同。截至 2026-07-08 查阅的公开 Windsurf 和 Devin Desktop 文档记录了 Cascade 模型选择、Devin Local、使用/信用核算以及用于工具的 MCP 服务器。它们没有记录一个原生的“自定义 OpenAI 兼容提供商”屏幕，让您可以为 Cascade 本身粘贴第三方 LLM 基础 URL。

这一点很重要，因为安全的 Flatkey 模式不是假装 Windsurf 有一个文档中未显示的本机提供商字段。请将 Flatkey 用于围绕 Windsurf 驱动项目的 OpenAI 兼容 SDK 和应用流量：测试脚本、代理工具、后端服务、CLI 工作流以及已经调用聊天完成（Chat Completions）风格端点的应用程序代码。

Flatkey 为这些流量提供一个密钥、一个 OpenAI 兼容的基础 URL、模型路由、使用情况可见性和账单审查。Windsurf 仍然是编码环境；Flatkey 则成为您的项目代码使用的 API 路由。

Windsurf OpenAI 兼容 API 设置快速解答

在进行配置前，请使用此决策表。

实用的 Windsurf OpenAI 兼容 API 路径是：让 Windsurf 帮助编辑代码，但通过 Flatkey 路由代码的模型调用。这使得 Windsurf OpenAI 兼容 API 设置可审计，因为编码环境、API 密钥和生产路由各自都有明确的所有者。

Windsurf 和 Devin 官方文档实际支持的功能

当前的公开文档支持三个事实，这些事实构成了本指南的基础。

因此，一篇关于 Windsurf OpenAI 兼容 API 的文章不应该说“打开 Windsurf 设置并添加 Flatkey 作为自定义 OpenAI 提供商”，除非您正在使用的实时文档或产品 UI 明确显示了该功能。一个更安全的生产指南是配置 Windsurf 生成的代码和工具。

第 1 步：创建 Flatkey 密钥并选择路由

在 Flatkey 中，为此工作负载创建一个密钥，并选择一个与您计划调用的端点系列相匹配的模型别名。对于聊天完成（Chat Completions）风格的路由，请将 API 根路径和端点分开：

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_MODEL=your-current-flatkey-model-alias

对于直接的 curl 调用，请添加端点路径：

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      { "role": "user", "content": "请准确回复：flatkey route ok" }
    ]
  }'

不要同时将 https://router.flatkey.ai/v1 和 /chat/completions 作为基础 URL 提供给 SDK。SDK 基础 URL 通常应在 /v1 处停止；直接的 curl 请求使用完整的端点。

第 2 步：将路由放入 SDK 客户端工厂

最有用的 Windsurf OpenAI 兼容 API 设置是一个小型的客户端边界，Windsurf 可以帮助安全地编辑它。将密钥保存在环境变量中，并保持模型别名可配置。

Python 模板：

import os
from openai import OpenAI


def make_llm_client() -> OpenAI:
    return OpenAI(
        api_key=os.environ["FLATKEY_API_KEY"],
        base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
    )


client = make_llm_client()

response = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[
        {"role": "user", "content": "请准确回复：sdk route ok"}
    ],
)

print(response.choices[0].message.content)
print(response.usage)

Node 模板：

import OpenAI from "openai";

export function makeLlmClient() {
  return new OpenAI({
    apiKey: process.env.FLATKEY_API_KEY,
    baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
  });
}

const client = makeLlmClient();

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [
    { role: "user", content: "Reply with exactly: sdk route ok" },
  ],
});

console.log(response.choices[0]?.message?.content);
console.log(response.usage);

在根据您已安装的 SDK 版本、当前的 Flatkey 密钥、当前的模型别名和端点系列对这些代码片段进行测试之前，请将它们视为模板。如果您的应用程序已经有一个基础 URL 包装器，请更新该包装器，而不是将 Flatkey 变量分散到各个控制器和脚本中。

有关特定于 SDK 的迁移详细信息，请将本指南与 Flatkey 的 Cursor OpenAI 兼容 API 设置和 Claude Code API 路由器设置指南结合使用。

第 3 步：要求 Windsurf 进行代码更改，而不是持有密钥

Windsurf 对于在整个代码库中应用迁移很有用，但提示应限制工作范围。

更新 LLM 客户端设置，以便所有 OpenAI 兼容的聊天请求都使用：
- FLATKEY_API_KEY 作为持有者令牌
- FLATKEY_BASE_URL 作为 API 根
- FLATKEY_MODEL 作为模型别名

不要硬编码密钥。
不要更改提示、业务逻辑或重试策略。
仅更新客户端工厂和验证路由所需的最小测试。

这将 Windsurf OpenAI 兼容 API 的工作范围限定在配置上，而不是一次广泛的重构。

第 4 步：保持 MCP 配置分离

这是最常见的设置错误。Windsurf 的 MCP 配置将 Cascade 连接到工具。远程 MCP 条目可能如下所示：

{
  "mcpServers": {
    "internal-docs": {
      "serverUrl": "https://tools.example.com/mcp"
    }
  }
}

那个 serverUrl 不是您放置 https://router.flatkey.ai/v1 的地方。MCP 服务器可以向 Cascade 公开工具，如果您以这种方式构建它们，这些工具可以在内部调用 Flatkey。但 MCP 传输配置和 OpenAI 兼容的模型路由是不同的层。

使用以下划分：

如果您的 MCP 服务器调用模型，请将 Flatkey 密钥放在 MCP 服务器端，而不是 Windsurf 客户端配置中，除非您的安全模型明确允许本地开发者凭据。

第 5 步：保存验证包

只有当您能证明路由正常工作并且可以回滚时，Windsurf OpenAI 兼容 API 迁移才算准备就绪。Windsurf OpenAI 兼容 API 验证包的要点是使第一次路由更改足够小，以便工程、财务和运营部门可以共同检查。

对于更深入的用量字段，请在第一次冒烟测试成功后，使用令牌用量仪表板指南。

第 6 步：在普通聊天后测试流式传输和工具

不要从最难的路由开始。首先验证一个非流式聊天请求。然后将流式传输和工具调用作为独立的部分进行测试。

流式传输证明：

curl -N "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Count from one to five." }
    ]
  }'

工具调用证明应在尝试生产工具集之前使用一个微小的函数模式：

{
  "type": "function",
  "function": {
    "name": "lookup_ticket",
    "description": "Return a test ticket status.",
    "parameters": {
      "type": "object",
      "properties": {
        "ticket_id": { "type": "string" }
      },
      "required": ["ticket_id"]
    }
  }
}

如果普通聊天通过但流式传输或工具失败，那么您就不再是调试基本 URL。您正在检查该功能的路由能力、模型支持、SDK 解析或网关行为。

故障排除表

最终核对清单

在增加流量之前，请确认：

1. 目标是围绕 Windsurf 的应用程序、脚本或工具流量，而不是未记录的原生 Cascade 提供商设置。
2. FLATKEY_API_KEY、FLATKEY_BASE_URL 和 FLATKEY_MODEL 在源代码控制之外进行配置。
3. 直接 curl 对 $FLATKEY_BASE_URL/chat/completions 有效。
4. 应用程序的 SDK 工厂使用相同的密钥、基本 URL 和模型别名。
5. 流式传输和工具与普通聊天分开测试。
6. Flatkey 用量或请求日志显示测试请求。
7. 在生产流量转移之前，记下回滚值。

Windsurf OpenAI 兼容 API 设置在明确边界时非常有用：Windsurf 帮助您构建和修改代码，而 Flatkey 则路由该代码发出的 OpenAI 兼容调用。当您准备好通过一个密钥路由这些调用时，获取一个 Flatkey 密钥并从一个低风险的冒烟测试开始。