Ollama

Yerel ve LAN Ollama ana makineleri gerçek bir bearer token gerektirmez. OpenClaw, yerel ollama-local işaretçisini yalnızca loopback, özel ağ, .local ve yalın ana makine adlı Ollama temel URL'leri için kullanır.

Uzak genel ana makineler ve Ollama Cloud (https://ollama.com), OLLAMA_API_KEY, bir kimlik doğrulama profili veya sağlayıcının apiKey değeri üzerinden gerçek bir kimlik bilgisi gerektirir.

api: "ollama" ayarlayan özel sağlayıcı kimlikleri aynı kuralları izler. Örneğin, özel bir LAN Ollama ana makinesini işaret eden bir ollama-remote sağlayıcısı apiKey: "ollama-local" kullanabilir ve alt ajanlar, bunu eksik bir kimlik bilgisi olarak ele almak yerine Ollama sağlayıcı kancası üzerinden çözer. Bellek araması da agents.defaults.memorySearch.provider değerini bu özel sağlayıcı kimliğine ayarlayabilir; böylece embedding'ler eşleşen Ollama uç noktasını kullanır.

auth-profiles.json, bir sağlayıcı kimliği için kimlik bilgisini depolar. Uç nokta ayarlarını (baseUrl, api, model kimlikleri, üstbilgiler, zaman aşımları) models.providers.<id> içine koyun. { "ollama-windows": { "apiKey": "ollama-local" } } gibi eski düz kimlik doğrulama profili dosyaları bir çalışma zamanı biçimi değildir; bunları yedekle birlikte kanonik ollama-windows:default API anahtarı profiline yeniden yazmak için openclaw doctor --fix çalıştırın. Bu dosyadaki baseUrl uyumluluk gürültüsüdür ve sağlayıcı yapılandırmasına taşınmalıdır.

Ollama bellek embedding'leri için kullanıldığında, bearer kimlik doğrulaması bildirildiği ana makineyle sınırlıdır:

• Sağlayıcı düzeyindeki anahtar yalnızca o sağlayıcının Ollama ana makinesine gönderilir.
• agents.*.memorySearch.remote.apiKey yalnızca kendi uzak embedding ana makinesine gönderilir.
• Saf bir OLLAMA_API_KEY ortam değeri, Ollama Cloud kuralı olarak ele alınır; varsayılan olarak yerel veya kendi barındırdığınız ana makinelere gönderilmez.

Ollama Gateway ile aynı makinede çalıştığında ve OpenClaw’ın kurulu modelleri otomatik olarak keşfetmesini istediğinizde bunu kullanın.

ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4

Bu yol yapılandırmayı en az düzeyde tutar. Modelleri elle tanımlamak istemediğiniz sürece bir models.providers.ollama bloğu eklemeyin.

LAN host’ları için yerel Ollama URL’leri kullanın. /v1 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 tarafındaki bağlam bütçesidir. params.num_ctx, istek için Ollama’ya gönderilir. Donanımınız modelin duyurulan tam bağlamını çalıştıramadığında bunları uyumlu tutun.

Yerel daemon çalıştırmadığınızda ve barındırılan Ollama modellerini doğrudan istediğinizde bunu kullanın.

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

Yerel veya LAN Ollama daemon’u ollama signin ile oturum açmışsa ve hem yerel modelleri hem de :cloud modellerini sunması gerekiyorsa bunu kullanın.

ollama signin
ollama pull gemma4

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        models: [
          { id: "gemma4", name: "gemma4", input: ["text"] },
          { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text", "image"] },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama/gemma4",
        fallbacks: ["ollama/kimi-k2.5:cloud"],
      },
    },
  },
}

Birden fazla Ollama sunucunuz olduğunda özel sağlayıcı kimlikleri kullanın. Her sağlayıcının kendi host’u, modelleri, kimlik doğrulaması, zaman aşımı ve model başvuruları olur.

{
  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 isteği gönderdiğinde etkin sağlayıcı öneki kaldırılır; böylece ollama-large/qwen3.5:27b, Ollama’ya qwen3.5:27b olarak ulaşır.

Bazı yerel modeller basit prompt’ları yanıtlayabilir ancak tam agent araç yüzeyiyle zorlanabilir. Küresel çalışma zamanı ayarlarını değiştirmeden önce araçları ve bağlamı sınırlayarak başlayın.

{
  agents: {
    defaults: {
      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 yalnızca model veya sunucu araç şemalarında güvenilir biçimde başarısız olduğunda kullanın. Bu, kararlılık karşılığında ajan yeteneğinden ödün verir. localModelLean, tarayıcı, cron ve mesaj araçlarını ajan yüzeyinden kaldırır, ancak Ollama'nın çalışma zamanı bağlamını veya düşünme modunu değiştirmez. Döngüye giren ya da yanıt bütçesini gizli akıl yürütmeye harcayan küçük Qwen tarzı düşünme modelleri için bunu açık params.num_ctx ve params.thinking: false ile eşleştirin.

Bunun yerine OpenAI uyumlu uç noktayı kullanmanız gerekiyorsa (örneğin yalnızca OpenAI biçimini destekleyen bir proxy arkasında), 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. Model yapılandırmasında params: { streaming: false } ile akışı devre dışı bırakmanız gerekebilir.

Ollama ile api: "openai-completions" kullanıldığında OpenClaw varsayılan olarak options.num_ctx enjekte eder, böylece Ollama sessizce 4096 bağlam penceresine geri dönmez. Proxy'niz/yukarı akışınız bilinmeyen options alanlarını reddediyorsa bu davranışı 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 modeller için OpenClaw, mevcut olduğunda özel Modelfile'lardan gelen daha büyük PARAMETER num_ctx değerleri dahil olmak üzere Ollama tarafından bildirilen bağlam penceresini kullanır. Aksi halde OpenClaw tarafından kullanılan varsayılan Ollama bağlam penceresine geri döner.

O Ollama sağlayıcısı altındaki her model için sağlayıcı düzeyinde contextWindow, contextTokens ve maxTokens varsayılanlarını ayarlayabilir, ardından gerektiğinde model başına bunları geçersiz kılabilirsiniz. contextWindow, OpenClaw'ın istem ve Compaction bütçesidir. Yerel Ollama istekleri, params.num_ctx değerini açıkça yapılandırmadığınız sürece options.num_ctx alanını ayarlamaz; böylece Ollama kendi modelini, OLLAMA_CONTEXT_LENGTH değerini veya VRAM tabanlı varsayılanını uygulayabilir. Bir Modelfile'ı yeniden oluşturmadan Ollama'nın istek başına çalışma zamanı bağlamını sınırlamak veya zorlamak için params.num_ctx ayarlayın; geçersiz, sıfır, negatif ve sonlu olmayan değerler yok sayılır. OpenAI uyumlu Ollama bağdaştırıcısı, varsayılan olarak yapılandırılmış params.num_ctx veya contextWindow değerinden options.num_ctx enjekte etmeye devam eder; yukarı akışınız options değerini reddediyorsa bunu injectNumCtxForOpenAICompat: false ile devre dışı bırakın.

Yerel Ollama model girdileri ayrıca params altında temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread ve use_mmap dahil ortak Ollama çalışma zamanı seçeneklerini kabul eder. OpenClaw yalnızca Ollama istek anahtarlarını iletir, bu nedenle streaming gibi OpenClaw çalışma zamanı parametreleri Ollama'ya sızdırılmaz. Üst düzey Ollama think göndermek için params.think veya params.thinking kullanın; false, Qwen tarzı düşünme modelleri için API düzeyinde 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. İkisi de yapılandırılmışsa, açık sağlayıcı model girdisi ajan varsayılanına göre önceliklidir.

Yerel Ollama modelleri için OpenClaw düşünme denetimini Ollama'nın beklediği şekilde iletir: options.think değil, üst düzey think. /api/show yanıtı thinking yeteneğini içeren otomatik keşfedilen modeller /think low, /think medium, /think high ve /think max sunar; düşünmeyen modeller yalnızca /think off sunar.

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

Ayrıca bir model varsayılanı da ayarlayabilirsiniz:

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

Model başına params.think veya params.thinking, belirli bir yapılandırılmış model için Ollama API düşünmesini devre dışı bırakabilir ya da zorlayabilir. Etkin çalıştırmada yalnızca örtük varsayılan off olduğunda OpenClaw bu açık model parametrelerini korur; /think medium gibi off dışı çalışma zamanı komutları yine de etkin çalıştırmayı geçersiz kılar.

OpenClaw, deepseek-r1, reasoning veya think gibi adlara sahip modelleri varsayılan olarak akıl yürütme yetenekli kabul eder.

ollama pull deepseek-r1:32b

Ek yapılandırma gerekmez. OpenClaw bunları otomatik olarak işaretler.

Ollama ücretsizdir ve yerel olarak çalışır, bu nedenle tüm model maliyetleri $0 olarak ayarlanır. Bu, hem otomatik keşfedilen hem de elle tanımlanan modellere uygulanır.

Paketlenmiş 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, Ollama'nın mevcut /api/embed uç noktasını çağırır ve mümkün olduğunda birden fazla bellek parçasını tek bir input isteğinde toplu işler.

Sorgu zamanı gömmeleri, nomic-embed-text, qwen3-embedding ve mxbai-embed-large dahil bunları gerektiren veya öneren modeller için alma öneklerini kullanır. Mevcut dizinlerin biçim geçişine ihtiyaç duymaması için bellek belge toplu işlemleri ham kalır.

Bellek araması gömme sağlayıcısı olarak Ollama'yı seçmek için:

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

Uzak 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,
        },
      },
    },
  },
}

OpenClaw'ın Ollama entegrasyonu varsayılan olarak yerel Ollama API (/api/chat) kullanır; bu API akışı ve araç çağırmayı aynı anda tam olarak destekler. Özel yapılandırma gerekmez.

Yerel /api/chat istekleri için OpenClaw düşünme denetimini de doğrudan Ollama'ya iletir: /think off ve openclaw agent --thinking off, açık bir model params.think/params.thinking değeri yapılandırılmadığı sürece üst düzey think: false gönderir; /think low|medium|high ise eşleşen üst düzey think çaba dizesini gönderir. /think max, Ollama'nın en yüksek yerel çabasına, yani think: "high" değerine eşlenir.

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

Yaygın kanıtlar:

• Windows tarafından tekrarlanan WSL2 yeniden başlatmaları veya sonlandırmaları
• WSL2 başlangıcından kısa süre sonra app.slice veya ollama.service içinde yüksek CPU kullanımı
• Linux OOM-killer olayı yerine systemd kaynaklı SIGTERM

OpenClaw, WSL2'yi, Restart=always ile etkinleştirilmiş ollama.service birimini ve görünür CUDA işaretçilerini algıladığında başlangıçta bir uyarı günlüğe yazar.

Azaltma:

sudo systemctl disable ollama

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

[experimental]
autoMemoryReclaim=disabled

Ollama hizmet ortamında daha kısa bir canlı tutma süresi ayarlayın veya Ollama'yı yalnızca ihtiyaç duyduğunuzda elle başlatın:

export OLLAMA_KEEP_ALIVE=5m
ollama serve

Bkz. ollama/ollama#11317.

Ollama'nın çalıştığından, OLLAMA_API_KEY değerini (veya bir kimlik doğrulama profili) ayarladığınızdan ve açık bir models.providers.ollama girdisi tanımlamadığınızdan emin olun:

ollama serve

API'nin erişilebilir olduğunu doğrulayın:

curl http://localhost:11434/api/tags

Modeliniz listelenmiyorsa modeli yerel olarak çekin veya models.providers.ollama içinde açıkça tanımlayın.

ollama list  # Nelerin kurulu olduğunu görün
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Veya başka bir model

Ollama'nın doğru bağlantı noktasında çalıştığını kontrol edin:

# Ollama'nın çalışıp çalışmadığını kontrol edin
ps aux | grep ollama

# Veya Ollama'yı yeniden başlatın
ollama serve

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

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

Yaygın nedenler:

• baseUrl, localhost değerini gösterir, ancak Gateway Docker içinde veya başka bir ana makinede çalışır.
• URL /v1 kullanır; bu da yerel Ollama yerine OpenAI uyumlu davranışı seçer.
• Uzak ana makinede Ollama tarafında güvenlik duvarı veya LAN bağlama değişiklikleri gerekir.
• Model dizüstü bilgisayarınızdaki daemon'da vardır ancak uzak daemon'da yoktur.

Bu genellikle sağlayıcının OpenAI uyumlu modu kullandığı veya modelin araç şemalarını işleyemediği anlamına gelir.

Yerel Ollama modunu 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, dilsel olmayan sembol dizilerinden oluşan barındırılan Kimi/GLM yanıtları, başarılı bir asistan yanıtı yerine başarısız sağlayıcı çıktısı olarak değerlendirilir. Bu, bozuk metni oturuma kalıcı olarak yazmadan normal yeniden deneme, fallback veya hata işlemeyi devreye sokar.

Bu durum tekrar tekrar olursa ham model adını, geçerli oturum dosyasını ve çalıştırmanın Cloud + Local mı yoksa Cloud only mi kullandığını yakalayın; ardından yeni bir oturum ve bir fallback model deneyin:

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

Büyük yerel modeller, akış başlamadan önce uzun bir ilk yükleme süresine ihtiyaç duyabilir. Zaman aşımını Ollama sağlayıcısıyla sınırlı tutun ve isteğe bağlı olarak Ollama'dan modeli dönüşler arasında yüklü tutmasını isteyin:

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

Ana makinenin kendisi bağlantıları kabul etmekte yavaşsa, timeoutSeconds bu sağlayıcı için korumalı Undici bağlantı zaman aşımını da uzatır.

Birçok Ollama modeli, donanımınızın rahatça çalıştırabileceğinden daha büyük bağlamlar duyurur. Yerel Ollama, params.num_ctx ayarlamadığınız sürece Ollama'nın kendi çalışma zamanı bağlamı varsayılanını kullanır. Öngörülebilir ilk belirteç gecikmesi istediğinizde hem OpenClaw'ın bütçesini hem de Ollama'nın 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 önce contextWindow değerini düşürün. Ollama makine için çok büyük bir çalışma zamanı bağlamı yüklüyorsa params.num_ctx değerini düşürün. Üretim çok uzun sürüyorsa maxTokens değerini düşürün.