Thiết lập API Cursor tương thích OpenAI: URL cơ sở, Tên Model và Nhật ký sử dụng

Việc thiết lập API tương thích OpenAI của Cursor có vẻ đơn giản nếu bạn chỉ nghĩ đến ba trường: khóa API, URL cơ sở và tên model. Trên thực tế, Cursor là một công cụ lập trình cấp cao hơn với trình chọn model, kế toán sử dụng, kiểm soát nhóm và đường dẫn xây dựng prompt riêng, vì vậy việc thiết lập an toàn hơn là một quy trình xác minh thay vì sao chép-dán một cách mù quáng.

Theo tài liệu về khóa API của Cursor công khai hiện tại được kiểm tra vào ngày 8 tháng 7 năm 2026, Cursor ghi nhận việc Mang theo Khóa API của riêng bạn (Bring Your Own API Key) cho các nhà cung cấp được nêu tên trong Cài đặt Cursor > Model. Tài liệu này ghi nhận các khóa của OpenAI, Anthropic, Google, Azure OpenAI và AWS Bedrock; tài liệu cũng nói rằng các khóa API tùy chỉnh chỉ hoạt động với các model trò chuyện, tính năng hoàn thành bằng phím Tab vẫn tiếp tục sử dụng các model tích hợp sẵn của Cursor, và các yêu cầu sử dụng khóa riêng vẫn đi qua máy chủ của Cursor để xây dựng prompt cuối cùng. Tài liệu công khai không ghi nhận một trường URL cơ sở tương thích OpenAI tùy ý chung.

Điều đó quan trọng đối với người dùng Flatkey. Flatkey cung cấp cho các nhóm một khóa duy nhất, một cổng kết nối tương thích OpenAI tại https://router.flatkey.ai/v1, quyền truy cập model qua nhiều nhà cung cấp, và xem xét việc sử dụng và chi phí ở một nơi. Nếu bản dựng Cursor, chính sách quản trị hoặc cấu hình nhà cung cấp của bạn có hiển thị một trường URL cơ sở OpenAI tùy chỉnh, hãy sử dụng hướng dẫn này để xác thực thiết lập. Nếu giao diện người dùng Cursor của bạn chỉ hỗ trợ các khóa API do nhà cung cấp sở hữu, hãy sử dụng các kiểm tra tương tự để quyết định khi nào nên giữ Cursor trên luồng nhà cung cấp được ghi nhận của nó và sử dụng Flatkey trong các công cụ hiển thị rõ ràng một URL cơ sở tùy chỉnh, chẳng hạn như các quy trình làm việc của Cline hoặc Claude Code router.

Mục tiêu không phải là ép buộc mọi yêu cầu của Cursor phải đi qua một cổng kết nối. Mục tiêu là làm cho mọi quyết định về API tương thích OpenAI của Cursor đều có thể kiểm tra được: ai sở hữu khóa, URL cơ sở nào thực sự được sử dụng, tên model nào được chọn, việc sử dụng xuất hiện ở đâu, và cách để hoàn tác.

Thiết lập API tương thích OpenAI của Cursor: cần xác minh điều gì trước tiên

Hãy bắt đầu với một bảng quyết định ngắn gọn trước khi thay đổi bất kỳ cài đặt nào.

Đây là quy tắc đầu tiên của việc thiết lập API tương thích OpenAI của Cursor: đừng coi trường khóa API là bằng chứng của một tuyến đường qua cổng kết nối. Một trường khóa chứng minh việc nhập thông tin xác thực. Một trường URL cơ sở, nhật ký yêu cầu và bản ghi sử dụng mới chứng minh việc định tuyến.

Các giá trị cần thu thập trước khi động đến Cursor

Hãy đặt các giá trị thiết lập vào một bảng tính nhỏ. Chia sẻ bảng này với người chịu trách nhiệm về thanh toán hoặc bảo mật, không chỉ với nhà phát triển thực hiện thay đổi giao diện người dùng.

Đối với một bài kiểm tra API tương thích OpenAI của Cursor, sai lầm phổ biến nhất là sử dụng tên hiển thị của model từ một hệ thống trong một hệ thống khác. Tên model của Cursor, ID model của nhà cung cấp và bí danh tuyến đường của Flatkey không tự động hoán đổi cho nhau được. Hãy chọn tên model từ nơi sẽ nhận yêu cầu.

Chạy một bài kiểm tra sơ bộ (smoke test) bên ngoài trước

Trước khi kiểm tra bên trong Cursor, hãy xác thực các giá trị của cổng kết nối ở bên ngoài Cursor. Các đoạn mã này chỉ là mẫu; hãy thay thế khóa và model bằng các giá trị từ tài khoản và danh mục Flatkey hiện tại của bạn.

export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_MODEL="your-current-model-alias"

curl -sS https://router.flatkey.ai/v1/models \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

Sử dụng phản hồi về các model để xác nhận ID hoặc bí danh model chính xác. Sau đó, kiểm tra đường dẫn trò chuyện:

curl -sS https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "Reply with exactly: cursor route probe ok"
      }
    ]
  }'

Lưu lại dấu thời gian yêu cầu, tên model, trạng thái HTTP, nội dung phản hồi và đối tượng usage nếu phản hồi có chứa nó. Định dạng API Chat Completions của OpenAI được xây dựng xoay quanh model và messages, và các phản hồi thành công có thể bao gồm thông tin sử dụng token. Điểm cuối models của OpenAI liệt kê các model hiện có cho một tài khoản. Hai sự thật đó làm cho bài kiểm tra sơ bộ (smoke test) này trở nên hữu ích trước khi bạn sử dụng Cursor.

Nếu bài kiểm tra bên ngoài này thất bại, đừng tiếp tục với Cursor. Hãy sửa khóa, bí danh model, hạn ngạch hoặc họ điểm cuối trước. Một bài kiểm tra bên ngoài thất bại sẽ không dễ gỡ lỗi hơn sau khi Cursor thêm vào bộ chọn model, trình tạo prompt và đường dẫn yêu cầu của riêng nó.

Chỉ cấu hình Cursor sau khi đường dẫn đã được chứng minh là hoạt động

Bây giờ hãy mở Cursor và kiểm tra các cài đặt thực tế có sẵn cho tài khoản của bạn.

1. Mở Cài đặt Cursor > Models.
2. Kiểm tra xem tổ chức của bạn có cho phép sử dụng khóa API cá nhân không. Quản trị viên doanh nghiệp có thể hạn chế việc sử dụng BYOK.
3. Nếu bạn đang sử dụng đường dẫn BYOK được tài liệu hóa của Cursor, hãy chọn hàng nhà cung cấp mà Cursor hỗ trợ và nhập khóa của nhà cung cấp đó.
4. Nếu môi trường Cursor của bạn có một trường URL cơ sở tùy chỉnh tương thích OpenAI, chỉ nhập phần gốc của URL cơ sở, ví dụ https://router.flatkey.ai/v1, không phải đường dẫn đầy đủ /chat/completions.
5. Nhập hoặc chọn tên model từ hệ thống nhận. Đối với Flatkey, hãy sử dụng bí danh model đã được xác nhận trong danh mục Flatkey hoặc trong bài kiểm tra sơ bộ /v1/models.
6. Lưu cài đặt, sau đó chọn model mục tiêu trong bộ chọn model của Cursor nếu nó được hiển thị ở đó.

Đây là điểm mà tiêu đề bài viết có thể gây hiểu lầm cho các nhóm: việc thiết lập API tương thích OpenAI của Cursor chưa hoàn tất khi trang cài đặt được lưu. Nó chỉ hoàn tất khi yêu cầu bạn gửi từ Cursor xuất hiện trong dấu vết sử dụng dự kiến.

Danh sách kiểm tra tên model cho việc định tuyến model của Cursor

Sử dụng bảng này khi có ai đó hỏi, "Tôi nên nhập tên model nào?"

Đối với việc triển khai API tương thích OpenAI của Cursor, hãy bắt đầu với chat văn bản thuần túy. Đừng sử dụng việc tái cấu trúc một codebase lớn, một lần chạy Agent sử dụng nhiều công cụ, hoặc một phiên Max Mode dài làm bài kiểm tra đầu tiên. Hãy làm cho prompt đầu tiên đủ đơn giản để bản ghi sử dụng là kết quả chính.

Xác minh nhật ký sử dụng ở ba nơi

Một thiết lập gateway trả về văn bản nhưng không để lại dấu vết sử dụng thì chưa sẵn sàng cho môi trường sản xuất. Kiểm tra ba lớp sau yêu cầu đầu tiên.

Chi tiết quan trọng về quyền sở hữu là tài liệu của chính Cursor nói rằng khóa API của bạn được gửi đến backend của Cursor với mỗi yêu cầu sử dụng khóa riêng để xây dựng prompt cuối cùng. Điều đó có nghĩa là một bài kiểm tra API tương thích OpenAI của Cursor nên được xem xét như một đường dẫn công cụ-cộng-gateway, chứ không phải là một cuộc gọi cục bộ trực tiếp từ máy tính xách tay của bạn đến nhà cung cấp.

Nếu nhóm của bạn dựa vào chính sách Cursor Zero Data Retention, hãy đọc ghi chú về quyền riêng tư của Cursor BYOK trước khi sử dụng khóa của riêng bạn. Cursor tuyên bố rằng chính sách Zero Data Retention của họ không áp dụng khi sử dụng khóa API của riêng bạn; việc xử lý dữ liệu tuân theo chính sách của nhà cung cấp đã chọn. Nếu bạn định tuyến qua Flatkey, hãy thêm chính sách hiện tại, bảng điều khiển và bằng chứng lưu giữ của Flatkey vào cùng một gói xem xét.

Xử lý sự cố lỗi URL cơ sở, khóa và model

Hầu hết các lỗi đều thuộc về một số ít nguyên nhân.

Hướng dẫn lỗi của chính OpenAI coi các lỗi xác thực, giới hạn tốc độ, hạn ngạch và dịch vụ quá tải là các hành động khác nhau của chủ sở hữu. Hãy duy trì sự tách biệt đó trong sổ tay vận hành Cursor của bạn. Chính sách thử lại sẽ không khắc phục được tên model sai, và một tên model mới sẽ không khắc phục được việc bị chặn bởi chính sách BYOK.

Khi nào không nên sử dụng Flatkey cho Cursor

Có những lúc quyết định tốt nhất về API tương thích OpenAI của Cursor là dừng lại.

Không định tuyến Cursor qua Flatkey nếu bản dựng Cursor hiện tại của bạn không cung cấp tùy chọn ghi đè URL cơ sở và quy trình làm việc của bạn yêu cầu một điểm cuối tùy chỉnh thực sự. Không định tuyến Cursor qua Flatkey nếu quản trị viên doanh nghiệp của bạn đã vô hiệu hóa các khóa API cá nhân. Không định tuyến Cursor qua Flatkey nếu việc đánh giá bảo mật của bạn phụ thuộc vào các kiểm soát quyền riêng tư của model tích hợp sẵn trong Cursor mà không áp dụng cho lưu lượng sử dụng khóa riêng.

Trong những trường hợp đó, hãy giữ Cursor trên đường dẫn nhà cung cấp đã được ghi trong tài liệu và sử dụng Flatkey ở những nơi client hỗ trợ rõ ràng các URL cơ sở tương thích OpenAI: SDK ứng dụng, công cụ nội bộ, kịch bản đánh giá, Cline, Open WebUI, LangChain, LlamaIndex, hoặc các bề mặt tích hợp khác. Nếu bạn cần mẫu di chuyển chung, hãy bắt đầu với hướng dẫn di chuyển API tương thích OpenAI. Đối với các mẫu bộ định tuyến tác nhân mã hóa, hãy so sánh thiết lập bộ định tuyến Claude Code API và thiết lập API tương thích Cline OpenAI.

Danh sách kiểm tra cho môi trường production

Trước khi coi như đã hoàn tất việc thiết lập API tương thích OpenAI của Cursor, hãy lưu lại các bằng chứng sau:

Thiết lập API tương thích OpenAI của Cursor có giá trị khi nó biến lưu lượng truy cập từ công cụ mã hóa thành việc sử dụng model có quản lý và có thể xem xét lại. Hãy giữ URL cơ sở, tên model, và bằng chứng nhật ký sử dụng cùng nhau. Khi bạn cần một khóa gateway và một nơi để xem xét lưu lượng model, hãy lấy một khóa Flatkey, thử nghiệm một yêu cầu trò chuyện có rủi ro thấp trước, và chỉ chuyển đổi sau khi nhật ký chứng minh được tuyến đường.