Ollama

local loopback, özel ağ, .local ve yalnızca ana makine adından oluşan Ollama URL'leri gerçek bir taşıyıcı belirteci gerektirmez. OpenClaw bunlar için ollama-local işaretçisini kullanır.

Genel uzak ana makineler ve https://ollama.com gerçek bir kimlik bilgisi gerektirir: OLLAMA_API_KEY, bir kimlik doğrulama profili veya sağlayıcının apiKey değeri. Doğrudan barındırılan kullanım için ollama-cloud sağlayıcısını tercih edin.

api: "ollama" kullanan özel bir sağlayıcı aynı kurallara uyar. Örneğin, özel bir LAN ana makinesine yönlendirilmiş ollama-remote sağlayıcısı apiKey: "ollama-local" kullanabilir; alt aracılar bu işaretçiyi eksik kimlik bilgisi olarak değerlendirmek yerine Ollama sağlayıcı kancası üzerinden çözümler. agents.defaults.memorySearch.provider da gömmelerin bu Ollama uç noktasını kullanması için özel bir sağlayıcı kimliğine işaret edebilir.

auth-profiles.json, bir sağlayıcı kimliğinin kimlik bilgisini depolar; uç nokta ayarlarını (baseUrl, api, modeller, üstbilgiler, zaman aşımları) models.providers.<id> içine koyun. { "ollama-windows": { "apiKey": "ollama-local" } } gibi eski düz dosyalar bir çalışma zamanı biçimi değildir; openclaw doctor --fix, bunları yedek oluşturarak standart bir ollama-windows:default API anahtarı profiline dönüştürür. Bu eski dosyadaki bir baseUrl değeri gereksizdir ve sağlayıcı yapılandırmasına taşınmalıdır.

Ollama bellek gömmeleri için taşıyıcı kimlik doğrulaması, bildirildiği ana makineyle sınırlıdır:

• Sağlayıcı düzeyindeki bir anahtar yalnızca o sağlayıcının ana makinesine gönderilir.
• agents.*.memorySearch.remote.apiKey yalnızca kendi uzak gömme ana makinesine gönderilir.
• Tek başına kullanılan bir OLLAMA_API_KEY ortam değişkeni Ollama Cloud kuralı olarak değerlendirilir ve varsayılan olarak yerel/kendi barındırdığınız ana makinelere gönderilmez.

Gateway ile aynı makinedeki Ollama otomatik olarak keşfedilir:

ollama serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw models set ollama/gemma4

Elle model belirtmeniz gerekmiyorsa bir models.providers.ollama bloğu eklemeyin.

{  models: {    providers: {      ollama: {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 300,        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            reasoning: true,            input: ["text"],            params: {              num_ctx: 32768,              thinking: false,              keep_alive: "15m",            },          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "ollama/qwen3.5:9b" },    },  },}

contextWindow, OpenClaw'ın bağlam bütçesidir; params.num_ctx Ollama'ya gönderilir. Donanım, modelin duyurulan tam bağlamını çalıştıramıyorsa bunları uyumlu tutun.

Yerel arka plan programı olmadan doğrudan barındırılan modeller:

export OLLAMA_API_KEY="your-ollama-api-key"

{  models: {    providers: {      ollama: {        baseUrl: "https://ollama.com",        apiKey: "OLLAMA_API_KEY",        api: "ollama",        models: [          {            id: "kimi-k2.5:cloud",            name: "kimi-k2.5:cloud",            reasoning: false,            input: ["text", "image"],            contextWindow: 128000,            maxTokens: 8192,          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "ollama/kimi-k2.5:cloud" },    },  },}

Bu yapı yerine özel ollama-cloud sağlayıcı kimliğini kullanmak için Ollama Cloud sayfasına bakın.

Birden fazla Ollama sunucusu çalıştırırken özel sağlayıcı kimlikleri kullanılır; her birinin kendi sunucusu, modelleri, kimlik doğrulaması ve zaman aşımı vardır.

{  models: {    providers: {      "ollama-fast": {        baseUrl: "http://mini.local:11434",        apiKey: "ollama-local",        api: "ollama",        contextWindow: 32768,        models: [{ id: "gemma4", name: "gemma4", input: ["text"] }],      },      "ollama-large": {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        api: "ollama",        timeoutSeconds: 420,        contextWindow: 131072,        maxTokens: 16384,        models: [{ id: "qwen3.5:27b", name: "qwen3.5:27b", input: ["text"] }],      },    },  },  agents: {    defaults: {      model: {        primary: "ollama-fast/gemma4",        fallbacks: ["ollama-large/qwen3.5:27b"],      },    },  },}

OpenClaw, Ollama'yı çağırmadan önce etkin sağlayıcı önekini kaldırır (önek yoksa düz ollama/ önekine geri döner); böylece ollama-large/qwen3.5:27b, Ollama'ya qwen3.5:27b olarak ulaşır.

Bazı yerel modeller basit istemleri işleyebilir ancak aracın tüm özellikleriyle çalışmakta zorlanır. Genel çalışma zamanı ayarlarına dokunmadan önce araçları ve bağlamı sınırlandırın:

{  agents: {    list: [      {        id: "local",        experimental: {          localModelLean: true,        },        model: { primary: "ollama/gemma4" },      },    ],  },  models: {    providers: {      ollama: {        baseUrl: "http://127.0.0.1:11434",        apiKey: "ollama-local",        api: "ollama",        contextWindow: 32768,        models: [          {            id: "gemma4",            name: "gemma4",            input: ["text"],            params: { num_ctx: 32768 },            compat: { supportsTools: false },          },        ],      },    },  },}

compat.supportsTools: false seçeneğini yalnızca model veya sunucu, araç şemalarında güvenilir biçimde başarısız olduğunda kullanın; bu seçenek kararlılık karşılığında ajan yeteneğinden ödün verir. localModelLean, açıkça gerekmedikleri sürece ağır tarayıcı, Cron, mesaj, medya oluşturma, ses ve PDF araçlarını doğrudan ajan yüzeyinden kaldırır ve daha büyük katalogları Araç Araması'nın arkasına yerleştirir. Ollama'nın çalışma zamanı bağlamını veya düşünme modunu değiştirmez. Döngüye giren ya da bütçesini gizli akıl yürütmeye harcayan küçük Qwen tarzı düşünme modellerinde bunu params.num_ctx ve params.thinking: false ile birlikte kullanın.

/v1/chat/completions arkasındaki bir vekil için api: "openai-completions" değerini açıkça ayarlayın:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: true, // default: true        apiKey: "ollama-local",        models: [...]      }    }  }}

Bu mod, akış ve araç çağırmayı aynı anda desteklemeyebilir; modelde params: { streaming: false } ayarını kullanmanız gerekebilir.

OpenClaw bu modda varsayılan olarak options.num_ctx ekler; böylece Ollama sessizce 4096 belirteçli bağlama geri dönmez. Vekiliniz bilinmeyen options alanlarını reddediyorsa bunu devre dışı bırakın:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: false,        apiKey: "ollama-local",        models: [...]      }    }  }}

Otomatik keşfedilen modellerde OpenClaw, özel Modelfile dosyalarındaki daha büyük PARAMETER num_ctx değerleri dâhil olmak üzere /api/show tarafından bildirilen bağlam penceresini kullanır; aksi hâlde OpenClaw'ın varsayılan Ollama bağlam penceresine geri döner.

Sağlayıcı düzeyindeki contextWindow, contextTokens ve maxTokens, bu sağlayıcı altındaki her model için varsayılanları belirler ve model bazında geçersiz kılınabilir. contextWindow, OpenClaw'ın kendi istem/Compaction bütçesidir. params.num_ctx değerini açıkça ayarlamadığınız sürece yerel /api/chat istekleri options.num_ctx değerini ayarlanmamış bırakır; böylece Ollama kendi model, OLLAMA_CONTEXT_LENGTH veya VRAM tabanlı varsayılanını uygular. Geçersiz, sıfır, negatif veya sonlu olmayan params.num_ctx değerleri yok sayılır. Eski bir yapılandırma, yerel istek bağlamını zorlamak için yalnızca contextWindow/maxTokens kullandıysa bunları params.num_ctx alanına kopyalamak üzere openclaw doctor --fix komutunu çalıştırın. OpenAI uyumlu bağdaştırıcı, yapılandırılan params.num_ctx veya contextWindow değerinden varsayılan olarak yine options.num_ctx ekler; üst sistem options alanını reddediyorsa injectNumCtxForOpenAICompat: false ile devre dışı bırakın.

Yerel model girdileri ayrıca params altında yaygın Ollama çalışma zamanı seçeneklerini kabul eder ve bunları yerel /api/chat options alanı olarak iletir: num_keep, seed, num_predict, top_k, top_p, min_p, typical_p, repeat_last_n, temperature, repeat_penalty, presence_penalty, frequency_penalty, stop, num_batch, num_gpu, main_gpu, use_mmap ve num_thread. Birkaç anahtar (format, keep_alive, truncate, shift), iç içe options yerine üst düzey istek alanları olarak iletilir. OpenClaw yalnızca bu Ollama istek anahtarlarını ilettiğinden streaming gibi yalnızca çalışma zamanına özgü parametreler hiçbir zaman Ollama'ya gönderilmez. Üst düzey think değerini ayarlamak için params.think (veya params.thinking) kullanın; false, Qwen tarzı düşünme modellerinde API düzeyindeki düşünmeyi devre dışı bırakır.

{  models: {    providers: {      ollama: {        contextWindow: 32768,        models: [          {            id: "llama3.3",            contextWindow: 131072,            maxTokens: 65536,            params: {              num_ctx: 32768,              temperature: 0.7,              top_p: 0.9,              thinking: false,            },          }        ]      }    }  }}

Model başına agents.defaults.models["ollama/<model>"].params.num_ctx da çalışır; ikisi de ayarlanmışsa açık sağlayıcı model girdisi önceliklidir.

OpenClaw, düşünme ayarını Ollama'nın beklediği şekilde iletir: options.think değil, üst düzey think. /api/show yanıtı thinking yeteneği bildiren otomatik keşfedilmiş modeller /think low, /think medium, /think high ve /think max seçeneklerini sunar; düşünme özelliği olmayan modeller yalnızca /think off seçeneğini sunar.

openclaw agent --model ollama/gemma4 --thinking offopenclaw agent --model ollama/gemma4 --thinking low

Ya da bir model varsayılanı ayarlayın:

{  agents: {    defaults: {      models: {        "ollama/gemma4": {          thinking: "low",        },      },    },  },}

Model bazında params.think/params.thinking, belirli bir model için API düşünmesini devre dışı bırakabilir veya zorunlu kılabilir. Etkin çalıştırmada yalnızca örtük off varsayılanı bulunduğunda OpenClaw bu açık yapılandırmayı korur; /think medium gibi kapalı olmayan bir çalışma zamanı komutu yine de bunu geçersiz kılar. Doğru değerli bir düşünme isteği, açıkça reasoning: false olarak işaretlenmiş bir modele asla gönderilmez; think: false isteği ise her durumda gönderilir.

deepseek-r1, reasoning, reason veya think adlı modeller varsayılan olarak akıl yürütme yeteneğine sahip kabul edilir — ek yapılandırma gerekmez:

ollama pull deepseek-r1:32b

Ollama yerel olarak çalışır ve ücretsizdir; bu nedenle hem otomatik keşfedilen hem de elle tanımlanan modeller için tüm model maliyetleri 0 değerindedir.

Paketle gelen Ollama Plugin'i, bellek araması için bir bellek gömme sağlayıcısı kaydeder. Yapılandırılmış Ollama temel URL'sini ve API anahtarını kullanır, /api/embed çağrısı yapar ve mümkün olduğunda birden fazla bellek parçasını tek bir input isteğinde toplar.

proxy.enabled=true olduğunda, yapılandırılmış baseUrl değerinden türetilen tam ana makineye ait local loopback kaynağına yönelik gömme istekleri, yönetilen iletme proxy'si yerine OpenClaw'ın korumalı doğrudan yolunu kullanır. Yapılandırılmış ana makine adının kendisi localhost veya bir loopback IP değişmezi olmalıdır — yalnızca loopback'e çözümlenen DNS adları yine yönetilen proxy yolunu kullanır. LAN, tailnet, özel ağ ve genel Ollama ana makineleri her zaman yönetilen proxy yolunda kalır; başka bir ana makineye/bağlantı noktasına yapılan yönlendirmeler güveni devralmaz. proxy.loopbackMode: "proxy" yine de loopback trafiğini proxy üzerinden yönlendirir; proxy.loopbackMode: "block" ise bağlantı kurulmadan önce bunu reddeder — bkz. Yönetilen proxy.

Sorgu zamanı gömmeleri, bunları gerektiren veya öneren modeller için getirme öneklerini kullanır: nomic-embed-text, qwen3-embedding ve mxbai-embed-large. Belge grupları ham biçimde kalır; dolayısıyla mevcut dizinler için biçim geçişi gerekmez.

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        remote: {          // Default for Ollama. Raise on larger hosts if reindexing is too slow.          nonBatchConcurrency: 1,        },      },    },  },}

Uzak bir gömme ana makinesi için kimlik doğrulamayı o ana makineyle sınırlı tutun:

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        model: "nomic-embed-text",        remote: {          baseUrl: "http://gpu-box.local:11434",          apiKey: "ollama-local",          nonBatchConcurrency: 2,        },      },    },  },}

Ollama varsayılan olarak akış ile araç çağırmayı birlikte destekleyen yerel API'yi (/api/chat) kullanır — özel bir yapılandırma gerekmez.

Yerel isteklerde düşünme denetimi doğrudan iletilir: açık bir params.think/params.thinking yapılandırılmamışsa /think off ve openclaw agent --thinking off, üst düzey think: false gönderir; /think low|medium|high eşleşen efor dizesini gönderir; /think max, Ollama'nın en yüksek eforu olan think: "high" değerine eşlenir.

NVIDIA/CUDA kullanılan WSL2'de resmi Ollama Linux yükleyicisi, Restart=always ayarlı bir ollama.service systemd birimi oluşturur. Bu hizmet otomatik olarak başlar ve WSL2 önyüklemesi sırasında GPU destekli bir model yüklerse Ollama yükleme sırasında ana makine belleğini sabitleyebilir; Hyper-V bellek geri kazanımı bu sayfaları her zaman geri alamaz. Bunun sonucunda Windows, WSL2 sanal makinesini sonlandırabilir, systemd Ollama'yı yeniden başlatır ve döngü tekrarlanır.

Kanıtlar: tekrarlanan WSL2 yeniden başlatmaları/sonlandırmaları, WSL2 başlatıldıktan hemen sonra app.slice veya ollama.service içinde yüksek CPU kullanımı ve Linux OOM sonlandırıcısı yerine systemd kaynaklı SIGTERM.

OpenClaw; WSL2'yi, Restart=always ile etkinleştirilmiş ollama.service hizmetini ve görünür CUDA işaretlerini algıladığında başlangıçta bir uyarı kaydeder.

Geçici çözüm:

sudo systemctl disable ollama

Windows tarafında %USERPROFILE%\.wslconfig dosyasına şunu ekleyin, ardından wsl --shutdown komutunu çalıştırın:

[experimental]autoMemoryReclaim=disabled

Alternatif olarak canlı tutma süresini kısaltın veya Ollama'yı yalnızca gerektiğinde elle başlatın:

export OLLAMA_KEEP_ALIVE=5mollama serve

Bkz. ollama/ollama#11317.

Ollama'nın çalıştığını, OLLAMA_API_KEY değerinin (veya bir kimlik doğrulama profilinin) ayarlandığını ve models.providers.ollama değerinin açıkça tanımlanmadığını doğrulayın:

ollama servecurl http://localhost:11434/api/tags

Modeli yerel olarak indirin veya models.providers.ollama içinde açıkça tanımlayın:

ollama list  # See what's installedollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Or another model

Gateway'i çalıştıran aynı makine ve çalışma zamanından doğrulayın:

openclaw gateway status --deepcurl http://ollama-host:11434/api/tags

Yaygın nedenler:

• baseUrl, localhost değerini gösteriyor ancak Gateway Docker içinde veya başka bir ana makinede çalışıyor.
• URL, yerel Ollama davranışı yerine OpenAI uyumlu davranışı seçen /v1 yolunu kullanıyor.
• Uzak ana makinede güvenlik duvarı veya LAN bağlama değişiklikleri gerekiyor.
• Model dizüstü bilgisayarınızdaki arka plan programında bulunuyor ancak uzak arka plan programında bulunmuyor.

Genellikle sağlayıcı OpenAI uyumlu moddadır veya model araç şemalarını işleyemiyordur. Yerel modu tercih edin:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434",        api: "ollama",      },    },  },}

Küçük bir yerel model araç şemalarında hâlâ başarısız oluyorsa o model girdisinde compat.supportsTools: false ayarlayın ve yeniden test edin.

Uzun ve dilsel olmayan sembol dizilerinden oluşan barındırılan Kimi/GLM yanıtları başarılı yanıt olarak değil, başarısız sağlayıcı çağrısı olarak değerlendirilir. Böylece bozuk metin oturuma kalıcı olarak yazılmak yerine normal yeniden deneme/geri dönüş/hata işleme devreye girer.

Sorun tekrarlanırsa model adını, geçerli oturum dosyasını ve çalıştırmada Cloud + Local mı yoksa Cloud only mı kullanıldığını kaydedin; ardından yeni bir oturum ve geri dönüş modeli deneyin:

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --jsonopenclaw models set ollama/gemma4

Büyük yerel modellerin ilk yüklemesi uzun sürebilir. Zaman aşımını Ollama sağlayıcısıyla sınırlayın ve isteğe bağlı olarak modeli etkileşimler arasında yüklü tutun:

{  models: {    providers: {      ollama: {        timeoutSeconds: 300,        models: [          {            id: "gemma4:26b",            name: "gemma4:26b",            params: { keep_alive: "15m" },          },        ],      },    },  },}

Ana makinenin bağlantıları kabul etmesi de yavaşsa timeoutSeconds, bu sağlayıcının korumalı bağlantı zaman aşımını da uzatır.

Birçok model, donanımınızın rahatça çalıştırabileceğinden daha büyük bağlamların desteklendiğini belirtir. params.num_ctx ayarlanmadığı sürece yerel Ollama kendi çalışma zamanı varsayılanını kullanır. Öngörülebilir ilk token gecikmesi için hem OpenClaw bütçesini hem de Ollama istek bağlamını sınırlayın:

{  models: {    providers: {      ollama: {        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            params: { num_ctx: 32768, thinking: false },          },        ],      },    },  },}

OpenClaw çok fazla istem gönderiyorsa contextWindow değerini düşürün. Ollama'nın çalışma zamanı bağlamı makine için çok büyükse params.num_ctx değerini düşürün. Üretim çok uzun sürüyorsa maxTokens değerini düşürün.