Windsurf OpenAI互換APIセットアップ：コーディングエージェントのトラフィックを単一キーでルーティング

「Windsurf OpenAI互換API」のセットアップを検索した場合、おそらく次の2つの異なることのいずれかを意味しているでしょう：

• WindsurfまたはDevin DesktopがCascade内で使用するモデルを変更したい。
• Windsurfが構築を支援するコード、スクリプト、ツール、またはローカルアプリが、単一の共有ゲートウェイキーを介してOpenAI互換のAPIトラフィックを送信するようにしたい。

これらは同じセットアップではありません。2026年7月8日に確認された公開されているWindsurfおよびDevin Desktopのドキュメントには、Cascadeのモデル選択、Devin Local、使用量/クレジットの会計、およびツール用のMCPサーバーについて記載されています。Cascade自体にサードパーティのLLMベースURLを貼り付けるネイティブの「カスタムOpenAI互換プロバイダー」画面については記載されていません。

これは重要です。なぜなら、安全なFlatkeyのパターンは、ドキュメントに示されていないネイティブのプロバイダーフィールドがWindsurfにあるかのように見せかけることではないからです。Windsurf主導のプロジェクト周辺のOpenAI互換SDKおよびアプリのトラフィック（テストスクリプト、エージェントツール、バックエンドサービス、CLIワークフロー、およびすでにChat Completions形式のエンドポイントを呼び出しているアプリケーションコード）にはFlatkeyを使用してください。

Flatkeyは、そのトラフィックに単一のキー、OpenAI互換のベースURL、モデルルーティング、使用状況の可視性、および請求レビューを提供します。Windsurfはコーディング環境のままであり、Flatkeyはプロジェクトコードが使用するAPIルートになります。

Windsurf OpenAI互換APIセットアップのクイックアンサー

設定に触れる前に、この決定表を使用してください。

実用的なWindsurf OpenAI互換APIのパスは、Windsurfにコードの編集を任せ、コードのモデル呼び出しはFlatkeyを介してルーティングすることです。これにより、コーディング環境、APIキー、および本番ルートのそれぞれに明確な所有者がいるため、Windsurf OpenAI互換APIのセットアップは監査可能に保たれます。

公式のWindsurfおよびDevinドキュメントが実際にサポートしていること

現在の公開ドキュメントは、このガイドを形成する3つの事実をサポートしています。

したがって、Windsurf OpenAI互換APIに関する記事では、使用しているライブドキュメントや製品UIにその機能が明確に示されていない限り、「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にベースURLとしてhttps://router.flatkey.ai/v1と/chat/completionsの両方を与えないでください。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": "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固有の移行詳細については、このガイドをCursor OpenAI-compatible API setupおよびClaude Code API router setupに関するFlatkeyガイドと併せてお読みください。

ステップ3：Windsurfにコード変更を依頼し、シークレットは保持させない

Windsurfはリポジトリ全体に移行を適用するのに役立ちますが、プロンプトで作業を制約する必要があります。

LLMクライアントのセットアップを更新し、すべてのOpenAI互換チャットリクエストが以下を使用するようにしてください：
- ベアラートークンにはFLATKEY_API_KEY
- APIルートにはFLATKEY_BASE_URL
- モデルエイリアスには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キーはWindsurfクライアント設定ではなく、MCPサーバー側に配置してください。

ステップ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." }
    ]
  }'

ツール呼び出しの証明には、本番用のツールセットを試す前に、1つの小さな関数スキーマを使用する必要があります：

{
  "type": "function",
  "function": {
    "name": "lookup_ticket",
    "description": "テストチケットのステータスを返します。",
    "parameters": {
      "type": "object",
      "properties": {
        "ticket_id": { "type": "string" }
      },
      "required": ["ticket_id"]
    }
  }
}

プレーンなチャットは成功するが、ストリーミングやツールが失敗する場合、もはやベースURLのデバッグではありません。その機能のルート機能、モデルサポート、SDKの解析、またはゲートウェイの動作を確認しています。

トラブルシューティング表

最終チェックリスト

トラフィックを増やす前に、以下を確認してください：

1. 目標は、文書化されていないネイティブのCascadeプロバイダー設定ではなく、Windsurf周辺のアプリ、スクリプト、またはツールのトラフィックであること。
2. FLATKEY_API_KEY、FLATKEY_BASE_URL、およびFLATKEY_MODELがソース管理外で設定されていること。
3. $FLATKEY_BASE_URL/chat/completionsに対して直接curlが機能すること。
4. アプリのSDKファクトリが同じキー、ベースURL、およびモデルエイリアスを使用していること。
5. ストリーミングとツールがプレーンなチャットとは別にテストされていること。
6. Flatkeyの使用状況またはリクエストログにテストリクエストが表示されること。
7. 本番トラフィックを移行する前に、ロールバック値が書き留められていること。

Windsurf OpenAI互換APIセットアップは、その境界線を明確に認識している場合に役立ちます。つまり、Windsurfはコードの構築と変更を支援し、Flatkeyはそのコードが行うOpenAI互換の呼び出しをルーティングします。これらの呼び出しを単一のキーでルーティングする準備ができたら、Flatkeyキーを取得し、リスクの低いスモークテストから始めてください。