Configuração da API compatível com OpenAI do Windsurf: Direcione o tráfego do agente de codificação através de uma única chave

Se você procurou por uma configuração de API compatível com OpenAI do Windsurf, provavelmente quer dizer uma de duas coisas diferentes:

• Você quer mudar o modelo que o Windsurf ou o Devin Desktop usa dentro do Cascade.
• Você quer que o código, scripts, ferramentas ou aplicativo local que o Windsurf ajuda a construir envie tráfego de API compatível com OpenAI através de uma única chave de gateway compartilhada.

Essas não são a mesma configuração. A documentação pública do Windsurf e do Devin Desktop, verificada em 08/07/2026, documenta a seleção de modelos do Cascade, o Devin Local, a contabilidade de uso/crédito e os servidores MCP para ferramentas. Eles não documentam uma tela nativa de "provedor personalizado compatível com OpenAI" onde você cola uma URL base de LLM de terceiros para o próprio Cascade.

Isso é importante porque o padrão seguro do Flatkey não é fingir que o Windsurf tem um campo de provedor nativo que a documentação não mostra. Use o Flatkey para o SDK compatível com OpenAI e o tráfego de aplicativos em torno de um projeto impulsionado pelo Windsurf: scripts de teste, ferramentas de agente, serviços de backend, fluxos de trabalho de CLI e código de aplicativo que já chamam um endpoint no estilo Chat Completions.

O Flatkey fornece a esse tráfego uma única chave, uma URL base compatível com OpenAI, roteamento de modelos, visibilidade de uso e revisão de faturamento. O Windsurf continua sendo o ambiente de codificação; o Flatkey se torna a rota de API que o código do seu projeto usa.

Resposta rápida para a configuração da API compatível com OpenAI do Windsurf

Use esta tabela de decisão antes de mexer na configuração.

O caminho prático da API compatível com OpenAI do Windsurf é: deixar o Windsurf ajudar a editar o código, mas direcionar as chamadas de modelo do código através do Flatkey. Isso mantém a configuração da API compatível com OpenAI do Windsurf auditável porque o ambiente de codificação, a chave de API e a rota de produção têm, cada um, um proprietário claro.

O que a documentação oficial do Windsurf e do Devin realmente suporta

A documentação pública atual suporta três fatos que moldam este guia.

Portanto, um artigo sobre a API compatível com OpenAI do Windsurf não deve dizer: "Abra as configurações do Windsurf e adicione o Flatkey como um provedor OpenAI personalizado", a menos que a documentação ao vivo ou a interface do produto que você está usando mostre claramente essa capacidade. Um guia de produção mais seguro é configurar o código e as ferramentas que o Windsurf produz.

Passo 1: Crie uma chave Flatkey e escolha a rota

No Flatkey, crie uma chave para esta carga de trabalho e escolha um alias de modelo que corresponda à família de endpoints que você planeja chamar. Para uma rota no estilo Chat Completions, mantenha a raiz da API e o endpoint separados:

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

Para chamadas curl diretas, adicione o caminho do endpoint:

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": "Responda com exatamente: rota flatkey ok" }
    ]
  }'

Não forneça a um SDK tanto https://router.flatkey.ai/v1 quanto /chat/completions como a URL base. A URL base do SDK normalmente deve parar em /v1; solicitações curl diretas usam o endpoint completo.

Passo 2: Coloque a rota em uma fábrica de clientes SDK

A configuração mais útil da API compatível com OpenAI do Windsurf é um pequeno limite de cliente que o Windsurf pode ajudar a editar com segurança. Mantenha os segredos em variáveis de ambiente e mantenha os aliases de modelo configuráveis.

Modelo 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": "Responda com exatamente: rota sdk ok"}
    ],
)

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

Modelo 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);

Trate esses trechos de código como modelos até testá-los com a versão do SDK instalada, a chave Flatkey atual, o alias do modelo atual e a família de endpoints. Se seu aplicativo já tiver um wrapper de URL base, atualize esse wrapper em vez de espalhar variáveis Flatkey por controladores e scripts.

Para detalhes de migração específicos do SDK, combine este guia com os guias Flatkey para a configuração da API compatível com OpenAI do Cursor e a configuração do roteador da API Claude Code.

Etapa 3: Peça ao Windsurf para fazer a alteração no código, não para guardar o segredo

O Windsurf é útil para aplicar a migração em um repositório, mas o prompt deve restringir o trabalho.

Atualize a configuração do cliente LLM para que todas as solicitações de chat compatíveis com OpenAI usem:
- FLATKEY_API_KEY para o token de portador
- FLATKEY_BASE_URL como a raiz da API
- FLATKEY_MODEL como o alias do modelo

Não codifique segredos.
Não altere prompts, lógica de negócios ou política de repetição.
Atualize apenas a fábrica de clientes e o menor teste necessário para verificar a rota.

Isso mantém o trabalho da API compatível com OpenAI do Windsurf no escopo da configuração, não em uma refatoração ampla.

Etapa 4: Mantenha a configuração do MCP separada

Este é o erro de configuração mais comum. A configuração MCP do Windsurf conecta o Cascade a ferramentas. Uma entrada MCP remota pode ser assim:

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

Esse serverUrl não é onde você coloca https://router.flatkey.ai/v1. O servidor MCP pode expor ferramentas ao Cascade, e essas ferramentas podem chamar o Flatkey internamente se você as construir dessa forma. Mas a configuração de transporte do MCP e o roteamento de modelo compatível com OpenAI são camadas diferentes.

Use esta divisão:

Se o seu servidor MCP chamar um modelo, coloque a chave Flatkey do lado do servidor MCP, não na configuração do cliente Windsurf, a menos que seu modelo de segurança permita explicitamente uma credencial de desenvolvedor local.

Etapa 5: Salve um pacote de verificação

Uma migração da API compatível com OpenAI do Windsurf só está pronta quando você pode provar que a rota funciona e pode ser revertida. O objetivo de um pacote de verificação da API compatível com OpenAI do Windsurf é tornar a primeira alteração de rota pequena o suficiente para que engenharia, finanças e operações possam inspecioná-la juntas.

Para campos de uso mais detalhados, use o guia do painel de uso de tokens depois que o primeiro teste de fumaça funcionar.

Etapa 6: Teste o streaming e as ferramentas após o chat simples

Não comece pela rota mais difícil. Primeiro, prove uma solicitação de chat sem streaming. Em seguida, teste o streaming e as chamadas de ferramentas como contratos separados.

Prova 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": "Conte de um a cinco." }
    ]
  }'

A prova de chamada de ferramenta deve usar um esquema de função minúsculo antes de você tentar um conjunto de ferramentas de produção:

{
  "type": "function",
  "function": {
    "name": "lookup_ticket",
    "description": "Retornar o status de um ticket de teste.",
    "parameters": {
      "type": "object",
      "properties": {
        "ticket_id": { "type": "string" }
      },
      "required": ["ticket_id"]
    }
  }
}

Se o chat simples passar, mas o streaming ou as ferramentas falharem, você não está mais depurando a URL base. Você está verificando a capacidade da rota, o suporte do modelo, a análise do SDK ou o comportamento do gateway para esse recurso.

Tabela de solução de problemas

Lista de verificação final

Antes de aumentar o tráfego, confirme:

1. O objetivo é o tráfego de aplicativos, scripts ou ferramentas em torno do Windsurf, não uma configuração de provedor nativo do Cascade não documentada.
2. FLATKEY_API_KEY, FLATKEY_BASE_URL e FLATKEY_MODEL estão configurados fora do controle de origem.
3. O curl direto funciona em $FLATKEY_BASE_URL/chat/completions.
4. A fábrica de SDK do aplicativo usa a mesma chave, URL base e alias de modelo.
5. Streaming e ferramentas são testados separadamente do chat simples.
6. Os logs de uso ou de solicitação do Flatkey mostram a solicitação de teste.
7. Os valores de reversão são anotados antes que o tráfego de produção seja movido.

Uma configuração de API compatível com OpenAI do Windsurf é útil quando é honesta sobre o limite: o Windsurf ajuda você a construir e modificar o código, enquanto o Flatkey direciona as chamadas compatíveis com OpenAI que esse código faz. Quando estiver pronto para direcionar essas chamadas através de uma única chave, obtenha uma chave Flatkey e comece com um teste de fumaça de baixo risco.