Configuración de la API de Windsurf compatible con OpenAI: Enruta el tráfico del agente de codificación con una sola clave

Si buscaste una configuración de API de Windsurf compatible con OpenAI, probablemente te refieres a una de dos cosas diferentes:

• Quieres cambiar el modelo que Windsurf o Devin Desktop usan dentro de Cascade.
• Quieres que el código, los scripts, las herramientas o la aplicación local que Windsurf te ayuda a construir envíen tráfico de API compatible con OpenAI a través de una única clave de puerta de enlace compartida.

Esas no son la misma configuración. La documentación pública de Windsurf y Devin Desktop, consultada el 08-07-2026, documenta la selección de modelos de Cascade, Devin Local, la contabilidad de uso/créditos y los servidores MCP para herramientas. No documentan una pantalla nativa de "proveedor personalizado compatible con OpenAI" donde puedas pegar una URL base de LLM de terceros para el propio Cascade.

Eso es importante porque el patrón seguro de Flatkey no es pretender que Windsurf tiene un campo de proveedor nativo que la documentación no muestra. Usa Flatkey para el SDK compatible con OpenAI y el tráfico de la aplicación en torno a un proyecto impulsado por Windsurf: scripts de prueba, herramientas de agente, servicios de backend, flujos de trabajo de CLI y código de aplicación que ya llaman a un punto de conexión de estilo Chat Completions.

Flatkey le da a ese tráfico una única clave, una URL base compatible con OpenAI, enrutamiento de modelos, visibilidad del uso y revisión de la facturación. Windsurf sigue siendo el entorno de codificación; Flatkey se convierte en la ruta de API que utiliza el código de tu proyecto.

Respuesta rápida para la configuración de la API de Windsurf compatible con OpenAI

Usa esta tabla de decisiones antes de tocar la configuración.

La ruta práctica para la API de Windsurf compatible con OpenAI es: deja que Windsurf ayude a editar el código, pero enruta las llamadas al modelo del código a través de Flatkey. Eso mantiene la configuración de la API de Windsurf compatible con OpenAI auditable porque el entorno de codificación, la clave de API y la ruta de producción tienen cada uno un propietario claro.

Lo que la documentación oficial de Windsurf y Devin realmente admite

La documentación pública actual respalda tres hechos que dan forma a esta guía.

Por lo tanto, un artículo sobre la API de Windsurf compatible con OpenAI no debería decir: "Abre la configuración de Windsurf y añade Flatkey como un proveedor de OpenAI personalizado", a menos que la documentación en vivo o la interfaz de usuario del producto que estás utilizando muestren claramente esa capacidad. Una guía de producción más segura es configurar el código y las herramientas que Windsurf produce.

Paso 1: Crea una clave de Flatkey y elige la ruta

En Flatkey, crea una clave para esta carga de trabajo y elige un alias de modelo que coincida con la familia de puntos de conexión a la que planeas llamar. Para una ruta de estilo Chat Completions, mantén la raíz de la API y el punto de conexión separados:

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

Para llamadas directas con curl, añade la ruta del punto de conexión:

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": "Responde exactamente con: flatkey route ok" }
    ]
  }'

No le des a un SDK tanto https://router.flatkey.ai/v1 como /chat/completions como URL base. La URL base del SDK normalmente debe detenerse en /v1; las solicitudes directas con curl usan el punto de conexión completo.

Paso 2: Pon la ruta en una factoría de clientes SDK

La configuración más útil de la API de Windsurf compatible con OpenAI es un pequeño límite de cliente que Windsurf pueda ayudar a editar de forma segura. Mantén los secretos en variables de entorno y los alias de modelo configurables.

Plantilla de 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": "Responde exactamente con: sdk route ok"}
    ],
)

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

Plantilla de 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);

Trata estos fragmentos como plantillas hasta que los pruebes con tu versión del SDK instalada, la clave de Flatkey actual, el alias del modelo actual y la familia de puntos de conexión. Si tu aplicación ya tiene un contenedor de URL base, actualiza ese contenedor en lugar de dispersar las variables de Flatkey por los controladores y scripts.

Para obtener detalles de migración específicos del SDK, combina esta guía con las guías de Flatkey para la configuración de la API compatible con OpenAI de Cursor y la configuración del enrutador de la API de Claude Code.

Paso 3: Pídele a Windsurf que haga el cambio de código, no que guarde el secreto

Windsurf es útil para aplicar la migración en todo un repositorio, pero el prompt debe limitar el trabajo.

Actualiza la configuración del cliente LLM para que todas las solicitudes de chat compatibles con OpenAI usen:
- FLATKEY_API_KEY para el token de portador
- FLATKEY_BASE_URL como la raíz de la API
- FLATKEY_MODEL como el alias del modelo

No codifiques secretos.
No cambies los prompts, la lógica de negocio ni la política de reintentos.
Actualiza solo la fábrica de clientes y la prueba más pequeña necesaria para verificar la ruta.

Eso mantiene el trabajo de la API compatible con OpenAI de Windsurf limitado a la configuración, no a una refactorización amplia.

Paso 4: Mantén la configuración de MCP separada

Este es el error de configuración más común. La configuración MCP de Windsurf conecta Cascade con las herramientas. Una entrada MCP remota puede tener este aspecto:

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

Ese serverUrl no es donde pones https://router.flatkey.ai/v1. El servidor MCP puede exponer herramientas a Cascade, y esas herramientas pueden llamar a Flatkey internamente si las construyes de esa manera. Pero la configuración de transporte de MCP y el enrutamiento de modelos compatibles con OpenAI son capas diferentes.

Usa esta división:

Si tu servidor MCP llama a un modelo, coloca la clave de Flatkey del lado del servidor MCP, no en la configuración del cliente de Windsurf, a menos que tu modelo de seguridad permita explícitamente una credencial de desarrollador local.

Paso 5: Guarda un paquete de verificación

Una migración de la API compatible con OpenAI de Windsurf solo está lista cuando puedes demostrar que la ruta funciona y que se puede revertir. El objetivo de un paquete de verificación de la API compatible con OpenAI de Windsurf es hacer que el primer cambio de ruta sea lo suficientemente pequeño como para que los equipos de ingeniería, finanzas y operaciones lo inspeccionen juntos.

Para campos de uso más detallados, utiliza la guía del panel de uso de tokens después de que la primera prueba de humo funcione.

Paso 6: Prueba el streaming y las herramientas después del chat simple

No empieces por la ruta más difícil. Primero, prueba una solicitud de chat sin streaming. Luego, prueba el streaming y las llamadas a herramientas como contratos separados.

Prueba de streaming:

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": "Cuenta del uno al cinco." }
    ]
  }'

La prueba de llamada a herramienta debe usar un esquema de función diminuto antes de probar un conjunto de herramientas de producción:

{
  "type": "function",
  "function": {
    "name": "lookup_ticket",
    "description": "Devuelve el estado de un ticket de prueba.",
    "parameters": {
      "type": "object",
      "properties": {
        "ticket_id": { "type": "string" }
      },
      "required": ["ticket_id"]
    }
  }
}

Si el chat simple funciona pero el streaming o las herramientas fallan, ya no estás depurando la URL base. Estás verificando la capacidad de la ruta, el soporte del modelo, el análisis del SDK o el comportamiento de la puerta de enlace para esa función.

Tabla de solución de problemas

Lista de verificación final

Antes de aumentar el tráfico, confirma:

1. El objetivo es el tráfico de la aplicación, script o herramienta en torno a Windsurf, no una configuración de proveedor nativo de Cascade no documentada.
2. FLATKEY_API_KEY, FLATKEY_BASE_URL y FLATKEY_MODEL están configurados fuera del control de código fuente.
3. El curl directo funciona contra $FLATKEY_BASE_URL/chat/completions.
4. La fábrica de SDK de la aplicación utiliza la misma clave, URL base y alias de modelo.
5. El streaming y las herramientas se prueban por separado del chat simple.
6. Los registros de uso o de solicitudes de Flatkey muestran la solicitud de prueba.
7. Los valores de reversión se anotan antes de mover el tráfico de producción.

Una configuración de API de Windsurf compatible con OpenAI es útil cuando es honesta sobre los límites: Windsurf te ayuda a construir y modificar el código, mientras que Flatkey enruta las llamadas compatibles con OpenAI que hace ese código. Cuando estés listo para enrutar esas llamadas a través de una sola clave, obtén una clave de Flatkey y comienza con una prueba de humo de bajo riesgo.