Client tools

Các hướng dẫn dưới đây dùng API key tạo trên website của hệ thống, kèm endpoint và model được cấp cho key.

Tool nào dùng được?

Tool	Cách kết nối	Lưu ý
OpenClaw	Custom provider	Chọn đúng giao thức của model
Hermes Agent	Custom endpoint	Cấu hình bằng `hermes model`
OpenCode	Custom provider	Phân biệt Chat Completions và Responses
Cursor	OpenAI key + Override Base URL	Có điều kiện; không dùng cho Tab completion
Qwen Code	Custom Provider / `settings.json`	Không bắt buộc dùng model Qwen
Chatbox	Custom provider	Phân biệt API Host và API Path
Cline	OpenAI Compatible	Model cần hỗ trợ tool calling để chạy agent
DeepSeek Harness	Custom model API	Có ba lựa chọn giao thức; đang developer preview
9Router	OpenAI Compatible provider	Thêm API VNAI Pro làm provider upstream

Phạm vi xác minh: đối chiếu tài liệu/mã nguồn chính thức ngày 27/09/2026 và các giao thức của gateway. Đây là hướng dẫn cấu hình tương thích, chưa phải kết quả chạy inference thực tế cho mọi tool/model/group. Quyền model và khả năng tool calling cần kiểm tra bằng key của bạn.

1. Chuẩn bị key và model

Làm theo hướng dẫn tạo API key tại https://api.vnaipro.app/keys; kiểm tra số dư tại https://api.vnaipro.app/wallet và quota còn lại của key.
Chọn group Auto để dùng chung một key cho Codex, Claude và các model khác được hỗ trợ, hoặc chọn group riêng chứa model muốn dùng.
Mở Kiểm tra model, nhập key và sao chép model ID chính xác.
Thay YOUR_API_KEY và mọi chỗ YOUR_MODEL_ID trong hướng dẫn bằng giá trị của bạn.

Danh sách /v1/models xác nhận model có trong catalog của key; không tự chứng minh model hỗ trợ mọi giao thức, ảnh, reasoning hay tool calling.

2. Chọn đúng URL và giao thức

Mục đích	URL của môi trường này
URL gốc gateway	`https://api.vnaipro.app`
Base URL cho OpenAI Chat Completions / Responses	`https://api.vnaipro.app/v1`
Danh sách model	`https://api.vnaipro.app/v1/models`
Request Chat Completions	`https://api.vnaipro.app/v1/chat/completions`
Request Responses	`https://api.vnaipro.app/v1/responses`
Request Anthropic Messages	`https://api.vnaipro.app/v1/messages`

Các ô Base URL thường cần URL kết thúc bằng /v1, không phải URL request đầy đủ. Các adapter Anthropic có quy tắc khác; làm theo trang của từng tool. Không dùng domain docs làm API endpoint.

Key được dán nguyên vào ô API key, không thêm Bearer . Client tự tạo header xác thực. Lưu key trong cấu hình cá nhân; không commit file chứa key vào Git.

3. Kiểm tra sau cấu hình

Tạo hội thoại mới, chọn provider và model vừa thêm.
Gửi “Chỉ trả lời OK” để kiểm tra xác thực và phản hồi.
Với coding agent, dùng thư mục thử nghiệm và yêu cầu đọc một file hoặc liệt kê file. Giữ bước duyệt tool của client.
Kiểm tra lịch sử sử dụng trên website để xác nhận request đi qua gateway.

Chat chạy được chưa có nghĩa agent đã chạy được: model và kênh upstream còn cần hỗ trợ streaming và tool/function calling. Dịch vụ web search, ảnh, giọng nói hoặc embedding của client có thể cần endpoint/key khác.

Lỗi thường gặp

Lỗi	Cách xử lý
`401/403`	Kiểm tra key, môi trường, quyền group, số dư và giới hạn key
`404` hoặc trả về HTML	Kiểm tra domain API, giao thức và tránh lặp `/v1/v1`
Model không tồn tại	Dùng ID từ Kiểm tra model, không dùng tên hiển thị
Chat được nhưng tool lỗi	Kiểm tra model/kênh có tool calling và dùng đúng adapter
`400` với tham số không hỗ trợ	Đối chiếu thông báo lỗi; bỏ tùy chọn reasoning/ảnh/tham số mà model không nhận
`429`	Kiểm tra quota và giảm số request/agent chạy cùng lúc