OpenHands + JoinGonka Gateway: kendi uç noktanızda ajan

Projenin bugün birkaç arayüzü vardır ve hangisinin sizde çalıştığına bağlı olarak model ayarlarının nerede aranacağı değişir. Değerlerin kendisi her yerde aynıdır, sadece onlara giden yol farklıdır.

Agent Canvas için Node.js ve uv gereklidir — ajanın yerel sunucusu bunun üzerinde çalışır (ayrıntılar kurulum kılavuzunda mevcuttur). Kılavuz Node.js 22.12 veya üzerini belirtir, ancak paketin kendisi 1.17 sürümünden itibaren Node.js 24 ve üzerini ister — uyumsuz sürüm uyarısı almamak için 24 sürümünü yükleyin. Bir de konteyner seçeneği vardır: ghcr.io/openhands/agent-canvas imajı, arayüzü http://localhost:8000/canvas adresinde sunar ve yalnızca bağladığınız (mount ettiğiniz) dizinleri görür.

JoinGonka anahtarı. gate.joingonka.ai/register adresinden kaydolun, adresinizi doğrulayın ve „API-Keys“ bölümünde jg- ön ekine sahip bir anahtar oluşturun. Bir anahtar ve bir bakiye, ağdaki tüm modeller için geçerlidir. @joingonka/setup yükleyicisinin araç listesinde OpenHands yoktur ve bu bir eksiklik değildir: ayarları, dışarıdan temiz bir şekilde yazılabilecek bir metin yapılandırma dosyasında değil, arayüzde ve arka uçun güvenli depolama alanında tutulur.

Adım 1. Agent Canvas'ı başlatın ve Settings > LLM kısmına gidin. İlk çalıştırma sihirbazı kendi OpenHands sağlayıcısını önerir; bu adımı atlayabilirsiniz, ayarlara daha sonra kolayca geri dönülebilir.

Adım 2. Add LLM Profile butonuna tıklayın ve Advanced sekmesine geçin: Basic sekmesi yalnızca yerleşik listedeki sağlayıcıları ve modelleri sunar.

Adım 3. Üç alanı doldurun:

Adım 4. Profili kaydedin. Kaydetmeden önce Canvas, konfigürasyonu arka uçtan bir istekle doğrular: anahtar reddedilirse veya model erişilebilir değilse, profil kaydedilmez ve hata metnini görürsünüz.

Adım 5. Yeni bir konuşma başlatın ve kısa bir mesaj gönderin. Hali hazırda açık olan konuşmalar, başlatıldıkları modelle çalışmaya devam eder.

Neden openai/. LiteLLM, sağlayıcıyı model önekine göre belirler. openai/ öneki "OpenAI'dan bir model" anlamına gelmez, "sunucuyla OpenAI Chat Completions protokolü üzerinden konuş" anlamına gelir. Sadece ilk segment kesilir, böylece ağ geçidine gerçek tanımlayıcı olan deepseek-ai/DeepSeek-V4-Flash-0731 ulaşır. OpenHands belgelerinde aynı şema openai/qwen/qwen3.6-35b-a3b örneğiyle gösterilmiştir. Önek olmazsa, LiteLLM LLM Provider NOT provided mesajıyla çalışmayı reddeder.

Neden /v1 ve daha fazlası değil. LiteLLM, sunucuya resmi OpenAI istemcisi aracılığıyla gider ve o zaten /chat/completions ekler. Bu nedenle adres /v1 ile bitmelidir: sonek olmadan istek API'yi ıskalar, fazladan bir ek ile mevcut olmayan bir yola gider. Canvas'ın bir diğer şartı: adresin sadece tarayıcıdan değil, arka uçtan da erişilebilir olması gerekir. Ağ geçidi halka açık bir HTTPS adresidir; Docker konteynerinden, ana makineden görüldüğü gibi görünür; host.docker.internal gibi numaralar sadece kendi makinenizdeki modeller için gereklidir.

Üç model için de profiller. Her ağ modeli için birer profil oluşturun ve bunlara kısa isimler verin; örneğin deepseek, glm ve minimax (belgeler on profil sınırı olduğunu belirtir). Bağlam kaybetmeden doğrudan konuşma içinde geçiş yapabilirsiniz: giriş alanındaki profil seçim butonuyla veya /model glm komutuyla; argümansız /model listeyi gösterir. Anahtarı her profile yapıştırmamak için, onu bir kez Provider Connections bloğunda kaydedebilirsiniz; yerel arka uçta mevcuttur.

Docker'daki önceki arayüz. Alanlar aynıdır: Settings → LLM sekmesi → Advanced etkinleştir → Custom Model, Base URL, API Key → Save Changes.

CLI, uv ile tek komutla kurulur ve ilk çalıştırmada sizi model yapılandırmasından kendisi geçirir; sonrasında Ctrl+P → Settings ile buraya dönebilirsiniz:

uv tool install openhands --python 3.12
openhands

Betikler için ortam değişkenleri daha kullanışlıdır. Önemli bir ayrıntı: CLI bunları varsayılan olarak yok sayar ve yalnızca --override-with-envs bayrağıyla uygular — tek bir çalıştırma için, hiçbir şey kaydetmeden:

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

Aynı set arayüz olmadan da çalışır — CI ve toplu görevler için:

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

Headless modda ajan her zaman otomatik onayla hareket eder; bu yüzden onu her şeyi yapabileceği bir yerde başlatın: ayrı bir dizinde veya konteynerde. --json bayrağı çıktıyı bir JSONL olay akışına dönüştürür — bunu bir iş hattında işlemek kullanışlıdır. Bağlantıyı tam da bu şekilde 21 Eylül 2026'da CLI 1.16.0 ile test ettik: CLI başlığında Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731 yazar, ardından ajan dosyayı okur ve özüne uygun yanıt verir.

Kaydedilmiş CLI ayarları ~/.openhands/agent_settings.json içinde bulunur: buradaki model, llm bloğundaki üç alan düzenlenerek değiştirilir — model, api_key ve base_url. Dosyayı sıfırdan oluşturmak iyi bir fikir değildir: ilk çalıştırma sihirbazı oraya ajanın diğer ayarlarını da yazar; bunlar arasında bağlam penceresine dayanan uzun sohbetler için gerekli olan geçmiş sıkıştırma da vardır.

Ajanı kendi kodunuza entegre ediyorsanız, OpenHands SDK aynı üç değeri kabul eder:

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"),
)

Ağ modellerindeki fiyat aynıdır, bu yüzden seçim tamamen davranışla ilgilidir. Otonom bir ajan için iki rakam önemlidir. Bağlam penceresi: Her adım geçmişi yeniden gönderir; pencere ne kadar uzun olursa, ajan o kadar uzun süre kayıp yaşamadan çalışır. Yanıt tavanı: Ajanın büyük bir dosyayı tamamen yazdığı adım, tek bir yanıta sığmalıdır. Tabloda, aynı görevi (dosyayı okumak ve hatayı bulmak) OpenHands CLI 1.16.0 ve SDK 1.21.0 ile çalıştırdığımız sonuçlar yer almaktadır.

Uzun süreli görevler için çalışma şeması, OpenHands belgelerindeki tavsiyeyi tekrarlar: bir modelle planlayın, diğeriyle uygulayın. Konuşmayı glm profilinde başlatın ve dosya düzenlemeleri olmadan bir plan isteyin; ardından /model deepseek komutunu gönderin ve yürütme komutunu verin. Geçmiş, dosyalar ve görev durumu geçiş yapıldığında korunur. minimax profilini üçüncü sırada tutun: Diğer ikisinin yoğun saatlerde kapasitesi bittiğinde bu profile geçmek uygundur ve Settings > Application kısmında konuşma başlıklarının oluşturulması ona atanabilir.

Geçmiş sıkıştırma. Yüz binlerce token'lık bir pencere bile saatler süren görevlerde sınırlıdır. OpenHands'te bundan kondansatör sorumludur: eski olayları kısa bir özette toplar, bu da belgelere göre uzun konuşmalarda gecikmeyi ve token tüketimini azaltır. Agent Canvas'ta bu Settings > Condenser bölümünden ayarlanır; CLI testimizde, 80 olaylık bir eşik ile kendiliğinden devreye girdi.

Model limitleri. OpenHands bağlam penceresini ve yanıt tavanını LiteLLM rehberinden alır, ancak Gonka ağı tanımlayıcıları orada yoktur (LiteLLM 1.81'de kontrol ettik), bu nedenle ajanın bu modeller için kendi değerleri yoktur. Bu durum çalışmayı engellemez: ağ geçidi, yukarıdaki tabloya göre yanıt tavanını kendisi uygular. Limitleri açıkça belirlemek isterseniz, SDK'da bunlar max_input_tokens ve max_output_tokens alanlarıdır, Canvas'ta ise All sekmesi profil alanlarının tam listesini açar. Varsayılan model hakkında detaylar DeepSeek V4 Flash genel bakış sayfasındadır.

İsteklerin gerçekten ağ geçidi üzerinden geçip geçmediğinden iki şekilde emin olabilirsiniz. OpenHands tarafında — yeni bir konuşma başlatıp "README dosyasını oku ve tek cümleyle özetle" gibi kısa bir görev verin: ajan aracı çağırmalı ve yanıt vermelidir. Ağ geçidi tarafında — panelde "Kullanım" bölümüne bakın: istek "Modellere göre" dökümünde görünecek ve "Anahtarlara göre" bloğunda son isteğin zamanı güncellenecektir. Eğer boş görünüyorsa, konuşma başka bir profil üzerinden yürütülüyor demektir: hangisinin aktif olarak işaretlendiğini kontrol edin.

OpenHands belgelerine göre, 429 hatası durumunda tekrar sayısı ve aralarındaki bekleme süreleri LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT ve LLM_RETRY_MAX_WAIT değişkenleriyle ayarlanabilir. Belgelerdeki ve SDK'daki varsayılan değerler farklılık gösterebilir, bu yüzden gerçek değerleri baz alın: CLI 1.16.0 konuşma durumunda, 8 ile 64 saniye arasında değişen aralıklarla 5 deneme gördük.

JoinGonka Gateway üzerinden tokenlar, girişte milyon başına $0.0069 ve çıkışta milyon başına $0.021 maliyetindedir — fiyat ağdaki tüm modeller için aynıdır ve bu sayfaya canlı kaynaktan çekilir.

Sağ sütundaki tahminler Eylül 2026 fiyatlarına göredir; ajan ekonomisinin nasıl işlediği, en ucuz AI-ajan API'si hakkındaki makalede ayrıntılı olarak açıklanmıştır.

Harcama tavanı. OpenHands harcama limitleri koymanızı önerir; ağ geçidinde bu, ödeme modelinin kendisine yerleşiktir: bakiye ön ödemelidir ve ajan hesaptakinden fazlasını harcayamaz. Kalan bakiye ve günlük harcama panelde görülebilir. CI ve arka plan otomasyonları için ayrı bir anahtar oluşturun, böylece harcamaları sizinkine karışmaz; günlük limitli alt anahtarlar Management Keys hakkındaki makalede anlatılmıştır.

Güven sınırı. npm üzerinden çalıştırılan Agent Canvas, kullanıcı haklarınızla çalışır ve tüm dosya sistemini görür. Başkasının kodu için Docker'daki sürümü kullanın: ajan sadece bağlı olan dizini görür. Bu, OpenHands'in kendi özelliğidir, model sağlayıcısına bağlı değildir.

Yazışmalar sizde kalır. OpenHands konuşma geçmişini kendi tarafında, ~/.openhands içinde tutar ve her adımda modele gönderir; ağ geçidi yazışmaları saklamaz — promp'larınız ve kodunuz yanıt verildikten sonra orada kalmaz.

Eğer görev resim içeriyorsa — arayüz ekran görüntüleri, şemalar — bunun için vision-model içeren ayrı bir profil oluşturun: Gonka ağ modelleri metin tabanlıdır. Kod, komutlar ve dosyalar için bu bir kısıtlama değildir.