Claude Code Router: Verimli Kodlama için Çok Modelli Yönlendirme

Claude Code’u yoğun şekilde kullanmaya başladığımda iki şeyi hızla fark ettim: kalite mükemmel ve fatura buna yansıyor. İster üç satırlık bir docstring ister kapsamlı bir mimari yeniden düzenleme olsun, her istek aynı Anthropic uç noktasına aynı ücretle gidiyor. 

Zamanla, tek bir satıcıya bağımlılık sadece maliyet baskısı yaratmakla kalmıyor; risk de oluşturuyor. Ayrıca tek bir modeldeki hız limiti tüm iş akışınızı durdurabiliyor.

Claude Code Router (CCR) bu iki sorunu doğrudan ele alıyor. Sağlayıcıya ulaşmadan önce Claude Code isteklerini yakalayan, ardından her isteği göreve en uygun arka uç modele yönlendiren açık kaynaklı bir vekil sunucu (proxy). 

Bu eğitimde sizi uçtan uca kurulumdan geçireceğim: yönlendiriciyi yükleme, çoklu sağlayıcı yönlendirme yollarını yapılandırma ve sistemi günlük operasyonel kullanım için sağlamlaştırma. Takip etmek için kullanmak istediğiniz sağlayıcıların API anahtarlarını (DeepSeek, Gemini, OpenRouter veya diğer desteklenen arka uçlar) alın ve terminalinizi açın. Başlayalım.

Yeni LLM’ler ve güçlü yönleri hakkında ilham için, en güncel modellere dair rehberlerimize göz atın:

• GPT-5.4
• GPT-5.3 Instant
• Gemini 3.1
• Claude Sonnet 4.6
• Claude Opus 4.6
• Qwen3.5
• MiniMax M2.5

Claude Code Router Nedir?

Kuruluma dalmadan önce, CCR’ın tam olarak ne olduğunu ve neden bu şekilde çalıştığını anlamaya değer. Claude Code ile henüz çalışmadıysanız, önce Claude Code 2.1 Pratik Rehberimizi inceleyin.

Claude Code Router yerel bir proxy geçididir. Çalıştırdığınızda makinenizde bir porta bağlanır (varsayılan olarak 127.0.0.1:3456) ve Claude Code istemciniz ile harici LLM sağlayıcıları arasına konumlanır. Claude Code’un perspektifinden bakıldığında, sadece yerel bir uç noktayla konuşuyordur. Perde arkasında CCR, isteğin gerçekte nereye gideceğine anlık olarak karar verir.

Çözdüğü temel sorun tek sağlayıcıya bağımlılıktır. Her şey bir sağlayıcı üzerinden yönlendirildiğinde, o sağlayıcının tüm kısıtlarını devralırsınız: 

• Fiyatlandırma katmanları
• Hız sınırları (rate limit)
• Bağlam penceresi tavanları 

CCR, görev türüne, token sayısına veya yazacağınız özel mantığa göre modelleri otomatik değiştiren yönlendirme kuralları tanımlamanıza izin vererek bunu ortadan kaldırır. Arka planda dosya taraması, bir Plan Modu muhakeme oturumuyla aynı modeli gerektirmez ve CCR ile zaten aynı modeli kullanmaz.

CCR’ı doğrudan sağlayıcı API’lerinden veya bulut tabanlı toplayıcılardan ayıran şey, çalıştığı yerdir. 

Proxy yerelde çalıştığı için, istek yükleriniz hedefe ulaşmadan önce üçüncü taraf bir toplama hizmetinden geçmez. Ayrıca, tamamen makinenizde çalışan bir dönüştürücü sistemi aracılığıyla, üstbilgileri (header) değiştirme, önbellek alanlarını temizleme ve token sınırlarını sınırlama dahil olmak üzere istek dönüşümü üzerinde ince ayarlı kontrole sahip olursunuz. 

Benim için CCR’ı sadece akıllı bir geçici çözüm değil gerçekten pratik kılan şey bu yerel yürütme modelidir: sonuç, her şeyi tek bir bulut sağlayıcısı üzerinden yönlendirmeye kıyasla daha ekonomik, daha dayanıklı ve daha gizli bir kurulumdur.

Claude Code Router Mimarisi ve Önkoşullar

CCR’ın ne yaptığı netleştiğine göre, şimdi perde arkasında nasıl çalıştığına ve kurulumdan önce nelere ihtiyacınız olduğuna bakalım.

Temel kavramsal model

CCR’ın mimarisini anlamak, yapılandırmayı kavramayı çok kolaylaştırır ve proxy deseninin uçtan uca görüldüğünde hızla oturduğunu düşünüyorum. 

CCR’ı başlattığınızda, terminalinizden çıkan tüm istekleri varsayılan Anthropic uç noktasına ulaşmadan önce yakalar. Her istek için şunları yapar:

1. İsteği inceler.
2. Yönlendirme kurallarınızı uygular.
3. Yükü hedef sağlayıcının beklediği formata dönüştürür.
4. İletir. 

Yanıt aynı şekilde geri döner ve Claude Code’un beklediği formata çevrilir, böylece istemci hiçbir şeyin değiştiğini fark etmez.

Bu yakalamanın içindeki kilit mekanizma görev tabanlı yönlendirmedir. CCR gelen istekleri türüne göre sınıflandırır ve uygun modele eşler. Başlıca görev kategorileri pratikte şöyle davranır:

Her görev türü işe en uygun aracı alır ve yapılandırıldıktan sonra manuel müdahale gerektirmez. Benim deneyimimde, arka plan rotası en büyük anlık getiriyi sağlar: bu sessiz dosya tarama istekleri bir kodlama oturumu boyunca sürekli olurdu ve CCR’dan önce fark ettirmeden ne kadar biriktiğini hiç bilmiyordum.

Gerekli önkoşullar

CCR’ı yüklemeden önce aşağıdakilerin hazır olduğundan emin olun:

• Çalışma zamanı olarak Node.js v18 veya üzeri

• Paket yöneticisi olarak npm

• Claude Code’un global kurulumu (npm install -g @anthropic-ai/claude-code)

• En az bir model arka ucu: desteklenen harici bir sağlayıcıdan (DeepSeek, Gemini, OpenRouter, Groq, Volcengine, SiliconFlow ve diğerleri) bir API anahtarı veya harici sağlayıcılardan tamamen kaçınmak istiyorsanız, modeli önceden çekilmiş yerel bir Ollama örneği

Başta tüm sağlayıcılarda hesap açmanız gerekmez. Bu eğitimi tamamlamak için çalışan tek bir arka uç yeterlidir; daha sonra yenilerini ekleyebilirsiniz.

Claude Code’u en popüler alternatiflerinden biriyle karşılaştırmak için, OpenClaw ve Claude Code yazımızı okumanızı öneririm.

Adım Adım Eğitim: Claude Code Router Kurulumu

Kavramlar ve önkoşullar netleştiğine göre, kurulumu adım adım oluşturalım.

Yönlendiriciyi yükleyin ve başlatın

Önkoşullar tamamlandıktan sonra, CCR’ı npm ile global kurabilirsiniz. Ancak Linux’ta, npm’in /usr/lib/node_modules dizinine yazmaya çalışması ve buranın root’a ait olması nedeniyle global paket kurulumlarında izin hatasıyla karşılaşabilirsiniz. Önerilen çözüm, komutu sudo ile çalıştırmak yerine npm’in global dizinini zaten size ait bir klasöre yönlendirmektir:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Bu PATH değişikliğini kalıcı yapmak için, export satırını ~/.bashrc veya ~/.zshrc dosyanıza ekleyip kabuğunuzu yeniden yükleyin. Ardından CCR’ı yükleyin:

npm install -g @musistudio/claude-code-router

Bu işlem ccr CLI’ını kabuğunuzda global olarak kullanılabilir hale getirir. Şimdi yönlendirici servisiniz başlatın:

ccr start

CCR varsayılan olarak http://127.0.0.1:3456’ya bağlanır. Başlangıç çıktısında servisin porta bağlandığını gördüğünüzde, proxy istekleri kabul etmeye hazırdır.

Temel bir sağlayıcı yapılandırın

Tüm CCR yapılandırması ~/.claude-code-router/config.json dosyasında bulunur. Birden fazla sağlayıcıyı bağlamadan önce, değişkenleri izole etmek ve temelin çalıştığını doğrulamak için tek, güvenilir bir sağlayıcıyla başlamanızı öneririm.

OpenRouter burada iyi bir başlangıç noktasıdır ve CCR’ı yeni bir makinede kurarken önce buna yönelirim. Tek bir API anahtarıyla, ücretsiz katmandakiler de dahil onlarca modele erişim sağlar; bu da belirli sağlayıcılara karar vermeden önce yönlendirme katmanını çalıştırmak için idealdir. Kayıt olup bir anahtar almak için OpenRouter’ı ziyaret edebilirsiniz.

OpenRouter kullanan minimal bir yapılandırma şöyle görünür:

{
  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "YOUR_OPENROUTER_API_KEY",
      "models": ["openai/gpt-oss-120b:free"],
      "transformer": {
        "use": ["openrouter"]
      }
    }
  ],
  "Router": {
    "default": "openrouter,openai/gpt-oss-120b:free"
  }
}

Burada dikkat edilmesi gereken birkaç nokta:

• api_base_url, yalnızca temel alan adı değil, sağlayıcının tam sohbet tamamlama uç noktasını göstermelidir.

• transformer, sağlayıcıların farklı istek formatları beklemesi nedeniyle CCR’ın hangi yerleşik yük dönüştürücüsünü kullanacağını belirtir. Dönüştürücü bu çeviriyi sessizce halleder.

• Router.default, daha spesifik bir kuralla eşleşmeyen tüm istekler için geri dönüş (fallback) modelini sağlayıcı,model sözdizimiyle ayarlar.

Güvenlik için, anahtarları dosyaya doğrudan gömmekten kaçının. CCR ortam değişkeni interpolasyonunu destekler: YOUR_OPENROUTER_API_KEY yerine $OPENROUTER_API_KEY yazıp değişkeni kabuğunuzda dışa aktarın. Bu interpolasyon yapılandırmanın tamamında özyineli çalışır, bu nedenle daha fazla sağlayıcı eklediğinizde de temiz şekilde ölçeklenir.

Claude Code’u proxy’ye bağlayın

Yapılandırma hazır olduğunda, Claude Code’u yönlendirici üzerinden başlatmak tek bir komutla olur:

ccr code

Hepsi bu. ccr code, proxy servisini başlatır ve Claude Code’u eşzamanlı olarak çalıştırır; ortam değişkenlerini otomatik yapılandırır. ccr start’ı ayrıca çalıştırmanıza gerek yoktur.

Yönlendirmenin etkin olduğunu doğrulamak için ~/.claude-code-router/logs/ klasörünü kontrol edin. Oradaki ccr-*.log adlı bir dosya, proxy’nin başladığını ve istek aldığını doğrular. Gerçek zamanlı izlemek için günlüğü takip edebilirsiniz:

tail -f ~/.claude-code-router/logs/$(ls -t ~/.claude-code-router/logs/ | head -1)

Claude Code Router günlükleri

Doğrulama hakkında bilinmesi gereken iki şey var. Claude Code başlığı, CCR hangi modele yönlendirirse yönlendirsin, her zaman geçerli varsayılan Claude modelini gösterir; çünkü bu, etkin arka uçtan değil, Anthropic hesap oturumunuzdan türetilir. Modele “hangi modelsiniz?” diye sorarsanız, istemci ona böyle kimlik vermeye ayarladığı için Claude Sonnet 4.6 diyecektir. Bunların hiçbiri güvenilir bir sinyal değildir.

Claude Code Router oturumu

Tek doğru kaynak günlük dosyasıdır. Yanıt girdilerindeki "model" alanını arayın. Orada yapılandırdığınız model adını, örneğin "model":"openai/gpt-oss-120b:free" görüyorsanız, yönlendirme çalışıyor demektir.

CCR’ı kalıcı hale getirip ccr code olmadan doğrudan claude komutunu kullanmak isterseniz, ~/.bashrc veya ~/.zshrc dosyanıza şunu ekleyin:

eval "$(ccr activate)"

Bu durumda activate yalnızca ortam değişkenlerini ayarladığı ve servisin kendisini başlatmadığı için önce ccr start’ın çalıştığından emin olun.

Çoklu sağlayıcı yönlendirmeyi uygulayın

Artık temel doğrulandığına göre, farklı görev türlerini farklı sağlayıcılara yönlendirecek şekilde yapılandırmayı genişletelim. Daha kapsamlı bir Router yapılandırması şöyle olabilir:

{
  "Router": {
    "default": "deepseek,deepseek-chat",
    "background": "ollama,qwen2.5-coder:latest",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "openrouter,google/gemini-2.5-pro-preview",
    "longContextThreshold": 60000,
    "webSearch": "gemini,gemini-2.5-flash"
  }
}

Her anahtar bir görev kategorisini "sağlayıcı,model" çiftine eşler:

• background rotası dosya tarama ve bağlam toplama isteklerini ele alır. Bunlar güvenle yerel bir Ollama modeline gidebilir; böylece ücretsiz kalır ve bu tek değişiklik aylık API faturamda en büyük düşüşü sağladı. 

• think rotası, Plan Modu ve karmaşık muhakeme görevlerini yakalar; deepseek-reasoner gibi bir model burada maliyetini karşılar. 

• longContext rotası, bir istek longContextThreshold token’ını (varsayılan 60.000) aştığında otomatik devreye girer ve manuel geçişe gerek olmadan yüksek kapasiteli bir modele yönlendirir. 

• webSearch için, modelin yerleşik web arama desteğine sahip olması gerektiğini unutmayın. OpenRouter üzerinden yönlendiriyorsanız, modele :online soneki eklemeniz gerekir (örneğin, "anthropic/claude-3.5-sonnet:online").

Hız sınırı dayanıklılığı için, CCR’ın özel yönlendirici özelliğiyle JavaScript’te geri dönüş (fallback) mantığı tanımlayabilirsiniz. Seçtiğiniz bir yolda bir dosya oluşturun, yapılandırmanızda "CUSTOM_ROUTER_PATH": "/path/to/custom-router.js" ile referans verin ve "sağlayıcı,model" dizesi veya varsayılan kurallara dönmek için null döndüren bir async fonksiyon dışa aktarın:

module.exports = async function router(req, config) {
  // Primary logic here. Return null to fall back to config-defined rules.
  return null;
};

Örneğin 429 yanıtını algılayıp otomatik olarak ikincil bir sağlayıcıya yeniden yönlendirerek hız limiti durumunda yeniden denemeyi burada uygularsınız. Her yapılandırma değişikliğinden sonra etkinleşmesi için servisi yeniden başlatmayı unutmayın:

ccr restart

Claude Code Router’ı İşletme ve Sorun Giderme

Yönlendirme çalıştıktan sonra odak, bir şeyler ters gittiğinde sistemi gözlemlenebilir, güvenli ve kolay hata ayıklanabilir tutmaya kayar.

Kullanımı izleyin ve bütçeleri uygulayın

CCR, bilinmeye değer iki ayrı günlükleme sistemi sunar:

• Sunucu düzeyi günlükler HTTP isteklerini, API çağrılarını ve sunucu olaylarını kapsar. ~/.claude-code-router/logs/ içine ccr-*.log adıyla yazılır. Pratikte en çok bu günlükleri kullanırsınız.

• Uygulama düzeyi günlükler yönlendirme kararlarını yakalar ve ~/.claude-code-router/claude-code-router.log dosyasına yazılır; ancak bu dosya kurulumunuza ve günlük seviyesi yapılandırmanıza bağlı olarak her zaman mevcut olmayabilir.

Sunucu günlüğünü düzenli gözden geçirmek, hangi rotaların tetiklendiğini, hangi modellerin çağrıldığını ve sağlayıcı hataları olup olmadığını net biçimde gösterir. 

Gerçek zamanlı görünürlük için CCR, ccr ui ile etkinleştirilebilen (v1.0.40’tan itibaren mevcut) bir durum satırı aracı da içerir. Etkinleştirildiğinde, Claude Code çalışırken geçerli yönlendirme durumunu doğrudan terminalinizde gösterir ve her isteği hangi modelin ele aldığını bir bakışta görmenizi sağlar.

Bütçe tarafında, en etkili güvenlik parmaklığı bizzat yönlendirme yapılandırmanızdır. background ve default rotalarını daha ucuz veya yerel modellere yönlendirerek, düşük değerli görevler için üst düzey modellerin çağrılmasını önlersiniz. think ve longContext rotalarını maliyetini hak eden modellere ayırın ve longContext için token eşiğini iş akışınızın tolere ettiği kadar yüksek tutun. 

Deneyimlerime göre bu yapılandırma düzeyi disiplini, harcamayı gerçekleşmeden önce önlediği için tepkisel izlemeye göre daha güvenilirdir.

Kimlik bilgilerini ve erişim kontrollerini güvenceye alın

Sağlayıcı listeniz büyüdükçe kimlik bilgisi yönetimi özel dikkat gerektirir. Benim izlediğim kurallar basit:

• Ham API anahtarlarını sürüm kontrolünde izlenen config.json’a asla gömmeyin. Her zaman "$PROVIDER_API_KEY" sözdizimiyle ortam değişkeni interpolasyonunu kullanın ve anahtarları kabuk profilinizden veya bir gizli yönetim aracından dışa aktarın.

• Proxy’yi bireysel geliştirici kurulumlarında localhost’ta tutun. Yapılandırmanızda bir APIKEY ayarlamazsanız, CCR sunucunun yalnızca 127.0.0.1’e bağlanmasını otomatik olarak zorlar; bu da paylaşılan makine veya ağlarda dış erişimi engeller.

• Takım dağıtımları için bir APIKEY belirleyin ve host’u 0.0.0.0’a açmanız gerekirse kullanın. Yönlendiriciye bağlanan her istemci bu anahtarı Authorization: Bearer veya x-api-key üstbilgisinde iletmelidir.

• Günlüklemeyi devre dışı bırakın veya azaltın eğer hassas kod yönlendiriyorsanız. Günlükleme varsayılan olarak etkindir ("LOG": true). İstek yüklerinin diske yazılmasını durdurmak için "LOG": false ayarlayın veya ayrıntılı hata ayıklama çıktısını bastırmak için "LOG_LEVEL": "warn" kullanın.

Bunu uygulamanın pratik bir yolu, tüm API anahtarlarınızı kabuk profilinizde tutup config.json içinde $VAR_NAME sözdizimiyle referanslamaktır. Böylece yapılandırma dosyasının kendisi hiçbir sır içermez ve güvenle paylaşılabilir veya sürüm kontrolüne alınabilir.

Bir anahtarın günlüklerde sızıp sızmadığından emin değilseniz, önce günlük seviyesi ayarınızı kontrol edin. "LOG_LEVEL": "warn"’a geçmek, günlüklemeyi tamamen kapatmadan diske yazılanları azaltmanın en hızlı yoludur.

Yaygın yönlendirme hatalarını giderin

Bir şey bozulduğunda, katmanlı bir tanılama dizisi çok zaman kazandırır. En dış katmandan başlayıp içeri doğru ilerlemek en iyisi.

Adım 1: Proxy’nin çalıştığını kontrol edin 

ccr code çalıştırın ve servis başlangıç onayını arayın. Port meşgulse veya servis başlatılamadıysa, Claude Code’da bağlantı reddedildi hataları görürsünüz. 

Ayrıntılar için ~/.claude-code-router/logs/ içindeki sunucu günlüklerini kontrol edin. Başlangıç hatalarının çoğu ya bir port çakışmasına ya da hatalı biçimlendirilmiş bir config.json dosyasına dayanır.

Adım 2: Model adlarının eşleştiğini kontrol edin

En yaygın yapılandırma hatası, Providers içindeki model adı ile Router içindeki model adının uyuşmamasıdır. Her ikisi de birebir aynı olmalıdır. 

Farklılarsa, CCR modeli olmayan bir istek gönderir ve Missing model in request body hatası görürsünüz. Yapılandırmayı düzelttikten sonra yeniden yüklemek için mutlaka ccr restart çalıştırın.

Adım 3: Sağlayıcı tarafı ayarlarını kontrol edin

Model adı doğruysa ancak istekler hâlâ 404 ile başarısız oluyorsa, sağlayıcı hesap ayarlarınızı kontrol edin. Örneğin OpenRouter’da, ücretsiz modellerin üçüncü taraf sağlayıcılara veri göndermesini engelleyen varsayılan bir gizlilik politikası vardır. No endpoints found matching your data policy gibi bir hata görürsünüz. 

Çözüm, OpenRouter gizlilik ayarlarınıza gidip ücretsiz model kullanımını etkinleştirmektir. Beklenmedik 4xx hataları alırsanız diğer sağlayıcılarda da benzer hesap düzeyi anahtarlar olabilir; onları da kontrol edin.

Adım 4: Dönüştürücü (transformer) yapılandırmasını kontrol edin

İstekler sağlayıcıya ulaşıyor ancak yanıtlar hatalı biçimleniyor veya araç çağrıları başarısız oluyorsa, sorun genellikle eksik veya hatalı bir dönüştürücüdür. Sağlayıcınızı yerleşik dönüştürücü listesiyle karşılaştırın ve doğru olanın "use" dizisinde olduğundan emin olun.

Çoğu durumda bu dört adımı sırayla uygulamak sorunu hızla izole eder. Sunucu günlüğü, hem giden isteği hem de sağlayıcının ham yanıtını yakalar; bu da hatanın nerede meydana geldiğini anlamanız için gereken her şeyi sağlar.

Sonuç

Artık Claude Code’un üzerinde kurulu, çoklu sağlayıcı yönlendirme altyapınız var. Arka plan görevleri hızlı yerel modellere gidiyor, yoğun muhakeme gerektiren işler uzman modellere yönlendiriliyor ve uzun bağlamlı istekler yüksek kapasiteli sağlayıcılar tarafından ele alınıyor—hepsi sizin kontrol ettiğiniz kurallara göre otomatik olarak.

Anlık faydalar; daha düşük API maliyetleri, hız limitlerinde tek hata noktası olmaması ve iş akışınıza dokunmadan sağlayıcıları değiştirme esnekliğidir.

Kurulumu zaman içinde verimli tutmak için yönlendirme günlüklerinizi periyodik olarak gözden geçirin. Sunucu günlüğü, hangi rotaların daha sık tetiklendiğini ve pahalı modellerin, daha ucuz bir alternatifin üstesinden gelebileceği görevler için devreye girip girmediğini gösterir. longContextThreshold ve geri dönüş kurallarını gerçek kullanıma göre ayarlamak, bir kez belirleyip bırakmaktan çok daha etkilidir.

Son olarak, çalışmanız tescilli kod içeriyorsa, bu istekleri Ollama üzerinden yerel bir LLM’e yönlendirmenizi kesinlikle öneririm. Yayınlanmamış kod içeren müşteri çalışmalarında benim de yaptığım budur. Sağlayıcı olarak eklemesi bir dakikadan az sürer ve en hassas sorgularınız makinenizden dışarı çıkmaz.

Yapay zekâ uygulama geliştirme becerilerinizi ileri taşımak isteyenler için, LangChain ile Yapay Zekâ Mühendisliği yetkinlik yoluna kaydolmanızı şiddetle tavsiye ederim. Eğitim içeriği yapay zekâ yerli olup, size AI iş akışlarını mühendislikte gerçek bir profesyonel olmanız için gereken becerileri birebir öğreten kişisel bir eğitmene erişim sağlar.