Ollama

Локальні хости Ollama та хости Ollama в LAN не потребують справжнього bearer-токена. OpenClaw використовує локальний маркер ollama-local лише для loopback, приватної мережі, .local і базових URL Ollama з простим іменем хоста.

Віддалені публічні хости та Ollama Cloud (https://ollama.com) потребують справжніх облікових даних через OLLAMA_API_KEY, профіль автентифікації або apiKey провайдера.

Користувацькі ідентифікатори провайдерів, які задають api: "ollama", дотримуються тих самих правил. Наприклад, провайдер ollama-remote, який вказує на приватний LAN-хост Ollama, може використовувати apiKey: "ollama-local", а субагенти розв’язуватимуть цей маркер через хук провайдера Ollama замість того, щоб трактувати його як відсутні облікові дані. Пошук пам’яті також може задати agents.defaults.memorySearch.provider на цей користувацький ідентифікатор провайдера, щоб embeddings використовували відповідну кінцеву точку Ollama.

auth-profiles.json зберігає облікові дані для ідентифікатора провайдера. Розміщуйте налаштування кінцевої точки (baseUrl, api, ідентифікатори моделей, заголовки, тайм-аути) у models.providers.<id>. Старі пласкі файли auth-profile на кшталт { "ollama-windows": { "apiKey": "ollama-local" } } не є runtime-форматом; запустіть openclaw doctor --fix, щоб переписати їх у канонічний профіль API-ключа ollama-windows:default із резервною копією. baseUrl у цьому файлі є шумом сумісності, і його слід перенести до конфігурації провайдера.

Коли Ollama використовується для embeddings пам’яті, bearer-автентифікація обмежується хостом, де її було оголошено:

• Ключ рівня провайдера надсилається лише до хоста Ollama цього провайдера.
• agents.*.memorySearch.remote.apiKey надсилається лише до його віддаленого хоста embeddings.
• Чисте значення env OLLAMA_API_KEY трактується як домовленість Ollama Cloud і за замовчуванням не надсилається до локальних або self-hosted хостів.

Використовуйте це, коли Ollama працює на тій самій машині, що й Gateway, і ви хочете, щоб OpenClaw автоматично виявляв установлені моделі.

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

Цей шлях зберігає конфігурацію мінімальною. Не додавайте блок models.providers.ollama, якщо не хочете визначати моделі вручну.

Використовуйте нативні URL Ollama для LAN-хостів. Не додавайте /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 — це бюджет контексту на боці OpenClaw. params.num_ctx надсилається до Ollama для запиту. Тримайте їх узгодженими, коли ваше обладнання не може запустити повний заявлений контекст моделі.

Використовуйте це, коли ви не запускаєте локальний демон і хочете напряму використовувати хостингові моделі 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" },
    },
  },
}

Використовуйте це, коли локальний або LAN-демон Ollama увійшов у систему через ollama signin і має обслуговувати як локальні моделі, так і моделі :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"],
      },
    },
  },
}

Використовуйте власні ID провайдерів, коли маєте більше ніж один сервер Ollama. Кожен провайдер отримує власний хост, моделі, автентифікацію, timeout і посилання на моделі.

{
  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 надсилає запит, активний префікс провайдера прибирається, тому ollama-large/qwen3.5:27b доходить до Ollama як qwen3.5:27b.

Деякі локальні моделі можуть відповідати на прості prompts, але мають труднощі з повною поверхнею інструментів агента. Почніть з обмеження інструментів і контексту, перш ніж змінювати глобальні налаштування runtime.

{
  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 лише тоді, коли модель або сервер стабільно не працюють зі схемами інструментів. Це обмінює можливості агента на стабільність. localModelLean прибирає браузер, cron та інструменти повідомлень із поверхні агента, але не змінює runtime-контекст Ollama або режим мислення. Поєднуйте це з явними params.num_ctx і params.thinking: false для невеликих моделей мислення у стилі Qwen, які зациклюються або витрачають бюджет відповіді на приховане міркування.

Якщо натомість потрібно використовувати OpenAI-сумісний endpoint (наприклад, за проксі, який підтримує лише формат OpenAI), явно задайте api: "openai-completions":

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

Цей режим може не підтримувати потокову передачу та виклики інструментів одночасно. Може знадобитися вимкнути потокову передачу за допомогою params: { streaming: false } у конфігурації моделі.

Коли api: "openai-completions" використовується з Ollama, OpenClaw типово ін’єктує options.num_ctx, щоб Ollama не повертався непомітно до контекстного вікна 4096. Якщо ваш проксі/upstream відхиляє невідомі поля options, вимкніть цю поведінку:

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

Для автоматично виявлених моделей OpenClaw використовує контекстне вікно, повідомлене Ollama, коли воно доступне, включно з більшими значеннями PARAMETER num_ctx із користувацьких Modelfile. Інакше він повертається до стандартного контекстного вікна Ollama, яке використовує OpenClaw.

Ви можете встановити стандартні значення contextWindow, contextTokens і maxTokens на рівні провайдера для кожної моделі під цим провайдером Ollama, а потім за потреби перевизначати їх для окремих моделей. contextWindow — це бюджет prompt і Compaction в OpenClaw. Нативні запити Ollama залишають options.num_ctx незаданим, якщо ви явно не налаштуєте params.num_ctx, щоб Ollama міг застосувати власне стандартне значення моделі, OLLAMA_CONTEXT_LENGTH або значення на основі VRAM. Щоб обмежити або примусово задати runtime-контекст Ollama для окремого запиту без перебудови Modelfile, задайте params.num_ctx; недійсні, нульові, від’ємні та нескінченні значення ігноруються. OpenAI-сумісний адаптер Ollama все ще типово ін’єктує options.num_ctx із налаштованого params.num_ctx або contextWindow; вимкніть це за допомогою injectNumCtxForOpenAICompat: false, якщо ваш upstream відхиляє options.

Нативні записи моделей Ollama також приймають загальні runtime-параметри Ollama у params, включно з temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread і use_mmap. OpenClaw передає лише ключі запиту Ollama, тому runtime-параметри OpenClaw, такі як streaming, не потрапляють до Ollama. Використовуйте params.think або params.thinking, щоб надсилати верхньорівневий Ollama think; false вимикає мислення на рівні API для моделей мислення у стилі 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,
            },
          }
        ]
      }
    }
  }
}

Також працює agents.defaults.models["ollama/<model>"].params.num_ctx для окремої моделі. Якщо налаштовано обидва варіанти, явний запис моделі провайдера має пріоритет над стандартним значенням агента.

Для нативних моделей Ollama OpenClaw передає керування мисленням так, як очікує Ollama: верхньорівневий think, а не options.think. Автоматично виявлені моделі, відповідь /api/show яких містить можливість thinking, показують /think low, /think medium, /think high і /think max; моделі без мислення показують лише /think off.

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

Ви також можете задати стандартне значення моделі:

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

params.think або params.thinking для окремої моделі може вимкнути або примусово ввімкнути мислення Ollama API для конкретної налаштованої моделі. OpenClaw зберігає ці явні параметри моделі, коли активний запуск має лише неявне стандартне значення off; runtime-команди не off, такі як /think medium, усе одно перевизначають активний запуск.

OpenClaw типово вважає моделі з назвами на кшталт deepseek-r1, reasoning або think здатними до міркування.

ollama pull deepseek-r1:32b

Додаткова конфігурація не потрібна. OpenClaw позначає їх автоматично.

Ollama безкоштовний і працює локально, тому вартість усіх моделей задано як $0. Це стосується як автоматично виявлених, так і вручну визначених моделей.

Вбудований Plugin Ollama реєструє провайдера вбудовувань пам’яті для пошуку в пам’яті. Він використовує налаштований базовий URL Ollama і API-ключ, викликає поточний endpoint /api/embed Ollama та за можливості об’єднує кілька фрагментів пам’яті в один запит input.

Вбудовування під час запиту використовують префікси retrieval для моделей, які їх потребують або рекомендують, включно з nomic-embed-text, qwen3-embedding і mxbai-embed-large. Пакети документів пам’яті залишаються необробленими, щоб наявні індекси не потребували міграції формату.

Щоб вибрати Ollama як провайдера вбудовувань для пошуку в пам’яті:

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

Для віддаленого хоста вбудовувань обмежуйте автентифікацію цим хостом:

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

Інтеграція OpenClaw з Ollama за замовчуванням використовує нативний API Ollama (/api/chat), який повністю підтримує потокове передавання та виклик інструментів одночасно. Спеціальна конфігурація не потрібна.

Для нативних запитів /api/chat OpenClaw також передає керування міркуванням безпосередньо в Ollama: /think off і openclaw agent --thinking off надсилають верхньорівневе think: false, якщо не налаштовано явне значення моделі params.think/params.thinking, тоді як /think low|medium|high надсилають відповідний верхньорівневий рядок зусилля think. /think max зіставляється з найвищим нативним зусиллям Ollama, think: "high".

У WSL2 з NVIDIA/CUDA офіційний інсталятор Ollama для Linux створює systemd unit ollama.service з Restart=always. Якщо цей сервіс автоматично запускається і завантажує модель із підтримкою GPU під час запуску WSL2, Ollama може закріпити пам'ять хоста під час завантаження моделі. Механізм повернення пам'яті Hyper-V не завжди може звільнити ці закріплені сторінки, тому Windows може завершити VM WSL2, systemd знову запускає Ollama, і цикл повторюється.

Типові ознаки:

• повторні перезавантаження або завершення WSL2 з боку Windows
• високе навантаження CPU в app.slice або ollama.service невдовзі після запуску WSL2
• SIGTERM від systemd, а не подія Linux OOM-killer

OpenClaw записує попередження під час запуску, коли виявляє WSL2, увімкнений ollama.service з Restart=always і видимі маркери CUDA.

Пом'якшення:

sudo systemctl disable ollama

Додайте це до %USERPROFILE%\.wslconfig на боці Windows, а потім виконайте wsl --shutdown:

[experimental]
autoMemoryReclaim=disabled

Задайте коротший keep-alive в середовищі сервісу Ollama або запускайте Ollama вручну лише тоді, коли вона потрібна:

export OLLAMA_KEEP_ALIVE=5m
ollama serve

Див. ollama/ollama#11317.

Переконайтеся, що Ollama запущено, що ви встановили OLLAMA_API_KEY (або профіль автентифікації), і що ви не визначили явний запис models.providers.ollama:

ollama serve

Перевірте, що API доступний:

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

Якщо вашої моделі немає в списку, завантажте модель локально або явно визначте її в models.providers.ollama.

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

Перевірте, що Ollama працює на правильному порту:

# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve

Перевірте з тієї самої машини та runtime, де працює Gateway:

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

Типові причини:

• baseUrl вказує на localhost, але Gateway працює в Docker або на іншому хості.
• URL використовує /v1, що вибирає OpenAI-сумісну поведінку замість нативної Ollama.
• Віддалений хост потребує змін firewall або прив'язування LAN на боці Ollama.
• Модель присутня в daemon на вашому ноутбуці, але не у віддаленому daemon.

Зазвичай це означає, що провайдер використовує OpenAI-сумісний режим або модель не може обробляти схеми інструментів.

Віддавайте перевагу нативному режиму Ollama:

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

Якщо невелика локальна модель усе ще не працює зі схемами інструментів, задайте compat.supportsTools: false для цього запису моделі та повторіть тест.

Hosted-відповіді Kimi/GLM, які є довгими нелінгвістичними послідовностями символів, обробляються як невдалий вивід провайдера, а не як успішна відповідь асистента. Це дає змогу звичайному повтору, fallback або обробці помилок взяти керування на себе без збереження пошкодженого тексту в сесії.

Якщо це повторюється, зафіксуйте raw-назву моделі, поточний файл сесії та чи використовував запуск Cloud + Local або Cloud only, а потім спробуйте нову сесію та fallback-модель:

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

Великим локальним моделям може знадобитися тривале перше завантаження перед початком потокового передавання. Обмежте timeout провайдером Ollama і, за потреби, попросіть Ollama тримати модель завантаженою між ходами:

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

Якщо сам хост повільно приймає з'єднання, timeoutSeconds також розширює захищений timeout підключення Undici для цього провайдера.

Багато моделей Ollama оголошують контексти, більші за ті, які ваше обладнання може комфортно запускати. Нативна Ollama використовує власне стандартне значення runtime-контексту Ollama, якщо ви не задаєте params.num_ctx. Обмежте і бюджет OpenClaw, і контекст запиту Ollama, коли потрібна передбачувана затримка до першого токена:

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

Спочатку зменште contextWindow, якщо OpenClaw надсилає забагато prompt. Зменште params.num_ctx, якщо Ollama завантажує runtime-контекст, який завеликий для машини. Зменште maxTokens, якщо генерація триває надто довго.