Ollama

Lokalni hostowie Ollama i hostowie w sieci LAN nie potrzebują prawdziwego tokena bearer. OpenClaw używa lokalnego znacznika ollama-local tylko dla adresów URL bazowych Ollama typu local loopback, sieci prywatne, .local i gołe nazwy hostów.

Zdalni publiczni hostowie i Ollama Cloud (https://ollama.com) wymagają prawdziwych danych uwierzytelniających przez OLLAMA_API_KEY, profil uwierzytelniania albo apiKey dostawcy. Do bezpośredniego hostowanego użycia preferuj dostawcę ollama-cloud.

Niestandardowe identyfikatory dostawców, które ustawiają api: "ollama", stosują te same reguły. Na przykład dostawca ollama-remote, który wskazuje prywatnego hosta Ollama w sieci LAN, może używać apiKey: "ollama-local", a podagenci rozwiążą ten znacznik przez hak dostawcy Ollama zamiast traktować go jako brakujące dane uwierzytelniające. Wyszukiwanie w pamięci może też ustawić agents.defaults.memorySearch.provider na ten niestandardowy identyfikator dostawcy, aby embeddingi używały pasującego punktu końcowego Ollama.

auth-profiles.json przechowuje dane uwierzytelniające dla identyfikatora dostawcy. Ustawienia punktu końcowego (baseUrl, api, identyfikatory modeli, nagłówki, limity czasu) umieść w models.providers.<id>. Starsze płaskie pliki profili uwierzytelniania, takie jak { "ollama-windows": { "apiKey": "ollama-local" } }, nie są formatem uruchomieniowym; uruchom openclaw doctor --fix, aby przepisać je do kanonicznego profilu klucza API ollama-windows:default z kopią zapasową. baseUrl w tym pliku jest szumem zgodności i powinien zostać przeniesiony do konfiguracji dostawcy.

Gdy Ollama jest używana do embeddingów pamięci, uwierzytelnianie bearer jest ograniczone do hosta, na którym zostało zadeklarowane:

• Klucz na poziomie dostawcy jest wysyłany tylko do hosta Ollama tego dostawcy.
• agents.*.memorySearch.remote.apiKey jest wysyłany tylko do jego zdalnego hosta embeddingów.
• Czysta wartość środowiskowa OLLAMA_API_KEY jest traktowana jako konwencja Ollama Cloud i domyślnie nie jest wysyłana do hostów lokalnych ani samodzielnie hostowanych.

Użyj tego, gdy Ollama działa na tym samym komputerze co Gateway i chcesz, aby OpenClaw automatycznie wykrył zainstalowane modele.

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

Ta ścieżka ogranicza konfigurację do minimum. Nie dodawaj bloku models.providers.ollama, chyba że chcesz definiować modele ręcznie.

Używaj natywnych adresów URL Ollama dla hostów w sieci LAN. Nie dodawaj /v1.

{  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 po stronie OpenClaw. params.num_ctx jest wysyłane do Ollama dla żądania. Utrzymuj je spójne, gdy Twój sprzęt nie może uruchomić pełnego deklarowanego kontekstu modelu.

Użyj tego, gdy nie uruchamiasz lokalnego demona i chcesz bezpośrednio korzystać z hostowanych modeli Ollama.

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

Użyj tego, gdy lokalny lub sieciowy demon Ollama jest zalogowany przez ollama signin i ma obsługiwać zarówno modele lokalne, jak i modele :cloud.

ollama signinollama 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"],      },    },  },}

Używaj niestandardowych identyfikatorów dostawców, gdy masz więcej niż jeden serwer Ollama. Każdy dostawca otrzymuje własny host, modele, uwierzytelnianie, limit czasu i referencje modeli.

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

Gdy OpenClaw wysyła żądanie, aktywny prefiks dostawcy jest usuwany, więc ollama-large/qwen3.5:27b trafia do Ollama jako qwen3.5:27b.

Niektóre modele lokalne potrafią odpowiadać na proste prompty, ale mają trudności z pełnym zakresem narzędzi agenta. Zacznij od ograniczenia narzędzi i kontekstu, zanim zmienisz globalne ustawienia środowiska uruchomieniowego.

{  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. Zamienia to możliwości agenta na stabilność. localModelLean usuwa narzędzia przeglądarki, Cron i wiadomości z bezpośredniej powierzchni agenta oraz domyślnie umieszcza większe katalogi za ustrukturyzowanymi kontrolkami Tool Search, z wyjątkiem sytuacji, gdy uruchomienie musi zachować semantykę bezpośredniego dostarczania wiadomości, ale nie zmienia kontekstu środowiska uruchomieniowego Ollama ani trybu myślenia. Połącz to z jawnym params.num_ctx i params.thinking: false dla małych modeli myślących w stylu Qwen, które zapętlają się lub zużywają budżet odpowiedzi na ukryte rozumowanie.

Jeśli zamiast tego musisz użyć punktu końcowego zgodnego z OpenAI (na przykład za proxy, które obsługuje tylko format OpenAI), ustaw jawnie api: "openai-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 wyłączenie strumieniowania za pomocą params: { streaming: false } w konfiguracji modelu.

Gdy api: "openai-completions" jest używane z Ollama, OpenClaw domyślnie wstrzykuje options.num_ctx, aby Ollama nie wracała po cichu do okna kontekstu 4096. Jeśli Twoje proxy/upstream odrzuca nieznane pola options, wyłącz to zachowanie:

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

Dla automatycznie wykrytych modeli OpenClaw używa okna kontekstu zgłoszonego przez Ollama, gdy jest dostępne, w tym większych wartości PARAMETER num_ctx z niestandardowych Modelfiles. W przeciwnym razie wraca do domyślnego okna kontekstu Ollama używanego przez OpenClaw.

Możesz ustawić domyślne wartości contextWindow, contextTokens i maxTokens na poziomie providera dla każdego modelu pod tym providerem Ollama, a następnie w razie potrzeby nadpisać je dla konkretnego modelu. contextWindow to budżet promptu i Compaction w OpenClaw. Natywne żądania Ollama pozostawiają options.num_ctx nieustawione, chyba że jawnie skonfigurujesz params.num_ctx, dzięki czemu Ollama może zastosować własny model, OLLAMA_CONTEXT_LENGTH albo domyślną wartość opartą na VRAM. Aby ograniczyć lub wymusić kontekst uruchomieniowy Ollama dla pojedynczego żądania bez przebudowywania Modelfile, ustaw params.num_ctx; wartości nieprawidłowe, zerowe, ujemne i nieskończone są ignorowane. Jeśli zaktualizowano starszą konfigurację, która używała tylko contextWindow lub maxTokens, aby wymusić kontekst natywnego żądania Ollama, uruchom openclaw doctor --fix, aby skopiować te jawne budżety providera lub modelu do params.num_ctx. Adapter Ollama 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 upstream odrzuca options.

Wpisy natywnych modeli Ollama akceptują też wspólne opcje uruchomieniowe Ollama pod params, w tym temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread i use_mmap. OpenClaw przekazuje dalej tylko klucze żądań Ollama, więc parametry uruchomieniowe OpenClaw, takie jak streaming, nie wyciekają do Ollama. Użyj params.think lub params.thinking, aby wysłać najwyższego poziomu think Ollama; false wyłącza myślenie na poziomie API dla modeli 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,            },          }        ]      }    }  }}

Działa też agents.defaults.models["ollama/<model>"].params.num_ctx dla konkretnego modelu. Jeśli skonfigurowano oba ustawienia, jawny wpis modelu providera ma pierwszeństwo przed domyślną wartością agenta.

Dla natywnych modeli Ollama OpenClaw przekazuje sterowanie myśleniem tak, jak oczekuje tego Ollama: najwyższego poziomu think, nie options.think. Automatycznie wykryte modele, których odpowiedź /api/show zawiera zdolność 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

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

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

params.think lub params.thinking dla konkretnego modelu może wyłączyć albo wymusić myślenie API Ollama dla określonego skonfigurowanego modelu. OpenClaw zachowuje te jawne parametry modelu, gdy aktywne uruchomienie ma tylko niejawne domyślne off; polecenia uruchomieniowe inne niż off, takie jak /think medium, nadal nadpisują aktywne uruchomienie.

OpenClaw domyślnie traktuje modele o nazwach takich jak deepseek-r1, reasoning lub think jako zdolne do rozumowania.

ollama pull deepseek-r1:32b

Nie jest potrzebna żadna dodatkowa konfiguracja. OpenClaw oznacza je automatycznie.

Ollama jest bezpłatna i działa lokalnie, więc wszystkie koszty modeli są ustawione na 0 USD. Dotyczy to zarówno modeli wykrytych automatycznie, jak i zdefiniowanych ręcznie.

Dołączony Plugin Ollama rejestruje providera embeddingów pamięci dla wyszukiwania w pamięci. Używa skonfigurowanego bazowego URL i klucza API Ollama, wywołuje bieżący endpoint Ollama /api/embed oraz grupuje wiele fragmentów pamięci w jedno żądanie input, gdy to możliwe.

Gdy proxy.enabled=true, żądania embeddingów pamięci Ollama do dokładnego źródła host-local loopback wyprowadzonego ze skonfigurowanego baseUrl używają chronionej ścieżki bezpośredniej OpenClaw zamiast zarządzanego proxy przekazującego. Sama skonfigurowana nazwa hosta musi być localhost lub literalnym adresem IP loopback; nazwy DNS, które tylko rozwiązują się do loopback, nadal używają ścieżki zarządzanego proxy. Hosty Ollama w sieci LAN, tailnet, sieci prywatnej i publicznej również pozostają na ścieżce zarządzanego proxy. Przekierowania do innego hosta lub portu nie dziedziczą zaufania. Operatorzy nadal mogą ustawić globalne ustawienie proxy.loopbackMode: "proxy", aby wysyłać ruch loopback przez proxy, albo proxy.loopbackMode: "block", aby odrzucać połączenia loopback przed otwarciem połączenia; zobacz Zarządzane proxy, aby poznać wpływ tego ustawienia w całym procesie.

Embeddingi w czasie zapytania używają prefiksów pobierania dla modeli, które ich wymagają lub zalecają, w tym nomic-embed-text, qwen3-embedding i mxbai-embed-large. Partie dokumentów pamięci pozostają surowe, aby istniejące indeksy nie wymagały migracji formatu.

Aby wybrać Ollama jako providera embeddingów wyszukiwania w pamięci:

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

Dla zdalnego hosta embeddingów ogranicz auth do tego hosta:

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

Integracja Ollama w OpenClaw domyślnie używa natywnego API Ollama (/api/chat), które w pełni obsługuje jednocześnie streaming i wywoływanie narzędzi. Nie jest potrzebna żadna specjalna konfiguracja.

Dla natywnych żądań /api/chat OpenClaw przekazuje też sterowanie myśleniem bezpośrednio do Ollama: /think off i openclaw agent --thinking off wysyłają najwyższego poziomu think: false, chyba że skonfigurowano jawną wartość modelu params.think/params.thinking, natomiast /think low|medium|high wysyłają pasujący ciąg wysiłku najwyższego poziomu think. /think max mapuje się na najwyższy natywny wysiłek Ollama, think: "high".

W WSL2 z NVIDIA/CUDA oficjalny instalator Ollama dla Linuksa tworzy jednostkę systemd ollama.service z Restart=always. Jeśli ta usługa uruchamia się automatycznie i ładuje model wspierany przez GPU podczas startu WSL2, Ollama może zablokować pamięć hosta, gdy model się ładuje. Odzyskiwanie pamięci Hyper-V nie zawsze może odzyskać te zablokowane strony, więc Windows może zakończyć VM WSL2, systemd ponownie uruchamia Ollama i pętla się powtarza.

Typowe dowody:

• powtarzające się ponowne uruchomienia lub zakończenia WSL2 po stronie Windows
• wysokie użycie CPU w app.slice lub ollama.service krótko po starcie WSL2
• SIGTERM z systemd zamiast zdarzenia Linux OOM-killer

OpenClaw rejestruje ostrzeżenie startowe, gdy wykryje WSL2, włączone ollama.service z Restart=always i widoczne znaczniki CUDA.

Ograniczenie problemu:

sudo systemctl disable ollama

Dodaj to do %USERPROFILE%\.wslconfig po stronie Windows, a następnie uruchom wsl --shutdown:

[experimental]autoMemoryReclaim=disabled

Ustaw krótszy czas podtrzymania w środowisku usługi Ollama albo uruchamiaj Ollama ręcznie tylko wtedy, gdy jej potrzebujesz:

export OLLAMA_KEEP_ALIVE=5mollama serve

Zobacz ollama/ollama#11317.

Upewnij się, że Ollama działa, że ustawiono OLLAMA_API_KEY (lub profil auth) oraz że nie zdefiniowano jawnego wpisu models.providers.ollama:

ollama serve

Sprawdź, czy API jest dostępne:

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

Jeśli model nie jest wymieniony, pobierz go lokalnie albo zdefiniuj jawnie w models.providers.ollama.

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

Sprawdź, czy Ollama działa na właściwym porcie:

# Check if Ollama is runningps aux | grep ollama # Or restart Ollamaollama serve

Sprawdź z tej samej maszyny i tego samego środowiska uruchomieniowego, 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.
• URL używa /v1, co wybiera zachowanie zgodne z OpenAI zamiast natywnego Ollama.
• Zdalny host wymaga zmian zapory lub wiązania LAN po stronie Ollama.
• Model jest obecny w daemonie laptopa, ale nie w zdalnym daemonie.

Zazwyczaj oznacza to, że provider używa trybu zgodnego z OpenAI albo model nie obsługuje schematów narzędzi.

Preferuj natywny tryb Ollama:

{  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 w tym wpisie modelu i przetestuj ponownie.

Hostowane odpowiedzi Kimi/GLM, które są długimi, nielingwistycznymi ciągami symboli, są traktowane jako nieudane wyjście providera zamiast udanej odpowiedzi asystenta. Pozwala to przejąć sterowanie zwykłemu ponowieniu, fallbackowi lub obsłudze błędu bez utrwalania uszkodzonego tekstu w sesji.

Jeśli zdarza się to wielokrotnie, przechwyć surową nazwę modelu, bieżący plik sesji oraz informację, czy uruchomienie używało Cloud + Local czy Cloud only, a następnie spróbuj świeżej sesji i modelu fallback:

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ą potrzebować długiego pierwszego ładowania, zanim rozpocznie się streaming. Ogranicz timeout do providera Ollama i opcjonalnie poproś Ollama o utrzymywanie modelu załadowanego 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 także chroniony limit czasu połączenia Undici dla tego dostawcy.

Wiele modeli Ollama deklaruje konteksty większe, niż Twój sprzęt może komfortowo obsłużyć. Natywne Ollama używa domyślnego kontekstu środowiska uruchomieniowego Ollama, chyba że ustawisz params.num_ctx. Ogranicz zarówno budżet OpenClaw, jak i kontekst żądania Ollama, gdy chcesz przewidywalnego opóźnienia pierwszego tokenu:

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

Najpierw zmniejsz contextWindow, jeśli OpenClaw wysyła zbyt dużo promptu. Zmniejsz params.num_ctx, jeśli Ollama ładuje kontekst środowiska uruchomieniowego, który jest zbyt duży dla maszyny. Zmniejsz maxTokens, jeśli generowanie trwa zbyt długo.