Configuration de l'API Windsurf compatible OpenAI : Acheminez le trafic de l'agent de codage via une seule clé

Si vous avez recherché une configuration d'API Windsurf compatible OpenAI, vous voulez probablement dire l'une des deux choses suivantes :

• Vous souhaitez modifier le modèle que Windsurf ou Devin Desktop utilise à l'intérieur de Cascade.
• Vous souhaitez que le code, les scripts, les outils ou l'application locale que Windsurf vous aide à créer envoient le trafic d'API compatible OpenAI via une seule clé de passerelle partagée.

Ce ne sont pas les mêmes configurations. La documentation publique de Windsurf et Devin Desktop, consultée le 2026-07-08, documente la sélection de modèles Cascade, Devin Local, la comptabilisation de l'utilisation/des crédits et les serveurs MCP pour les outils. Elle ne documente pas d'écran natif de « fournisseur personnalisé compatible OpenAI » où vous pourriez coller une URL de base de LLM tiers pour Cascade lui-même.

C'est important car le modèle sécurisé de Flatkey n'est pas de prétendre que Windsurf dispose d'un champ de fournisseur natif que la documentation ne montre pas. Utilisez Flatkey pour le SDK compatible OpenAI et le trafic applicatif autour d'un projet piloté par Windsurf : scripts de test, outils d'agent, services backend, workflows CLI et code d'application qui appellent déjà un point de terminaison de type Chat Completions.

Flatkey fournit à ce trafic une clé unique, une URL de base compatible OpenAI, le routage des modèles, la visibilité de l'utilisation et la révision de la facturation. Windsurf reste l'environnement de codage ; Flatkey devient la route d'API que votre code de projet utilise.

Réponse rapide pour la configuration de l'API Windsurf compatible OpenAI

Utilisez ce tableau de décision avant de toucher à la configuration.

La voie pratique pour une API Windsurf compatible OpenAI est la suivante : laissez Windsurf aider à modifier le code, mais acheminez les appels de modèle du code via Flatkey. Cela maintient la configuration de l'API Windsurf compatible OpenAI auditable car l'environnement de codage, la clé d'API et la route de production ont chacun un propriétaire clair.

Ce que la documentation officielle de Windsurf et Devin prend réellement en charge

La documentation publique actuelle soutient trois faits qui façonnent ce guide.

Ainsi, un article sur l'API Windsurf compatible OpenAI ne devrait pas dire : « Ouvrez les paramètres de Windsurf et ajoutez Flatkey comme fournisseur OpenAI personnalisé », à moins que la documentation en ligne ou l'interface utilisateur du produit que vous utilisez ne montre clairement cette capacité. Un guide de production plus sûr consiste à configurer le code et les outils que Windsurf produit.

Étape 1 : Créer une clé Flatkey et choisir la route

Dans Flatkey, créez une clé pour cette charge de travail et choisissez un alias de modèle qui correspond à la famille de points de terminaison que vous prévoyez d'appeler. Pour une route de type Chat Completions, gardez la racine de l'API et le point de terminaison séparés :

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

Pour les appels curl directs, ajoutez le chemin du point de terminaison :

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": "Répondez avec exactement : flatkey route ok" }
    ]
  }'

Ne donnez pas à un SDK à la fois https://router.flatkey.ai/v1 et /chat/completions comme URL de base. L'URL de base du SDK doit normalement s'arrêter à /v1 ; les requêtes curl directes utilisent le point de terminaison complet.

Étape 2 : Placer la route dans une fabrique de client SDK

La configuration d'API Windsurf compatible OpenAI la plus utile est une petite frontière client que Windsurf peut aider à modifier en toute sécurité. Conservez les secrets dans des variables d'environnement et gardez les alias de modèle configurables.

Modèle 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": "Répondez avec exactement : sdk route ok"}
    ],
)

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

Modèle 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);

Considérez ces extraits comme des modèles jusqu'à ce que vous les testiez avec votre version du SDK installée, votre clé Flatkey actuelle, votre alias de modèle actuel et votre famille de points de terminaison. Si votre application dispose déjà d'un wrapper pour l'URL de base, mettez à jour ce wrapper au lieu de disperser les variables Flatkey dans les contrôleurs et les scripts.

Pour des détails de migration spécifiques au SDK, associez ce guide aux guides Flatkey pour la configuration de l'API compatible OpenAI de Cursor et la configuration du routeur d'API de code Claude.

Étape 3 : Demandez à Windsurf d'effectuer la modification du code, pas de détenir le secret

Windsurf est utile pour appliquer la migration sur un dépôt, mais le prompt doit limiter le travail.

Mettez à jour la configuration du client LLM pour que toutes les requêtes de chat compatibles OpenAI utilisent :
- FLATKEY_API_KEY pour le jeton bearer
- FLATKEY_BASE_URL comme racine de l'API
- FLATKEY_MODEL comme alias de modèle

Ne codez pas les secrets en dur.
Ne modifiez pas les prompts, la logique métier ou la politique de nouvelle tentative.
Mettez à jour uniquement la fabrique de clients et le plus petit test nécessaire pour vérifier la route.

Cela maintient le travail de l'API compatible OpenAI de Windsurf limité à la configuration, et non à une refactorisation large.

Étape 4 : Gardez la configuration MCP séparée

C'est l'erreur de configuration la plus courante. La configuration MCP de Windsurf connecte Cascade aux outils. Une entrée MCP distante peut ressembler à ceci :

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

Ce serverUrl n'est pas l'endroit où vous mettez https://router.flatkey.ai/v1. Le serveur MCP peut exposer des outils à Cascade, et ces outils peuvent appeler Flatkey en interne si vous les construisez de cette manière. Mais la configuration du transport MCP et le routage des modèles compatibles OpenAI sont des couches différentes.

Utilisez cette répartition :

Si votre serveur MCP appelle un modèle, placez la clé Flatkey du côté du serveur MCP, et non dans la configuration du client Windsurf, à moins que votre modèle de sécurité n'autorise explicitement une information d'identification de développeur local.

Étape 5 : Enregistrez un paquet de vérification

Une migration de l'API compatible OpenAI de Windsurf n'est prête que lorsque vous pouvez prouver que la route fonctionne et qu'elle peut être annulée. L'objectif d'un paquet de vérification de l'API compatible OpenAI de Windsurf est de rendre le premier changement de route suffisamment petit pour que l'ingénierie, la finance et les opérations puissent l'inspecter ensemble.

Pour des champs d'utilisation plus détaillés, utilisez le guide du tableau de bord d'utilisation des jetons après que le premier test de fumée a fonctionné.

Étape 6 : Testez le streaming et les outils après le chat simple

Ne commencez pas par la route la plus difficile. Prouvez d'abord qu'une requête de chat sans streaming fonctionne. Testez ensuite le streaming et les appels d'outils comme des contrats distincts.

Preuve du 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": "Count from one to five." }
    ]
  }'

La preuve d'appel d'outil doit utiliser un schéma de fonction minuscule avant d'essayer un ensemble d'outils de production :

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

Si le chat simple passe mais que le streaming ou les outils échouent, vous ne déboguez plus l'URL de base. Vous vérifiez la capacité de la route, la prise en charge du modèle, l'analyse du SDK ou le comportement de la passerelle pour cette fonctionnalité.

Tableau de dépannage

Liste de contrôle finale

Avant d'augmenter le trafic, confirmez :

1. L'objectif est le trafic d'application, de script ou d'outil autour de Windsurf, et non un paramètre de fournisseur natif non documenté de Cascade.
2. FLATKEY_API_KEY, FLATKEY_BASE_URL et FLATKEY_MODEL sont configurées en dehors du contrôle de code source.
3. Le curl direct fonctionne sur $FLATKEY_BASE_URL/chat/completions.
4. La fabrique SDK de l'application utilise la même clé, la même URL de base et le même alias de modèle.
5. Le streaming et les outils sont testés séparément du chat simple.
6. Les journaux d'utilisation ou de requêtes de Flatkey affichent la requête de test.
7. Les valeurs de restauration sont notées avant le déplacement du trafic de production.

Une configuration d'API Windsurf compatible OpenAI est utile lorsqu'elle est transparente sur la délimitation : Windsurf vous aide à créer et à modifier le code, tandis que Flatkey achemine les appels compatibles OpenAI que ce code effectue. Lorsque vous êtes prêt à acheminer ces appels via une seule clé, obtenez une clé Flatkey et commencez par un test de fumée à faible risque.