Hướng dẫn cấu hình Windsurf với Beeknoee

Windsurf là gì?

Windsurf là AI-powered IDE (trước đây thuộc Codeium) — nổi bật với tính năng Cascade Flow cho phép AI hiểu ngữ cảnh toàn bộ project và chỉnh sửa nhiều file.

🔴 Lưu ý quan trọng (cập nhật 2026): Cascade (engine AI gốc của Windsurf) không hỗ trợ cắm endpoint OpenAI-compatible tuỳ chỉnh. BYOK native của Windsurf hiện chỉ chấp nhận key Anthropic, không cho nhập Base URL/Key của bên thứ ba như Beeknoee cho Cascade. Vì vậy cách dùng Beeknoee trong Windsurf là cài extension AI coding (Cline / Kilo Code / Continue) rồi trỏ extension đó tới Beeknoee — Windsurf là bản fork của VS Code nên cài extension được.

Yêu cầu

• Windsurf IDE phiên bản mới nhất (windsurf.com)
• API Key từ Beeknoee Platform

📌 Bước 1: Tạo API Key

1. Truy cập https://platform.beeknoee.com/api-keys
2. Đăng nhập bằng tài khoản Google
3. Nhấn "Tạo API Key"
4. Copy API Key (dạng sk-bee-xxxx...)

⚠️ API key chỉ hiển thị 24 giờ đầu — copy và lưu ngay!

📌 Bước 2: Cài đặt Windsurf

1. Tải Windsurf tại windsurf.com
2. Cài đặt và mở Windsurf
3. Đăng nhập tài khoản Windsurf

📌 Bước 3: Cài extension AI coding và trỏ tới Beeknoee

🔴 Vì sao phải qua extension? Tính năng BYOK gốc của Windsurf chỉ hỗ trợ model Anthropic, và Cascade không có ô nhập Base URL tuỳ chỉnh. Nghĩa là bạn không thể trỏ thẳng Cascade về Beeknoee. Đây là giới hạn phía Windsurf, không phải do Beeknoee.

Cách dùng được Beeknoee trong Windsurf là cài một extension OpenAI-compatible chạy bên trong nó:

1. Mở Extensions (Ctrl+Shift+X) → tìm và cài Cline (hoặc Kilo Code, Continue)
2. Mở extension vừa cài → vào phần cấu hình provider
3. Chọn API Provider: OpenAI Compatible và điền:

4. Save — giờ bạn chat/agent qua extension này, chạy hoàn toàn trên Beeknoee.

⚠️ Base URL phải kết thúc bằng /v1: https://platform.beeknoee.com/v1

💡 Chi tiết cấu hình từng extension: xem Cline, Kilo Code, Continue.

📌 Bước 4: Sử dụng

Phím tắt AI trong Windsurf

Cascade Flow — Tính năng đặc biệt

Cascade Flow là tính năng nổi bật của Windsurf — AI tự động:

• Đọc và hiểu ngữ cảnh toàn bộ project (nhiều file)
• Đề xuất thay đổi trên nhiều file cùng lúc
• Hiển thị diff view trước khi áp dụng — bạn review rồi mới accept

Ví dụ sử dụng

• Ctrl+L → "Refactor toàn bộ authentication flow sang JWT"
• Ctrl+K → "Thêm error handling cho API call này"
• Ctrl+L → "Tạo REST API với NestJS cho feature Users"

Supercomplete

Bật Supercomplete trong Settings để nhận gợi ý code thông minh hơn — AI dự đoán code bạn muốn viết tiếp dựa trên context.

Models khuyên dùng với Windsurf

💡 Model ID chính xác và giá realtime xem tại trang Models trên Dashboard. Dùng model mạnh (Claude Sonnet, GPT-5 flagship) cho Cascade Flow để có trải nghiệm tốt nhất; model rẻ hơn cho inline edit nhanh.

🆓 Models miễn phí qua BeeSynapse

Khi đã kết nối email tại trang BeeSynapse Integrations, hệ thống tự động ưu tiên free quota:

Danh sách model free thay đổi theo quota nhà cung cấp — xem chính xác tại trang BeeSynapse Integrations. Bạn không cần thay đổi gì — Beeknoee tự route qua free quota trước, hết quota mới trừ VND.

Xử lý lỗi

"Could not verify API key"

• Kiểm tra API key bắt đầu bằng sk-bee-
• Kiểm tra key chưa bị thu hồi tại API Keys

"Model not available"

• Kiểm tra Model ID chính xác tại Text Models
• Thử đổi model sang deepseek/deepseek-v3.2 để test kết nối

"Network error"

• Kiểm tra Base URL: https://platform.beeknoee.com/v1
• Đảm bảo URL kết thúc bằng /v1

Cascade không hoạt động đúng

• Đảm bảo đang dùng model mạnh (claude-sonnet-4-6 hoặc gpt-5.4)
• Luôn review diff trước khi accept changes

HOÀN TẤT! 🎉

Cần hỗ trợ thêm? Sử dụng Support Chat (góc dưới phải trên platform) hoặc liên hệ qua email.