Hướng dẫn kết nối Cursor với API trung gian: Cấu hình Base URL tùy chỉnh

I. Cursor là gì?

Cursor là trình soạn thảo mã nguồn được tối ưu cho AI, được xây dựng dựa trên VS Code, tích hợp sâu các tính năng trò chuyện AI (Chat), tạo mã (Composer/Chat) và tự động hoàn thiện thông minh. Nó hỗ trợ BYOK (Bring Your Own Key), cho phép bạn sử dụng khóa API của riêng mình để kết nối với các điểm cuối mô hình cá nhân, phù hợp cho những người dùng không muốn mua gói đăng ký chính thức hoặc muốn đồng bộ chuyển đổi sang một mô hình cụ thể.

Sau khi kết nối qua trung gian, bạn có thể sử dụng các mô hình Claude / GPT / Gemini theo lưu lượng token bằng khóa sk- của hệ thống mà không cần mua gói đăng ký Cursor chính thức.

II. Công tác chuẩn bị

1. Đăng nhập vào bảng điều khiển API, tạo khóa sk-xxxxxx dành riêng cho bạn trong mục "API Key".
2. Xác nhận slug của mô hình muốn sử dụng (ví dụ: claude-sonnet-5, gpt-5.4, gemini-3.7-flash) trong phần "Định giá mô hình".
3. Xác nhận địa chỉ cổng kết nối (Gateway): https://www.relay-api.com.

III. Cấu hình trong Cursor

Mở Cursor → Settings → Models → API Keys (hoặc tìm kiếm Models trực tiếp trong phần cài đặt):

1. Chọn nhà cung cấp mô hình muốn kết nối (OpenAI chọn mục Open AI, Claude chọn mục Anthropic, Gemini chọn mục Google Gemini).
2. Nhập API Key: sk-khóa_của_bạn.
3. Nhập Override Base URL: Điền cổng kết nối tương ứng tùy theo nhà cung cấp:
   • Claude / Anthropic: https://www.relay-api.com
   • GPT / OpenAI: https://www.relay-api.com/v1
   • Gemini: https://www.relay-api.com/v1beta
4. Thêm ID mô hình chính xác mà bạn muốn sử dụng vào danh sách Models (sao chép slug từ bảng danh sách mô hình, không viết tên hiển thị).
5. Nhấp vào Verify để xác minh kết nối; sau đó thử gửi một đoạn văn bản ngắn trong Chat thông thường để xác nhận phản hồi bình thường.

IV. Nghiệm thu và khắc phục sự cố

Hiện tượng	Xử lý
401 / 403	Khóa không hợp lệ, chưa kích hoạt hoặc không đủ số dư; kiểm tra lại khóa sk- và nạp tiền.
404 / Mô hình không khả dụng	Slug mô hình không khớp với nền tảng hoặc mô hình chưa được kích hoạt; kiểm tra lại ID mô hình.
Verify thành công nhưng Agent thất bại	Phân biệt sự khác biệt giao thức /chat/completions, hãy thử nghiệm kết nối cơ bản bằng Chat thường trước.
Tab không tự động hoàn thiện	Các tính năng chuyên biệt như Tab Completion vẫn sử dụng mô hình tích hợp sẵn của Cursor, đây là giới hạn của sản phẩm, không liên quan đến cấu hình Base URL.

Khuyến nghị bảo mật: Không đẩy khóa API lên các kho lưu trữ công khai (public repository). Bạn nên tạo riêng một Key cho mỗi dự án và theo dõi số dư cũng như chi tiết sử dụng.