OpenHands Kurulumu: Açık Kaynak Otonom Geliştirici

OpenHands, All-Hands AI tarafından geliştirilen ve eski adıyla OpenDevin olarak bilinen açık kaynak bir otonom yazılım geliştirme ajanıdır. Bir sohbet asistanının ötesinde, terminal komutları çalıştırabilen, dosya oluşturup düzenleyebilen ve web tarayıcısını kullanabilen bir yazılım mühendisi gibi davranır. Proje, kapalı devre otonom geliştiricilere en yaygın açık kaynak cevap olarak kabul edilir. Bu rehber, Docker tabanlı kurulumu, ajan yeteneklerini, CLI alternatifini ve ekosistemdeki konumunu ele alır.

OpenHands Nedir

OpenHands’in temel fikri, büyük dil modelini yalnızca metin üretici değil, gerçek geliştirme araçlarını kullanan bir ajan olarak işletmektir. Ajan, planlama döngüsü içinde çalışır: görevi analiz eder, adımlara böler, her adımı terminalde veya kod düzenleyicide uygular, sonucu gözlemler ve gerekirse stratejisini değiştirir. Terminal erişimi, dosya düzenleme, kod yürütme ve tarayıcı kullanımı, dört temel eylem alanıdır.

Tüm bu eylemler güvenlik için izole bir çalışma alanında yürütülür. Web arayüzü kurulumunda ajanın komutları, ana makineden ayrı bir çalışma zamanı konteynerinde çalışır; böylece deneme yanılmaya dayalı otonom akış, ana sisteme zarar verme riski olmadan serbestçe ilerler.

Ön Koşullar

Web arayüzü kurulumu için tek zorunlu bileşen güncel bir Docker kurulumudur: Linux’ta Docker Engine, Windows ve macOS’ta Docker Desktop. Windows’ta WSL 2 arka ucunun etkinleştirilmiş olması önerilir. İkinci gereksinim bir model bağlantısıdır; ajan, güçlü bir model olmadan verimli çalışamaz. OpenAI, Anthropic gibi bulut sağlayıcılarının API anahtarı kullanılabilir veya Ollama gibi yerel bir sunucu tanımlanabilir. Yerel model seçeneği tamamen ücretsizdir; ancak otonom ajan görevleri, küçük modeller için zorlayıcıdır ve en iyi sonuç güçlü modellerle alınır.

Donanım tarafında ana makine yalnızca Docker konteynerlerini ve tarayıcıyı çalıştırdığı için sıradan bir geliştirme bilgisayarı yeterlidir; ağır çıkarım model tarafında yapılır.

Kurulum Adımları: Docker ile Web Arayüzü

1. OpenHands imajı indirilir ve konteyner başlatılır; komut, çalışma zamanı konteynerini yönetebilmesi için Docker soketini geçirir ve arayüzü 3000 numaralı bağlantı noktasına bağlar.

docker run -it --pull=always -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:latest -v /var/run/docker.sock:/var/run/docker.sock -v ~/.openhands:/.openhands -p 3000:3000 --add-host host.docker.internal:host-gateway --name openhands-app docker.all-hands.dev/all-hands-ai/openhands:latest

2. Konteynerin çalıştığı doğrulanır.

docker ps

3. Tarayıcıdan http://localhost:3000 adresi açılır.
4. İlk kullanımda bir LLM sağlayıcısı ve model seçilir, API anahtarı girilir.
5. Ayarlar bölümünden çalışma alanı klasörü bağlanır; ajanın proje dosyalarına erişmesi bu bağlantıyla sağlanır.

Windows üzerinde Docker Desktop kullanılıyorsa docker.sock yolu, WSL 2 arka ucu üzerinden çözülür ve komut PowerShell’den aynı biçimde çalıştırılabilir. Ana makinedeki bir proje klasörünün ajanın çalışma alanına bağlanması, -v parametresiyle eklenen ek bir hacim tanımıyla yapılır.

Kurulum Adımları: CLI Alternatifi

Terminal odaklı çalışan geliştiriciler için OpenHands CLI, Docker gerektirmeyen bir yol sunar; komutlar doğrudan geliştirme ortamında yürütür. Python ortamında paket kurularak kullanılır:

pip install openhands-ai
openhands

CLI modu, web arayüzündeki bazı görsel özelliklerden yoksundur ancak aynı ajan çekirdeğini kullanır ve hızlı görevler için pratiktir. CLI’nin doğrudan ortamda çalışması, kum havuzu izolasyonu olmadığı anlamına gelir; bu yüzden önemli projelerde önce git durumunun temizlenmesi ve değişikliklerin izlenebilir tutulması önerilir.

Ajan Yetenekleri

OpenHands’in yetenek seti beş başlıkta toplanabilir. Kod yazma ve düzenleme: ajan, yeni özellikler geliştirir, hata düzeltir ve refaktör yapar. Terminal komutları: bağımlılık kurulumu, derleme, test çalıştırma gibi işlemleri kendi başına yürütür ve çıktıyı okuyup bir sonraki adımı belirler. Web araştırma: tarayıcı yeteneği sayesinde dokümantasyon arayıp hata mesajlarını araştırabilir. Depo keşfi: büyük kod tabanlarında ilgili dosyaları bulmak için arama yapar. Test döngüsü: yazdığı kodu test edip başarısız olanları kendisi düzeltmeye çalışır.

Görevler sohbet üzerinden verilir; ne kadar net tanımlanırsa o kadar tutarlı sonuç alınır. Karmaşık görevlerin alt görevlere bölünmesi ve her adımın onaylanarak ilerlemesi, en güvenilir çalışma düzenidir. Arayüz, ajanın her adımını canlı gösterir; terminal çıktıları ve dosya değişiklikleri izlenebilir, gerekirse durdurulabilir.

Görev Senaryoları ve Kullanım Örnekleri

OpenHands’in yetenek seti, somut görev türleriyle anlaşılır hâle gelir. Hata düzeltme senaryosunda hata raporu ve varsa yığın izlemesi ajanla paylaşılır; ajan ilgili dosyaları okur, hipotez kurar, düzeltmeyi yazar, testleri çalıştırır ve sonucu raporlar. Test yazma senaryosunda mevcut kod analiz edilip eksik kapsama alanları için birim testleri üretilir; üretilen testler çalıştırılarak geçerlilikleri doğrulanır. Refaktör senaryosunda ajan, belirli bir deseni depo genelinde arayıp değişiklikleri tutarlı biçimde uygular ve her adımda derleme ile test durumunu gözler.

Araştırma görevleri de ajanın iş alanındadır: bir kütüphanenin nasıl kullanılacağını örnek kodla gösterme, bir hatanın önceki sürümlerde nasıl çözüldüğünü izleme veya bir bağımlılığın davranışını küçük deneylerle sınama gibi işler, terminal ve tarayıcı yeteneklerinin birleştiği noktada yürütülür. Bu senaryoların ortak paydası, görevin ölçülebilir bir bitiş koşuluyla tanımlanmasıdır. “Depoyu iyileştir” gibi açık uçlu istemler yerine “bu üç testin geçmesini sağla ve mevcut testleri bozma” biçiminde tanımlanmış görevler, ajanın döngüsünü yönlendirebilir bir hedefe bağlar ve sonucun denetlenebilir olmasını sağlar.

Güvenlik Modeli ve İzolasyon

Otonom bir ajanın terminalde çalışması, güvenlik tasarımını aracın merkezine yerleştirir. Web arayüzü kurulumunda OpenHands iki katmanlı izolasyon kullanır: arayüzün kendisi bir konteynerde çalışır, ajanın eylemleri ise ayrı bir çalışma zamanı konteynerinde yürütülür. Kum havuzu içinde ajan kendi dosya sistemini, kendi ortamını görür; ana makineye sızmak için tasarlanmış bir yol yoktur. Docker soketinin arayüz konteynerine verilmesi, yeni çalışma zamanı konteynerlerinin oluşturulabilmesi içindir ve bu geçişin yalnızca konteyner yönetimi için kullanılması tasarımın parçasıdır.

İzolasyona rağmen iyi uygulamalar işin bir parçasıdır. Ajanın çalışma alanına yalnızca ilgili projenin bağlanması, hassas dizinlerin ve gizli dosyaların bağlanmaması, ortamda saklanan anahtarların ajanın görebileceği kapsamın dışında tutulması önerilir. API anahtarları arayüz ayarlarında saklanır; paylaşılan bir kurulumda her kullanıcı kendi anahtarını kullanmalı ve yönetici hesaplarının paylaşılmasından kaçınılmalıdır. Ajanın çalıştırdığı komutların canlı akışı izlenebilir; uzun görevlerde düzenli gözden geçirme, istenmeyen yön sapmalarını erken yakalar. Kurumsal ortamlarda ajan eylemlerinin günlük kaydının tutulması, denetlenebilirliği garantiye alan son katmandır.

Ekosistemdeki Konumu ve Sınırları

OpenHands, otonom yazılım geliştirme alanının referans açık kaynak projesi olarak kabul edilir. Kapalı ve bulut tabanlı Devin’e açık kaynak cevap olarak doğmuş olması, karşılaştırmaların merkezinde yer almasına yol açar; ancak konumu daha geniştir: proje, akademik değerlendirmelerde ajan çerçevelerinin standart ölçütlerinden biri hâline gelmiş ve topluluk katkılarıyla hızla genişleyen bir araştırma-üretim kesişimini temsil eder. Model sağlayıcısı bağımsızlığı, kendini barındırma imkânı ve kaynak kodun denetlenebilirliği, kapalı rakiplerinden yapısal olarak ayrıştığı üç noktadır.

Sınırları da bilmek gerekir. Otonom ajanlar, açık uçlu ve belirsiz görevlerde tutarsız olabilir; en iyi sonuçlar, net tanımlı ve doğrulanabilir görevlerde alınır. Ajanın yürüttüğü her adım model çağrısı demektir; karmaşık görevler ciddi API maliyeti üretebilir ve maliyet sınırı tanımlamak pratik bir gerekliliktir. Küçük yerel modellerle ajan döngüsünü yönetmek zordur; araç çağırma biçimlerini izleyen, uzun bağlam taşıyabilen güçlü modeller beklenir. Son olarak proje hızla değişen bir geliştirme hattına sahiptir; sürüm notları takip edilerek güncellemeler test ortamında denendikten sonra üretime alınması, olası davranış değişikliklerine karşı sağlam bir yaklaşımdır.

Yaygın Hatalar ve İpuçları

En sık görülen sorun, Docker soketinin geçirilmemesi sonucu çalışma zamanı konteynerinin başlamamasıdır; komutun tamamının kopyalandığı ve daemon’ın çalıştığı kontrol edilir. Bağlantı noktası çakışmasında 3000 numaralı bağlantı noktası başka bir servis tarafından kullanılıyorsa -p parametresiyle farklı bir port seçilir. Windows’ta konteyner başlatma hatalarının çoğu, WSL 2 güncellemesiyle çözülür. Model tarafında ise bağlam penceresi aşımı, uzun görevlerde görülür; görevin küçültülmesi veya daha geniş bağlamlı bir model seçilmesi çözüm olur.

Verimlilik ipuçları arasında, her büyük değişiklik sonrası ajanın ürettiği diff’in elle gözden geçirilmesi, çalışma alanına yalnızca ilgili projenin bağlanması ve düşük bütçeli API kullanımında görev başına maliyetin izlenmesi sayılabilir. Güvenlik açısından ajanın çalıştığı konteynerin izolasyonuna güvenilir ancak API anahtarının konteyner içi ayarlarda saklandığı unutulmamalı, paylaşılan ortamlarda hesap erişimleri düzenli denetlenmelidir. OpenHands, topluluk tarafından hızlı geliştiği için imajın düzenli aralıklarla güncellenmesi yeni yetenek ve düzeltmelerden yararlanmayı sağlar.