Claude Code settings.json ve Ortam Değişkenleri: Base URL, Auth Token ve Model

Claude Code yapılandırmasını JSON ayar dosyalarından ve ortam değişkenlerinden alır. Anthropic API’si yerine bir ağ geçidi üzerinden çalıştırmak için ANTHROPIC_BASE_URL ve bir token olmak üzere iki değişkene, genellikle de bir modele ihtiyacınız vardır. Değişkenler basittir. Kafa karıştıran, bunları nereye koyacağınız; çünkü aynı değişken kabuk profilinizde, çeşitli settings.json dosyalarında ve VS Code ayarlarında bulunabilir.

Bu kılavuz, önce çalışan bir kurulum sunuyor, ardından dosyaların nerede bulunduğunu, hangi değerin öncelikli olduğunu ve karşılaşabileceğiniz hataları açıklıyor. Kılavuz, Anthropic belgeleriyle karşılaştırılarak doğrulandı ve 20 Ekim 2026’da Claude Code 2.1.304 üzerinde AIHubMix ile test edildi. Örneklerde ağ geçidi olarak AIHubMix kullanılıyor; Anthropic uyumlu tüm uç noktalar aynı şekilde yapılandırılır.

Kısaca

• Kişisel ayar dosyanız ~/.claude/settings.json, Windows’ta ise %USERPROFILE%\.claude\settings.json konumundadır.
• Bir ağ geçidi için ANTHROPIC_BASE_URL değerini (/v1 olmadan) ve ANTHROPIC_AUTH_TOKEN değerini bu dosyanın env bloğuna ekleyin.
• Bir ayar dosyasındaki env bloğunda yer alan değer, kabuğunuzda dışa aktarılan aynı değişkenin üzerine yazılır.
• Bir token ayarlandığında istekler Claude aboneliğinizi kullanmayı bırakır ve ücretlendirme ağ geçidi tarafından yapılır.
• VS Code eklentisi için aynı değişkenleri kendi claudeCode.environmentVariables ayarına eklemeniz gerekir.

Çalışan bir AIHubMix kurulumu

1. AIHubMix konsolunda bir anahtar oluşturun.
2. ~/.claude/settings.json dosyasına bunu ekleyin. Dosya yoksa oluşturun.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-aihubmix-key"
  },
  "model": "claude-sonnet-5-5"
}

3. Hızlıca test edin:

claude -p "1+1, output only the answer"

4. Bir projede claude komutunu başlatın. Logonun altındaki başlıkta Sonnet 5.5 · API Usage Billing gibi bir ifade, /status çıktısındaki Anthropic base URL satırında ise ağ geçidiniz görünmelidir.

İki ayrıntı önemli. Base URL kök adrestir: Claude Code /v1/messages yolunu kendisi ekler; dolayısıyla /v1 ile biten bir URL tüm isteklerin bozulmasına neden olur. Ayrıca AIHubMix, claude-sonnet-5-5 gibi Anthropic’in kendi model kimliklerini kullanır; bu nedenle sonnet, opus ve haiku kısayolları ek yapılandırma gerektirmeden çalışır.

$schema satırı isteğe bağlıdır. VS Code, Cursor ve diğer düzenleyicilerin siz yazarken dosyadaki hataları işaretlemesini sağlar.

Aynı iki değişkeni kabuğunuzda da dışa aktarabilirsiniz; ancak bunları saklamak için en uygun yer ayar dosyasıdır: tüm terminaller, IDE eklentileri ve arka plan aracıları bu dosyayı okur.

Ayar dosyalarının konumları

Token’ı projenin .claude/settings.json dosyasına asla koymayın; bu dosya git’e eklenir. Kullanıcı dosyanızı veya .claude/settings.local.json dosyasını kullanın.

Ayar dosyaları geçerli JSON biçiminde olmalıdır. // yorumu veya sondaki virgül, Claude Code’un token dahil dosyanın tamamını atlamasına neden olur; bu durumda ağ geçidiniz yerine oturum açma ekranını görürsünüz.

Bunları, ana klasörünüzde bulunan tek bir dosya olan ~/.claude.json ile karıştırmayın. Bu dosya oturum açma bilgileri ve MCP sunucuları gibi Claude Code’un kendi durum bilgilerini saklar; genellikle düzenlemeniz gerekmez.

Hangi değer öncelikli?

Birden fazla dosyada aynı ayar yapıldığında Anthropic’in ayar önceliği sıralaması geçerlidir; en yüksek öncelikten başlayarak:

1. Kuruluşunuzun yönetilen ayarları
2. Yalnızca o oturum için komut satırındaki --settings
3. .claude/settings.local.json
4. .claude/settings.json
5. ~/.claude/settings.json

Ortam değişkenleri için bir kural daha vardır: ayar dosyasının env bloğundaki bir değişken, kabuğunuzdaki aynı değişkenin üzerine yazar. Bu nedenle bir ayar dosyası da değer atıyorsa export ANTHROPIC_BASE_URL=... içindeki ~/.zshrc hiçbir işe yaramaz. Sağlayıcı değiştirme araçları genellikle ~/.claude/settings.json dosyasına yazar; bu yüzden kabuğunuzdaki değere üstün gelirler.

Claude Code içinde /status komutunun Setting sources satırı, yüklenen dosyaları listeler.

ANTHROPIC_AUTH_TOKEN mı, ANTHROPIC_API_KEY mi?

Ağ geçidinizin okuduğu değişkeni kullanın. AIHubMix ikisini de kabul eder; Claude Code kılavuzunda da kullanılan ANTHROPIC_AUTH_TOKEN daha basit bir seçenektir. İkisini birden ayarlamayın. Aksi takdirde Claude Code her iki üstbilgiyi de gönderir ve AIHubMix önce x-api-key değerini kontrol eder: testimizde settings.json dosyasındaki doğru token’a rağmen kabukta dışa aktarılmış eski bir ANTHROPIC_API_KEY nedeniyle 401 hatası aldık. env bloğu yalnızca tanımladığı değişkenlerin üzerine yazar; bu nedenle geçiş yaparken eski anahtarı kabuk profilinizden kaldırın.

Peki Claude aboneliğiniz ne olacak? Anthropic’in ağ geçidi kılavuzuna göre bir token veya API anahtarı değişkeni ayarlandığında isteklerde claude.ai oturum açma bilgileriniz yerine bu değişken kullanılır ve ağ geçidi token başına ücret alır. Oturum açma bilgileriniz kayıtlı kalır; değişkeni kaldırdığınızda yeniden devreye girer. Yalnızca ANTHROPIC_BASE_URL ayarlanır, token ayarlanmazsa aboneliğinizi kullanmaya devam edersiniz.

Modeli seçme

Anthropic’in model yapılandırması sayfasında en yüksek öncelikten başlayarak şu sıra veriliyor:

1. Oturum sırasında /model <name>
2. Başlangıçta claude --model <name>
3. ANTHROPIC_MODEL değişkeni
4. Ayar dosyasındaki model anahtarı

/model seçiminizi yeni varsayılan olarak kaydeder. Ancak ANTHROPIC_MODEL ayarlanmışsa her yeni oturum yine bu modelle başlar. Modeller arasında sık geçiş yapıyorsanız model anahtarını ayarlayın ve ANTHROPIC_MODEL değişkenini kullanmayın. Hiçbir yerde model ayarlanmamışsa Claude Code, Opus 5.5 kullanır.

ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL ve ANTHROPIC_DEFAULT_HAIKU_MODEL değişkenleri, her kısayolun hangi modeli kullanacağını değiştirir. Bunları yalnızca bir kısayolu başka bir modele yönlendirmek, örneğin sonnet kısayolunu eski bir sürümde tutmak istiyorsanız kullanmanız gerekir.

AIHubMix aynı adres üzerinden diğer sağlayıcıların modellerini de sunar; ancak Anthropic, Claude Code’u Claude dışındaki modellerde desteklemez, dolayısıyla bazı özellikler bu modellerle çalışmayabilir.

Değişiklikler ne zaman uygulanır?

Claude Code ayar dosyalarını izler ve env bloğu da dahil olmak üzere kaydedilen çoğu değişiklik çalışan oturuma uygulanır. model anahtarı, kaldırılan değişkenler ve kabuk dışa aktarımları için yeniden başlatma gerekir. Emin değilseniz Claude Code’u yeniden başlatın.

VS Code eklentisi

Eklenti aynı ayar dosyalarını okur; ancak başlamadan önce oturum açılıp açılmadığını kendi claudeCode.environmentVariables ayarını kullanarak kontrol eder. Bu nedenle CLI çalışırken VS Code sizden oturum açmanızı isteyebilir. Komut Paleti’nden Preferences: Open User Settings (JSON) seçeneğini açıp şunu ekleyin:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://aihubmix.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-your-aihubmix-key" }
  ]
}

Ardından Developer: Reload Window komutunu çalıştırın. Daha fazla seçenek için Anthropic’in VS Code belgelerine bakın. Claude Desktop uygulaması ayrıdır: ne settings.json dosyasını ne de bu değişkenleri okur.

Diğer yararlı değişkenler

Bunların tümünü env bloğuna ekleyebilirsiniz. Tam liste Anthropic’in ortam değişkenleri başvuru belgesinde yer alır.

Yaygın hatalar ve anlamları

Not logged in · Please run /login veya ilk açılışta oturum açma ekranı
Claude Code bir token bulamadı. Şu üç şeyi kontrol edin: dosyanın atlanmasına neden olan bir JSON hatası, eksik bir ANTHROPIC_AUTH_TOKEN ya da yalnızca proje dosyasında bulunan bir token. Oturum açma adımı proje ayarları yüklenmeden önce çalışır; bu nedenle token’ı ~/.claude/settings.json dosyasına taşıyın.

Invalid or malformed JSON
Mesajda belirtilen dosyada yorum, sondaki virgül veya başka bir sözdizimi hatası vardır ve ayarlarının hiçbiri uygulanmamıştır.

There's an issue with the selected model (...)
Ya model kimliği yanlış ya da base URL /v1 ile bitiyor ve istek /v1/v1/messages adresine gidiyor. Model kimliği doğru görünüyorsa önce URL’yi kontrol edin.

API Error: 400 ve This model ID is incorrect
AIHubMix’te bu kimliğe sahip bir model yoktur ve mesajda aldığı kimlik tekrarlanır. Genellikle yazım hatasıdır. Kimliği AIHubMix model listesinden yeniden kopyalayın.

Failed to authenticate. API Error: 401 invalid key: ...
AIHubMix anahtarı kabul etmiyor. Mesaj, aldığı anahtarın son altı karakteriyle biter; bu nedenle bunları token’ınızın sonuyla karşılaştırın. PI_KEY ifadesi, gerçek bir anahtar yerine AIHUBMIX_API_KEY yer tutucusunun yapıştırıldığı anlamına gelir. Bunun dışındaki durumlarda genellikle kabuğunuzdaki eski bir ANTHROPIC_API_KEY gönderilmiştir. Mesajda bunun yerine this key is not enabled yazıyorsa AIHubMix konsolunda anahtarın etkin olduğunu ve bakiyeniz bulunduğunu kontrol edin.

auth may not work as expected
Hem token değişkeni hem de kayıtlı claude.ai oturum açma bilgileri etkin. Ağ geçidini kullanmaya devam etmek için /logout komutunu çalıştırın veya aboneliğinize geri dönmek için değişkeni kaldırın.

Claude Code doesn't recognize the model ...
Bu bir hata değil, uyarıdır: istek yine gönderilir ancak Claude Code, bağlam penceresinin 200K token olduğunu varsayar. Kimlik daha yeni bir Claude modeline aitse claude update komutunu çalıştırarak uyarıyı kaldırabilirsiniz.

Hatalı bir anahtarla takılmış gibi görünüyor
Claude Code, başarısız istekleri en fazla 10 kez yeniden dener. Her seferinde başarısız olan bir anahtarla yaptığımız testte claude -p yaklaşık üç dakika boyunca yeniden denemeye devam etti. Hatayı daha erken görmek için CLAUDE_CODE_MAX_RETRIES değerini düşürün.

Claude Code’da Claude için, diğer araçlarınızda ise OpenAI, Google ve diğer sağlayıcılar için tek bir anahtar kullanmak istiyorsanız AIHubMix, Anthropic API’sini https://aihubmix.com adresinde sunar. Yukarıdaki ayar dosyası, Claude Code’un ihtiyaç duyduğu her şeyi içerir.

SSS

Claude Code’un settings.json dosyası nerede?
Kişisel dosyanız ~/.claude/settings.json, Windows’ta ise %USERPROFILE%.claude\settings.json konumundadır. Projede git aracılığıyla paylaşılan .claude/settings.json ve yalnızca size özel olan .claude/settings.local.json dosyaları da bulunabilir. Claude Code, kurulum sırasında bu dosyaları oluşturmaz.

settings.json ortam değişkenlerini geçersiz kılar mı?
Evet. Bir ayar dosyasının env bloğundaki değer, kabuğunuzda dışa aktarılan aynı değişkenin üzerine yazılır. Dosyada ayarlanmayan değişkenler (örneğin eski bir ANTHROPIC_API_KEY) kabuktan gelmeye devam eder.

ANTHROPIC_AUTH_TOKEN mı yoksa ANTHROPIC_API_KEY mi kullanmalıyım?
Ağ geçidinizin okuduğu değişkeni kullanın. ANTHROPIC_AUTH_TOKEN, Bearer token gönderir ve onay gerektirmez. AIHubMix için belgelerde önerilen tercih ANTHROPIC_AUTH_TOKEN'dır. İkisini birden ayarlamayın: AIHubMix önce x-api-key değerini okur, bu nedenle eski bir ANTHROPIC_API_KEY 401 hatasına yol açar.

ANTHROPIC_BASE_URL /v1 ile mi bitmeli?
Hayır. Claude Code, /v1/messages yolunu kendisi ekler. AIHubMix için https://aihubmix.com kullanın.

settings.json dosyasını düzenledikten sonra Claude Code'u yeniden başlatmam gerekir mi?
env değişiklikleri dâhil çoğu düzenleme, dosyayı kaydettiğinizde uygulanır. Model anahtarı ve kabuk dışa aktarımları için yeniden başlatma gerekir. En güvenlisi yeniden başlatmaktır.

CLI çalıştığı hâlde VS Code neden oturum açmamı istiyor?
Uzantı başlamadan önce claudeCode.environmentVariables ayarını kullanarak oturum açılıp açılmadığını kontrol eder; ~/.claude/settings.json içindeki değerler bu kontrole ulaşmaz. Temel URL'yi ve token'ı oraya ekleyip pencereyi yeniden yükleyin.

ANTHROPIC_BASE_URL ayarlamak Claude aboneliğimi kullanır mı?
Yalnızca token ayarlanmamışsa. ANTHROPIC_AUTH_TOKEN veya ANTHROPIC_API_KEY ayarlandığında istekler bu anahtarı kullanır ve ağ geçidi, token başına ücret alır.

Kaynaklar

• Ayar dosyaları ve öncelik sırası, Anthropic
• Ortam değişkenleri, Anthropic
• Claude Code'u bir LLM ağ geçidine bağlama, Anthropic
• Model yapılandırması, Anthropic
• Claude Code entegrasyon kılavuzu, AIHubMix