Ollama

Adresy URL Ollama wskazujące local loopback, sieć prywatną, domenę .local lub samą nazwę hosta nie wymagają prawdziwego tokenu okaziciela. OpenClaw używa dla nich znacznika ollama-local.

Publiczne hosty zdalne oraz https://ollama.com wymagają prawdziwych danych uwierzytelniających: OLLAMA_API_KEY, profilu uwierzytelniania lub właściwości apiKey dostawcy. Do bezpośredniego korzystania z usługi hostowanej preferuj dostawcę ollama-cloud.

Niestandardowy dostawca z ustawieniem api: "ollama" podlega tym samym regułom. Na przykład dostawca ollama-remote wskazujący prywatny host w sieci LAN może używać apiKey: "ollama-local"; podagenty rozwiązują ten znacznik za pośrednictwem haka dostawcy Ollama, zamiast traktować go jako brakujące dane uwierzytelniające. agents.defaults.memorySearch.provider może również wskazywać identyfikator niestandardowego dostawcy, aby osadzenia korzystały z tego punktu końcowego Ollama.

Plik auth-profiles.json przechowuje dane uwierzytelniające dla identyfikatora dostawcy; ustawienia punktu końcowego (baseUrl, api, modele, nagłówki, limity czasu) umieść w models.providers.<id>. Starsze płaskie pliki, takie jak { "ollama-windows": { "apiKey": "ollama-local" } }, nie są formatem używanym w czasie działania; polecenie openclaw doctor --fix przepisuje je do kanonicznego profilu klucza API ollama-windows:default, tworząc kopię zapasową. Wartość baseUrl w takim starszym pliku jest zbędna i powinna zostać przeniesiona do konfiguracji dostawcy.

Uwierzytelnianie okazicielem dla osadzeń pamięci Ollama jest ograniczone do hosta, dla którego je zadeklarowano:

• Klucz na poziomie dostawcy jest wysyłany wyłącznie do hosta tego dostawcy.
• agents.*.memorySearch.remote.apiKey jest wysyłany wyłącznie do zdalnego hosta osadzeń.
• Sama wartość zmiennej środowiskowej OLLAMA_API_KEY jest traktowana zgodnie z konwencją Ollama Cloud i domyślnie nie jest wysyłana do hostów lokalnych ani samodzielnie hostowanych.

Ollama na tej samej maszynie co Gateway, wykrywana automatycznie:

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

Nie dodawaj bloku models.providers.ollama, chyba że potrzebujesz modeli definiowanych ręcznie.

{  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 to budżet kontekstu OpenClaw; params.num_ctx jest wysyłane do Ollama. Zachowaj zgodność tych wartości, gdy sprzęt nie jest w stanie obsłużyć pełnego deklarowanego kontekstu modelu.

Bez lokalnego demona, bezpośrednio hostowane modele:

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

Aby zamiast tej struktury użyć dedykowanego identyfikatora dostawcy ollama-cloud, zobacz Ollama Cloud.

Niestandardowe identyfikatory dostawców przy uruchamianiu więcej niż jednego serwera Ollama; każdy ma własny host, modele, uwierzytelnianie i limit czasu.

{  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 usuwa prefiks aktywnego dostawcy (w razie potrzeby używając samego prefiksu ollama/) przed wywołaniem Ollama, dlatego ollama-large/qwen3.5:27b trafia do Ollama jako qwen3.5:27b.

Niektóre modele lokalne radzą sobie z prostymi poleceniami, ale mają trudności z pełnym zestawem narzędzi agenta. Ogranicz narzędzia i kontekst przed zmianą globalnych ustawień środowiska wykonawczego:

{  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 },          },        ],      },    },  },}

Używaj compat.supportsTools: false tylko wtedy, gdy model lub serwer niezawodnie zawodzi przy schematach narzędzi — oznacza to rezygnację z części możliwości agenta na rzecz stabilności. localModelLean usuwa z bezpośredniego zestawu narzędzi agenta rozbudowane narzędzia przeglądarki, Cron, wiadomości, generowania multimediów, obsługi głosu i plików PDF, chyba że są wyraźnie wymagane, a większe katalogi umieszcza za wyszukiwaniem narzędzi. Nie zmienia kontekstu środowiska wykonawczego ani trybu rozumowania Ollama. W przypadku małych modeli rozumujących w stylu Qwen, które wpadają w pętle lub zużywają budżet na ukryte rozumowanie, połącz tę opcję z params.num_ctx i params.thinking: false.

Ustaw jawnie api: "openai-completions" dla serwera proxy dostępnego za /v1/chat/completions:

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

Ten tryb może nie obsługiwać jednocześnie strumieniowania i wywoływania narzędzi; może być konieczne ustawienie params: { streaming: false } w modelu.

OpenClaw domyślnie wstrzykuje w tym trybie options.num_ctx, aby Ollama nie przechodziła bez ostrzeżenia do kontekstu o długości 4096 tokenów. Jeśli serwer proxy odrzuca nieznane pola options, wyłącz tę funkcję:

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

W przypadku automatycznie wykrytych modeli OpenClaw używa okna kontekstu zgłaszanego przez /api/show, w tym większych wartości PARAMETER num_ctx z niestandardowych plików Modelfile; w przeciwnym razie używa domyślnego okna kontekstu Ollama w OpenClaw.

Opcje contextWindow, contextTokens i maxTokens na poziomie dostawcy ustawiają wartości domyślne dla każdego modelu tego dostawcy i mogą być nadpisane osobno dla każdego modelu. contextWindow jest własnym budżetem polecenia/Compaction OpenClaw. Natywne żądania /api/chat pozostawiają options.num_ctx bez ustawienia, chyba że jawnie ustawisz params.num_ctx, dzięki czemu Ollama stosuje własną wartość domyślną modelu, OLLAMA_CONTEXT_LENGTH lub wartość zależną od pamięci VRAM; nieprawidłowe, zerowe, ujemne lub nieskończone wartości params.num_ctx są ignorowane. Jeśli starsza konfiguracja używała tylko contextWindow/maxTokens do wymuszania kontekstu natywnego żądania, uruchom openclaw doctor --fix, aby skopiować te wartości do params.num_ctx. Adapter zgodny z OpenAI nadal domyślnie wstrzykuje options.num_ctx ze skonfigurowanego params.num_ctx lub contextWindow; wyłącz to za pomocą injectNumCtxForOpenAICompat: false, jeśli system nadrzędny odrzuca options.

Natywne wpisy modeli przyjmują również typowe opcje środowiska wykonawczego Ollama w params, przekazywane jako natywne options żądania /api/chat: 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 i num_thread. Kilka kluczy (format, keep_alive, truncate, shift) jest przekazywanych jako pola żądania najwyższego poziomu zamiast zagnieżdżonych options. OpenClaw przekazuje tylko te klucze żądań Ollama, dlatego parametry dotyczące wyłącznie środowiska wykonawczego, takie jak streaming, nigdy nie są wysyłane do Ollama. Użyj params.think (lub params.thinking), aby ustawić think najwyższego poziomu; false wyłącza rozumowanie na poziomie API w modelach rozumujących w stylu Qwen.

{  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,            },          }        ]      }    }  }}

Opcja agents.defaults.models["ollama/<model>"].params.num_ctx dla poszczególnych modeli również działa; jawny wpis modelu dostawcy ma pierwszeństwo, jeśli ustawiono obie opcje.

OpenClaw przekazuje ustawienie rozumowania w sposób oczekiwany przez Ollama: jako think najwyższego poziomu, a nie options.think. Automatycznie wykryte modele, dla których /api/show zgłasza możliwość thinking, udostępniają /think low, /think medium, /think high i /think max; modele bez rozumowania udostępniają tylko /think off.

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

Możesz też ustawić wartość domyślną modelu:

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

Parametry params.think/params.thinking poszczególnych modeli mogą wyłączyć lub wymusić myślenie API dla konkretnego modelu. OpenClaw zachowuje tę jawną konfigurację, gdy aktywne uruchomienie ma tylko domyślną, niejawną wartość off; polecenie środowiska uruchomieniowego z wartością inną niż off, takie jak /think medium, nadal ma nad nią pierwszeństwo. Żądanie myślenia o wartości prawdziwej nigdy nie jest wysyłane do modelu jawnie oznaczonego jako reasoning: false; żądanie think: false jest zawsze wysyłane niezależnie od tego ustawienia.

Modele o nazwach deepseek-r1, reasoning, reason lub think są domyślnie traktowane jako zdolne do rozumowania — nie jest wymagana dodatkowa konfiguracja:

ollama pull deepseek-r1:32b

Ollama działa lokalnie i jest bezpłatna, dlatego wszystkie koszty modeli wynoszą 0 zarówno dla modeli wykrytych automatycznie, jak i zdefiniowanych ręcznie.

Dołączony plugin Ollama rejestruje dostawcę osadzeń pamięci dla wyszukiwania w pamięci. Używa skonfigurowanego bazowego adresu URL Ollama i klucza API, wywołuje /api/embed oraz, gdy jest to możliwe, grupuje wiele fragmentów pamięci w jedno żądanie input.

Gdy proxy.enabled=true, żądania osadzeń kierowane dokładnie do lokalnego względem hosta źródła local loopback wyprowadzonego ze skonfigurowanego baseUrl korzystają z chronionej ścieżki bezpośredniej OpenClaw zamiast zarządzanego pośredniczącego serwera proxy. Skonfigurowana nazwa hosta musi sama być wartością localhost lub literałem adresu IP pętli zwrotnej — nazwy DNS, które jedynie wskazują na pętlę zwrotną, nadal korzystają z zarządzanej ścieżki proxy. Hosty Ollama w sieci LAN, tailnecie, sieci prywatnej i sieci publicznej zawsze pozostają na zarządzanej ścieżce proxy, a przekierowania do innego hosta lub portu nie dziedziczą zaufania. proxy.loopbackMode: "proxy" mimo to kieruje ruch pętli zwrotnej przez proxy; proxy.loopbackMode: "block" odrzuca go przed nawiązaniem połączenia — zobacz Zarządzane proxy.

Osadzenia wykonywane podczas zapytania używają prefiksów wyszukiwania w przypadku modeli, które ich wymagają lub je zalecają: nomic-embed-text, qwen3-embedding oraz mxbai-embed-large. Partie dokumentów pozostają niezmienione, więc istniejące indeksy nie wymagają migracji formatu.

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        remote: {          // Domyślna wartość dla Ollama. Zwiększ ją na wydajniejszych hostach, jeśli ponowne indeksowanie jest zbyt wolne.          nonBatchConcurrency: 1,        },      },    },  },}

W przypadku zdalnego hosta osadzeń ogranicz zakres uwierzytelniania do tego hosta:

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

Ollama domyślnie używa natywnego API (/api/chat), które obsługuje jednocześnie przesyłanie strumieniowe i wywoływanie narzędzi — nie jest wymagana specjalna konfiguracja.

W przypadku żądań natywnych sterowanie myśleniem jest przekazywane bezpośrednio: /think off i openclaw agent --thinking off wysyłają parametr najwyższego poziomu think: false, chyba że skonfigurowano jawną wartość params.think/params.thinking; /think low|medium|high wysyła odpowiadający ciąg poziomu intensywności; /think max jest mapowane na najwyższy poziom intensywności Ollama, think: "high".

W WSL2 z NVIDIA/CUDA oficjalny instalator Ollama dla systemu Linux tworzy jednostkę systemd ollama.service z ustawieniem Restart=always. Jeśli ta usługa uruchamia się automatycznie i ładuje model korzystający z GPU podczas rozruchu WSL2, Ollama może blokować pamięć hosta podczas ładowania; mechanizm odzyskiwania pamięci Hyper-V nie zawsze może odzyskać te strony, więc Windows może zakończyć maszynę wirtualną WSL2, systemd ponownie uruchamia Ollama i pętla się powtarza.

Symptomy: powtarzające się ponowne uruchomienia lub zakończenia WSL2, wysokie użycie procesora przez app.slice albo ollama.service bezpośrednio po uruchomieniu WSL2 oraz sygnał SIGTERM od systemd, a nie od mechanizmu OOM systemu Linux.

OpenClaw rejestruje ostrzeżenie podczas uruchamiania, gdy wykryje WSL2, włączoną usługę ollama.service z ustawieniem Restart=always oraz widoczne znaczniki CUDA.

Sposób ograniczenia problemu:

sudo systemctl disable ollama

Po stronie Windows dodaj poniższy wpis do %USERPROFILE%\.wslconfig, a następnie uruchom wsl --shutdown:

[experimental]autoMemoryReclaim=disabled

Możesz też skrócić czas utrzymywania aktywności lub uruchamiać Ollama ręcznie tylko wtedy, gdy jest potrzebna:

export OLLAMA_KEEP_ALIVE=5mollama serve

Zobacz ollama/ollama#11317.

Sprawdź, czy Ollama jest uruchomiona, ustawiono OLLAMA_API_KEY (lub profil uwierzytelniania), a models.providers.ollama nie jest zdefiniowane jawnie:

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

Pobierz model lokalnie lub zdefiniuj go jawnie w models.providers.ollama:

ollama list  # Sprawdź, co jest zainstalowaneollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Lub inny model

Sprawdź z tej samej maszyny i w tym samym środowisku uruchomieniowym, w którym działa Gateway:

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

Typowe przyczyny:

• baseUrl wskazuje na localhost, ale Gateway działa w Dockerze lub na innym hoście.
• Adres URL zawiera /v1, co wybiera zachowanie zgodne z OpenAI zamiast natywnego trybu Ollama.
• Zdalny host wymaga zmian zapory sieciowej lub powiązania z siecią LAN.
• Model znajduje się w demonie na laptopie, ale nie na hoście zdalnym.

Zwykle dostawca działa w trybie zgodności z OpenAI albo model nie potrafi obsługiwać schematów narzędzi. Preferuj tryb natywny:

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

Jeśli mały model lokalny nadal nie radzi sobie ze schematami narzędzi, ustaw compat.supportsTools: false we wpisie tego modelu i przeprowadź test ponownie.

Hostowane odpowiedzi Kimi/GLM składające się z długich, nielingwistycznych ciągów symboli są traktowane jako nieudane wywołanie dostawcy, a nie pomyślna odpowiedź, dzięki czemu uruchamiana jest standardowa obsługa ponowień, modeli rezerwowych lub błędów zamiast zapisywania uszkodzonego tekstu w sesji.

Jeśli problem wystąpi ponownie, zapisz nazwę modelu, bieżący plik sesji oraz informację, czy uruchomienie używało trybu Cloud + Local, czy Cloud only, a następnie wypróbuj nową sesję i model rezerwowy:

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

Duże modele lokalne mogą wymagać dużo czasu przy pierwszym ładowaniu. Ogranicz zakres limitu czasu do dostawcy Ollama i opcjonalnie pozostaw model załadowany między turami:

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

Jeśli sam host wolno akceptuje połączenia, timeoutSeconds wydłuża również chroniony limit czasu nawiązania połączenia dla tego dostawcy.

Wiele modeli deklaruje konteksty większe, niż sprzęt jest w stanie komfortowo obsłużyć. Natywny tryb Ollama używa własnej wartości domyślnej środowiska uruchomieniowego, chyba że ustawiono params.num_ctx. Ogranicz zarówno budżet OpenClaw, jak i kontekst żądania Ollama, aby uzyskać przewidywalne opóźnienie pierwszego tokena:

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

Zmniejsz contextWindow, jeśli OpenClaw wysyła zbyt długi prompt. Zmniejsz params.num_ctx, jeśli kontekst środowiska uruchomieniowego Ollama jest zbyt duży dla tej maszyny. Zmniejsz maxTokens, jeśli generowanie trwa zbyt długo.