Ollama

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

Publiczne hosty zdalne i https://ollama.com wymagają prawdziwych danych uwierzytelniających: OLLAMA_API_KEY, profilu uwierzytelniania lub wartości apiKey dostawcy. Do bezpośredniego korzystania z usługi hostowanej zalecany jest dostawca ollama-cloud.

Niestandardowy dostawca z 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"; subagenty 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ć niestandardowy identyfikator dostawcy, dzięki czemu osadzenia korzystają z tego punktu końcowego Ollama.

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

Uwierzytelnianie bearer dla osadzeń pamięci Ollama jest ograniczone do hosta, dla którego zostało zadeklarowane:

• 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ść środowiskowa OLLAMA_API_KEY jest traktowana zgodnie z konwencją Ollama Cloud i domyślnie nie jest wysyłana do hostów lokalnych ani hostowanych samodzielnie.

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 potrzebne są modele ręczne.

{  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 określa budżet kontekstu OpenClaw; params.num_ctx jest wysyłane do Ollama. Zachowaj ich zgodność, jeśli 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" },    },  },}

Dla dedykowanego identyfikatora dostawcy ollama-cloud zamiast tej struktury zobacz Ollama Cloud.

Niestandardowe identyfikatory dostawców podczas uruchamiania więcej niż jednego serwera Ollama; każdy otrzymuje 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 dociera do Ollama jako qwen3.5:27b.

Niektóre modele lokalne radzą sobie z prostymi poleceniami, ale mają problemy z pełnym zestawem narzędzi agenta. Przed zmianą globalnych ustawień środowiska uruchomieniowego ogranicz narzędzia i kontekst:

{  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 na schematach narzędzi — odbywa się to kosztem możliwości agenta na rzecz stabilności. localModelLean usuwa rozbudowane narzędzia przeglądarki, cron, wiadomości, generowania multimediów, głosu i plików PDF z bezpośredniego zestawu narzędzi agenta, chyba że są jawnie wymagane, oraz umieszcza większe katalogi za Tool Search. Nie zmienia kontekstu środowiska uruchomieniowego Ollama ani trybu myślenia. Połącz tę opcję z params.num_ctx i params.thinking: false w przypadku małych modeli myślących w stylu Qwen, które wpadają w pętle lub zużywają swój budżet na ukryte rozumowanie.

Ustaw api: "openai-completions" jawnie dla serwera proxy działającego za /v1/chat/completions:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: true, // wartość domyślna: 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 } dla modelu.

OpenClaw domyślnie wstrzykuje options.num_ctx w tym trybie, aby Ollama nie przełączała się po cichu na kontekst 4096 tokenów. Jeśli serwer proxy odrzuca nieznane pola options, wyłącz tę opcję:

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

W przypadku modeli wykrytych automatycznie 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 skonfigurowanego w OpenClaw.

Ustawienia contextWindow, contextTokens i maxTokens na poziomie dostawcy określają wartości domyślne dla każdego modelu tego dostawcy i można je zastąpić osobno dla modelu. contextWindow jest własnym budżetem poleceń/Compaction OpenClaw. Natywne żądania /api/chat pozostawiają options.num_ctx bez wartości, chyba że params.num_ctx zostanie ustawione jawnie, dzięki czemu Ollama stosuje własną wartość domyślną modelu, OLLAMA_CONTEXT_LENGTH lub opartą na 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ć je do params.num_ctx. Adapter zgodny z OpenAI nadal domyślnie wstrzykuje options.num_ctx na podstawie skonfigurowanego params.num_ctx lub contextWindow; wyłącz tę funkcję za pomocą injectNumCtxForOpenAICompat: false, jeśli system nadrzędny odrzuca options.

Natywne wpisy modeli akceptują również typowe opcje środowiska uruchomieniowego Ollama w params, przekazywane jako natywne /api/chat options: 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żonego options. OpenClaw przekazuje tylko te klucze żądań Ollama, dlatego parametry dotyczące wyłącznie środowiska uruchomieniowego, 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 myślenie na poziomie API w modelach myślą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,            },          }        ]      }    }  }}

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

OpenClaw przekazuje ustawienie myślenia 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 myślenia udostępniają tylko /think off.

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

Lub ustaw domyślny model:

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

Ustawienia params.think/params.thinking dla poszczególnych modeli mogą wyłączyć lub wymusić myślenie API dla konkretnego modelu. OpenClaw zachowuje tę jawną konfigurację, gdy aktywne uruchomienie ma tylko niejawne ustawienie domyślne off; polecenie środowiska wykonawczego inne niż wyłączające, takie jak /think medium, nadal ją zastępuje. Żądanie myślenia o wartości logicznej prawda nigdy nie jest wysyłane do modelu jawnie oznaczonego jako reasoning: false; żądanie think: false jest zawsze wysyłane niezależnie od tego.

Modele o nazwach deepseek-r1, reasoning, reason lub think są domyślnie traktowane jako obsługujące rozumowanie — dodatkowa konfiguracja nie jest potrzebna:

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 i klucza API Ollama, wywołuje /api/embed oraz, gdy jest to możliwe, grupuje wiele fragmentów pamięci w jednym żądaniu input.

Gdy ustawiono proxy.enabled=true, żądania osadzeń kierowane dokładnie do lokalnego źródła pętli zwrotnej hosta, wyprowadzonego ze skonfigurowanej wartości baseUrl, używają chronionej ścieżki bezpośredniej OpenClaw zamiast zarządzanego serwera proxy przekazującego. Skonfigurowana nazwa hosta musi sama być wartością localhost lub literałem adresu IP pętli zwrotnej — nazwy DNS, które jedynie są rozwiązywane na adres pętli zwrotnej, nadal używają zarządzanej ścieżki proxy. Hosty Ollama w sieci LAN, tailnet, sieci prywatnej i 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ądzany serwer 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: {          // Wartość domyślna dla Ollama. Zwiększ na większych hostach, jeśli ponowne indeksowanie jest zbyt wolne.          nonBatchConcurrency: 1,        },      },    },  },}

W przypadku zdalnego hosta osadzeń ogranicz uwierzytelnianie 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 jednocześnie obsługuje strumieniowanie i wywoływanie narzędzi — specjalna konfiguracja nie jest potrzebna.

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

W systemie 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 uruchamiania WSL2, Ollama może zablokować 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 uruchomi Ollama, a pętla się powtórzy.

Symptomy: wielokrotne ponowne uruchomienia lub zakończenia WSL2, wysokie użycie CPU przez app.slice albo ollama.service bezpośrednio po uruchomieniu WSL2 oraz sygnał SIGTERM od systemd, a nie od mechanizmu Linux OOM killer.

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

Obejście:

sudo systemctl disable ollama

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

[experimental]autoMemoryReclaim=disabled

Można też skrócić czas utrzymywania aktywności lub uruchamiać Ollama ręcznie tylko w razie potrzeby:

export OLLAMA_KEEP_ALIVE=5mollama serve

Zobacz ollama/ollama#11317.

Upewnij się, że Ollama działa, ustawiono OLLAMA_API_KEY (lub profil uwierzytelniania), a models.providers.ollama nie zdefiniowano jawnie:

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

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

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

Sprawdź na tej samej maszynie i w tym samym środowisku wykonawczym, 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 używa /v1, wybierając zachowanie zgodne z OpenAI zamiast natywnego zachowania Ollama.
• Zdalny host wymaga zmian zapory lub powiązania z siecią LAN.
• Model znajduje się w demonie na laptopie, ale nie w zdalnym demonie.

Zwykle dostawca działa w trybie zgodnym z OpenAI albo model nie potrafi obsługiwać schematów narzędzi. Preferowany jest tryb natywny:

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

Jeśli mały model lokalny nadal nie obsługuje schematów narzędzi, ustaw compat.supportsTools: false we wpisie tego modelu i przeprowadź test ponownie.

Hostowane odpowiedzi Kimi/GLM będące długimi ciągami symboli bez znaczenia językowego są traktowane jako nieudane wywołanie dostawcy, a nie pomyślna odpowiedź, dzięki czemu zamiast utrwalenia uszkodzonego tekstu w sesji uruchamiana jest standardowa obsługa ponawiania prób, przełączania awaryjnego lub błędów.

Jeśli problem się powtórzy, zapisz nazwę modelu, bieżący plik sesji i informację, czy uruchomienie używało Cloud + Local, czy Cloud only, a następnie wypróbuj nową sesję i model zapasowy:

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Odpowiedz dokładnie: ok" --jsonopenclaw models set ollama/gemma4

Duże modele lokalne mogą wymagać długiego czasu pierwszego ładowania. Ogranicz zakres limitu czasu do dostawcy Ollama i opcjonalnie pozostaw model załadowany pomię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 również wydłuża chroniony limit czasu nawiązywania połączenia dla tego dostawcy.

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

{  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 wykonawczego Ollama jest zbyt duży dla tej maszyny. Zmniejsz maxTokens, jeśli generowanie trwa zbyt długo.