Thiết lập API tương thích OpenAI của Windsurf: Định tuyến lưu lượng coding-agent qua một khóa duy nhất

Nếu bạn tìm kiếm thiết lập API tương thích OpenAI của Windsurf, có lẽ bạn đang muốn nói đến một trong hai điều khác nhau:

• Bạn muốn thay đổi mô hình mà Windsurf hoặc Devin Desktop sử dụng bên trong Cascade.
• Bạn muốn mã, kịch bản, công cụ hoặc ứng dụng cục bộ mà Windsurf giúp bạn xây dựng gửi lưu lượng API tương thích OpenAI qua một khóa cổng chia sẻ duy nhất.

Đó không phải là cùng một thiết lập. Tài liệu công khai của Windsurf và Devin Desktop được kiểm tra vào ngày 08-07-2026 ghi lại việc lựa chọn mô hình Cascade, Devin Local, kế toán sử dụng/tín dụng và máy chủ MCP cho các công cụ. Chúng không ghi lại màn hình "nhà cung cấp tương thích OpenAI tùy chỉnh" gốc nơi bạn dán URL cơ sở LLM của bên thứ ba cho chính Cascade.

Điều đó quan trọng vì mẫu Flatkey an toàn không phải là giả vờ rằng Windsurf có một trường nhà cung cấp gốc mà tài liệu không hiển thị. Hãy sử dụng Flatkey cho SDK tương thích OpenAI và lưu lượng ứng dụng xung quanh một dự án do Windsurf điều khiển: kịch bản kiểm thử, công cụ agent, dịch vụ backend, quy trình làm việc CLI và mã ứng dụng đã gọi một điểm cuối kiểu Chat Completions.

Flatkey cung cấp cho lưu lượng đó một khóa duy nhất, một URL cơ sở tương thích OpenAI, định tuyến mô hình, khả năng hiển thị mức sử dụng và xem xét thanh toán. Windsurf vẫn là môi trường mã hóa; Flatkey trở thành tuyến API mà mã dự án của bạn sử dụng.

Câu trả lời nhanh cho thiết lập API tương thích OpenAI của Windsurf

Sử dụng bảng quyết định này trước khi động đến cấu hình.

Con đường thực tế cho API tương thích OpenAI của Windsurf là: để Windsurf giúp chỉnh sửa mã, nhưng định tuyến các lệnh gọi mô hình của mã thông qua Flatkey. Điều đó giữ cho thiết lập API tương thích OpenAI của Windsurf có thể kiểm tra được vì môi trường mã hóa, khóa API và tuyến sản xuất đều có chủ sở hữu rõ ràng.

Những gì tài liệu chính thức của Windsurf và Devin thực sự hỗ trợ

Tài liệu công khai hiện tại hỗ trợ ba sự thật định hình hướng dẫn này.

Vì vậy, một bài viết về API tương thích OpenAI của Windsurf không nên nói, "Mở cài đặt Windsurf và thêm Flatkey làm nhà cung cấp OpenAI tùy chỉnh," trừ khi tài liệu trực tiếp hoặc giao diện người dùng sản phẩm bạn đang sử dụng cho thấy rõ khả năng đó. Một hướng dẫn sản xuất an toàn hơn là cấu hình mã và các công cụ mà Windsurf tạo ra.

Bước 1: Tạo khóa Flatkey và chọn tuyến đường

Trong Flatkey, tạo một khóa cho khối lượng công việc này và chọn một bí danh mô hình phù hợp với họ điểm cuối bạn dự định gọi. Đối với một tuyến đường kiểu Chat Completions, hãy giữ riêng gốc API và điểm cuối:

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

Đối với các lệnh gọi curl trực tiếp, hãy thêm đường dẫn điểm cuối:

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" }
    ]
  }'

Đừng cung cấp cho SDK cả https://router.flatkey.ai/v1 và /chat/completions làm URL cơ sở. URL cơ sở của SDK thường nên dừng ở /v1; các yêu cầu curl trực tiếp sử dụng điểm cuối đầy đủ.

Bước 2: Đặt tuyến đường vào một factory máy khách SDK

Thiết lập API tương thích OpenAI của Windsurf hữu ích nhất là một ranh giới máy khách nhỏ mà Windsurf có thể giúp chỉnh sửa một cách an toàn. Giữ bí mật trong các biến môi trường và giữ cho các bí danh mô hình có thể cấu hình được.

Mẫu 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)

Mẫu 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);

Hãy xem các đoạn mã này như mẫu cho đến khi bạn kiểm tra chúng với phiên bản SDK đã cài đặt, khóa Flatkey hiện tại, bí danh mô hình hiện tại và họ điểm cuối. Nếu ứng dụng của bạn đã có một trình bao bọc URL cơ sở, hãy cập nhật trình bao bọc đó thay vì rải các biến Flatkey khắp các bộ điều khiển và tập lệnh.

Để biết chi tiết di chuyển dành riêng cho SDK, hãy kết hợp hướng dẫn này với các hướng dẫn của Flatkey về thiết lập API tương thích OpenAI của Cursor và thiết lập bộ định tuyến API Claude Code.

Bước 3: Yêu cầu Windsurf thực hiện thay đổi mã, không giữ bí mật

Windsurf hữu ích cho việc áp dụng di chuyển trên toàn bộ repo, nhưng lời nhắc nên giới hạn công việc.

Update the LLM client setup so all OpenAI-compatible chat requests use:
- FLATKEY_API_KEY for the bearer token
- FLATKEY_BASE_URL as the API root
- FLATKEY_MODEL as the model alias

Do not hardcode secrets.
Do not change prompts, business logic, or retry policy.
Update only the client factory and the smallest test needed to verify the route.

Điều đó giữ cho công việc API tương thích OpenAI của Windsurf được giới hạn trong phạm vi cấu hình, không phải là một cuộc tái cấu trúc rộng lớn.

Bước 4: Giữ cấu hình MCP riêng biệt

Đây là lỗi thiết lập phổ biến nhất. Cấu hình MCP của Windsurf kết nối Cascade với các công cụ. Một mục MCP từ xa có thể trông như thế này:

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

serverUrl đó không phải là nơi bạn đặt https://router.flatkey.ai/v1. Máy chủ MCP có thể hiển thị các công cụ cho Cascade, và các công cụ đó có thể gọi Flatkey nội bộ nếu bạn xây dựng chúng theo cách đó. Nhưng cấu hình vận chuyển MCP và định tuyến mô hình tương thích OpenAI là các lớp khác nhau.

Sử dụng cách phân chia này:

Nếu máy chủ MCP của bạn gọi một mô hình, hãy đặt khóa Flatkey ở phía máy chủ MCP, không phải trong cấu hình máy khách Windsurf, trừ khi mô hình bảo mật của bạn cho phép rõ ràng thông tin xác thực của nhà phát triển cục bộ.

Bước 5: Lưu một gói xác minh

Một cuộc di chuyển API tương thích OpenAI của Windsurf chỉ sẵn sàng khi bạn có thể chứng minh rằng tuyến đường hoạt động và có thể được khôi phục. Mục đích của một gói xác minh API tương thích OpenAI của Windsurf là làm cho thay đổi tuyến đường đầu tiên đủ nhỏ để các bộ phận kỹ thuật, tài chính và vận hành có thể cùng nhau kiểm tra.

Để biết các trường sử dụng sâu hơn, hãy sử dụng hướng dẫn bảng điều khiển sử dụng token sau khi kiểm tra sơ bộ đầu tiên hoạt động.

Bước 6: Kiểm tra streaming và công cụ sau khi trò chuyện thông thường

Đừng bắt đầu với tuyến đường khó nhất. Trước tiên, hãy chứng minh một yêu cầu trò chuyện không streaming. Sau đó, kiểm tra streaming và các lệnh gọi công cụ như các hợp đồng riêng biệt.

Bằng chứng 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." }
    ]
  }'

Bằng chứng gọi công cụ nên sử dụng một lược đồ hàm nhỏ trước khi bạn thử một bộ công cụ sản xuất:

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

Nếu trò chuyện thông thường thành công nhưng streaming hoặc các công cụ thất bại, bạn không còn đang gỡ lỗi URL cơ sở nữa. Bạn đang kiểm tra khả năng định tuyến, hỗ trợ mô hình, phân tích cú pháp SDK, hoặc hành vi cổng cho tính năng đó.

Bảng khắc phục sự cố

Danh sách kiểm tra cuối cùng

Trước khi tăng lưu lượng, hãy xác nhận:

1. Mục tiêu là lưu lượng ứng dụng, tập lệnh hoặc công cụ xung quanh Windsurf, không phải là một cài đặt nhà cung cấp Cascade gốc không được ghi nhận.
2. FLATKEY_API_KEY, FLATKEY_BASE_URL, và FLATKEY_MODEL được cấu hình bên ngoài kiểm soát nguồn.
3. Lệnh curl trực tiếp hoạt động với $FLATKEY_BASE_URL/chat/completions.
4. Factory SDK của ứng dụng sử dụng cùng một khóa, URL cơ sở và bí danh mô hình.
5. Streaming và các công cụ được kiểm tra riêng biệt với trò chuyện thông thường.
6. Nhật ký sử dụng hoặc yêu cầu của Flatkey hiển thị yêu cầu kiểm tra.
7. Các giá trị khôi phục được ghi lại trước khi chuyển lưu lượng sản xuất.

Một thiết lập API tương thích OpenAI của Windsurf hữu ích khi nó minh bạch về ranh giới: Windsurf giúp bạn xây dựng và sửa đổi mã, trong khi Flatkey định tuyến các lệnh gọi tương thích OpenAI mà mã đó thực hiện. Khi bạn sẵn sàng định tuyến các lệnh gọi đó qua một khóa duy nhất, hãy nhận một khóa Flatkey và bắt đầu với một bài kiểm tra khói (smoke test) có rủi ro thấp.