Kodlama aracılarında Ollama kullanımı ve yapılandırma

Bağlantı kurduğunuz yapı

Ollama'yı kodlama aracınızla kullanabilirsiniz; bağlantı süreci beklenenden çok daha basittir. Yalnızca bir temel URL değiştirmeniz ve bir model adı seçmeniz yeterlidir. API anahtarı alanı bir değer girilmesini gerektirir, ancak yerel sunucu bu değeri dikkate almadığı için herhangi bir metin dizisi kullanılabilir.

Ollama, 11434 numaralı portu dinler ve aynı anda iki farklı istek biçimine yanıt verir. /v1/chat/completions, OpenAI uyumlu olan biçimdir ve Ollama belgelerinde buradaki anahtarın zorunlu olduğu ancak işleme alınmadığı belirtilir. /v1/messages ise Claude Code'un kullandığı Anthropic uyumlu biçimdir. Aracınız bu iki biçimden birini zaten desteklediği için başka bir ayar değişikliğine gerek kalmaz.

Bu işlem beş dakika sürer. Sonucun kullanılabilir olup olmadığı, neredeyse kimsenin değiştirmediği iki ayara (bağlam uzunluğu ve keep-alive) ve modele uygun iş yükünün verilmesine bağlıdır. Her iki konu kendi bölümünde ele alınmış olup, gerçekçi sınırlar ise en sonda belirtilmiştir.

Hangi kodlama aracıları yerel bir temel URL kabul eder

Test tek bir sorudan ibarettir: Araç, bir temel URL (base URL) ayarı sunuyor mu? Eğer sunuyorsa, sunucunuzla iletişim kurabilir.

Ollama; Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, JetBrains IDE'leri ve VS Code için entegrasyon sayfaları yayınlar. Aider, kendi Ollama desteğini ayrı olarak belgeler. Bu, Ağustos 2026 itibarıyla insanların kodlama aracısı denildiğinde kastettiği çoğu şeyi kapsar. Hepsi aynı formatta iletişim kurmaz ve kurulumların başarısız olduğu nokta da bu farktır.

• Çoğu aracı, OpenAI uyumlu bir uç nokta ister. Onlara http://localhost:11434/v1 temel URL'sini ve boş olmayan herhangi bir API anahtarı dizisini verin.
• Claude Code, OpenAI temel URL'sini hiçbir şekilde kabul etmez. Anthropic Messages API ile iletişim kurar, bu nedenle ANTHROPIC_BASE_URL değerinin http://localhost:11434 olarak ayarlanması gerekir; Ollama burada /v1/messages hizmetini sunar.
• Codex, OpenAI Responses API'sini kullanır. Ollama, 0.13.3 sürümüyle eklenen /v1/responses hizmetini de sunar.
• Temel URL ayarı olmayan bir aracı yönlendirilemez, çünkü uç nokta istemcinin içine gömülüdür. Bunun yerine önüne kendi kendine barındırılan bir LiteLLM ağ geçidi gibi bir çeviri katmanı koyun ve modelinizi istemcinin talep ettiği formatta yeniden sunun.

Ollama bu yapılandırmaları sizin yerinize yazabilir. ollama launch opencode, seçtiğiniz model için satır içi yapılandırmayla OpenCode'u başlatır; ollama launch claude aynı işlemi Claude Code için yapar ve ollama launch droid --config aracı başlatmadan yapılandırmayı yazar.

Ollama kurulumu ve araç çağırma yeteneğine sahip bir modelin indirilmesi

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama ls

Kurulum aracı bir systemd birimi ekler ve bunu başlatır; bu nedenle systemctl status ollama komutu active (running) çıktısını vermelidir. Eğer vermezse, journalctl -e -u ollama komutu başarısızlığın nedenini gösterir.

Modelin araç çağırma (tool calling) özelliğini desteklemesi gerekir, çünkü bir ajan bu şekilde çalışır. Ajan bir dosyayı okur, bir yama yazar, testi çalıştırır, ardından hatayı okur ve tekrar dener. Araç çağrısı yapamayan bir model, düzenlemeyi yapmak yerine düz yazı ile tarif eder; bu durumda ajan döngüye girer veya durur. İndirme yapmadan önce ollama.com üzerindeki model sayfasında tools etiketini arayın. qwen3-coder:30b bu özelliği destekler ve Ağustos 2026 itibarıyla bu etiket 19 GB boyutunda bir indirme olup 256K bağlam penceresine sahiptir. Eğer sunucunuz yalnızca CPU kullanıyorsa veya RAM kapasiteniz düşükse, bir VPS üzerinde Qwen 27B etiketi için bellek hesaplamaları rehberi, indirme işlemine başlamadan önce 8 ile 64 GB arasında nelerin sığabileceğini gösterir. İndirme işlemini tamamladığınızda, bu gigabaytlar sunucunun kök dizinine kaydedilir; bu alan bir VPS üzerinde genellikle en kısıtlı alandır, bu nedenle Ollama'nın model dosyalarını nerede tuttuğu ve başka bir yere nasıl taşınacağı konusu disk dolmadan önce okunmalıdır.

Şimdi sunucunun hangi isimleri servis ettiğini doğrulayın:

curl http://localhost:11434/v1/models

Bu yanıttaki dizgiler, ajan yapılandırmanızda karakteri karakterine bulunması gereken değerlerdir. Bunu önceden kontrol etmek, "model bulunamadı" hatalarının çoğunu çözer. Eğer Ollama henüz kurulu değilse, daha kapsamlı anlatım bir VPS üzerinde Ollama ile LLM barındırma rehberinde mevcuttur.

OpenCode'u Ollama'ya Yönlendirme

~/.config/opencode/opencode.json dosyasını düzenleyin:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "qwen3-coder 30b"
        }
      }
    }
  }
}

models altındaki anahtar, Ollama'ya gönderilen model adıdır; bu nedenle ollama ls ile tam olarak eşleşmelidir. name alanı ise yalnızca model seçicideki etikettir. opencode'ü başlatın, Ollama sağlayıcısına geçin ve isteğin başka bir yere değil, kendi sunucunuza ulaştığını doğrulamak için journalctl -e -u ollama'i izleyin. Ajanın kurulumu OpenCode'u bir VPS üzerinde çalıştırma bölümünde ele alınmıştır.

Claude Code'u Ollama'ya Yönlendirme

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30b

ANTHROPIC_API_KEY, özellikle boş bir dizge olarak ayarlanmıştır. Ortamda bırakılan gerçek bir anahtar, isteklerinizi yerel çıkarım yerine barındırılan API'ye gönderir; bu da yerel çıkarım alamamanıza ve faturalandırılmanıza neden olur. ollama launch claude, tüm bu ayarları sizin yerinize yapılandırır.

Uyumluluk katmanının neleri dışarıda bıraktığını bilmeniz gerekir. tool_choice veya istem önbelleğe alma (prompt caching) özelliklerini uygulamaz ve token sayma uç noktası bulunmaz; bu nedenle gördüğünüz token sayıları, modelin kendi belirleyicisinden (tokenizer) gelen tahminlerdir. Claude Code ayrıca büyük bir sistem istemi ve geniş bir araç setiyle birlikte gelir, bu yüzden bir sohbet istemcisinden daha fazla bağlama ihtiyaç duyar. Nelerin aktarılıp nelerin aktarılmadığına dair daha geniş kapsamlı soru, Claude'u kendi sunucunuzda barındırıp barındıramayacağınız konusunda ele alınmıştır.

Aider'ı Ollama'ya Yönlendirme

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30b

Aider dokümantasyonu, ollama/ yerine ollama_chat/ ön ekinin kullanılmasını önermektedir. Ayrıca, bir modelin sunucu varsayılanından farklı bir bağlam penceresine ihtiyaç duyduğu durumlar için .aider.model.settings.yml içerisinde model bazında bağlam penceresi sabitleme imkanı sunar:

- name: ollama_chat/qwen3-coder:30b
  extra_params:
    num_ctx: 65536

Çalışan bir kurulum neden anlamsız sonuçlar üretir

Bu bölüm kritik öneme sahiptir. Ollama, görebildiği VRAM (GPU üzerindeki video belleği) kapasitesine göre varsayılan bir bağlam uzunluğu (context length) seçer ve bu varsayılanlar yayınlanmıştır:

[
  {
    "label": "Under 24 GiB VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "24 to 48 GiB VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "48 GiB VRAM or more",
    "default_context_tokens": "262,144"
  }
]

Çoğu VPS planı ve yalnızca CPU kullanan tüm sunucular ilk satıra girer: 4,096 token. Yalnızca büyük bir GPU, son satırdaki 262,144 token değerine ulaşır.

Bir aracı (agent), herhangi bir işlem yapmadan önce 4096 token tüketir. Sistem istemi, araç tanımları, depo listesi ve açtığı ilk dosya zaten bu boyuttan daha büyüktür. Bundan sonra yaşananlar ise asıl sorundur: hiçbir hata oluşmaz. Aider belgeleri, Ollama'nın pencereyi aşan bağlamı sessizce attığını belirtir. En eski tokenlar silinir; bu nedenle model artık göremediği bir dosya hakkında kendinden emin bir şekilde yanıt verir veya iki adım önce verdiğiniz bir talimatı unutur. Yerel bir modelin kod yazamayacak kadar yetersiz olduğu yönündeki raporların çoğu bu mekanizmadan kaynaklanır. Sayının kendisini seçmek ayrı bir karardır ve her boyutta KV önbellek belleğinde num_ctx maliyeti konusunu, bir değerde karar kılmadan önce okumaya değerdir.

Ollama belgeleri, aracılar ve kodlama araçları gibi görevlerin en az 64000 token olarak ayarlanması gerektiğini belirtir. Bunu sunucuda ayarlayın:

sudo systemctl edit ollama.service

Geçersiz kılma (override) dosyasına şu satırları ekleyin:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Ardından yeniden yükleyin ve yeniden başlatın:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps kontrol için kullanılır. Bir CONTEXT sütunu yazdırır ve bu sayı, modelin fiilen aldığı değerdir. ID ve SIZE değerleriniz farklı olacaktır:

NAME               ID              SIZE     PROCESSOR    CONTEXT    UNTIL
qwen3-coder:30b    a1b2c3d4e5f6    24 GB    100% GPU     64000      4 minutes from now

Bunu aracı içinde değil, sunucuda ayarlamanızın iki nedeni vardır. OpenAI sohbet tamamlama şemasında bağlam uzunluğu için bir alan yoktur, bu nedenle OpenAI uyumlu bir istemci bunu talep edemez. Ayrıca ayar sunucu bazlıdır, bu sayede sunucuya yönlendirdiğiniz her aracı bu ayarı devralır. Çıktı tarafının kendi üst sınırı vardır ve bağlam uzunluğunun aksine bu, uyumluluk uç noktası üzerinden iletilir; bu nedenle bir yanıt yamanın ortasında kesildiğinde num_predict ve ona eşlenen max_tokens alanı başvurulması gereken yerdir. Eğer bir model farklı bir pencereye ihtiyaç duyarsa, bunu bir Modelfile ile bir kopyaya işleyin:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

Bağlam ücretsiz değildir. Daha uzun bir pencere daha fazla bellek tüketir, bu yüzden PROCESSOR sütununu izleyin. 100% GPU hedeflemeniz gereken değerdir. Modelin bir kısmı CPU'ya taştığında token hızı, aracı döngüsünü kullanılamaz hale getirecek kadar düşer; yerel bir LLM üzerinde saniyedeki token sayısını ölçmek, sunucunuz için gerçek üst sınırı bulmanın yoludur. Makineyi satın almadan önce boyutlandırma konusu bir kodlama aracı VPS'inin ne kadar RAM ve CPU'ya ihtiyaç duyduğu bölümünde ele alınmıştır.

Modeli istekler arasında bellekte tutma

Ollama, varsayılan olarak bir modeli son isteğinden 5 dakika sonra bellekten boşaltır. Bu davranış, sohbet arayüzleri için uygun olsa da otonom ajan çalışmaları için yanlıştır. Bir kod farkını (diff) incelemek için durakladığınızda zamanlayıcı dolar ve bir sonraki istek, ilk token görünmeden önce onlarca gigabaytlık ağırlığı diskten tekrar yükler. Bu durum, sistemin yanıt vermediği izlenimini yaratır.

OLLAMA_KEEP_ALIVE, 10m veya 24h gibi bir süre dizisi, saniye cinsinden düz bir sayı, modeli süresiz olarak bellekte tutmak için -1 veya hemen boşaltmak için 0 değerlerini kabul eder. Bu ayarı bağlam uzunluğu (context length) ile birlikte yapılandırın:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"

keep_alive istek alanı yalnızca Ollama'nın yerel /api/generate ve /api/chat uç noktalarında bulunur, uyumluluk uç noktalarında yer almaz; bu nedenle bir ajan bunu istek bazında ayarlayamaz. Ortam değişkeni, elinizdeki tek kontrol mekanizmasıdır. Belleği geri kazanmanız gerektiğinde, ollama stop qwen3-coder:30b komutu sunucuyu durdurmadan modeli bellekten boşaltır. Ayarın yeniden başlatma sonrasında da geçerli kalmasını istiyorsanız veya ağırlıkları tüm gün bellekte tutmanın maliyeti ile belleği geri kazanma ihtiyacını değerlendirmek istiyorsanız, Ollama modelini bellekte tutma rehberi her iki durumu da kapsamaktadır.

Ollama'yı ayrı bir sunucuda çalıştırma

Ollama varsayılan olarak localhost üzerinde dinleme yapar. Başka bir makineden erişmek için aynı systemd override dosyası içerisinde OLLAMA_HOST=0.0.0.0:11434 değişkenini ayarlayın ve servisi yeniden başlatın.

Bunu yalnızca özel bir ağ içerisinde yapın. Ollama belgeleri, yerel API için herhangi bir kimlik doğrulamanın gerekmediğini belirtir; bu nedenle 11434 numaralı portun internete açık olması, herkesin donanımınızı kullanabileceği ve temsilcinizin gönderdiği her şeyi okuyabileceği anlamına gelir. İki güvenli seçenek mevcuttur. Bağlantıyı localhost üzerinde tutun ve portu dizüstü bilgisayarınızdan SSH üzerinden yönlendirin:

ssh -N -L 11434:localhost:11434 you@your-vps

Temsilciniz http://localhost:11434/v1 adresine işaret etmeye devam eder ve aradaki farkı anlamaz. Diğer seçenek ise bir VPN kullanmaktır; bu durumda Ollama, 0.0.0.0 yerine VPN adresi üzerinde dinleme yapacak şekilde ayarlanır. Eğer birden fazla kişi veya birden fazla temsilci tek bir sunucuyu paylaşacaksa, Ollama'nın zamanlayıcısı bu yük için tasarlanmamıştır ve Ollama ile vLLM arasındaki karşılaştırma, verimlilik farkının nerede sorun yaratmaya başladığını göstermektedir.

Yerel bir kodlama modelinin avantajlı olduğu ve olmadığı durumlar

Kendi barındırdığınız bir model tarafından yönetilen bir ajan, her görevde bir sınır (frontier) API'sinin yerini almaz. Dört tür iş yükünde belirgin şekilde daha avantajlıdır:

• Her değişikliğin küçük olduğu ve kontrol edebildiğiniz toplu mekanik düzenlemeler. Bir depo genelinde yeniden adlandırma, tip ipuçları ekleme, docstring yazma, yorumları çevirme. Model saatlerce çalışsa bile maliyet artmaz.
• Donanımınızdan çıkmaması gereken işler. Gizlilik sözleşmesi kapsamındaki istemci kodu veya üçüncü bir tarafa gönderilmesine izin verilmeyen dahili bir depo.
• Hiçbir barındırılan API'ye erişimin olmadığı çevrimdışı ve hava boşluklu (air-gapped) makineler.
• Öngörülebilir maliyet. Sunucu ücreti ödendikten sonra, döngü içinde token tüketen bir ajanın ek maliyeti yoktur; bu durum, ücretlendirmeli bir API'nin tam tersidir. GPU VPS maliyetinin API token'ları ile başa baş noktası bu konudaki hesaplamaları içerir.

Uzun ve çok adımlı görevlerde ise başarısız olur. "Bu testin neden başarısız olduğunu bul, nedenini düzelt, çağrı yapanları güncelle" gibi görevler, tüm geçmişin bağlamda tutulduğu ve arka arkaya birçok doğru araç çağrısının yapıldığı süreçler gerektirir. Mütevazı bir sunucuda 8B ile 14B aralığındaki bir model, hatalı bir araç çağrısı üretecek veya birkaç adımdan sonra planı kaybedecektir; bu durumda modeli yönlendirmek için harcadığınız süre, görevin kendisinden daha uzun sürecektir. Bu, prompt yazarak çözebileceğiniz bir sorun değildir. Bu bir kapasite sorunudur.

Ayrıca, hatalı olmanın maliyetli olduğu ve her satırı okumayacağınız durumlarda da başarısız olur. Yerel modele çıktısını doğrulayabileceğiniz dar kapsamlı işler verin; adım adım kontrol etmeyeceğiniz işler için ise barındırılan bir model kullanmaya devam edin.

Hata modları ve karşılaşacağınız dizgeler

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. Sunucu çalışmıyor veya aracı (agent) farklı bir ana makineye yönlendirilmiş. systemctl status ollama komutunu çalıştırın, ardından journalctl -e -u ollama komutunu uygulayın.

Aracı, modelin mevcut olmadığını bildiriyor. Yapılandırmanızdaki isim, sunucunun sunduğu isimle eşleşmiyor. İsmi curl http://localhost:11434/v1/models ile karşılaştırın ve oradaki dizgeyi kopyalayın. Etiket (tag), ismin bir parçasıdır; bu nedenle hiç indirmediğiniz bir etiketi yapılandırmada belirtirseniz, benzer bir model yüklü olsa bile işlem başarısız olur.

Aracı düz metinle yanıt veriyor ve dosyayı düzenlemiyor. Modelin araç desteği yok ya da istek ve araç tanımları bağlam penceresini (context window) tamamen dolduruyor. Model sayfasındaki tools etiketini kontrol edin, ardından ollama ps içindeki CONTEXT sütununa bakın.

İlk belirteçten (token) önce uzun bir sessizlik, ardından normal hız. Keep-alive süresi dolmuş ve ağırlıklar diskten tekrar okunuyor. OLLAMA_KEEP_ALIVE ayarını yapılandırın.

Model, az önce okuduğu bir dosyayla çelişiyor. Bağlam kesilmesi (context truncation). ollama ps genellikle, ortam değişkeni systemd birimi yerine kabuğunuza (shell) gittiği için, ayarladığınızdan daha küçük bir CONTEXT değeri gösterir.

Her şey çalışıyor ancak yavaş ve PROCESSOR değeri 100% GPU değil. Model ve bağlamı VRAM'e sığmıyor. Bağlam uzunluğunu düşürün veya daha küçük bir modele ya da daha düşük bir nicemlemeye (quantisation) geçin. Yeniden indirme yapmadan önce, q4_K_M, q8_0 ve fp16'nın bellek maliyeti ve kalite kaybının nerede başladığı başlıklı yazı, bir alt seviyeye geçmenin size ne kadar alan kazandıracağını ve neleri feda edeceğinizi açıklar.

FAQ

Claude Code uygulamasını Ollama'ya yönlendirebilir miyim?

Evet, ancak OpenAI uyumlu bir URL ile değil. Claude Code, Anthropic Messages API protokolünü kullanır ve Ollama bu yapıyı aynı 11434 numaralı port üzerinde /v1/messages adresinde sunar. ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama ve boş bir ANTHROPIC_API_KEY değişkenini dışa aktarın, ardından claude --model qwen3-coder:30b ile başlatın. ollama launch claude, aynı ayarları sizin için yazar. Uyumluluk katmanı tool_choice veya istem önbelleğe alma (prompt caching) özelliklerini uygulamaz ve token sayma uç noktası bulunmadığından, bildirilen token sayıları tahminidir.

Yerel modelim neden göremediği kodlar hakkında cevap veriyor?

Çünkü istek artık bağlam penceresine (context window) sığmıyor ve isteğin en eski kısmı hata vermeden atılıyor. Ollama, varsayılan bağlam boyutunu tespit ettiği VRAM miktarına göre belirler. 24 GiB altındaki sistemlerde bu varsayılan değer 4,096 tokendır; bu değer, bir aracın sistem istemi ve araç tanımları tarafından tek başına aşılır. systemd birimi içerisinde OLLAMA_CONTEXT_LENGTH=64000 değerini ayarlayın, Ollama'yı yeniden başlatın ve ollama ps çıktısındaki CONTEXT sütununda yeni değeri doğrulayın.

VPS üzerinde bir kodlama aracı için hangi modeli çalıştırmalıyım?

64k bağlam penceresiyle belleğe sığan ve tools etiketine sahip en büyük modeli seçin; kod için optimize edilmiş modelleri tercih edin. Yeterli VRAM kapasitesine sahip bir GPU sunucusunda yaygın cevap qwen3-coder:30b modelidir. Eğer bu etiket sunucunuz için çok büyükse, indirme işlemine karar vermeden önce Nemotron 3.5 Lightning için RAM değerleri ve sadece CPU hızı karşılaştırmaları faydalı bir referans olacaktır. Yaklaşık 14B parametrenin altındaki modeller kod hakkındaki soruları iyi yanıtlayabilir ancak çok adımlı düzenlemelerde başarısız olabilir; çünkü araç kullanımı, küçük biçimlendirme hatalarını bile tolere etmez. Örnek bir istem yerine kendi deponuzdan gerçek bir görevle test edin.

Kendi modelimde bir kodlama aracı çalıştırmak için GPU'ya ihtiyacım var mı?

Pratikte evet. Sadece CPU ile çıkarım yapmak mümkündür ve tekil sorular için yeterlidir; ancak bir araç, görev başına birçok istek gönderir ve her biri uzun bir geçmişi yeniden okur. Bu nedenle düşük token hızı, iki dakikalık bir görevi bir saate çıkarır. ollama ps içerisindeki PROCESSOR sütununu kontrol edin: 100% GPU dışındaki herhangi bir değer, modelin bir kısmının CPU üzerinde çalıştığı anlamına gelir ve token hızı ciddi oranda düşer.