Claude Code kurulum rehberi — macOS, Windows komutları; kurulumdan sonra abonelik veya API anahtarıyla bağlanma

Claude Code kurulumu tek bir komut gerektirir: macOS, Linux ve WSL'de curl -fsSL https://claude.ai/install.sh | bash, Windows'ta PowerShell'de irm https://claude.ai/install.ps1 | iex çalıştırın (Komut İstemi CMD'de ise aşağıdaki install.cmd satırını kullanın). Kurulumdan sonra yeni bir terminal açın, claude --version ile doğrulayın ve başlamak için claude çalıştırın. İlk bağlantı için iki yol vardır: Pro, Max, Team, Enterprise veya Console hesabıyla oturum açmak (Claude.ai ücretsiz planı Claude Code'u içermez) ya da ANTHROPIC_BASE_URL ve ANTHROPIC_AUTH_TOKEN ortam değişkenlerini ayarlayıp kullanım başına ücretlendirilen API anahtarına geçmek; abonelik tamamen gerekli değildir.

Komutlar şu tarihte doğrulandı: 11 Eylül 2026, kaynak Anthropic'in resmi kurulum belgeleridir. Bu sayfa yalnızca kurulumu ve ilk bağlantıyı ele alır; kurulumdan sonraki günlük kullanım için Claude Code öğreticisine bakın.

Kurulumdan önce kontrol edin

macOS kurulumu

“Terminal”i açıp şu satırı yapıştırın:

# macOS、Linux、WSL
curl -fsSL https://claude.ai/install.sh | bash

Bu, resmî olarak önerilen bağımsız kurulum yöntemidir: bağımsız bir çalıştırılabilir dosya kurulur ve arka planda otomatik güncellenir. Çalıştırılabilir dosyanın giriş noktası ~/.local/bin/claude yolundadır; açık olan terminal yeni PATH'i okumaz, bu nedenle kurulumdan sonra yeni bir pencere açın. Linux ve WSL aynı komutu kullanır.

Windows kurulumu

Windows'ta, açtığınız terminal türüne göre değişen iki farklı komut vardır. İstemde PS C:\Users\你的名字> görünüyorsa PowerShell'dir; PS yok ve yalnızca C:\Users\你的名字> varsa Komut İstemi'dir (CMD). Yönetici olarak çalıştırmanız gerekmez.

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

:: Windows 命令提示字元（CMD）
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Yanlış yere yapıştırmak Windows'taki en yaygın başarısızlıktır. PowerShell'de CMD satırını çalıştırırsanız The token '&&' is not a valid statement separator görürsünüz; CMD'de PowerShell satırını çalıştırırsanız 'irm' is not recognized as an internal or external command görürsünüz. macOS'taki curl … | bash komutunu PowerShell'e yapıştırırsanız A parameter cannot be found that matches parameter name 'fsSL' görünür. Üç durumda da doğru satıra dönmeniz yeterlidir.

Git for Windows yüklemeniz ayrıca önerilir: Claude Code, komutları çalıştırmak için bununla gelen Git Bash'i kullanır; kurulu değilse PowerShell'e geçer. Kurulu olduğu hâlde Git Bash bulunamıyorsa ayar dosyasının env bölümüne CLAUDE_CODE_GIT_BASH_PATH ekleyerek bash.exe yolunu gösterin.

WSL'yi seçerseniz yukarıdaki macOS/Linux satırını WSL terminali içinde çalıştırın ve claude komutunu yine WSL içinde başlatın; PowerShell veya CMD'den başlatmayın.

Paket yöneticisiyle kurulum

Mevcut paket yöneticinizin yönetmesini de sağlayabilirsiniz; karşılığında varsayılan olarak hiçbir şey otomatik güncellenmez ve düzenli yükseltmeleri kendiniz yapmanız gerekir (örneğin brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode). Debian/Ubuntu, Fedora/RHEL ve Alpine için ayrıca resmi imzalı apt, dnf ve apk paket depoları vardır.

# Homebrew（macOS、Linux）— stable 通道
brew install --cask claude-code

# WinGet（Windows）
winget install Anthropic.ClaudeCode

# npm — 需要 Node.js 22 以上；絕對不要加 sudo
npm install -g @anthropic-ai/claude-code

npm yolu v2.1.198'den itibaren Node.js 22 veya üzerini gerektirir; Node.js sürümü daha eskiyse npm yalnızca EBADENGINE uyarısını yazdırır, ancak kurulum tamamlanır. Bağımsız kurulum programıyla aynı çalıştırılabilir dosyayı kurar ve çalışma sırasında Node.js'e bağlı değildir. Kesinlikle sudo npm install -g kullanmayın; izin sorunları bırakır ve güvenlik riski oluşturur.

Kurulumun başarılı olduğunu doğrulama

claude --version   # 正常會印出版本號，例如 2.1.211 (Claude Code)
claude doctor      # 唯讀的安裝與設定診斷，不會開啟工作階段

claude doctor hatırlamaya en çok değer komuttur: çalışma oturumu açmaz; yalnızca kurulum durumunu, yapılandırma dosyasındaki hataları ve önerilen düzeltmeleri listeler. “Kurulum bozuk” ile “yapılandırma bozuk” durumlarını ayırt etmenin en hızlı yoludur.

command not found: claude veya Windows'ta 'claude' is not recognized görünürse kurulum dizini PATH içinde değildir. macOS/Linux'ta önce yeni bir terminal açıp tekrar deneyin; yine olmazsa ~/.local/bin dizinini ~/.zshrc veya ~/.bashrc dosyasındaki PATH değişkenine ekleyin. Windows kurulum konumu şu dizindir: %USERPROFILE%\.local\bin; PowerShell ile denetleyip ekleyin:

# 1. 檢查安裝目錄是否已在 PATH 裡
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. 沒有任何輸出的話，把它加進「使用者」PATH，然後關掉終端機重開
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. 重開後再確認一次；若有兩份安裝，這行會列出兩個路徑
where.exe claude

İlk bağlantı: abonelikle giriş veya kullandıkça öde anahtarı

Yol A: Abonelik hesabıyla giriş yapma

Proje klasöründe claude çalıştırın ve tarayıcıdaki yönergeleri izleyerek Pro, Max, Team, Enterprise veya Console hesabınızla giriş yapın. Küçük ama önemli bir ayrıntı: Ortamda zaten ANTHROPIC_API_KEY varsa Claude Code, bu anahtarı kullanmak isteyip istemediğinizi bir kez sorar; o sırada reddederseniz bundan sonra anahtarı sessizce yok sayar ve tekrar sormaz; bu da değişken okunmamış gibi görünür. Yeniden etkinleştirmek için /config içindeki Use custom API key seçeneğine gidin.

Yol B: Abonelik kullanmadan kullandıkça öde anahtarıyla çalışma

Claude Code ANTHROPIC_BASE_URL desteğini yerleşik olarak sunar; bu nedenle Anthropic Messages API sağlayan herhangi bir uç noktaya yönlendirmek, eklenti, proxy veya değiştirilmiş yürütülebilir dosya gerektirmeyen resmî olarak desteklenen bir ayardır. Adımlar: hesap oluşturun, bakiye yükleyin (minimum $10), anahtar yönetimi sayfasında sk-kn- ile başlayan bir anahtar oluşturun (yalnızca bir kez gösterilir), ardından aşağıdaki değişkenleri ayarlayın. macOS/Linux:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # 只寫到網域，不要加 /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
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

Windows'ta önce bir PowerShell penceresinde denemek için:

# 只對這個 PowerShell 視窗有效，關掉就沒了
$env:ANTHROPIC_BASE_URL = "https://api.kunavo.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-kn-..."
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-5-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

Uzun süreli kullanım için kullanıcı yapılandırma dosyanızın ~/.claude/settings.json içindeki env bölümüne yazmanız önerilir (Windows'ta bu %USERPROFILE%\.claude\settings.json dosyasıdır). Buraya yazıldığında her terminal, düzenleyici uzantısı ve arka plan işlemi okuyabilir; dosyada başka ayarlar varsa env bölümünü mevcut ayarlarla birleştirmeniz yeterlidir:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Bu altı satırın her birinde, yanlış ayarlanırsa uzun süre takılı kalmanıza neden olabilecek bir nokta vardır:

• ANTHROPIC_BASE_URL yalnızca alan adını içermeli.Claude Code otomatik olarak /v1/messages ekler; /v1 eklerseniz sonuç /v1/v1/messages olur ve 404 döner.
• ANTHROPIC_AUTH_TOKEN kullanın, ANTHROPIC_API_KEY kullanmayın. Bunlar farklı HTTP başlıklarına gider: ilki Authorization: Bearer gönderir ve hemen etkinleşir; ikincisi x-api-key gönderir ve yukarıda açıklanan tek seferlik onaydan geçer.
• ANTHROPIC_MODEL eksiksiz ve doğru model adı olmalı.Kunavo yalnızca tam eşleşen adları tanır; tarih sonekli eski adları otomatik olarak eşleştirmez.
• ANTHROPIC_DEFAULT_OPUS_MODEL, opus takma adını yönetir. Claude Code'un varsayılan modeli ve opus takma adı en yeni Opus'a işaret eder. Kunavo bu modeli henüz kullanıma sunmadıysa 404 döndürür; bu nedenle hem bu satır hem de ANTHROPIC_MODEL sabitlenmelidir. Burada opus takma adı Opus 5.5'e (claude-opus-5-5) sabitlenir. Bunun için Claude Code v2.1.280 veya daha yeni bir sürüm gerekir; eski bir sürüm kullanıyorsanız önce claude update komutunu çalıştırın.
• ANTHROPIC_DEFAULT_SONNET_MODEL, sonnet takma adını yönetir. Anthropic API'de sonnet takma adı Sonnet 5.5'e işaret eder; Kunavo ise bu modeli sunmaz. Model sabitlenmezse /model sonnet, opusplan yürütme aşaması ve model: sonnet olarak ayarlanan alt ajanların tümü 404 döndürür. Bu nedenle burada da model Claude Sonnet 5 (claude-sonnet-5) olarak sabitlenir.
• ANTHROPIC_DEFAULT_HAIKU_MODEL haiku takma adının modelini belirler. Claude Code v2.1.293'ten itibaren haiku takma adı Haiku 5.5'e, daha eski sürümlerde ise tarih soneki taşıyan Haiku 4.5 adına karşılık gelir; Kunavo bu iki adı da tanımaz. Sabitlenmezse /model haiku ve model: haiku olarak ayarlanan alt ajanlar (Claude Code'un kendi başlattığı claude-code-guide dâhil) 404 hatası verir; bu nedenle burada claude-haiku-4-5 olarak sabitlenmiştir.
• ANTHROPIC_DEFAULT_HAIKU_MODEL, arka plan çağrılarından sorumludur.Claude Code'un oluşturduğu özetler ve başlıklar bu modeli kullanır: Claude Haiku 4.5 her 1M token için $0,70 / $3,50, ana Claude Sonnet 5 ise $1,40 / $7,00 (Anthropic'in resmî fiyatıyla aynı).

Anahtarı projedeki .claude/settings.json dosyasına yazmayın — bu dosya commit edilir ve projeyi klonlayan herkesle paylaşılır. VS Code uzantısını kullanıyorsanız değişkenleri VS Code kullanıcı ayarlarındaki claudeCode.environmentVariables içine yerleştirin; çünkü uzantı, başlatılmadan önce kimlik bilgilerini kontrol eder.

Hangi yolun kullanıldığını doğrulama

Claude Code'a girdikten sonra /status çalıştırın. Auth token satırını görüyorsanız anahtar etkin demektir; Login method görüp claude.ai hesabı listeleniyorsa değişken okunmamıştır. İkisi birlikte çalışmaz: Anahtar değişkeni bulunduğu sürece giriş yapılmış abonelik beklemeye alınır; değişkeni kaldırınca yeniden aboneliğe dönülür, yeniden kurulum gerekmez.

Ağ geçidi kullanırken üç şey farklı olur: Remote Control ve sesli giriş claude.ai kimliği gerektirdiğinden kullanılamaz; /fast kullanılabilirlik kontrolü doğrudan Anthropic'e sorar ve kullanılamıyor gösterebilir, ancak normal istekler etkilenmez; /context değerleri yerel tahmine dönüşür. Kod yazma, araçlar, alt aracılar, MCP, hooks ve istem önbelleğe alma normal şekilde çalışır. Ayrıntılar Claude Code entegrasyon belgeleri ve Claude Code API key kılavuzu'nda (ikisi de İngilizce).

Yaygın hatalar karşılaştırması

Kurulumdan sonra

Projeye ilk girişte tüm projeyi okutmak ve CLAUDE.md oluşturmak için önce /init çalıştırın. Göreve göre Opus, Sonnet ve Haiku arasında nasıl geçiş yapılacağı, bir oturumun gerçekte ne kadar harcadığı ve maliyetin /clear, /compact ile nasıl düşürüleceği Claude Code öğreticisinde açıklanır.

Hangi yolu seçeceğinizi dürüstçe söylemek gerekirse: Her gün uzun süre etkileşimde bulunan ve yüksek kullanım yapan kişiler için aboneliğin sabit aylık ücreti genellikle daha avantajlıdır; kullandıkça öde modeli, kullanımı büyük ölçüde değişen veya 5 saatlik kullanım penceresiyle sınırlanmak istemeyen kişiler için uygundur; çalışılmayan aylarda maliyet $0 olur. Kunavo üzerinden paylaşılan kapasite kullanılır; özel kota veya sözleşmeli SLA yoktur. Bu güvencelere ihtiyaç duyan ekipler doğrudan Anthropic'ten satın almalıdır. İki yolun aylık ücretleri ve başabaş noktası Claude Code ücretleri bölümündedir.

Sık sorulan sorular