Cursor là trình soạn thảo mã AI được dùng rất rộng rãi. Ngoài hạn mức mô hình tích hợp, nó còn cho phép điền API Key và Base URL của riêng bạn. Với các đội trong nước, kết nối Cursor vào một cổng tương thích OpenAI thống nhất giúp cố định đường truy cập, tập trung hóa đơn và chuyển đổi giữa các mô hình.

Bài viết đi theo trình tự thao tác thực tế, làm rõ chuẩn bị, cấu hình, kiểm tra, giới hạn và triển khai trong nhóm. Tên menu có thể khác nhau giữa các phiên bản; hãy lấy Cursor Settings đang cài trên máy bạn làm chuẩn.

Ghi chú: Cursor là nhãn hiệu của Anysphere, Inc. Bài viết chỉ nhằm giải thích kỹ thuật, không có quan hệ trực thuộc hay đại lý với Cursor/Anysphere; giao diện, gói dịch vụ và quy tắc tính phí lấy trang của Cursor làm chuẩn.

1. Phân biệt hai loại "Cursor API"

Loại thứ nhất là API do chính nền tảng Cursor mở, ví dụ Cloud Agents và giao diện quản trị; Key được tạo trong tài khoản Cursor và dùng để gọi dịch vụ của Cursor. Loại thứ hai là "mang Key mô hình của bạn" (BYOK): điền Key của nhà cung cấp mô hình vào Cursor để trình soạn thảo dùng tài khoản của bạn gọi mô hình. Bài viết này nói về loại thứ hai.

Có một tiền đề dễ bị bỏ qua: yêu cầu mô hình của Cursor được máy chủ Cursor chuyển tiếp, không phải kết nối trực tiếp từ máy bạn. Vì vậy Base URL phải là địa chỉ truy cập được từ internet công cộng. Cổng chỉ truy cập được trong mạng nội bộ công ty thường khiến phía Cursor hết thời gian chờ. ZSQH AI Gateway là dịch vụ công cộng nên thường không bị giới hạn này.

2. Chuẩn bị Key, Base URL và tên mô hình

Trước khi bắt đầu, chuẩn bị ba thứ: một API Key, một địa chỉ tương thích và một mã mô hình chính xác.

  1. Mở trang đăng ký ZSQH AI Gateway, đăng ký và đăng nhập bảng điều khiển.
  2. Vào mục "API Key", tạo khóa mới, đặt tên rõ mục đích, ví dụ cursor-may-tram-work.
  3. Đặt hạn mức và thời gian hết hạn. Tài khoản cá nhân cũng nên đặt để tránh tiêu thụ bất thường.
  4. Sao chép Key, lưu vào trình quản lý mật khẩu. Bảng điều khiển thường chỉ hiển thị đầy đủ một lần.
  5. Mở giá mô hình, ghi lại mã mô hình cần dùng. Giá và mô hình sẽ điều chỉnh; lấy nội dung hiện tại trên trang làm chuẩn.

Cách viết ba mục cấu hình như sau:

Base URL: https://ai.zhongshangqihang.com/v1
API Key:  sk-... (tạo trong bảng điều khiển, chỉ lưu trong trình quản lý mật khẩu)
Model:    theo mã mô hình hiện đang hiển thị trên trang "giá mô hình"

Base URL dùng địa chỉ tương thích OpenAI, kết thúc bằng /v1. Đừng điền địa chỉ gốc của Anthropic, cũng đừng tự thêm /chat/completions, nếu không dễ bị lặp đường dẫn.

3. Điền cấu hình trong Cursor

Đường dẫn phổ biến là Cursor Settings → Models → API Keys. Các phiên bản khác nhau có thể thêm bớt tùy chọn, nhưng các bước cốt lõi gần giống nhau.

  1. Mở Cursor Settings, phím tắt thường là Cmd/Ctrl + ,.
  2. Vào Models, mở rộng khu vực API Keys.
  3. Bật OpenAI API Key, dán Key vừa tạo, bấm Save.
  4. Bật Override OpenAI Base URL, điền https://ai.zhongshangqihang.com/v1.
  5. Bấm + Add Custom Model (một số phiên bản gọi là + Add model), điền mã mô hình trên trang giá và bật mô hình đó.
  6. Chọn mô hình này trong bộ chọn mô hình của cuộc trò chuyện, gửi một yêu cầu đơn giản.

Nếu không tìm thấy Override OpenAI Base URL, nghĩa là phiên bản hoặc gói hiện tại không hỗ trợ trỏ lưu lượng tương thích OpenAI đến địa chỉ tùy chỉnh. Khi đó đừng thử đi thử lại; hãy nâng cấp phiên bản hoặc dùng bản cài có công tắc này.

Tên mô hình là định danh định tuyến, không phải ghi chú. Chữ hoa chữ thường, dấu gạch nối và hậu tố phiên bản đều phải khớp với cổng. Điền sai thường biểu hiện là mô hình không tồn tại, lỗi 404 hoặc yêu cầu bị từ chối.

4. Chọn mô hình thế nào

Trong Cursor có thể thêm nhiều mô hình tùy chỉnh, nhưng yêu cầu có thành công hay không phụ thuộc cổng có cung cấp mô hình cùng tên và có hỗ trợ cách gọi tương ứng hay không.

Tình huống sử dụng Bậc đề xuất Cách điền Lưu ý
Hỏi đáp hằng ngày, sửa nhỏ Mô hình nhẹ, nhanh Sao chép mã mô hình trên trang giá Độ trễ thấp, năng lực tái cấu trúc phức tạp hạn chế
Sửa nhiều tệp, Agent Mô hình mã chủ lực Sao chép mã mô hình trên trang giá Cần hỗ trợ gọi công cụ
Thiết kế kiến trúc, xử lý sự cố khó Mô hình năng lực cao Sao chép mã mô hình trên trang giá Chi phí cao hơn, dùng theo nhu cầu
Gợi ý Tab Mô hình tích hợp của Cursor Không qua Key tùy chỉnh BYOK không bao phủ gợi ý

Chế độ Agent có thể phụ thuộc Responses API hoặc gọi công cụ. Nếu cổng chỉ tương thích Chat Completions, một số chức năng Agent sẽ thất bại. Khi gặp tình huống này, hãy kiểm tra trong cuộc trò chuyện thường trước, rồi xác định là vấn đề mô hình hay không tương thích chức năng.

Ngoài ra, Auto, Composer và gợi ý Tab không nhất thiết đi qua Key của bạn. Theo trang trợ giúp của Cursor, gợi ý Tab luôn dùng mô hình tích hợp; chế độ Auto cũng có thể do Cursor tự định tuyến. Hãy coi mô hình tùy chỉnh là kênh "chỉ có hiệu lực sau khi chọn rõ ràng", sát thực tế hơn.

5. Kiểm tra cấu hình có hiệu lực

Chỉ nhìn Cursor có trả lời hay không là chưa đủ, vì câu trả lời có thể đến từ kênh tích hợp. Nên kiểm tra theo thứ tự sau.

  1. Tạo một cuộc trò chuyện trống mới để tránh ngữ cảnh lịch sử gây nhiễu.
  2. Chọn rõ mô hình tùy chỉnh trong bộ chọn mô hình, đừng dùng Auto.
  3. Gửi một yêu cầu ngắn, ví dụ nhờ giải thích một đoạn mã dưới mười dòng.
  4. Mở mức sử dụng hoặc log yêu cầu trong bảng điều khiển cổng, xác nhận có bản ghi cùng thời gian, cùng mô hình, cùng Key.
  5. Ghi lại kết quả kiểm tra. Nếu log không có bản ghi, yêu cầu chưa đến cổng; quay lại kiểm tra Base URL và công tắc.

Các lỗi thường gặp có thể đối chiếu như sau:

  • 401 hoặc 403: Key sai, bị vô hiệu hóa hoặc đã hết hạn mức.
  • 404: đường dẫn Base URL không đúng hoặc tên mô hình không tồn tại.
  • 429: chạm giới hạn tần suất hoặc đạt hạn mức của Key.
  • Hết thời gian: điểm cuối không truy cập được hoặc đường mạng có vấn đề.
  • Chỉ Agent thất bại: có thể do năng lực giao diện không khớp, không hẳn là lỗi Key.

6. Những giới hạn cần biết

  • BYOK chủ yếu bao phủ mô hình trò chuyện; gợi ý Tab vẫn dùng mô hình tích hợp của Cursor.
  • Các phiên bản khác nhau hỗ trợ Key OpenAI ở phạm vi khác nhau. Trang trợ giúp Cursor nêu Key OpenAI tự mang chỉ bao phủ mô hình trò chuyện tiêu chuẩn không có suy luận; mô hình suy luận và một số chức năng mới có thể không dùng được.
  • Yêu cầu được chuyển tiếp qua máy chủ Cursor, điểm cuối tùy chỉnh phải truy cập được từ internet công cộng.
  • Yêu cầu dùng Key tự mang không chắc hưởng chính sách không lưu dữ liệu của Cursor; cách xử lý dữ liệu phụ thuộc nhà cung cấp mô hình và cổng. Đội có yêu cầu cứng về lưu trữ dữ liệu nên đánh giá trước.
  • Gói nhóm và gói doanh nghiệp dù tự mang Key vẫn có thể bị thu phí nền tảng theo quy tắc của Cursor; cụ thể lấy trang tính phí của Cursor làm chuẩn.
  • Cursor cập nhật khá nhanh; tên menu, mô hình hỗ trợ và quy tắc tính phí đều có thể thay đổi.

7. Các bước triển khai trong nhóm

  • Thí điểm phạm vi nhỏ trước: chọn ba đến năm lập trình viên, thống nhất một mô hình chủ lực, chạy một tuần.
  • Ghi ba loại dữ liệu: tỷ lệ thành công của yêu cầu, độ trễ trung bình, mức tiêu thụ mỗi người mỗi ngày.
  • Tạo Key riêng cho từng người trên cổng, đặt hạn mức theo người, không dùng Key chung.
  • Duy trì bảng ánh xạ mô hình: điền gì trong Cursor, cổng tương ứng gì, chuyển sang gì khi thất bại.
  • Ghi cấu hình vào tài liệu nội bộ, gồm Base URL, mã mô hình và cách xử lý lỗi thường gặp.
  • Sau khi quan sát chi phí mới quyết định thành viên nào dùng Key tự mang, thành viên nào tiếp tục dùng hạn mức gói. Giá lấy giá mô hình làm chuẩn.
  • Khi nghỉ việc, đổi máy hoặc kết thúc dự án, vô hiệu hóa Key tương ứng ngay trong ngày.

8. Danh sách an toàn

  • Một mục đích một Key, không dùng lại qua thiết bị.
  • Đặt hạn mức và thời gian hết hạn.
  • Không ghi Key vào mã nguồn, .env, ảnh chụp màn hình hoặc phiếu công việc.
  • Không lưu Key lâu dài trên máy dùng chung.
  • Luân chuyển định kỳ; khi nghi ngờ lộ, vô hiệu hóa trước rồi điều tra.
  • Nhóm dùng chung qua cổng, giữ log yêu cầu để thuận tiện kiểm toán.
  • Với kho mã nhạy cảm, xác nhận trước dữ liệu có rời khỏi máy không và chảy đến những dịch vụ nào.

9. Câu hỏi thường gặp

Cursor có hỗ trợ mọi giao diện tương thích OpenAI không?

Không hẳn. Có dùng được hay không phụ thuộc phiên bản Cursor có cung cấp Override OpenAI Base URL và giao diện có tương thích đường dẫn, tham số mà nó thực sự gọi hay không. Hãy kiểm tra trong cuộc trò chuyện thường trước, rồi thử chức năng Agent.

Đã điền Key của mình, vì sao vẫn báo cần đăng ký gói?

Key tự mang không đồng nghĩa mở khóa toàn bộ chức năng. Một số chức năng trình soạn thảo, quản lý nhóm và mô hình tích hợp vẫn bị giới hạn bởi gói; lấy quy tắc gói hiện tại của Cursor làm chuẩn.

Vì sao gợi ý Tab không tiêu thụ Key của tôi?

Theo trang trợ giúp của Cursor, gợi ý Tab luôn dùng mô hình tích hợp của Cursor, không đi qua Key tự mang. Đây là thiết kế sản phẩm, không phải lỗi cấu hình.

Base URL nên điền địa chỉ gốc hay /v1?

Khi dùng giao thức tương thích OpenAI, điền đến /v1. Không mang theo /chat/completions, nếu không dễ bị lặp đường dẫn và lỗi 404.

Nhóm có thể dùng chung một Key không?

Về kỹ thuật thì được, nhưng không nên. Key chung không phân biệt được mức dùng của từng thành viên, khi lộ cũng khó truy vết. Mỗi người một Key, kèm hạn mức và log sẽ ổn định hơn.

Bước tiếp theo

Trước tiên hãy đăng ký ZSQH AI Gateway, tạo một Key riêng cho Cursor, điền Base URL và mô hình theo bài viết. Sau khi chạy thông cuộc trò chuyện thường, xem giá mô hình để điều chỉnh mô hình chủ lực và hạn mức.

Bài viết liên quan: