OpenHands + JoinGonka Gateway: agen di endpoint sendiri

Saat ini proyek tersebut memiliki beberapa antarmuka, dan lokasi untuk mencari pengaturan model bergantung pada mana yang Anda jalankan. Nilai-nilainya sendiri sama di mana-mana — hanya jalurnya yang berbeda.

Untuk Agent Canvas diperlukan Node.js dan uv — tempat server lokal agen berjalan (detail ada di instruksi instalasi). Instruksi menyebutkan Node.js 22.12 atau yang lebih baru, namun paket itu sendiri sejak versi 1.17 menetapkan Node.js 24 ke atas — gunakan versi 24 agar tidak mendapatkan peringatan versi yang tidak kompatibel. Tersedia juga opsi dalam container: image ghcr.io/openhands/agent-canvas memberikan antarmuka di http://localhost:8000/canvas dan hanya melihat direktori yang Anda mounting.

Kunci JoinGonka. Daftar di gate.joingonka.ai/register, konfirmasi alamat Anda, dan buat kunci dengan awalan jg- di bagian «API-keys». Satu kunci dan satu saldo berlaku untuk semua model di jaringan. Daftar alat penginstal @joingonka/setup tidak menyertakan OpenHands, dan itu bukan kelalaian: pengaturannya tersimpan di dalam antarmuka dan di penyimpanan backend yang aman, bukan di file konfigurasi teks yang bisa diubah dengan mudah dari luar.

Langkah 1. Jalankan Agent Canvas dan buka Settings > LLM. Wizard peluncuran pertama menawarkan penyedia OpenHands bawaan — langkah ini bisa dilewati, karena pengaturan mudah diakses nanti.

Langkah 2. Klik Add LLM Profile dan buka tab Advanced: tab Basic hanya menawarkan penyedia dan model dari daftar bawaan.

Langkah 3. Isi ketiga kolom tersebut:

Langkah 4. Simpan profil. Sebelum menyimpan, Canvas memeriksa konfigurasi dengan permintaan dari backend: jika kunci ditolak atau model tidak tersedia, profil tidak akan disimpan, dan Anda akan melihat teks kesalahan.

Langkah 5. Mulai percakapan baru dan kirim pesan singkat. Percakapan yang sudah terbuka akan terus berjalan menggunakan model yang digunakan saat dimulai.

Mengapa openai/. LiteLLM menentukan penyedia melalui prefiks model. Prefiks openai/ tidak berarti "model dari OpenAI", melainkan "berbicara dengan server menggunakan protokol OpenAI Chat Completions". Hanya segmen pertama yang dipotong, sehingga pengidentifikasi asli sampai ke gateway — deepseek-ai/DeepSeek-V4-Flash-0731. Dalam dokumentasi OpenHands, skema yang sama ditunjukkan dengan contoh openai/qwen/qwen3.6-35b-a3b. Tanpa prefiks, LiteLLM akan menolak untuk bekerja dengan pesan LLM Provider NOT provided.

Mengapa /v1 dan tidak ada yang lain. LiteLLM mengakses server melalui klien resmi OpenAI, yang secara otomatis menambahkan /chat/completions. Oleh karena itu, alamat harus diakhiri dengan /v1: tanpa akhiran, permintaan akan meleset dari API, dan dengan tambahan akhiran, permintaan akan diarahkan ke jalur yang tidak ada. Persyaratan lain dari Canvas: alamat harus dapat diakses dari backend, bukan hanya dari peramban. Gateway adalah alamat HTTPS publik, yang terlihat dari kontainer Docker sama seperti dari host; trik seperti host.docker.internal hanya diperlukan untuk model yang ada di mesin Anda.

Profil untuk ketiga model. Buat profil untuk setiap model jaringan dan beri nama singkat — misalnya deepseek, glm, dan minimax (dokumentasi menyebutkan batas sepuluh profil). Anda dapat berpindah profil langsung di dalam percakapan tanpa kehilangan konteks: menggunakan tombol pemilih profil di kolom input atau perintah /model glm; /model tanpa argumen akan menampilkan daftar. Agar tidak perlu memasukkan kunci di setiap profil, Anda dapat menyimpannya satu kali di blok Provider Connections — tersedia di backend lokal.

Antarmuka lama di Docker. Kolomnya sama: Settings → tab LLM → aktifkan Advanced → Custom Model, Base URL, API Key → Save Changes.

CLI dipasang dengan satu perintah lewat uv dan saat pertama dijalankan akan memandu Anda menyiapkan model; nanti Anda bisa kembali ke sana dengan Ctrl+P → Settings:

uv tool install openhands --python 3.12
openhands

Untuk skrip, variabel lingkungan lebih praktis. Satu detail penting: secara default CLI mengabaikannya dan hanya menerapkannya dengan flag --override-with-envs — untuk satu kali jalan, tanpa menyimpan apa pun:

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

Set yang sama berfungsi tanpa antarmuka — untuk CI dan tugas batch:

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

Dalam mode headless, agen selalu bertindak dengan persetujuan otomatis, jadi jalankanlah di tempat yang memberinya kebebasan penuh: di direktori terpisah atau kontainer. Flag --json mengubah output menjadi aliran event JSONL — mudah diproses dalam pipeline. Begitulah cara kami menguji integrasi ini pada 21 September 2026 di CLI 1.16.0: di header CLI mencetak Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731, lalu agen membaca file dan menjawab secara substantif.

Pengaturan CLI yang tersimpan berada di ~/.openhands/agent_settings.json: model di dalamnya diubah dengan menyunting tiga field blok llm — model, api_key, dan base_url. Sebaiknya jangan membuat file itu dari nol: wizard peluncuran pertama juga menuliskan pengaturan agen lainnya ke sana, termasuk kompresi riwayat, yang tanpanya percakapan panjang akan mentok di jendela konteks.

Jika Anda menyematkan agen ke dalam kode Anda sendiri, OpenHands SDK menerima tiga nilai yang sama:

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

Harga model di jaringan sama, jadi pilihan bergantung pada perilaku. Dua angka penting bagi agen otonom. Jendela konteks: setiap langkah mengirim ulang riwayat, dan semakin panjang jendelanya, semakin lama agen bekerja tanpa kehilangan informasi. Batas respons: langkah di mana agen menulis file besar secara utuh harus muat dalam satu respons. Tabel menunjukkan hasil dari pengujian kami atas tugas yang sama (membaca file dan menemukan kesalahan) melalui OpenHands CLI 1.16.0 dengan SDK 1.21.0.

Skema kerja untuk tugas jangka panjang mengikuti saran dari dokumentasi OpenHands — rencanakan dengan satu model, eksekusi dengan yang lain. Mulai percakapan pada profil glm dan minta rencana tanpa melakukan perubahan file; lalu kirim /model deepseek dan beri perintah untuk mengeksekusi. Riwayat, file, dan status tugas tetap terjaga saat beralih. Gunakan profil minimax sebagai pilihan ketiga: nyaman untuk digunakan ketika dua model lainnya kehabisan kapasitas di jam sibuk, dan Anda bisa menetapkan pembuatan judul percakapan untuk profil ini di Settings > Application.

Kompresi riwayat. Bahkan jendela ratusan ribu token tetap terbatas untuk tugas berjam-jam. Di OpenHands, kondenser menangani hal ini: ia meringkas peristiwa lama menjadi ringkasan singkat, yang menurut dokumentasi, mengurangi latensi dan penggunaan token dalam percakapan panjang. Di Agent Canvas, ini dikonfigurasi di bagian Settings > Condenser; dalam pengujian CLI kami, fitur ini aktif secara otomatis dengan ambang batas 80 peristiwa.

Batas model. OpenHands mengambil jendela konteks dan batas respons dari direktori LiteLLM, dan ID jaringan Gonka tidak ada di sana (kami telah memeriksa pada LiteLLM 1.81), jadi agen tidak memiliki nilai sendiri untuk model ini. Hal ini tidak mengganggu operasional: gateway menerapkan batas respons sendiri sesuai tabel di atas. Jika ingin menetapkan batas secara eksplisit, gunakan field max_input_tokens dan max_output_tokens di SDK, dan di Canvas, tab All menampilkan semua field profil. Detail selengkapnya tentang model default tersedia di ulasan DeepSeek V4 Flash.

Anda dapat memastikan bahwa permintaan benar-benar melalui gateway dari dua sisi. Dari sisi OpenHands — buka percakapan baru dan berikan tugas singkat seperti "baca README dan jelaskan dalam satu kalimat": agen harus memanggil alat (tool) dan menjawab. Dari sisi gateway — buka dasbor, bagian "Penggunaan" (Usage): permintaan akan muncul dalam rincian "Per model", dan di blok "Per kunci" (By keys), waktu permintaan terakhir akan diperbarui. Jika kosong, berarti percakapan terjadi di profil lain: periksa profil mana yang ditandai aktif.

Menurut dokumentasi OpenHands, jumlah pengulangan dan jeda di antaranya saat terjadi kesalahan 429 dapat diatur melalui variabel LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT, dan LLM_RETRY_MAX_WAIT. Nilai default dalam dokumentasi dan SDK berbeda, jadi acuannya adalah kondisi aktual: dalam status percakapan CLI 1.16.0, kami melihat 5 upaya dengan jeda mulai dari 8 hingga 64 detik.

Melalui JoinGonka Gateway, harga token adalah $0.0069 per juta untuk input dan $0.021 per juta untuk output — harga ini sama untuk semua model jaringan dan diambil secara langsung di halaman ini.

Estimasi di kolom kanan didasarkan pada harga September 2026; detail mengenai ekonomi agen dibahas secara mendalam dalam artikel tentang API termurah untuk AI-agen.

Batas pengeluaran. OpenHands menyarankan untuk menetapkan batas pengeluaran — gateway telah mengintegrasikannya langsung ke dalam model pembayaran: saldo prabayar, dan agen tidak akan menghabiskan lebih dari yang ada di akun. Sisa saldo dan pengeluaran harian dapat dilihat di dasbor. Untuk CI dan otomatisasi latar belakang, gunakan kunci terpisah agar pengeluarannya tidak tercampur dengan milik Anda; kunci turunan dengan batas harian dijelaskan dalam artikel tentang Management Keys.

Batas kepercayaan. Agent Canvas yang dijalankan melalui npm beroperasi dengan hak pengguna Anda dan dapat melihat seluruh sistem file. Untuk kode pihak lain, gunakan versi Docker: agen hanya akan melihat direktori yang dipasang (mounted). Ini adalah properti dari OpenHands itu sendiri, tidak bergantung pada penyedia model.

Percakapan tetap milik Anda. OpenHands menyimpan riwayat percakapan di ~/.openhands dan mengirimkannya ke model di setiap langkah; gateway tidak menyimpan percakapan — prompt dan kode Anda tidak tertinggal di gateway setelah mendapatkan jawaban.

Jika tugas melibatkan gambar — tangkapan layar antarmuka, diagram — buat profil terpisah untuknya dengan model vision: model jaringan Gonka bersifat teks. Untuk kode, perintah, dan file, ini bukan batasan.