Kurulum komutunu çalıştırdınız, terminal hata vermedi, oturum da açıldı. Sonra ilk gerçek isteği gönderiyorsunuz ve imleç orada öylece bekliyor. Tanıdık geldiyse yalnız değilsiniz: kurulumun bittiği yerle CLI'nin gerçekten işe yaradığı yer çoğu zaman aynı nokta değil. Bu yazı ikisini ayrı tutarak ilerliyor, çünkü çoğu kişinin saatini yiyen şey tam da bu ayrımı atlamak.
Aşağıdaki sıra, temiz bir makinede kendim ne yaparsam onun aynısı. macOS, Linux ya da Windows fark etmez; küçük komut farkları dışında izlediğiniz yol bir. Acele edip ortasından girmek yerine baştan sona okumanızı öneririm, çünkü her adım bir sonrakinin neden çalıştığını açıklıyor.
Kurulmak ile çalışmak aynı şey değil
Kurulumun başarısı yerel ortama bağlı: doğru Node sürümü, doğru komut, doğru izinler. İlk çalıştırmanın başarısı ise buna bir de sizinle API arasındaki hattı ekler. Bu ikisi birbirinden bağımsız bozulabilir, ve bozulduklarında çoğu zaman aynı belirtiyi verirler — komut yanıt vermez. İşte kafa karışıklığı buradan çıkıyor.
İnsanların en sık düştüğü tuzak şu: "kuruldu ama çalışmıyor" durumunu bir kurulum hatası sanıp tekrar tekrar kaldırıp kurmak. Hat yavaşsa bunu bin kez yapsanız da sonuç değişmez. Kurulumu yeniden yapmak yerel dosyaları tazeler, ama aradaki gecikmeye dokunmaz. Önce hangi tarafın bozuk olduğunu bilirseniz, geri kalan her şey çok daha hızlı çözülür. Bu yüzden aşağıdaki adımlar ikisini bilerek ayırıyor.
Adımlar
Node sürümünü doğrulayın
npm paketi Node.js 18 ve üzerini ister. Pratikte 22 LTS rahat bir seçim; iyi test edilmiş ve uzun süre desteklenecek. Tek komutla görürsünüz:
node --version
Sürüm eskiyse önce onu halledin. İlk gün yaşanan kurulum sorunlarının büyük kısmı egzotik bir şey değil, sadece sürüm uyumsuzluğu. Çıktı beklediğiniz numarayı vermiyorsa, sisteminizde birden çok Node kurulu olabilir ve terminal yanlış olanı buluyordur; bu durumda hangi yolu çağırdığını which node ile teyit etmek işe yarar. Bir de hesap tarafı: CLI ücretsiz web planına dahil değil, uygun bir plan gerekiyor. Bunu kurmadan önce kontrol edin ki oturum açma adımında boşuna uğraşmayasınız.
Kurulum yöntemini seçin
İki desteklenen yol var. Yerel yükleyici hiçbir bağımlılık istemez, kendini arka planda günceller; tek bir makinede en az uğraştıran seçenek bu. Sisteminizde Node olmasa bile çalışır, çünkü gereken çalışma zamanını kendisi taşır. npm yolu ise zaten Node araç zincirini yönetiyorsanız mantıklı:
npm install -g @anthropic-ai/claude-code
Hangisini seçerseniz seçin tek bir şeye dikkat: komutun başına sudo koymayın. İzin hatası alıyorsanız çözüm root yetkisi vermek değil, nvm gibi bir sürüm yöneticisiyle Node'u kullanıcı alanınıza almak. sudo ile kurulan global paketler dosyaları root'a ait dizinlere yazar; sonraki güncellemelerde yine yetki çatışması çıkar ve kısır döngüye girersiniz. Bir kez doğru kurmak, her seferinde sudo'yla zorlamaktan çok daha az yorucu.
Windows tarafında küçük bir not: birçok geliştirici komut satırı araçlarının tutarlı davranması için CLI'yi WSL içinde çalıştırıyor. Yerleşik PowerShell yerine WSL, ileride yol biçimi ve dosya izni farklarından gelen baş ağrılarını azaltıyor. WSL henüz kurulu değilse, dağıtımı bir kez kurmak sonradan çıkacak ufak tefek tutarsızlıkları baştan eler.
Oturum açın ve uçtan uca kanıtlayın
CLI'yi başlatın:
claude
İstenen oturum akışını tamamlayın. Sonra kurulumu lafla değil, çalıştırarak doğrulayın. İkili dosya yerinde mi:
claude --version
Oturum içinde yapılandırmayı tarayın:
/doctor
Bu komut yol, izin ve sürüm tarafında gözden kaçan sorunları erkenden yakalar; bir uyarı verirse oturumu derinleştirmeden önce onu kapatın. Şimdi en sıradan isteği gönderin — "buradaki dosyaları listele" gibi — ve dönüşü izleyin. Bilerek küçük bir istek seçiyoruz: amaç modeli zorlamak değil, sadece tam bir gidiş-dönüşün temiz tamamlanıp tamamlanmadığını görmek. Bu tur temizse kurulumunuz sağlam. Tamamlanmıyorsa, yani oturum açık ama ilk istek takılıyorsa, kurulum suçlu değil. Sıradaki bölüm tam da bunun için.
İlk bağlantıyı dayanıklı hale getirin
İşte çoğu anlatımın atladığı kısım. CLI kusursuz kurulmuş, oturum açılmış olabilir; ama API'ye giden yol yavaş ve paket kaybediyorsa deneyim bozuk gibi gelir. Sebebi şu: bir agent çalışması tek istek değil, arka arkaya onlarca gidiş-dönüş. Model dosya okur, düşünür, yeni istek atar, yanıt bekler. Bunlardan biri takılırsa tüm oturum donmuş gibi görünür, oysa aslında tek bir atlama gecikmiştir.
Önce ölçün. API ana makinesine bir ping atın, gecikmeye bakın. Sunuculardan coğrafi olarak uzaktaysanız ve rakam yüksekse, darboğaz makineniz değil aradaki hat. Yerel donanımı yükseltmek, kurulumu yeniden yapmak ya da sürümü değiştirmek bu tabloyu düzeltmez; düzeltecek olan tek şey paketin daha kısa ve kararlı bir yoldan gitmesi. NasaCode'un geliştiriciye yönelik düşük gecikmeli düğümleri tam bu iş için ayarlı: kurulumunuz ister sunucunun yanında olsun ister bir kıta ötede, ilk oturum benzer davranır. Hattı baştan dayanıklı kurmak, sonradan "neden donuyor" diye saatlerce uğraşmaktan çok daha ucuza gelir.
Yöntemleri yan yana koyunca
| Yöntem | Bağımlılık | Güncelleme | Kime uygun |
|---|---|---|---|
| Yerel yükleyici | Yok | Arka planda otomatik | Tek makine, en hızlı başlangıç |
| npm global | Node.js 18+ | Elle latest ile yeniden kurma | Hâlihazırda Node araç zinciri olanlar |
| Sürüm yöneticisi (nvm vb.) | nvm/fnm | Elle, yalıtılmış | Birden çok Node sürümü yönetenler |
Tek bir iş istasyonunda kararsız kalıyorsanız yerel yükleyici güvenli varsayılan. npm'i ancak Node sürümlerinizi zaten elle yönetiyorsanız tercih edin; aksi halde fazladan bir bakım yükü almış olursunuz.
Sık çıkan takıntılar
Ücretsiz hesapla olmaz mı?
Olmuyor. CLI uygun bir ücretli plan ya da konsol erişimi istiyor, ücretsiz web katmanına dahil değil. Hesabı kurulumdan önce doğrularsanız oturum adımında tıkanmazsınız.
npm neden izin hatası verdi?
Genelde iki sebepten: ya yükseltilmiş yetkiyle çalıştırdınız ya da sistemin kendi Node'u üzerine kurmaya çalıştınız. Bir sürüm yöneticisiyle yeniden kurun, global paket kullanıcı alanınıza gelsin; hata kaybolur ve sonraki güncellemeler de sorun çıkarmaz.
Kuruldu ama ilk komut donuyor
Bu neredeyse her zaman bağlantı tarafı. API ana makinesine gecikmeyi ölçün; yüksekse sorun rotanızda. Daha kısa bir hat çoğu durumda ilk agent çalışmasını sonuna kadar götürür.
WSL şart mı?
Şart değil, ama Windows'ta önerilen yol. Yerleşik kabukla da çalışır; yine de yol ve izin tutarlılığı açısından WSL daha az sürprizle gelir.
Özetle: sürümü doğrula, makinene uyan yöntemle kur, sıradan bir istekle oturumu sına, sonra API'ye giden hattın gerçekten güvenilir olduğundan emin ol. İlk üçünü herkes yapıyor; dördüncüyü atlayınca kusursuz bir kurulum bile ilk görevde bozuk gibi hissettiriyor.
Kurulumu bitirirken NasaCode istemcisini de yanına alırsanız, ilk oturumun ihtiyaç duyduğu düşük gecikmeli hattı baştan kurmuş olursunuz.
