Ollama

Lokalne i LAN-owe hosty Ollama nie potrzebują prawdziwego tokena bearer. OpenClaw używa lokalnego znacznika ollama-local tylko dla adresów URL bazowych Ollama typu loopback, sieci prywatnej, .local oraz samych nazw hostów.

Zdalne hosty publiczne oraz Ollama Cloud (https://ollama.com) wymagają prawdziwych danych uwierzytelniających przez OLLAMA_API_KEY, profil uwierzytelniania albo apiKey providera.

Niestandardowe identyfikatory providerów, które ustawiają api: "ollama", stosują te same reguły. Na przykład provider ollama-remote, który wskazuje na prywatny host LAN Ollama, może używać apiKey: "ollama-local", a podagenci rozwiążą ten znacznik przez hook providera 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 providera, aby embeddingi używały pasującego endpointu Ollama.

auth-profiles.json przechowuje dane uwierzytelniające dla identyfikatora providera. Ustawienia endpointu (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 runtime; uruchom openclaw doctor --fix, aby przepisać je do kanonicznego profilu klucza API ollama-windows:default z kopią zapasową. baseUrl w tym pliku to szum zgodności i należy go przenieść do konfiguracji providera.

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 providera jest wysyłany tylko do hosta Ollama tego providera.
• agents.*.memorySearch.remote.apiKey jest wysyłany tylko do swojego zdalnego hosta embeddingów.
• Czysta wartość env 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 tej samej maszynie co Gateway i chcesz, aby OpenClaw automatycznie wykrywał zainstalowane modele.

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

Ta ścieżka utrzymuje konfigurację na minimalnym poziomie. Nie dodawaj bloku models.providers.ollama, chyba że chcesz definiować modele ręcznie.

Używaj natywnych adresów URL Ollama dla hostów 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 demon Ollama lub demon Ollama w LAN jest zalogowany przez ollama signin i ma obsługiwać zarówno modele lokalne, jak i modele :cloud.

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

Użyj 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 odwołania 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 dociera 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: {
    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 },
          },
        ],
      },
    },
  },
}

Używaj compat.supportsTools: false tylko wtedy, gdy model lub serwer niezawodnie zawodzi na schematach narzędzi. Zamienia możliwości agenta na stabilność. localModelLean usuwa narzędzia przeglądarki, cron i wiadomości z powierzchni agenta, ale nie zmienia kontekstu wykonania ani trybu myślenia Ollama. Połącz to z jawnymi params.num_ctx i params.thinking: false dla małych modeli myślących w stylu Qwen, które wpadają w pętle 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 przez 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 modeli wykrytych automatycznie 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 dostawcy dla każdego modelu pod tym dostawcą Ollama, a następnie nadpisywać je dla poszczególnych modeli w razie potrzeby. 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 lub domyślne ustawienie oparte na VRAM. Aby ograniczyć lub wymusić kontekst wykonania na żądanie Ollama bez przebudowywania Modelfile, ustaw params.num_ctx; wartości nieprawidłowe, zerowe, ujemne i nieskończone są ignorowane. 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ą także typowe opcje wykonania Ollama w params, w tym temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread i use_mmap. OpenClaw przekazuje tylko klucze żądań Ollama, więc parametry wykonania OpenClaw, takie jak streaming, nie są ujawniane Ollama. Użyj params.think lub params.thinking, aby wysłać najwyższego poziomu Ollama think; 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 dostawcy ma pierwszeństwo przed domyślnym ustawieniem agenta.

Dla natywnych modeli Ollama OpenClaw przekazuje sterowanie myśleniem tak, jak oczekuje tego Ollama: najwyższego poziomu think, a nie options.think. Modele wykryte automatycznie, których odpowiedź /api/show zawiera możliwość thinking, udostępniają /think low, /think medium, /think high i /think max; modele niemyślące udostępniają tylko /think off.

openclaw agent --model ollama/gemma4 --thinking off
openclaw 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ć lub wymusić myślenie API Ollama dla konkretnego skonfigurowanego modelu. OpenClaw zachowuje te jawne parametry modelu, gdy aktywne uruchomienie ma tylko niejawne domyślne off; polecenia wykonania 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 dodatkowa konfiguracja. OpenClaw oznacza je automatycznie.

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

Wbudowany Plugin Ollama rejestruje dostawcę embeddingów pamięci dla wyszukiwania pamięci. Używa skonfigurowanego bazowego adresu URL Ollama i klucza API, wywołuje bieżący punkt końcowy Ollama /api/embed oraz grupuje wiele fragmentów pamięci w jedno żądanie input, gdy to możliwe.

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

Aby wybrać Ollama jako dostawcę embeddingów wyszukiwania 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 utrzymuj uwierzytelnianie ograniczone 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 OpenClaw z Ollama 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 wymagana żadna specjalna konfiguracja.

W przypadku natywnych żądań /api/chat OpenClaw przekazuje też kontrolę thinking bezpośrednio do Ollama: /think off i openclaw agent --thinking off wysyłają think: false najwyższego poziomu, chyba że skonfigurowano jawną wartość modelu params.think/params.thinking, natomiast /think low|medium|high wysyłają odpowiadający ciąg effort think najwyższego poziomu. /think max mapuje się na najwyższy natywny effort 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 przypiąć pamięć hosta w trakcie ładowania modelu. Odzyskiwanie pamięci Hyper-V nie zawsze może odzyskać te przypięte strony, więc Windows może zakończyć maszynę wirtualną WSL2, systemd ponownie uruchamia Ollama i pętla się powtarza.

Typowe dowody:

• powtarzające się restarty lub zakończenia WSL2 po stronie Windows
• wysokie użycie CPU w app.slice lub ollama.service krótko po uruchomieniu WSL2
• SIGTERM od systemd zamiast zdarzenia zabójcy OOM Linuksa

OpenClaw rejestruje ostrzeżenie przy starcie, gdy wykryje WSL2, włączone ollama.service z Restart=always oraz 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 keep-alive w środowisku usługi Ollama albo uruchamiaj Ollama ręcznie tylko wtedy, gdy jej potrzebujesz:

export OLLAMA_KEEP_ALIVE=5m
ollama serve

Zobacz ollama/ollama#11317.

Upewnij się, że Ollama działa, że ustawiono OLLAMA_API_KEY (lub profil uwierzytelniania) 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 Twojego modelu nie ma na liście, pobierz model lokalnie albo zdefiniuj go jawnie w models.providers.ollama.

ollama list  # See what's installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model

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

# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve

Zweryfikuj z tej samej maszyny i tego samego środowiska uruchomieniowego, w którym działa Gateway:

openclaw gateway status --deep
curl 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 w zaporze lub powiązaniu LAN po stronie Ollama.
• Model jest obecny w demonie na Twoim laptopie, ale nie w zdalnym demonie.

Zwykle oznacza to, że dostawca używa trybu zgodnego z OpenAI albo model nie potrafi obsłużyć 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 dostawcy zamiast udanej odpowiedzi asystenta. Dzięki temu normalna logika ponawiania, fallbacku lub obsługi błędów może przejąć działanie bez zapisywania uszkodzonego tekstu w sesji.

Jeśli dzieje 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" --json
openclaw models set ollama/gemma4

Duże modele lokalne mogą wymagać długiego pierwszego ładowania, zanim rozpocznie się streaming. Ogranicz limit czasu do dostawcy 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 rozszerza również 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ć. Natywna Ollama używa własnej domyślnej wartości 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 do pierwszego tokena:

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