Claude Code kurulumu — tek komut ve sonrasında karşılaşılan iki engel

Claude Code'un kurulumu tek satırlık bir komuttur; asıl sorunlar sonrasında başlar. Kurulumu anlatan yazıların çoğu “Kurulum tamamlandı” noktasında biter; ancak Güney Kore'de çalıştırmaya ulaşmak için iki engel daha vardır — global kurulum izinleri ve giriş·ödeme. Bu yazı üç aşamayı sırayla ve her aşamada takıldığınızda uygulanacak çözümlerle birlikte ele alır.

1. aşama — Kurulum (tek satır komut)

Tek ön koşul Node.js 18 veya üzeridir. macOS, Windows (WSL) ve Linux'ta aynı komut kullanılır.

# Node.js 18 이상이 필요합니다. 먼저 확인하세요.
node --version

# 설치
npm install -g @anthropic-ai/claude-code

# 확인 — 버전이 출력되면 설치 자체는 끝난 것입니다
claude --version

claude --version bu sürümü görüntülüyorsa kurulum tamamlanmıştır. Burada duruyorsanız aşağıdaki iki bölümden biri sizin durumunuza karşılık gelir.

2. aşama — İzin ve yol hataları

Kurulum aşamasında en sık görülen iki hata şunlardır.

EACCES üzerine sudo eklemek önerilmez. O an kurulum yapılır; ancak sonraki her güncellemede aynı sorun tekrarlanır ve global dizinin sahibi root olduğundan işler daha da karmaşıklaşır. Yolu ana dizine taşımak daha temizdir.

# npm 전역 설치에서 EACCES가 나면 sudo를 붙이지 말고
# 전역 경로를 홈 디렉터리로 옮기는 편이 안전합니다.
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

# 셸 설정에 추가한 뒤 새 터미널을 엽니다
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

Windows kullanıyorsanız WSL içine kurun. Proje dosyalarını da WSL dosya sistemi içinde tutmalısınız; böylece dosya izleme ve yol işleme düzgün çalışır.

3. aşama — Giriş ve ödeme (Güney Kore'de asıl sorun çıkan yer)

Kurulum tamamlandıktan sonra claude komutunu çalıştırdığınızda giriş yapmanız istenir. Güney Kore'de en çok burada takılınır ve neden kurulumla ilgili değildir.

• Yurt dışı ödemeleri engellenmiş kart — abonelik ödemesi başarısız olur. Kart şirketinin uygulamasında veya web sitesinde yurt dışı ödemelerini etkinleştirmek çoğu sorunu çözer.
• KakaoPay·Toss — claude.ai web ödemelerinde desteklenmez (yalnızca mobil uygulama aboneliklerinin mağaza ödeme yöntemlerinde bulunur). Yerel hızlı ödeme yöntemlerinin çalışacağını varsayarak denerseniz bu aşamada takılırsınız.
• Yurt dışı ödemelerine açık bir kartınız yoksa web aboneliği yolunu kullanamazsınız. Aşağıdaki anahtar kimlik doğrulaması Kunavo bakiyesi yükleyerek kullanılır; ödeme sayfası Kore wonu olarak gösterildiğinde KakaoPay, Naver Pay, PAYCO, Samsung Pay ve yerel kartlar (yurt dışı ödemeleri açık olmayan kartlar) ödeme yöntemi olarak sunulduğundan yurt dışı ödemelerine açık kart olmadan da yükleme yapabilirsiniz (Toss desteklenmez).

Hangi ödeme yöntemlerinin çalıştığını ve hangilerinin çalışmadığını Claude ödeme yöntemleri bölümünde açıkladık.

Abonelik ödemesi engellendiğinde — kurulu sürümü anahtarla çalıştırma

Claude Code, abonelikle girişin yanı sıra API anahtarıyla kimlik doğrulamayı da destekler. Aşağıdaki iki ortam değişkeni ayarlanmışsa giriş ekranını atlayarak çalışır; değişkenleri silerseniz normal işleyişe dönersiniz. Yeniden kurulum gerekmez.

# 구독 결제가 막혔을 때 설치한 클로드 코드를 그대로 쓰는 방법.
# 이 두 줄이 있으면 로그인 대신 키로 인증하고, 지우면 원래대로 돌아갑니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# 클로드 코드의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 따라가므로,
# Kunavo가 제공하는 모델로 고정해 404를 막습니다. sonnet 별칭은 Kunavo가 제공하지
# 않는 Sonnet 5.5를 요청하므로, 고정하지 않으면 /model sonnet, opusplan의 실행 단계,
# sonnet 서브에이전트가 404로 실패합니다. opus는 Opus 5.5로 고정하며,
# 클로드 코드 v2.1.280 이상이 필요합니다(이전 버전은 claude update).
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

claude

Bu yöntemde aylık sabit ücret yerine yalnızca gerçekten kullandığınız tokenlar için ücret ödersiniz; çalışmadığınız aylarda ücret oluşmaz. Anahtar alma adımları Claude API anahtarı alma bölümünde, abonelik ile kullandıkça öde seçeneklerinden hangisinin daha ucuz olduğu ise Claude Code fiyatları bölümündedir.

Kurulum sonrası ilk çalıştırma — 3 dakikalık kontrol

Çalıştığında proje dizininde claude komutunu açın ve /init komutunu bir kez çalıştırın. Depoyu okuyarak CLAUDE.md oluşturur ve bundan sonra tüm oturumlarda bunu otomatik olarak okur. Buradan sonraki kullanım — kural yazma, izin ayarlama ve özel komutlar — Claude Code kullanım kılavuzu bölümünde devam eder.

Çalıştırma sonrasında görülen 401·429·529 hatalarının nedenleri kurulum aşamasındakilerden tamamen farklıdır. Bunları ayırt etme yöntemi Claude Code hata özeti bölümünde ayrıca açıklanmıştır.

Sık sorulan sorular