Claude Code Router — Claude Code'u herhangi bir modele yönlendirin veya yönlendiriciyi tamamen atlayın

Claude Code Router araması yapan insanların çoğu iki farklı şeyden birini istiyor: Claude Code'u birden fazla model sağlayıcısı arasında yönlendirmek veya Claude Code'u Anthropic'in liste fiyatından daha ucuza çalıştırmak. Yalnızca ilki yönlendiriciyi gerektirir. Claude Code, ANTHROPIC_BASE_URL'yi doğrudan okur; bu nedenle ikincisi için yalnızca üç ortam değişkeni yeterlidir; hiçbir ek yazılım gerekmez.

Bu kılavuz her iki yolu da, tam değişken adlarını, sessiz bir 401 oluşturan kimlik bilgisi tuzağını ve herhangi bir geçidin arkasında çalışmayı bırakan şeylerin dürüst bir listesini kapsar. Yakın zamanda başka bir CCR yazısı okuduysanız önce B Seçeneği'ne geçin: bu yazıların düzenlemenizi söylediği config.json, artık yönlendiricinin okuduğu yapılandırma değildir.

Aslında hangisine ihtiyacınız var?

Yönlendirici yerel bir hizmettir: çalıştırmanız, yapılandırmanız ve güncel tutmanız gereken bir işlem daha — ayrıca 2026 itibarıyla düzenlediğiniz bir dosya yerine kendi arayüzüne sahip bir masaüstü uygulamasıdır. Gerçekten çok sağlayıcılı yönlendirmeye, istek başına muhasebeye veya alt aracı düzeyinde model seçimine ihtiyaç duyduğunuzda bu maliyeti karşılar. Bir temel URL yeterli olacakken bu maliyeti karşılamaz.

A Seçeneği — temel URL değişikliği (kurulum yok)

Kunavo Anthropic'e özgü Messages API'sini /v1/messages adresinde sunar; Claude Code'un çağırdığı uç nokta budur. Oraya yönlendirin:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...              # create at kunavo.com/app/keys
export ANTHROPIC_MODEL=claude-sonnet-5             # exact slug — see the table below
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5     # the opus alias and plan mode (v2.1.280+)
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5   # the sonnet alias; Sonnet 5.5 is not on Kunavo
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5   # background tasks

ANTHROPIC_BASE_URL yalnızca kaynak adresidir — Claude Code /v1/messages yolunu kendisi ekler; bu nedenle yol eklemeyin. Model satırlarını koruyun: Claude Code'un yerleşik varsayılanı ve opus takma adı en yeni Opus'a yönelir; Kunavo bu modeli henüz sunmuyorsa ilk istek 404 döner. sonnet takma adı, Kunavo'nun sunmadığı Sonnet 5.5'i ister; bu nedenle ANTHROPIC_DEFAULT_SONNET_MODEL satırı olmadan /model sonnet, opusplan'nın yürütme aşaması ve model: sonnet olarak ayarlanmış tüm alt aracılar 404 döner. opus takma adı Opus 5.5'e (claude-opus-5-5) sabitlenmiştir; bunun için Claude Code v2.1.280 veya üzeri gerekir — sürümünüz daha eskiyse claude update çalıştırın. Anahtarı kaydolup 10 $ yükledikten sonra panelden alın; anahtar yalnızca bir kez gösterilir.

Hangi kimlik bilgisi değişkeni — ve neden önemli

Claude Code iki kimlik bilgisi değişkenini farklı HTTP başlıklarında gönderir ve sunucunun okumadığı başlıktaki anahtar 401 ile başarısız olur:

Tek bir somut nedenle ANTHROPIC_AUTH_TOKEN değişkenini tercih edin: ANTHROPIC_API_KEY etkileşimli bir oturumda tek seferlik onay gerektirir ve bir kez reddettiğiniz anahtar daha sonra istem olmadan yok sayılır — değişken açıkça ayarlanmış ve açıkça kullanılmıyorken ortaya çıkan kafa karıştırıcı bir hata. Kunavo'da model keşfi buna karar vermez. Claude Code'un geçit model keşfi sadece bearer token'ı gönderir (ANTHROPIC_AUTH_TOKEN ayarlanmışsa); aksi durumda x-api-key başlığına geri döner. Kunavo'nun /v1/models uç noktası anahtarı her iki başlıktan da okur.

Kalıcı hâle getirin

Kabuk dışa aktarımları yalnızca o terminal ve ondan başlatılan her şey için geçerlidir — dock'tan açılan bir düzenleyici bunları görmez, arka plan aracıları da görmez. Her şeyi kapsamak için değerleri bir ayarlar dosyasına koyun:

{
  "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"
  }
}

Tüm projeler için ~/.claude/settings.json dosyasını kullanın. Bir anahtarı asla bir projenin .claude/settings.json dosyasına koymayın — bu dosya sürüm kontrolüne kaydedilir.

Güvenmeden önce doğrulayın

Önce uç noktayı doğrudan test edin; böylece bir hata Claude Code'u değil, yapılandırmayı işaret eder:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

# A response starting with {"id":"msg_ means the URL and key both work.
# 401 -> the key is in the wrong header; see "Which credential variable" below.

Ardından aynı kabuktan claude komutunu başlatın ve /status komutunu çalıştırın. Anthropic base URL satırında api.kunavo.com adresinin görünmesi ve Auth token satırında değişkeninizin adının görünmesi, her iki tarafın da etkin olduğunu doğrular.

Özel model ayarlayın — slug'ı açıkça seçin

Kunavo model slug'larını tam eşleşmeyle çözümler ve tarihle sonlandırılmış adlar için diğer ad kullanmaz; bu nedenle claude-sonnet-4-5-20250929 404 döndürürken claude-sonnet-5 başarılı olur. Yerleşik varsayılana güvenmek yerine her zaman ANTHROPIC_MODEL değişkenini ayarlayın:

Takma ad değişkenleri, herhangi bir yönlendirici olmadan göreve göre yönlendirme yapmanızı sağlar: ANTHROPIC_DEFAULT_OPUS_MODEL, opus takma adını ve plan modunu karşılar; ANTHROPIC_DEFAULT_SONNET_MODEL, sonnet takma adını ve opusplan'ın yürütme aşamasını karşılar; ANTHROPIC_DEFAULT_HAIKU_MODEL ise haiku takma adını ve Claude Code'un özetler ile başlıklar gibi arka plan işlerini karşılar. Kunavo üzerinden kullanımda son iki ayar gereklidir; sabitlenmezlerse Kunavo'nun sunmadığı model kimliklerini (Sonnet 5.5 ve v2.1.293'ten itibaren Haiku 5.5) isterler. Haiku ayarını claude-haiku-4-5 olarak belirleyin; bu, arka plan işlerini ana modelden de alır. (ANTHROPIC_SMALL_FAST_MODEL, aynı ayarın kullanımdan kaldırılmış yazımıdır.)

İsteğe bağlı: seçicide her modeli gösterin

CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 ayarını yapın (Claude Code v2.1.129+); Claude Code başlangıçta GET /v1/models isteğini göndererek bulduğu modelleri /model seçicisine From gateway etiketiyle ekler. Kunavo bu uç noktayı sunduğundan etkinleştirilmiş her Claude modeli görünür ve /model, elle koruduğunuz bir liste yerine canlı bir menüye dönüşür. Her iki kimlik bilgisi değişkeni de bunun için çalışır — yukarıya bakın.

B Seçeneği — claude-code-router, şu an gerçekten çalıştığı şekliyle

Buradan başlayın; çünkü CCR hakkında yazılanların neredeyse tamamı artık var olmayan bir sürümü anlatıyor. Yönlendirici eskiden bir JSON dosyası ve bir ccr code komutuydu. Şimdi masaüstü uygulaması, yönetim arayüzü, istek günlükleri ve model geçidi olan yerel bir kontrol düzlemidir — ve her eğitimde gösterilen config.json artık onu yapılandırmaz.

CCR çalışma zamanı yapılandırmasını ~/.claude-code-router/config.sqlite içinde tutar (Windows'ta %APPDATA%\claude-code-router\config.sqlite). Eski bir config.json, henüz SQLite yapılandırması yokken taşıma kaynağı olarak bir kez okunur. Bu ilk çalıştırmadan sonra düzenlemek çalışan yapılandırmayı etkilemez — hata veya uyarı olmadan. Özenle yapıştırdığınız Providers bloğu yapılandırma değildir.

Buna 2026-09-06'dan önceki bu sayfa da dahildir: burada bulunan JSON parçacığı yanlıştı ve hiçbir şey yok sayıldığını size söylemediği için bir öğleden sonranıza mal olabilecek türden bir yanlıştı. Yapılandırma artık arayüzde yapılır (veya yedekleme için Settings → Export data kullanılır — CCR çalışırken canlı SQLite dosyalarını kopyalamayın).

Kurulum ve başlatma

CCR iki şekilde sunulur: GitHub Releases'tan bir masaüstü uygulaması (tepsi, otomatik güncelleme, masaüstü entegrasyonları) ve başsız veya denetimli dağıtımlar için bir npm CLI. İkisi de aynı yapılandırma dizinini paylaşır.

# CCR ships as a desktop app (GitHub Releases) or an npm CLI. Both read the
# same ~/.claude-code-router directory. The CLI needs Node.js 22+.
npm install -g @musistudio/claude-code-router
ccr ui        # management UI on :3458, model gateway on :3456

# Configure the provider and an Agent Config profile in that UI, then launch
# Claude Code through the profile by name:
ccr "Claude Code - Kunavo"        # npm CLI
ccr-app "Claude Code - Kunavo"    # the desktop app's own launcher

# There is no 'ccr code' in the current command reference. The service commands
# are start / ui / stop / serve / web; everything else is a profile name.

Kunavo'yu eklemek tek bir sağlayıcı girdisi — Providers → Add provider, ön ayar Other / custom API endpoint, uç nokta https://api.kunavo.com, sk-kn- anahtarınız — ve bir Agent Config → Add profile → Claude Code profilidir. Check Connection ve model keşfi de dahil olmak üzere alan alan sürüm Claude Code Router entegrasyon sayfasında yer alır. Bu bölümün geri kalanı o sayfanın kapsamadığı konulardır: kimlik bilgileri, ekonomi ve hata kipleri.

Üç kimlik bilgisi ve 401'in hangisiyle ilgili olduğu

Çalışan bir kurulumun bozuk görünmesinin en yaygın yolu budur. CCR'nin üç ayrı gizli bilgisi vardır ve bunlar üç farklı sıçramayı kimlik doğrular:

Bağlantı noktası eşleşmesi de kullanıcıları şaşırtır: yönetim varsayılan olarak 127.0.0.1:3458, model geçidi ise 127.0.0.1:3456 kullanır. 3458'e yönlendirilen bir temel URL geçide değil, arayüze ulaşır. (Docker her ikisini de kasıtlı olarak tek bir Nginx uç noktası arkasında birleştirir; Docker talimatlarının farklı görünmesinin nedeni budur.) Ulaşılabilir bir arayüz, çalışan bir geçit anlamına gelmez: geçit adresindeki /health yolunu kontrol edin ve Server alanının Running gösterdiğini doğrulayın.

Katman başına eşleme temel noktadır

Claude Code bir model istemez; bir katman ister — ana döngü Sonnet veya Opus'u, arka plan işleri (alt ajanlar, arama, özetler, konuşma başlıkları) ise küçük ve hızlı olanı kullanır. Agent Config'teki bir Claude Code profili bunları ayrı alanlar olarak sunar: varsayılan bir Model ile isteğe bağlı Fable, Opus, Sonnet ve Haiku geçersiz kılmaları; bunların her biri bir Provider/model değeri alır. Bir katmanı boş bırakırsanız Claude Code onu seçer.

Birinin seviye eşlemesini kopyalamadan önce bu tabloyu okuyun; çünkü en belirgin ayrım ilk kaldıraçtır: claude-sonnet-5, Kunavo'da claude-opus-5-5'den %50 daha ucuzdur ($1,40 / $7,00, $2,80 / karşısında). İkinci kaldıraç Haiku seviyesidir: $0,70 / $3,50 fiyatıyla Sonnet 5'ten 2× daha ucuzdur ve hiç görmediğiniz hacmi taşır — her alt aracı, her dosya önceliklendirme geçişi, oluşturulan her başlık. claude-sonnet-4-6 artık ucuz Sonnet değildir: $2,10 / $10,50 fiyatıyla Sonnet 5'ten %50 daha pahalıdır; bu nedenle yukarıdaki parçacıklar ANTHROPIC_MODEL=claude-sonnet-5 ayarını yapar.

Alt ajan yönlendirmesi — katman eşlemesinin yapamadığı şey

Katman geçersiz kılmaları tüm alt ajanları tek bir modele sabitler. CCR daha ayrıntılı çalışabilir: bir Claude Code isteği yerleşik rotayla eşleştiğinde kullanılabilir modeller listesini Agent / Task araç açıklamasına ekler ve Claude Code, başlattığı her ajanın isteminin önüne istediği modeli belirten bir etiket koyar:

<CCR-SUBAGENT-MODEL>provider/model</CCR-SUBAGENT-MODEL>

CCR etiketi kaldırır ve o isteği buna göre yönlendirir; böylece bir arama alt ajanı Haiku'da, bir inceleme alt ajanı ise Opus'ta çalışabilir — seçim sabitlenmek yerine göreve göre yapılır. Bu anahtar kolayca gözden kaçar: Modeller sayfasında en az bir model için Açıklama bulunana kadar mekanizma kapalıdır. Açıklama yoksa CCR hiçbir şey eklemez ve her alt ajan sessizce profil varsayılanına döner. Açıklamaları göreve uygun yazın — Haiku için “kod arama, dosya ayıklama, ucuz paralel alt ajanlar”, Opus için “mimari analizi, yüksek riskli inceleme”. Çalıştığında istek günlükleri rota nedeni olarak builtin:claude-code-subagent değerini gösterir.

Protokol seçimi ve önbellekteki maliyeti

CCR uç noktayı yoklar ve bir kablo protokolü seçer. Ona yalın origin https://api.kunavo.com değerini verirseniz Anthropic Messages ile konuşur; https://api.kunavo.com/v1 değerini verirseniz OpenAI uyumlu biçimi kullanır. Her iki arayüz de aynı anahtarda aktiftir ve Gelişmiş ayarlardan otomatik algılamayı geçersiz kılabilirsiniz.

Anthropic Messages biçimini tercih edin. Bu biçim, iletilen isteklerde cache_control alanını korur; böylece istem önbelleğe alma modele ulaşır ve önbelleğe alınmış girdiler, girdi ücretinin %10'u üzerinden ücretlendirilir (nasıl çalışır) — her adımda sabit bir öneki yeniden gönderen bir ajan döngüsünde mevcut en büyük tek tasarruf budur. Dürüst olmak gerekirse, aradaki yönlendirici istekleri yine de düzenler: CCR, Claude Code'un eklediği faturalandırma başlığını içeren sistem mesajını kaldırır ve alt ajan yönlendirmesi açıksa araç açıklamalarına model listesini ekler. Her iki içerik de önbellek kesme noktalarınızdan önce yer alır; dolayısıyla bu içerikteki her değişiklik, yeni önek önbelleğe yerleşirken bir önbellek kaçırmasına neden olur. Bundan sonra kararlı hale gelir — ancak bu, çalıştırılacak daha az bileşen içermesinin yanı sıra Seçenek A'nın Seçenek B'den biraz daha iyi önbellekleme yapmasının gerçek bir nedenidir.

Ancak istem önbelleğe alma, OpenAI uyumlu biçimde de modele ulaşır. Uzun bir istemde Kunavo, bu rotada önbellek kesme noktalarını kendisi ayarlar: sistem isteminde, araç tanımlarında ve konuşma bir asistan turu içerdiğinde son mesajda. Bir mesajda veya araç tanımında gelen bir cache_control korunur.

Geri dönüş: yeniden deneme mi yük devretme mi

Yönlendirme sayfasındaki Başarısızlıkta varsayılan seçeneğini ihtiyaç duymadan önce ayarlamaya değer. Yeniden dene, 408, 409, 429 ve 5xx durumlarında aynı modele yeniden gönderir; Retry-After değerine uyar, aksi durumda 1 saniyeden başlayıp 30 saniyelik üst sınıra kadar üstel geri çekilme uygular. Geri dönüş hedefleri, yedek modellerin sıralı listesini dolaşır ve herhangi bir 4xx veya 5xx durumunda tetiklenir; bunun dayanağı, model bulunamaması ya da sağlayıcı reddinin yalnızca mevcut hedefi etkileyebilmesidir. Tek tek kurallar genel ayarı geçersiz kılabilir. Bir geri dönüş çalıştığında yanıt, sonradan anlayabilmeniz için x-ccr-fallback-attempts ve x-ccr-fallback-model değerlerini içerir.

Gerçekten yol üzerinde olduğunu doğrulayın

Profilden Claude Code'u başlatın, bir ileti gönderin, ardından CCR'de İstek günlüklerini açın. Satırda Claude Code'un istediği request model, isteğin gittiği resolved provider ve resolved model gösterilir — bu üçlü kanıttır. CLI içinde /model, CCR'nin sunduğu modelleri listeler. Claude Code yanıt veriyor ancak günlük satırı görünmüyorsa Claude Code'u CCR üzerinden değil, kendiniz başlatmışsınızdır ve profilin kapsamı Yalnızca CCR'den açıldı durumundadır.

Bir kodlama oturumunun maliyeti

Claude Code, her adımda sistem istemini, konuşmayı ve güncel dosya bağlamını yeniden gönderir; bu nedenle token başına ücret hızla birikir. claude-sonnet-5 üzerindeki Kunavo ücretleriyle:

Bu, istem önbelleğe alma öncesinde ana modelde yaklaşık 30% indirim demektir. Tam ücretler Claude API fiyatlandırma kılavuzunda, kendi token sayılarını kullanan hesaplama ise maliyet hesaplayıcısında bulunur.

Hâlâ çalışanlar — ve çalışmayanlar

Claude Code'u herhangi bir ağ geçidine yönlendirmek birkaç şeyi değiştirir. Karar vermeden önce bilinmesi gereken liste kısa ve değerlidir:

Son satırda: token sayımı, Anthropic'in kendi ağ geçidi belirtiminin isteğe bağlı olarak işaretlediği tek uç noktadır ve bulunmadığında Claude Code bağlam kullanımını yerel olarak tahmin eder. Kunavo bugün /v1/messages/count_tokens sunmadığından /context değeriniz kesin bir sayı değil, tahmindir. Bu sayı dışında hiçbir şey bozulmaz — otomatik sıkıştırma ve oturumun kendisi etkilenmez.

Sorun giderme

Temel URL yolu

…ve yönlendirici yol üzerindeyken

API'nin kendisindeki hatalara yönelik tek tek düzeltmeler geçersiz API anahtarı ve hız sınırı sorun giderme sayfalarındadır.

Sık sorulan sorular