Ollama

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

Загальнодоступні віддалені хости та https://ollama.com потребують справжніх облікових даних: OLLAMA_API_KEY, профілю автентифікації або apiKey провайдера. Для безпосереднього використання розміщеного сервісу віддавайте перевагу провайдеру ollama-cloud.

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

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

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

• Ключ рівня провайдера надсилається лише на хост цього провайдера.
• agents.*.memorySearch.remote.apiKey надсилається лише на відповідний віддалений хост вбудовувань.
• Окреме значення змінної середовища OLLAMA_API_KEY вважається домовленістю Ollama Cloud і за замовчуванням не надсилається на локальні або самостійно розміщені хости.

Ollama на тому самому комп’ютері, що й Gateway, виявляється автоматично:

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

Не додавайте блок models.providers.ollama, якщо вам не потрібне ручне налаштування моделей.

{  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. Узгоджуйте їх, якщо обладнання не може працювати з повним заявленим контекстом моделі.

Без локального демона, безпосереднє використання розміщених моделей:

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

Щоб замість цієї структури використовувати окремий ідентифікатор провайдера ollama-cloud, див. Ollama Cloud.

Використовуйте власні ідентифікатори провайдерів, коли запускаєте кілька серверів Ollama; кожен із них отримує власний хост, моделі, автентифікацію та час очікування.

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

Перед викликом Ollama OpenClaw видаляє префікс активного провайдера (інакше використовує звичайний префікс ollama/), тому ollama-large/qwen3.5:27b надходить до Ollama як qwen3.5:27b.

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

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

Використовуйте compat.supportsTools: false, лише коли модель або сервер стабільно зазнає помилок на схемах інструментів — це обмінює можливості агента на стабільність. localModelLean вилучає ресурсомісткі інструменти браузера, cron, повідомлень, генерування медіа, голосу та PDF із безпосередньої поверхні агента, якщо вони явно не потрібні, і переміщує більші каталоги за Tool Search. Це не змінює контекст середовища виконання Ollama або режим мислення. Поєднуйте його з params.num_ctx і params.thinking: false для невеликих моделей мислення в стилі Qwen, які зациклюються або витрачають свій бюджет на приховані міркування.

Явно задайте api: "openai-completions" для проксі, що працює за /v1/chat/completions:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: true, // типове значення: true        apiKey: "ollama-local",        models: [...]      }    }  }}

Цей режим може не підтримувати одночасно потокове передавання та виклик інструментів; можливо, доведеться задати params: { streaming: false } для моделі.

У цьому режимі OpenClaw типово додає options.num_ctx, щоб Ollama без попередження не повертався до контексту на 4096 токенів. Якщо ваш проксі відхиляє невідомі поля options, вимкніть це:

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

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

contextWindow, contextTokens і maxTokens на рівні провайдера задають типові значення для кожної моделі цього провайдера та можуть бути перевизначені для окремої моделі. contextWindow — це власний бюджет запиту/Compaction в OpenClaw. Власні запити /api/chat не задають options.num_ctx, якщо ви явно не встановили params.num_ctx, тому Ollama застосовує власне типове значення моделі, OLLAMA_CONTEXT_LENGTH або значення на основі VRAM; недійсні, нульові, від’ємні або нескінченні значення params.num_ctx ігноруються. Якщо стара конфігурація використовувала лише contextWindow/maxTokens, щоб примусово задати контекст власного запиту, запустіть openclaw doctor --fix, щоб скопіювати їх до params.num_ctx. Адаптер, сумісний з OpenAI, як і раніше типово додає options.num_ctx із налаштованого params.num_ctx або contextWindow; вимкніть це за допомогою injectNumCtxForOpenAICompat: false, якщо сервер вище за ланцюжком відхиляє options.

Власні записи моделей також приймають поширені параметри середовища виконання Ollama в params, які передаються як options власного /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 і num_thread. Кілька ключів (format, keep_alive, truncate, shift) передаються як поля запиту верхнього рівня замість вкладених options. OpenClaw передає лише ці ключі запиту Ollama, тому параметри лише для середовища виконання, як-от streaming, ніколи не надсилаються до Ollama. Використовуйте params.think (або params.thinking), щоб задати 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 для окремої моделі також працює; якщо задано обидва, пріоритет має явний запис моделі провайдера.

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

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

Або задайте типове значення для моделі:

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

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

Моделі з назвами deepseek-r1, reasoning, reason або think типово вважаються здатними до міркування — додаткова конфігурація не потрібна:

ollama pull deepseek-r1:32b

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

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

Коли proxy.enabled=true, запити векторних представлень до точного локального для хоста джерела local loopback, отриманого з налаштованого baseUrl, використовують захищений прямий шлях OpenClaw замість керованого проксі пересилання. Саме налаштоване ім’я хоста має бути localhost або літералом IP-адреси зворотного зв’язку — DNS-імена, які лише розв’язуються в адресу зворотного зв’язку, усе одно використовують шлях через керований проксі. Хости Ollama в LAN, tailnet, приватній або публічній мережі завжди залишаються на шляху через керований проксі, а переспрямування на інший хост або порт не успадковують довіру. proxy.loopbackMode: "proxy" усе одно спрямовує трафік зворотного зв’язку через проксі; proxy.loopbackMode: "block" забороняє його до встановлення з’єднання — див. Керований проксі.

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

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

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

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

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

Ознаки: повторні перезавантаження або завершення роботи WSL2, високе використання процесора в app.slice або ollama.service відразу після запуску WSL2, а також SIGTERM від systemd, а не від засобу завершення процесів через нестачу пам’яті Linux.

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

Спосіб усунення:

sudo systemctl disable ollama

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

[experimental]autoMemoryReclaim=disabled

Або скоротіть час підтримання активності чи запускайте Ollama вручну лише за потреби:

export OLLAMA_KEEP_ALIVE=5mollama serve

Див. ollama/ollama#11317.

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

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

Завантажте модель локально або визначте її явно в models.providers.ollama:

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

Перевірте на тій самій машині й у тому самому середовищі виконання, де працює Gateway:

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

Поширені причини:

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

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

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

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

Розміщені на сервері відповіді Kimi/GLM, що складаються з довгих послідовностей немовних символів, вважаються невдалим викликом постачальника, а не успішною відповіддю, тому замість збереження пошкодженого тексту в сеансі застосовується звичайна обробка повторних спроб, резервного перемикання або помилок.

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

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

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

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

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

Багато моделей заявляють контексти, які перевищують можливості вашого обладнання для комфортної роботи. Власний режим 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 надсилає надто великий запит. Зменште params.num_ctx, якщо контекст середовища виконання Ollama завеликий для машини. Зменште maxTokens, якщо генерування триває надто довго.