Настройка Windsurf для API, совместимого с OpenAI: маршрутизация трафика от coding-agent через один ключ

Если вы искали настройку API Windsurf, совместимого с OpenAI, вы, вероятно, имели в виду одно из двух:

• Вы хотите изменить модель, которую Windsurf или Devin Desktop использует внутри Cascade.
• Вы хотите, чтобы код, скрипты, инструменты или локальное приложение, которое Windsurf помогает вам создавать, отправляли трафик API, совместимого с OpenAI, через один общий ключ шлюза.

Это не одна и та же настройка. В общедоступной документации Windsurf и Devin Desktop, проверенной 2026-07-08, описан выбор модели Cascade, Devin Local, учет использования/кредитов и серверы MCP для инструментов. В ней не описан встроенный экран «пользовательского провайдера, совместимого с OpenAI», куда можно было бы вставить базовый URL сторонней LLM для самого Cascade.

Это важно, потому что безопасный паттерн использования Flatkey заключается не в том, чтобы делать вид, будто в Windsurf есть встроенное поле для провайдера, которого нет в документации. Используйте Flatkey для трафика SDK и приложений, совместимых с OpenAI, в рамках проекта, управляемого Windsurf: тестовых скриптов, инструментов агента, бэкенд-сервисов, рабочих процессов CLI и кода приложения, который уже вызывает эндпоинт в стиле Chat Completions.

Flatkey предоставляет для этого трафика один ключ, базовый URL, совместимый с OpenAI, маршрутизацию моделей, видимость использования и проверку счетов. Windsurf остается средой для кодирования; Flatkey становится маршрутом API, который использует код вашего проекта.

Краткий ответ по настройке API Windsurf, совместимого с OpenAI

Используйте эту таблицу для принятия решений, прежде чем изменять конфигурацию.

Практический путь для API Windsurf, совместимого с OpenAI, таков: позвольте Windsurf помогать редактировать код, но маршрутизируйте вызовы моделей из этого кода через Flatkey. Это делает настройку API Windsurf, совместимого с OpenAI, проверяемой, поскольку у среды кодирования, ключа API и производственного маршрута есть четкий владелец.

Что на самом деле поддерживается в официальной документации Windsurf и Devin

Текущая общедоступная документация подтверждает три факта, которые легли в основу этого руководства.

Поэтому в статье о API Windsurf, совместимом с OpenAI, не следует писать: «Откройте настройки Windsurf и добавьте Flatkey как пользовательского провайдера OpenAI», если только в используемой вами документации или пользовательском интерфейсе продукта явно не указана такая возможность. Более безопасное руководство для продакшена — настраивать код и инструменты, которые создает 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": "Reply with exactly: flatkey route ok" }
    ]
  }'

Не передавайте SDK одновременно https://router.flatkey.ai/v1 и /chat/completions в качестве базового URL. Базовый URL для SDK обычно должен заканчиваться на /v1; прямые запросы curl используют полный эндпоинт.

Шаг 2: Поместите маршрут в фабрику SDK-клиента

Наиболее полезная настройка API Windsurf, совместимого с OpenAI, — это небольшая граница клиента, которую 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": "Reply with exactly: 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 по настройке API, совместимого с Cursor OpenAI и настройке роутера API для Claude Code.

Шаг 3: Попросите Windsurf внести изменения в код, а не хранить секрет

Windsurf полезен для применения миграции по всему репозиторию, но промпт должен ограничивать объем работы.

Обновите настройку клиента LLM, чтобы все запросы чата, совместимые с OpenAI, использовали:
- FLATKEY_API_KEY в качестве токена носителя
- FLATKEY_BASE_URL в качестве корневого URL API
- FLATKEY_MODEL в качестве псевдонима модели

Не прописывайте секреты в коде.
Не изменяйте промпты, бизнес-логику или политику повторных попыток.
Обновите только фабрику клиента и минимальный тест, необходимый для проверки маршрута.

Это ограничивает работу с API, совместимым с Windsurf OpenAI, рамками конфигурации, а не широким рефакторингом.

Шаг 4: Держите конфигурацию MCP отдельно

Это самая распространенная ошибка при настройке. Конфигурация MCP в Windsurf соединяет 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: Сохраните верификационный пакет

Миграция на API, совместимый с Windsurf OpenAI, готова только тогда, когда вы можете доказать, что маршрут работает и его можно откатить. Смысл верификационного пакета для API, совместимого с Windsurf OpenAI, в том, чтобы сделать первое изменение маршрута достаточно небольшим, чтобы инженеры, финансисты и операционный отдел могли проверить его вместе.

Для получения более подробных полей использования воспользуйтесь руководством по панели мониторинга использования токенов после того, как первый дымовой тест пройдет успешно.

Шаг 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. Значения для отката записаны до того, как будет переключен производственный трафик.

Настройка API, совместимого с Windsurf OpenAI, полезна, когда она четко определяет границы: Windsurf помогает вам создавать и изменять код, в то время как Flatkey маршрутизирует совместимые с OpenAI вызовы, которые делает этот код. Когда вы будете готовы маршрутизировать эти вызовы через один ключ, получите ключ Flatkey и начните с одного дымового теста с низким уровнем риска.