Tài liệu

OpenHands

OpenHands định tuyến mọi lệnh gọi model qua LiteLLM, vì vậy điểm cuối cần hai trường phải khớp nhau: mã model có tiền tố openai/ và URL cơ sở giữ nguyên /v1. Đặt đúng cặp này, thẻ Advanced sẽ kết nối với Claude và GPT bằng cùng một khóa.

Settings → LLM → Advanced nhận ba trường — Custom Model, Base URL, API Key — với model id mang tiền tố openai/ và base URL giữ /v1.

Cài đặt → LLM → Nâng cao

# Settings → LLM → Advanced  (toggle "Advanced" on first)
Custom Model   openai/claude-sonnet-5
Base URL       https://api.kunavo.com/v1
API Key        sk-kn-...

# The "openai/" prefix is the provider, not a vendor: it tells OpenHands to
# speak the OpenAI Chat Completions protocol to the Base URL above. The model
# id after the slash is Kunavo's, and resolves at Kunavo.
#
# Keep the /v1. It belongs to the openai/ prefix — a litellm_proxy/ model
# takes the bare origin instead, which is the opposite convention.

Giữ nguyên /v1 và tiền tố openai/ — đây là một quyết định duy nhất, không phải hai quyết định riêng. Trang cài đặt của OpenHands chỉ ghi “Nếu nhà cung cấp của bạn có URL cơ sở riêng, hãy chỉ định tại đây”, vì vậy bản thân trường này không xác định được định dạng. Tiền tố mới là yếu tố quyết định. Trang Configure a Model yêu cầu dùng openai/<served-model-id> cho máy chủ tương thích OpenAI, với mã “thường lấy từ điểm cuối GET /v1/models”, và giá trị mẫu duy nhất họ đưa ra cho Base URL trên tuyến đó kết thúc bằng /v1 — http://host.docker.internal:1234/v1 trong hướng dẫn LM Studio. Sự đối lập này là bằng chứng: một model litellm_proxy/ được tài liệu hướng dẫn dùng URL cơ sở là https://your-litellm-proxy.com, hoàn toàn không có /v1. Trộn lẫn hai dạng — dùng openai/ với nguồn gốc URL trần hoặc đặt /v1 dưới litellm_proxy/ — là cách phổ biến dẫn đến lỗi 404 thay vì 401.

Cả hai ví dụ openai/ của OpenHands đều là máy chủ cục bộ — LM Studio, Ollama, vLLM, SGLang. Tài liệu của họ không đưa ra ví dụ thực tế nào về cổng tương thích OpenAI từ xa, nên nội dung trích ở trên là quy tắc tiền tố và cấu trúc giá trị, chứ không phải một trang viết về trường hợp này. Nếu sau này OpenHands có tài liệu hướng dẫn riêng, trang đó sẽ là nguồn có thẩm quyền.

Cấu hình này được đọc từ tài liệu chính thức của OpenHands vào ngày bên dưới. Kunavo chưa chạy OpenHands với điểm cuối của mình — chưa có cuộc hội thoại, lượt phản hồi truyền trực tuyến, vòng khứ hồi công cụ hay phiên bản ứng dụng khách được cố định nào. Trang hướng dẫn thiết lập đã xuất bản không phải là một lần kiểm thử, và không nên hiểu bất cứ nội dung nào ở đây là kết quả kiểm thử. Phần curl bên dưới là điều bạn có thể xác nhận trong mười giây; hành vi của ứng dụng khách là việc giữa bạn và OpenHands.

Kunavo không cung cấp model nhúng, chuyển văn bản thành giọng nói hoặc chuyển giọng nói thành văn bản, vì vậy điểm cuối này chỉ trả lời các yêu cầu chat completions — hãy để LLM_EMBEDDING_MODEL và LLM_EMBEDDING_DEPLOYMENT_NAME ở trạng thái chưa đặt, đồng thời giữ nguyên bất kỳ nhà cung cấp nào đang hỗ trợ chỉ mục vector hoặc bước xử lý âm thanh trong cấu hình của bạn.

Chưa có khóa? Tạo tài khoản Kunavo, tạo khóa (bắt đầu bằng sk-kn-) và nạp tín dụng từ $10 — các lệnh gọi được thanh toán từ số dư đó và các lệnh gọi thất bại không bị tính phí. Sau đó, bảng điều khiển mở tại phần thiết lập OpenHands.

Từng bước

Tạo khóa tại /app/keys rồi sao chép khóa — khóa chỉ hiển thị một lần.
Mở Cài đặt → LLM rồi bật công tắc Nâng cao. Ba trường xuất hiện theo thứ tự Model tùy chỉnh, URL cơ sở, Khóa API.
Nhập mã model cùng tiền tố — openai/claude-sonnet-5, không phải claude-sonnet-5. Các mã Kunavo cung cấp là những mã được GET /v1/models trả về, cũng chính là danh sách mà tài liệu của OpenHands hướng dẫn dùng để lấy mã tùy chỉnh.
Dán https://api.kunavo.com/v1 vào URL cơ sở và khóa của bạn vào Khóa API, rồi nhấp Lưu thay đổi. OpenHands nêu trong tài liệu rằng khi lưu hồ sơ cục bộ, cấu hình sẽ được xác thực với backend trước; nếu xác thực thất bại thì thao tác lưu bị chặn. Vì vậy, lỗi ở đây là một lần từ chối thực sự, không phải lỗi hiển thị.
Kiểm tra những gì backend có thể truy cập, không phải trình duyệt của bạn. URL cơ sở phải phân giải được từ máy chạy Agent Server — tài liệu nói rõ rằng nếu Agent Canvas chạy trong Docker thì 127.0.0.1 chính là container. Điểm cuối công khai như Kunavo là trường hợp đơn giản; có proxy doanh nghiệp đứng trước thì không.
Bắt đầu một cuộc hội thoại mới và giao cho nó một tác vụ đọc rồi chỉnh sửa tệp. OpenHands lưu ý rằng LLM đã lưu sẽ áp dụng cho các cuộc hội thoại mới, còn những cuộc hội thoại cũ phải được khởi động lại trước; một lần chạy có dùng đến các công cụ sẽ cho bạn biết nhiều hơn về cách kết hợp này so với một lời chào.

Đã kiểm tra đối chiếu với Trang Cài đặt Mô hình Ngôn ngữ (LLM) của OpenHands vào 21 tháng 9, 2026. Cài đặt của bên thứ ba có thể thay đổi; nếu tên trường ở đây không còn khớp với những gì bạn thấy, trang đó là nguồn có thẩm quyền, không phải trang này.

Xác minh trước khi gỡ lỗi ứng dụng khách

Một yêu cầu sẽ xác định liệu lỗi nằm ở endpoint, khóa hay tệp cấu hình. Nếu lệnh này trả về JSON, cùng base URL và khóa sẽ hoạt động trong OpenHands.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Đặt model id nào vào trường

Mọi mô hình văn bản đều có thể truy cập bằng model id — danh sách đang hoạt động là GET /v1/models, còn danh mục kèm giá nằm trên trang mô hình. Mức giá tính bằng USD trên mỗi 1M token, đầu vào / đầu ra.

ID mô hình	Kunavo vào / ra	Phù hợp ở đâu trong OpenHands
`claude-sonnet-5`	$1.40 / $7.00	model làm việc hằng ngày — nhập dưới dạng openai/claude-sonnet-5
`claude-opus-4-8`	$3.50 / $17.50	model được bảng chỉ mục chính thức của OpenHands đặt đầu nhóm Claude
`claude-haiku-4-5`	$0.70 / $3.50	hồ sơ chi phí thấp cho các chỉnh sửa thường lệ, có thể chuyển lại giữa cuộc hội thoại
`gpt-5-6-sol`	$2.00 / $12.00	một họ model thứ hai trên cùng khóa và cùng URL cơ sở
`gpt-6-astra`	$4.00 / $20.00	ý kiến thứ ba khi kế hoạch liên tục đi chệch hướng

Thanh toán theo token từ số dư trả trước, không có phí hàng tháng — xem trang Thanh toán. Với ngữ cảnh lặp lại — chiếm phần lớn dữ liệu mà trình chỉnh sửa hoặc ứng dụng trò chuyện gửi đi — bộ nhớ đệm prompt ảnh hưởng đến hóa đơn nhiều hơn lựa chọn mô hình.

Ba giới hạn cần biết trước khi xử lý sự cố

OpenHands có nhiều thành phần hơn một CLI chạy trong một tiến trình, và hai thành phần trông giống điểm cuối LLM nhưng không phải. Thông tin sau đây lấy từ tài liệu chính thức của họ, được đọc vào ngày ghi ở trên:

Sandbox không phải model. OpenHands chạy tác vụ của bạn trong sandbox của agent-server và gọi model qua mạng; đây là hai bề mặt riêng biệt với thông tin xác thực riêng. Khóa được cấu hình ở đây dùng cho các lần gọi model. Khóa này không quyết định sandbox có thể truy cập gì, và sự cố mạng của sandbox sẽ không biểu hiện thành lỗi xác thực.
Các tác nhân ACP hoàn toàn tách biệt. Agent Canvas có thể ủy quyền cho Claude Code, Codex hoặc Gemini CLI dưới dạng tác nhân ACP, và trang Configure a Model nêu rõ các tác nhân đó “tự quản lý quyền truy cập model của mình” — vì vậy hồ sơ LLM không chuyển hướng tiến trình con ấy. Nếu bạn mong đợi có lưu lượng qua khóa của mình nhưng không thấy, hãy kiểm tra tác nhân nào thực sự đang chạy. So sánh OpenHands với Claude Code trình bày sự khác biệt này, bao gồm quy tắc ưu tiên thông tin xác thực quyết định việc đó.
Hồ sơ và giới hạn 10 hồ sơ. Cấu hình đã lưu sẽ trở thành hồ sơ LLM, hồ sơ được lưu gần nhất sẽ hoạt động cho các cuộc hội thoại mới, và có thể chuyển đổi hồ sơ giữa cuộc hội thoại mà không mất ngữ cảnh — cơ chế này giúp bạn dùng một mã model rẻ và một mã model đắt trên cùng một khóa. Tài liệu giới hạn mỗi tài khoản ở 10 hồ sơ. Kết nối nhà cung cấp lưu nhà cung cấp, khóa API và URL cơ sở tùy chọn một lần để dùng cho nhiều hồ sơ; cùng trang đó cũng lưu ý bảng này có trên backend agent-server cục bộ và bị ẩn trên backend OpenHands Cloud.

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

Làm cách nào để trỏ OpenHands đến một điểm cuối API tùy chỉnh?

Mở Settings → LLM rồi bật công tắc Advanced; theo tài liệu OpenHands, đây là cách để “đặt model tùy chỉnh cũng như một số cài đặt LLM bổ sung”. Ba trường sẽ xuất hiện theo thứ tự: Custom Model, Base URL, API Key. Nhập mã model kèm tiền tố nhà cung cấp — openai/<model-id> cho điểm cuối tương thích OpenAI — điền điểm cuối vào Base URL, dán khóa rồi nhấp Save Changes. Cấu hình đã lưu sẽ trở thành hồ sơ LLM và áp dụng cho các cuộc hội thoại mới; cần khởi động lại những cuộc hội thoại cũ để chúng nhận cấu hình.

Base URL của OpenHands có cần kết thúc bằng /v1 không?

Với model có tiền tố openai/, thì có. Bản thân trang cài đặt chỉ nói cần chỉ định base URL nếu nhà cung cấp của bạn có URL riêng, nên riêng trang đó chưa xác định được định dạng — tiền tố mới là yếu tố quyết định. Trang Configure a Model của OpenHands quy định dùng openai/<served-model-id> cho máy chủ tương thích OpenAI và lấy id từ endpoint GET /v1/models; Base URL thực tế duy nhất được nêu cho cách này, trong hướng dẫn LM Studio, là http://host.docker.internal:1234/v1. Trường hợp model litellm_proxy/ thì ngược lại: base URL được tài liệu hướng dẫn là origin trần của proxy, không có /v1. Vì vậy, với Kunavo, giá trị là https://api.kunavo.com/v1.

Tại sao OpenHands từ chối lưu hồ sơ LLM của tôi?

OpenHands kiểm tra hồ sơ cục bộ với backend trước khi lưu, và tài liệu của họ cho biết nếu việc kiểm tra không đạt — ví dụ như khóa API không hợp lệ hoặc model không khả dụng — thao tác lưu sẽ bị chặn và lỗi sẽ được hiển thị. Vì vậy, lưu bị chặn là một lần từ chối thực sự. Trước tiên, hãy xác định phần nào sai bên ngoài ứng dụng: một lệnh curl đến /v1/models của endpoint với cùng khóa sẽ trả về JSON nếu cặp này hợp lệ, 401 nếu khóa sai và 404 nếu URL sai. Các backend cũ không hỗ trợ kiểm tra sẽ bỏ qua bước này và lưu bình thường.

OpenHands có thể dùng model Claude thông qua endpoint tương thích OpenAI không?

Có. Tiền tố openai/ chỉ định giao thức truyền tải, không phải nhà cung cấp: OpenHands gửi một yêu cầu chat completion theo định dạng OpenAI đến base URL bạn đã cấu hình và chuyển tiếp nguyên id phía sau dấu gạch chéo, vì vậy id Claude được phân giải tại endpoint đó chứ không phải bên trong OpenHands. Cần nhớ rằng OpenHands phụ thuộc nhiều vào khả năng gọi công cụ và tài liệu của họ cho biết ứng dụng cần một model mạnh để hoạt động tốt, vì vậy đây không phải nơi phù hợp để dùng id rẻ nhất bạn tìm được.

Kunavo đã kiểm thử cấu hình này trong OpenHands chưa?

Chưa. Nội dung được kiểm tra vào ngày 21 tháng 9 năm 2026 là tài liệu của chính OpenHands — tên các trường, thứ tự, quy tắc tiền tố và định dạng base URL đều được trích từ đó. Kunavo chưa chạy hội thoại OpenHands với endpoint của mình và không đưa ra khẳng định nào ở đây về xác thực, truyền phát, các lượt gọi công cụ qua lại hoặc định tuyến model trong một phiên bản client được cố định. Điều duy nhất bạn có thể tự kiểm tra riêng là endpoint và khóa có hoạt động hay không; lệnh curl trên trang này giúp kiểm tra việc đó.