Ollama kodlama aracına nasıl bağlanır?

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 zorunlu tutar ancak yerel sunucu bu değeri dikkate almadığı için herhangi bir metin girebilirsiniz.

Ollama, 11434 numaralı portu dinler ve aynı anda iki farklı istek biçimine yanıt verir. /v1/chat/completions, OpenAI uyumlu biçimdir ve Ollama belgelerinde bu alandaki 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ği yapmanız gerekmez.

Bu işlem beş dakika sürer. Sonucun kullanılabilirliği, neredeyse hiç kimsenin değiştirmediği iki ayara (bağlam uzunluğu ve keep-alive) ve modele uygun iş yükü 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 base URL kabul eder

Test tek bir sorudan ibarettir: araç bir 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 şeylerin çoğunu 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 endpoint ister. Onlara http://localhost:11434/v1 base URL'sini ve boş olmayan herhangi bir API anahtarı dizisini verin.
• Claude Code, OpenAI base URL'sini hiçbir şekilde kabul etmez. Anthropic Messages API ile konuştuğu için ANTHROPIC_BASE_URL değişkeninin http://localhost:11434 olarak ayarlanması gerekir; Ollama burada /v1/messages üzerinden hizmet verir.
• Codex, OpenAI Responses API'sini kullanır. Ollama, 0.13.3 sürümüyle eklenen /v1/responses üzerinden de hizmet verir.
• Base URL ayarı olmayan bir aracı yönlendirilemez, çünkü endpoint istemcinin içine gömülüdür. Bunun yerine, kendi kendine barındırılan bir LiteLLM ağ geçidi gibi bir çeviri katmanını araya 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ı dosyaya 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

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

Modelin araç çağırma (tool calling) özelliğini desteklemesi gerekir, çünkü bir ajanın çalışma mantığı araç çağırma üzerine kuruludur. Ajan bir dosyayı okur, bir yama yazar, testi çalıştırır, ardından hata çıktısını okuyup tekrar dener. Araç çağırma yeteneği olmayan bir model, düzenlemeyi yapmak yerine düz metin olarak tarif eder; bu durumda ajan döngüye girer veya durur. İndirme işleminden ö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, 256K bağlam penceresine sahip 19 GB boyutunda bir indirmedir. Eğer sunucunuz yalnızca CPU kullanıyorsa veya RAM kapasiteniz kısıtlıysa, bir VPS üzerinde Qwen 27B etiketi için bellek hesaplamaları, indirme işlemine başlamadan önce 8 ila 64 GB RAM aralığında nelerin çalışabileceğini gösterir.

Şimdi sunucunun hangi modelleri sunduğunu doğrulayın:

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

Bu yanıttaki dizeler, ajan yapılandırmanızda karakteri karakterine yer alması gereken değerlerdir. Bunu önceden kontrol etmek, "model bulunamadı" hatalarının çoğunu çözer. Ollama henüz kurulu değilse, daha kapsamlı rehber bir VPS üzerinde Ollama ile LLM self-hosting başlığında yer almaktadır.

OpenCode uygulamasını 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 uygulamasını başlatın, Ollama sağlayıcısına geçiş yapın ve isteğin başka bir yere değil, kendi sunucunuza ulaştığını doğrulamak için journalctl -e -u ollama kayıtlarını izleyin. Aracın kurulumu OpenCode uygulamasını VPS üzerinde çalıştırma bölümünde anlatılmış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. Ortam değişkeninde gerçek bir anahtar bırakılması, isteklerinizi yerel çıkarım yerine barındırılan API'ye gönderir; bu da yerel çıkarım yapamamanı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. Bu katman tool_choice veya istem önbellekleme (prompt caching) özelliklerini uygulamaz; ayrıca bir token sayma uç noktası bulunmadığından, gördüğünüz token sayıları modelin kendi tokenizer'ından gelen yaklaşık değerlerdir. Claude Code ayrıca büyük bir sistem istemi ve geniş bir araç setiyle birlikte gelir, bu nedenle 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.

Ollama'yı Aider'a 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, .aider.model.settings.yml içerisinde her model için bağlam penceresini (context window) sabitlemenize olanak tanır; bu özellik, bir modelin sunucu varsayılanından farklı bir pencere boyutuna ihtiyaç duyduğu durumlarda kullanışlıdır:

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

Çalışan bir kurulumun neden anlamsız sonuçlar ürettiği

Bu bölüm kritik öneme sahiptir. Ollama, görebildiği VRAM (GPU üzerindeki video belleği) miktarından varsayılan bir bağlam uzunluğu 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 tüm CPU tabanlı sunucular ilk satıra düşer: 4,096 token. Yalnızca büyük bir GPU, son satırdaki 262,144 token değerini alı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 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ğuna dair raporların çoğu bu mekanizmadan kaynaklanır.

Ollama belgeleri, aracılar ve kodlama araçları gibi görevlerin en az 64000 token değerine 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 komutudur. 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 nedenle sunucuya yönlendirdiğiniz her aracı bu ayarı devralır. Eğer bir model farklı bir pencereye ihtiyaç duyarsa, bunu bir Modelfile ile bir kopyasına 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. İstediğiniz değer 100% GPU değeridir. Modelin bir kısmı CPU'ya taştığında, token hızı bir aracı döngüsünü kullanılamaz hale getirecek kadar düşer; yerel bir LLM üzerinde saniyedeki token sayısını ölçmek, sunucunuzun gerçek sınırını bulmanızı sağlar. 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, aracı (agent) tabanlı işlemler için yanlıştır. Bir kod farkını (diff) okumak 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 parametresi, 10m veya 24h gibi bir süre dizgisi, saniye cinsinden düz bir sayı, modeli süresiz olarak bellekte tutmak için -1 veya hemen boşaltmak için 0 değerini alır. 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 mevcut değildir. Bu nedenle bir aracı, bu ayarı istek bazında yapılandıramaz. Elinizdeki tek seçenek ortam değişkenidir. Belleği geri kazanmanız gerektiğinde, ollama stop qwen3-coder:30b komutu sunucuyu durdurmadan modeli bellekten boşaltı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 yönlendirme yapmaya 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 yapılandırılı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 karşılaştırması, verimlilik farkının nerede sorun yaratmaya başladığını göstermektedir.

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

Kendi sunucunuzda barındırdığınız bir model tarafından yönetilen bir ajan, her görevde bir sınır ötesi (frontier) API'nin yerini almaz. Dört tür iş yükünde net bir şekilde üstünlük sağlar.

• 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ışır ve maliyetiniz değişmez.
• 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 çağrısının yapılamadığı ç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 bir maliyeti yoktur; bu, ücretli bir API'nin tam tersidir. GPU VPS maliyetinin API tokenları ile başa baş noktası hesaplamaları içermektedir.

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ığı bir süreç gerektirir. Mütevazı bir sunucuda 8B ile 14B aralığındaki bir model, hatalı bir araç çağrısı üretecek veya birkaç turdan sonra planı kaybedecektir; bu durumda ajanı 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. 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ç çekmediğ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 hiçbir dosyayı düzenlemiyor. Modelin araç desteği yoktur ya da istek ve araç tanımları bağlam penceresini (context window) tamamen doldurmuştur. 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 beklediğinizden daha küçük bir CONTEXT değeri gösterir; bunun nedeni ortam değişkeninin systemd birimi yerine kabuğunuza (shell) gitmiş olmasıdır.

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.

FAQ

Claude Code'u 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ı 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 ayarlar; 24 GiB altındaki sistemlerde bu değer 4,096 tokendır. Bir ajanın sistem istemi ve araç tanımları tek başına bu sınırı aşabilir. systemd birim dosyasında 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 ajanı için hangi modeli çalıştırmalıyım?

64k bağlam penceresiyle belleğe sığan ve tools etiketi taşıyan en büyük modeli seçin; kod için optimize edilmiş modelleri tercih edin. Yeterli VRAM'e sahip bir GPU sunucusunda qwen3-coder:30b yaygın bir tercihtir. 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ü ajan çalışmaları, araç çağrılarındaki küçük biçimlendirme hatalarını tolere etmez. Örnek bir istem yerine, kendi deponuzdan gerçek bir görevle test edin.

Kendi modelim üzerinde bir kodlama ajanı ç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 ajan 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 dönüştürür. ollama ps içindeki PROCESSOR sütununu kontrol edin: 100% GPU dışındaki herhangi bir değer, modelin bir kısmının CPU üzerinde çalıştığı ve token hızının ciddi oranda düştüğü anlamına gelir.