Dokumentasi

OpenHands

OpenHands merutekan setiap panggilan model melalui LiteLLM, jadi endpoint-nya terdiri dari dua field yang harus selaras: ID model dengan awalan openai/ dan URL dasar yang tetap menyertakan /v1. Jika pasangan itu benar, tab Advanced dapat mengakses Claude dan GPT dengan satu kunci.

Settings → LLM → Advanced menerima tiga field — Custom Model, Base URL, API Key — dengan model id membawa prefiks openai/ dan base URL tetap menyertakan /v1.

Pengaturan → LLM → Lanjutan

# 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.

Tetap sertakan /v1 dan awalan openai/ — keduanya merupakan satu keputusan, bukan dua. Halaman pengaturan OpenHands hanya menyatakan, “Jika penyedia Anda memiliki URL dasar khusus, tentukan di sini”, jadi field itu sendiri tidak memastikan formatnya. Awalanlah yang menentukannya. Halaman Configure a Model menetapkan openai/<served-model-id> untuk server yang kompatibel dengan OpenAI, dengan ID yang “biasanya diambil dari endpoint GET /v1/models miliknya”, dan satu-satunya contoh nilai yang diberikan untuk rute tersebut pada field Base URL diakhiri dengan /v1 — http://host.docker.internal:1234/v1 dalam panduan LM Studio. Perbedaannya menjadi bukti: model litellm_proxy/ didokumentasikan dengan URL dasar https://your-litellm-proxy.com, tanpa /v1 sama sekali. Mencampur keduanya — openai/ dengan origin tanpa akhiran, atau /v1 di bawah litellm_proxy/ — merupakan penyebab umum munculnya 404 alih-alih 401.

Kedua contoh openai/ OpenHands adalah server lokal — LM Studio, Ollama, vLLM, SGLang. Dokumentasinya tidak memberikan contoh penggunaan gateway kompatibel OpenAI jarak jauh, jadi kutipan di atas menjelaskan aturan awalan dan bentuk nilainya, bukan panduan khusus untuk kasus ini. Jika OpenHands kelak mendokumentasikan penggunaan seperti itu, halaman tersebutlah yang menjadi acuan.

Konfigurasi ini diambil dari dokumentasi OpenHands sendiri pada tanggal di bawah. Kunavo belum menjalankan OpenHands ke endpoint-nya — tidak ada percakapan, giliran streaming, siklus bolak-balik alat, atau versi klien yang dipatok. Halaman penyiapan yang diterbitkan bukanlah pengujian, dan isi di sini tidak boleh dianggap demikian. curl di bawah adalah bagian yang dapat Anda pastikan dalam sepuluh detik; perilaku klien ditentukan oleh OpenHands.

Kunavo tidak menyediakan model embedding, text-to-speech, atau speech-to-text, sehingga endpoint ini hanya menangani chat completions — biarkan LLM_EMBEDDING_MODEL dan LLM_EMBEDDING_DEPLOYMENT_NAME tidak ditetapkan, dan pertahankan penyedia yang sudah mendukung indeks vektor atau langkah audio dalam penyiapan Anda.

Belum punya kunci? Buat akun Kunavo, buat kunci (diawali sk-kn-) dan tambahkan kredit mulai dari $10 — panggilan dibayar dari saldo tersebut, dan panggilan yang gagal tidak ditagihkan. Dasbor kemudian terbuka pada penyiapan OpenHands.

Langkah demi langkah

Buat key di /app/keys dan salin — key hanya ditampilkan sekali.
Buka Settings → LLM, lalu aktifkan toggle Advanced. Tiga field akan muncul dengan urutan Custom Model, Base URL, API Key.
Ketik ID model dengan awalan — openai/claude-sonnet-5, bukan claude-sonnet-5. ID yang disediakan Kunavo adalah ID yang dikembalikan oleh GET /v1/models, yaitu daftar yang sama yang menurut dokumentasi OpenHands harus digunakan untuk mengambil ID kustom.
Tempelkan https://api.kunavo.com/v1 ke Base URL dan kunci Anda ke API Key, lalu klik Save Changes. OpenHands mendokumentasikan bahwa penyimpanan profil lokal akan lebih dulu memvalidasi konfigurasi terhadap backend dan memblokir penyimpanan jika validasi gagal, jadi kesalahan di sini merupakan penolakan nyata, bukan sekadar tampilan.
Periksa apa yang dapat dijangkau backend, bukan browser Anda. URL dasar harus dapat diakses dari mesin yang menjalankan Agent Server — dokumentasi secara eksplisit menyebutkan bahwa jika Agent Canvas berjalan di Docker, 127.0.0.1 adalah containernya. Endpoint publik seperti Kunavo adalah kasus yang mudah; proxy perusahaan di depannya bukan.
Mulai percakapan baru dan berikan tugas yang membaca serta mengedit file. OpenHands mencatat bahwa LLM tersimpan berlaku untuk percakapan baru dan percakapan lama harus dimulai ulang terlebih dahulu. Proses yang menggunakan alat akan memberi tahu Anda lebih banyak tentang kecocokan konfigurasi ini daripada sekadar sapaan.

Diperiksa terhadap Halaman Pengaturan Language Model (LLM) OpenHands pada 21 September 2026. Pengaturan pihak ketiga dapat berubah; jika nama bidang di sini tidak lagi sama dengan yang Anda lihat, halaman tersebut adalah acuan, bukan halaman ini.

Verifikasi sebelum men-debug klien

Satu permintaan menentukan apakah masalahnya ada pada endpoint, kunci, atau berkas konfigurasi. Jika ini mengembalikan JSON, base URL dan kunci yang sama berfungsi di 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-..."

ID model yang harus dimasukkan ke bidang

Setiap model teks dapat diakses melalui ID model — daftar terkininya ada di GET /v1/models, dan katalog beserta harga ada di halaman model. Tarif dalam USD per 1 juta token, input / output.

ID model	Kunavo masuk / keluar	Kegunaannya di OpenHands
`claude-sonnet-5`	$1.40 / $7.00	model kerja sehari-hari — masukkan sebagai openai/claude-sonnet-5
`claude-opus-4-8`	$3.50 / $17.50	model yang ditempatkan di posisi teratas keluarga Claude dalam tabel indeks OpenHands sendiri
`claude-haiku-4-5`	$0.70 / $3.50	profil murah untuk edit rutin, yang dapat dialihkan kembali di tengah percakapan
`gpt-5-6-sol`	$2.00 / $12.00	keluarga kedua dengan kunci dan URL dasar yang sama
`gpt-6-astra`	$4.00 / $20.00	pendapat ketiga saat rencana terus melenceng

Penagihan dilakukan per token dari saldo prabayar tanpa biaya bulanan — lihat penagihan. Pada konteks berulang — yang merupakan sebagian besar kiriman editor atau klien obrolan — caching prompt lebih memengaruhi tagihan daripada pilihan model.

Tiga batasan yang perlu diketahui sebelum melakukan debug

OpenHands memiliki lebih banyak komponen daripada CLI satu proses, dan dua di antaranya tampak seperti endpoint LLM padahal bukan. Informasi ini berasal dari dokumentasinya sendiri, yang dibaca pada tanggal di atas:

Sandbox bukan model. OpenHands menjalankan pekerjaan Anda di sandbox agent-server dan memanggil model melalui jaringan; keduanya adalah bagian terpisah dengan kredensial terpisah. Kunci yang dikonfigurasi di sini digunakan untuk panggilan model. Kunci itu tidak menentukan apa yang dapat dijangkau sandbox, dan masalah jaringan sandbox tidak tampak seperti kesalahan autentikasi.
Agen ACP sepenuhnya terpisah. Agent Canvas dapat mendelegasikan tugas ke Claude Code, Codex, atau Gemini CLI sebagai agen ACP, dan halaman Configure a Model menyatakan bahwa alat-alat tersebut “mengelola akses modelnya sendiri” — jadi profil LLM tidak mengalihkan proses tersebut. Jika Anda mengharapkan lalu lintas menggunakan kunci Anda tetapi tidak melihatnya, periksa agen mana yang sebenarnya berjalan. Perbandingan OpenHands dan Claude Code menjelaskan perbedaan ini, termasuk aturan prioritas kredensial yang menentukan pilihan.
Profil dan batas 10 profil. Konfigurasi yang disimpan menjadi profil LLM; profil yang terakhir disimpan menjadi profil aktif untuk percakapan baru. Profil dapat dialihkan di tengah percakapan tanpa kehilangan konteks — mekanisme inilah yang membuat ID murah dan ID mahal berguna dengan satu kunci. Dokumentasi membatasi jumlahnya hingga 10 profil per akun. Provider Connection menyimpan penyedia, kunci API, dan URL dasar opsional satu kali untuk beberapa profil, dan halaman yang sama menyebutkan bahwa panel tersebut tersedia pada backend agent-server lokal serta disembunyikan pada backend OpenHands Cloud.

Pertanyaan umum

Bagaimana cara mengarahkan OpenHands ke endpoint API kustom?

Buka Settings → LLM dan aktifkan toggle Advanced, yang menurut dokumentasi OpenHands digunakan untuk "menetapkan model kustom serta beberapa pengaturan LLM tambahan". Tiga field akan muncul dengan urutan berikut: Custom Model, Base URL, API Key. Masukkan ID model dengan awalan penyedia — openai/<model-id> untuk endpoint yang kompatibel dengan OpenAI — isi Base URL dengan endpoint, tempelkan kunci Anda, lalu klik Save Changes. Konfigurasi yang tersimpan menjadi profil LLM dan berlaku untuk percakapan baru; percakapan lama harus dimulai ulang agar konfigurasi tersebut digunakan.

Apakah Base URL OpenHands perlu diakhiri dengan /v1?

Untuk model dengan awalan openai/, ya. Halaman pengaturan hanya menyebutkan bahwa Base URL perlu ditentukan jika penyedia Anda memiliki URL khusus, jadi halaman itu sendiri tidak memastikan formatnya—awalan modellah yang menentukan. Halaman OpenHands Configure a Model menetapkan format openai/<served-model-id> untuk server yang kompatibel dengan OpenAI dan mengambil id dari endpoint GET /v1/models server tersebut. Satu-satunya contoh konkret Base URL yang ditampilkan untuk rute tersebut, dalam panduan LM Studio, adalah http://host.docker.internal:1234/v1. Sebaliknya, model litellm_proxy/ memiliki base URL yang didokumentasikan sebagai origin proxy saja tanpa /v1. Jadi, untuk Kunavo, nilainya adalah https://api.kunavo.com/v1.

Mengapa OpenHands menolak menyimpan profil LLM saya?

OpenHands memvalidasi profil lokal ke backend sebelum menyimpannya. Dokumentasinya menyebutkan bahwa jika validasi gagal—misalnya karena kunci API tidak valid atau model tidak tersedia—penyimpanan diblokir dan kesalahan ditampilkan. Jadi, penyimpanan yang diblokir merupakan penolakan sungguhan. Pastikan dulu di luar klien bagian mana yang salah: satu perintah curl ke endpoint /v1/models dengan kunci yang sama akan mengembalikan JSON jika pasangan URL dan kunci benar, 401 jika kuncinya salah, dan 404 jika URL-nya salah. Backend lama yang tidak mendukung validasi akan melewati pemeriksaan ini dan menyimpan profil seperti biasa.

Bisakah OpenHands menggunakan model Claude melalui endpoint yang kompatibel dengan OpenAI?

Ya. Awalan openai/ menamai protokol wire, bukan vendor: OpenHands mengirimkan permintaan chat completion berformat OpenAI ke Base URL yang Anda konfigurasi dan meneruskan id setelah garis miring apa adanya. Jadi, id Claude akan diresolusikan di endpoint tersebut, bukan di dalam OpenHands. Perlu diingat bahwa OpenHands sangat mengandalkan pemanggilan tool dan dokumentasinya sendiri menyebutkan bahwa aplikasi ini membutuhkan model yang mumpuni agar berfungsi dengan baik. Karena itu, gunakan id termurah yang bisa Anda temukan bukan pilihan yang tepat di sini.

Apakah Kunavo sudah menguji konfigurasi ini di OpenHands?

Tidak. Yang diperiksa pada 21 September 2026 adalah dokumentasi OpenHands sendiri—nama kolom, urutannya, aturan awalan, dan format Base URL dikutip dari sana. Kunavo belum menjalankan percakapan OpenHands melalui endpoint-nya dan tidak membuat klaim di sini tentang autentikasi, streaming, rangkaian bolak-balik tool, atau perutean model dalam versi klien yang dipatok. Satu hal yang dapat Anda pastikan secara terpisah adalah apakah endpoint dan kuncinya berfungsi, dan halaman ini menunjukkan caranya dengan curl.