AI OpenHands Nasıl Kullanılır: Kurulum, Komutlar ve Gerçek Dünya İş Akışları için Pratik Rehber
24/7 birlikte kod yazabileceğiniz yetenekli bir geliştirici hayal ettiyseniz, AI OpenHands bu beklentiye oldukça yakın. Repo’nuzu okuyabilen, kod yazan, terminal çalıştıran, dokümanları inceleyen ve hızlı öğrenen enerjik bir genç geliştirici gibi sürekli çalışan açık kaynak bir "AI mühendisi". Ancak gücü tam anlamıyla kullanmak için doğru kurulumu yapmalı ve nasıl yöneteceğinizi öğrenmelisiniz.
Bu rehber, AI OpenHands’ı adım adım nasıl kullanacağınızı gösterir—kurulumdan gelişmiş iş akışlarına kadar—böylece daha hızlı ve güvenle teslimatlar yapabilirsiniz.
- Kurulum seçenekleri ve hızlı başlangıç
- OpenHands’ı yerel veya bulut modellerle çalıştırma
- Komutlar, repolar ve görevler için en iyi uygulamalar
- Özellik geliştirme, hata ayıklama, test ve doküman için kanıtlanmış iş akışları
- Güvenlik önlemleri, gizlilik ve iş birliği
Not: OpenHands, All Hands ekibi ve topluluk tarafından aktif şekilde geliştiriliyor. Güncel talimatlar ve ipuçları için resmi dokümanlar yol göstericiniz olsun. Yerel ve VM kurulumlarını belgeleyen uygulayıcıların adım adım kurulum rehberlerini de takip edebilirsiniz. Yerel modellerle çalışmak için dokümanlarda özel yönlendirmeler mevcut.
AI OpenHands Nedir ve Neden Kullanmalı?
AI OpenHands’ı klavyeli bir AI takım arkadaşı gibi düşünün. Sadece sohbet asistanı değil, OpenHands şunları yapabilir:
- Proje dosyalarını açıp okuyabilir
- Terminal kullanarak komutlar, testler ve linter’lar çalıştırabilir
- Dosya ve dizinler arasında kod düzenleyebilir
- Yapılandırmaya bağlı olarak web’de gezinebilir
- Adım adım planlar önerebilir ve uygulayabilir
Bu, özellik uygulama, hata düzeltme, test yazma, doküman oluşturma, kodu refaktör etme ve güncelleme gibi görevler için ideal kılar. Komut ve kopyala/yapıştırla uğraşmak yerine OpenHands’a bir hedef verirsiniz, o iterasyonlar yaparken siz onu denetlersiniz.
Hızlı Başlangıç: OpenHands’ı En Hızlı Şekilde Kullanmak
Başlamak için birkaç seçenek var. Tercihiniz bulut LLM kullanmak mı yoksa her şeyi yerelde mi çalıştırmak istediğinize göre değişir.
Seçenek A: Bulut LLM Kullanmak (en kolay)
- Resmi "Start Building" ve "Getting Started" dokümanlarını takip ederek uygulamayı kurup çalıştırın. Genellikle:
- Gereksinimleri kurun (Docker, Node, Python, Git kullandığınız yola bağlı olarak)
- Desteklenen bulut modeli için bir API anahtarı sağlayın (ör. OpenAI, Anthropic veya projenin desteklediği o andaki diğer modeller)
- OpenHands arayüzünü başlatıp repoyu bağlayın
Bu yol, minimum donanım yüküyle hızlıca verimli olmanızı sağlar.
Seçenek B: OpenHands’ı Yerel LLM ile Çalıştırmak
- Kod ve komutları bulutta tutmak istemiyorsanız veya API maliyetlerinden kaçınmak istiyorsanız, resmi dokümanlardaki Yerel LLM kılavuzunu kullanın.
- Uyumlu yerel modeli kurmak (Ollama veya o anda desteklenen diğer altyapılarla)
- Model uç noktaları ve bağlam limitlerini yapılandırmak
- Makinenizin yeterli VRAM/CPU ve disk alanına sahip olduğundan emin olmak
Seçenek C: VM Üzerinde Dağıtım
- Özel bir ortam gerekiyorsa, uygulayıcılar OpenHands’ı bir VM üzerinde hızlıca kurup çalıştırmanın adımlarını belgeledi. Bu, kararlı ve paylaşılan bir AI mühendis örneği isteyen ekipler için faydalı.
İlk Çalıştırma: Proje Kurulumu ve Görev Belirleme
OpenHands, kodunuzu görebildiğinde en iyi performansı gösterir. Şunlarla başlayın:
- Çalışmasını istediğiniz repoyu açmak.
- Projeyi çalıştırmak veya indekslemek, böylece yapıyı haritalayabilir.
- Net bir hedef ve kısıtlar vermek.
İyi bir görev çerçevesi örneği:
- "
auth servisine token tabanlı e-posta linkleri kullanarak kullanıcı şifre sıfırlama özelliği ekle. Mevcut mailer modülünü kullan. Token oluşturma ve süresi için birim testleri ekle. Kullanıcı veri şemasını değiştirme."
Neden işe yarıyor:
- Bileşeni, kapsamı, bağımlılıkları ve sınırları açıkça belirtir. Ne kadar net olursanız, OpenHands o kadar iyi planlar ve uygular.
OpenHands için Etkili Komutlar Yazma
Komutları özlü biletler olarak düşünün. En iyileri:
- Sonucu tanımlar: "X’i Y kısıtlarıyla uygula"
- Dosya, modül veya testlere referans verir: "
auth/routes.py ve tests/test_auth.py dosyalarına bak"
- Kısıtları belirtir: "Veritabanı şeması değişikliği yok; mevcut arabirimleri koru"
- Kabul kriterlerini içerir: "Testler geçmeli:
pytest -k password_reset"
Tekrar kullanabileceğiniz şablon:
Hedef: <İstenilen yapı veya düzeltme>
Bağlam: <İlgili dosyalar, bilinen kısıtlar, dış servisler>
Kabul: <Başarının nasıl göründüğü: testler, uç noktalar, metrikler>
Sınırlar: <Değiştirmemesi gereken veya kaçınılması gereken yaklaşımlar>
Araçlar: <Çalıştırabileceği komutlar, scriptler veya veri kaynakları>
Temel İş Akışı: Planla → Uygula → Doğrula → İyileştir
OpenHands genellikle çok adımlı bir plan önerir. İşte nasıl yönlendireceğiniz:
- Planını erken onaylayın veya düzenleyin. Önce testleri çalıştırmasını isteyerek başarısızlıkların temelini oluşturun.
- Başarıyı tanımlamak için test oluşturmasını veya güncellemesini, sonra kodu uygulamasını isteyin.
- Test paketini ve linter’ları sık sık çalıştırmasını sağlayın.
- Tıkanırsa, dosya adları, yığın izleri veya loglar gibi daha fazla bağlam ekleyin.
İpucu: Monolitik değişiklikler yerine küçük PR boyutlarındaki güncellemeleri teşvik edin. Bu, inceleme ve geri alma işlemlerini kolaylaştırır.
Kopyalayabileceğiniz Örnek İş Akışları
1) Özellik Uygulama
- Komut: "
orders sayfasına CSV ihracatı ekle. Sunucu tarafında sayfalama kullan, sonuçları text/csv ile akıt. OrdersTable.jsx içinde Export butonu ve routes/orders.ts içinde uç nokta ekle. Sayfalama ve başlıklar için testler ekle."
- Repoyu tarar; plan taslağı oluşturur
- Uç nokta ve istemci butonu ekler
- Testleri yazar ve çalıştırır
- Başarısızlıklarda iterasyon yapar
- Siz denetler, değişiklikleri onaylar ve yeşil olduğunda birleştirirsiniz.
2) Başarısız Derlemenin Hata Ayıklaması
- Komut: "CI, Node 20’de başarısız oluyor.
build.mjs içindeki ESM/CJS ithalat hatalarını düzelt. Mevcut rollup eklentilerini tut; yapılandırma ve kodu CI geçecek şekilde güncelle."
- Logları veya CI çıktılarına link sağlayın.
- OpenHands’tan yerelde yeniden oluşturmasını (
npm run build) ve minimum farklar önerisini isteyin.
3) Test Kapsamı ve Sağlamlaştırma
- Komut: "
payments/service.py dosyasının kapsamını %62’den %85+’e çıkar. retry_charge, refund, webhook_signature için birim testler ekle. Test bir hata göstermezse iş mantığını değiştirme."
- OpenHands testleri oluşturur, çalıştırır ve iyileştirir.
4) Doküman ve Geliştirici Deneyimi
- Komut: "Bu repo için
CONTRIBUTING.md ve DEVELOPMENT.md dosyaları oluştur. Ortam kurulumunu, scriptleri, test komutlarını ve PR yönergelerini ekle."
- Komutları gerçekten çalıştırarak doğrulat.
Güvenlik Önlemleri: OpenHands’ı Yardımcı ve Güvenli Tutmak
- Dizin kapsamı: Yanlışlıkla başka yerleri değiştirmemesi için belirli bir repo veya dizini gösterin.
- Dosya koruması: Yapılandırma dosyaları veya kritik altyapıları mümkün olduğunda salt okunur yapın.
- Komut denetimi: Yıkıcı komutlar (örneğin
rm -rf, veritabanı sıfırlama) için onay isteyin.
- Gizli bilgiler hijyeni: API anahtarlarını komutlara asla yapıştırmayın. Çevresel değişkenler ve maskelenmiş loglar kullanın.
- Ağ erişimi: Eğer tarama açık ise, sandbox içinde çalıştırın ve çıkan çağrıları kaydedin.
Yerel ve Bulut Modeller: Sizin İçin Hangisi Doğru
- Avantajlar: Güçlü muhakeme/kodlama, minimal kurulum, hızlı iterasyon
- Dezavantajlar: Sürekli maliyet, veri yönetimi konuları
- Avantajlar: Gizlilik, kontrol, maliyet öngörülebilirliği
- Dezavantajlar: Donanım gereksinimleri, model kalitesi değişken, daha fazla ince ayar gerektirir
Model altyapılarını ve bellek limitlerini yapılandırmak için resmi Yerel LLM talimatlarına bakın.
Takım Oyunu: OpenHands’ı İş Birlikçi Bir Akışta Kullanmak
- Branch-öncelikli iş akışı: OpenHands’un özellik dalı oluşturup değişiklikleri PR incelemesi için itmesini sağlayın.
- Commit hijyeni: Atomik commit’ler oluşturmasını, net mesajlar yazmasını ve issue numaralarına referans vermesini isteyin.
- PR şablonları: Değişikliklerin ve sebeplerinin anlaşılması için şablonlar oluşturun ve zorunlu kılın.
- Kod sahipleri: OpenHands tarafından oluşturulan PR’ları doğru değerlendiricilere yönlendirmek için CODEOWNERS ile entegre edin.
Yaygın Sorunların Çözümü
- Tıkandığında veya döngüye girdiğinde: Kapsamı daraltın. Bir sonraki adımını açıklamasını isteyin. Başarısız bir testi verin.
- Karmaşık farklar: Küçük, aşamalı planlar talep edin—önce testler, sonra minimum kod değişiklikleri.
- Yanlış dosya düzenlemeleri: Kesin yolları belirtin ve sınırları hatırlatın.
- Yerelde geçiyor, CI’da başarısız oluyor: CI ortam detayları ve logları paylaşın; konteyner ile çoğaltmasını isteyin.
Performans İpuçları ve Güçlü Hamleler
- Ön ısınma bağlamı: Önce temel dosyaları (
README, package.json, ana servis dosyaları) okumasını isteyin.
- Script verin: Hızlı doğrulama için
make test veya npm run verify sağlayın.
- Alan bilgisini öğretin: Kısa bir mimari özet sunun; mantık hatalarını azaltır.
- Stil uygulayın: Doğru formatlama için
.eslintrc, .prettierrc, black/ruff konfigürasyonlarını gösterin.
- Kontrol noktaları kullanın: Her dönüm noktasından sonra özet ve sonraki adımları isteyerek yolda kalmasını sağlayın.
Gerçek Dünya Senaryosu: Bir Saatte Hata Raporundan Yama
- Durum: Üretim ortamında,
orders API’sinde biçimsiz JSON’un 500 hatası oluşturması.
- Komutunuz: "
orders POST’ta biçimsiz JSON ile 500 hatasını yeniden oluştur. Şema doğrulaması ekle ve hata detaylarıyla 400 dön. Bozuk yükleri kapsayan testleri güncelle."
- API’yı yerelde çalıştırır, hatayı yeniden üretir
- Doğrulama katmanı ve hata yöneticisi ekler
- Testleri günceller ve CI’ın geçmesini sağlar
- Kompakt bir PR ve değişiklik günlüğü hazırlar
Kazanç: Siz etki analizi ve yayılım odaklandınız, OpenHands iskeleti halletti.
OpenHands’ı Güçlendiren Entegrasyonlar
- Test çalıştırıcıları: pytest, Jest, Vitest, JUnit
- Derleyici araçları: Vite, Webpack, Rollup, Babel
- Paket yöneticileri: npm, pnpm, yarn, pip/poetry
- Linter/formatlayıcılar: ESLint, Prettier, black, ruff
- Konteynerler: Docker Compose ile yerel ve CI ortamı uyumu
Bu araçları standartlaştırarak, OpenHands yığınızı daha doğru yorumlar ve geliştirici döngüsünü daha çok otomatikleştirir.
Bu Arada: OpenHands ile Birlikte Sider.AI Kullanımı
İlgililik skoru: 8/10. OpenHands’ı AI mühendisi olarak kullanıyorsanız, teknik spesifikasyonlar, PR açıklamaları ve dokümantasyon için araştırma ve taslak destekçisi olarak yanında kullanmak faydalı olur. Sider.AI, teknik dökümanları hızlıca taslak haline getirebilir, RFC’leri özetleyebilir veya OpenHands çalışma günlüklerini temiz değişiklik listelerine ve sürüm notlarına dönüştürebilir. Bu kombinasyon bağlam geçişini azaltır: OpenHands kod için uğraşırken, Sider.AI sonuçları kullanıcıya yönelik temiz dokümanlara dönüştürür.
Güvenlik, Gizlilik ve Uyumluluk Kontrol Listesi
- Gizli bilgileri çevresel değişkenlerde tutun; anahtarları komutlara asla gömmeyin
- Her AI tarafından oluşturulan değişikliği junior bir geliştiricinin PR’ı gibi inceleyin
- Denetlenebilirlik için komutları ve eylemleri kaydedin
- Araç zinciri sürümlerini sabitleyin; kilit dosyalarında istemeden yükseltmeleri önleyin
- Bulut LLM kullanıyorsanız, veri saklama politikalarınızla uyumlu olun
OpenHands Kullanılmaması Gereken Durumlar
- Güçlü test ya da spesifikasyon altyapısı olmadan yenilikçi algoritma tasarımı
- Sağlam inceleme süreci olmayan, çok regülasyona tabi kod tabanları
- Elle kodlama daha hızlı olan tek seferlik, atıp geçici scriptler
OpenHands ile İlk 60 Dakikanız: Mini Oyun Kitabı
- Dakika 0–10: Resmi Hızlı Başlangıç rehberi ile kurulumu yapıp başlatın
- Dakika 10–20: Repoyu bağlayın; projenin yapısını haritalamasını isteyin
- Dakika 20–35: Küçük ve test edilebilir bir hedef tanımlayın; planını onaylayın
- Dakika 35–50: Uygulamasına ve testleri çalıştırmasına izin verin; gerektiğinde yönlendirin
- Dakika 50–60: Farkları inceleyin, iyileştirin ve bir özellik dalına birleştirin
Önemli Bağlantılar ve Sonraki Adımlar
- OpenHands için resmi "Start Building" ve kullanım dokümanları: ipuçları, hızlı başlangıç ve en iyi uygulamalar.
- Yerel LLM kurulum kılavuzu: OpenHands’ı tamamen kendi makinenizde yapılandırıp çalıştırabilirsiniz.
- Topluluk destekli VM kurulum rehberi: gerçek dünya kurulum adımları ve hızlı demo projesi.
Öğrenilenler
- Görevleri net kabul kriterleri ile bilet gibi çerçeveleyin.
- Tekrarlamaları küçük tutun; erken ve sık test edin.
- Güvenlik önlemleri uygulayın ve değişiklikleri inceleyin—onu junior bir takım arkadaşı gibi görün.
- Kolaylık için bulut, gizlilik için yerel modeller seçin.
- Teknik spesifikasyonlar ve sürüm notları için dokümantasyon araçları (örneğin Sider.AI) ile eşleştirerek hız kazanın.
Sıkça Sorulan Sorular
S1: AI OpenHands’ı hızlıca nasıl kurar ve kullanmaya başlarım? Resmi hızlı başlangıcı kullanarak gerekli ön koşulları kurun, desteklenen bir LLM’i (bulut veya yerel) takın ve kullanıcı arayüzünü açıp repoyu bağlayın. "Start Building" dokümanları adım adım kurulum ve ipuçları sunar.
S2: OpenHands’ı bulut modeli yerine yerel LLM ile çalıştırabilir miyim? Evet. Yerel LLM’ler kılavuzunu izleyerek yerel model altyapısını yapılandırıp bağlam ayarlarını değiştirin. Gizlilik hassasiyeti olan projeler veya API maliyetlerinden kaçınmak için idealdir.
S3: Kodlama görevleri için OpenHands’a en iyi nasıl komut yazılır? Komutları kısa ve öz bilet gibi yazın: hedefi tanımlayın, spesifik dosyalara referans verin, sınırları koyun ve kabul kriterlerini ekleyin. İlerlemeyi doğrulamak için testler oluşturmasını ya da çalıştırmasını isteyin.
S4: AI OpenHands üretim kodunda güvenli mi? Onu junior bir geliştirici gibi değerlendirin: dal koruması, kod incelemesi ve CI ile değişiklikleri doğrulayın. Komutlarda güvenlik önlemleri ekleyin ve gizli bilgileri komutlara katmayın.
S5: OpenHands geleneksel bir kod asistanıyla nasıl karşılaştırılır? Sadece sohbet aracı olmaktan öte, OpenHands komutlar çalıştırabilir, dosyaları düzenleyebilir ve repo içinde özerk şekilde iterasyon yapabilir. Özellik geliştirme, hata ayıklama ve testler gibi uçtan uca görevler için tasarlanmıştır.
