/api/chat), а не із сумісною з OpenAI
кінцевою точкою /v1. Підтримуються три режими:
ollama-cloud див.
Ollama Cloud. Використовуйте посилання ollama-cloud/<model>, коли
потрібно відокремити хмарну маршрутизацію від локального провайдера ollama.
Канонічний ключ конфігурації — baseUrl. baseURL також приймається для
прикладів у стилі OpenAI SDK, але в новій конфігурації слід використовувати baseUrl.
Правила автентифікації
Локальні хости та хости локальної мережі
Локальні хости та хости локальної мережі
.local і простого імені хоста не потребують справжнього bearer-токена. OpenClaw використовує для них маркер ollama-local.Віддалені хости та хости Ollama Cloud
Віддалені хости та хости Ollama Cloud
https://ollama.com потребують справжніх облікових даних: OLLAMA_API_KEY, профілю автентифікації або apiKey провайдера. Для безпосереднього використання розміщеної служби надавайте перевагу провайдеру ollama-cloud.Власні ідентифікатори провайдерів
Власні ідентифікатори провайдерів
api: "ollama" дотримується тих самих правил. Наприклад, провайдер ollama-remote, спрямований на приватний хост локальної мережі, може використовувати 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 у такому застарілому файлі є зайвим і має бути перенесене до конфігурації провайдера.Область дії вбудовувань пам’яті
Область дії вбудовувань пам’яті
- Ключ рівня провайдера надсилається лише на хост цього провайдера.
agents.*.memorySearch.remote.apiKeyнадсилається лише на його віддалений хост вбудовувань.- Чисте значення змінної середовища
OLLAMA_API_KEYвважається домовленістю Ollama Cloud і за замовчуванням не надсилається локальним або самостійно розміщеним хостам.
Початок роботи
- Початкове налаштування (рекомендовано)
- Ручне налаштування
Запустіть початкове налаштування
Виберіть модель
Cloud only запитує OLLAMA_API_KEY і пропонує типові хмарні моделі. Cloud + Local та Local only запитують базову URL-адресу Ollama, виявляють доступні моделі й автоматично завантажують вибрану локальну модель, якщо її немає. Установлений тег :latest, як-от gemma4:latest, показується один раз замість дублювання gemma4. Cloud + Local також перевіряє, чи виконано на хості вхід для доступу до хмари.Перевірте
--custom-base-url та --custom-model-id необов’язкові; якщо їх не вказати, використовуватимуться типовий локальний хост і запропонована модель gemma4.Хмарні моделі через локальний хост
Cloud + Local спрямовує локальні моделі та моделі :cloud через один доступний
хост Ollama — це гібридний процес Ollama й режим, який слід вибрати під час налаштування,
якщо потрібні обидва варіанти.
OpenClaw запитує базову URL-адресу, виявляє локальні моделі та перевіряє
стан ollama signin. Якщо вхід виконано, він пропонує типові розміщені моделі
(kimi-k2.5:cloud, minimax-m2.7:cloud, glm-5.1:cloud, glm-5.2:cloud). Якщо
вхід не виконано, налаштування залишається лише локальним, доки не буде запущено ollama signin.
Для доступу лише до хмари без локального демона використовуйте openclaw onboard --auth-choice ollama-cloud і див. Ollama Cloud — цей варіант не потребує ollama signin або запущеного сервера:
openclaw onboard, динамічно отримується з
https://ollama.com/api/tags і обмежений 500 записами, тому засіб вибору відображає
поточний каталог розміщених моделей. Якщо ollama.com недоступний або не повертає
моделей під час налаштування, OpenClaw використовує як резервний варіант жорстко закодований список рекомендованих моделей, щоб
початкове налаштування все одно завершилося.
Виявлення моделей (неявний провайдер)
Коли заданоOLLAMA_API_KEY (або профіль автентифікації) і не визначено ні
models.providers.ollama, ні іншого власного провайдера з api: "ollama",
OpenClaw виявляє моделі з http://127.0.0.1:11434:
models.providers.ollama із явним масивом models або
власного провайдера з api: "ollama" і не-loopback значенням baseUrl вимикає
автоматичне виявлення; тоді моделі потрібно визначати вручну (див.
Конфігурація). Запис models.providers.ollama, спрямований на
розміщений https://ollama.com, також пропускає виявлення, оскільки моделями Ollama Cloud
керує провайдер. Власні loopback-провайдери, як-от
http://127.0.0.2:11434, усе ще вважаються локальними й зберігають автоматичне виявлення.
Можна використовувати повне посилання, як-от ollama/<pulled-model>:latest, без
власноруч створеного запису models.json; OpenClaw розпізнає його динамічно. Для хостів,
на яких виконано вхід, вибір відсутнього у списку посилання ollama/<model>:cloud перевіряє саме цю
модель за допомогою /api/show і додає її до каталогу середовища виконання, лише якщо Ollama
підтверджує метадані — посилання з помилками усе одно не розпізнаються як відомі моделі.
Димові тести
Для вузької текстової перевірки без повної поверхні інструментів агента:--file із зображенням для спрощеної перевірки моделі зору (підтримуються PNG/JPEG/WebP;
файли, що не є зображеннями, відхиляються до виклику Ollama — використовуйте
openclaw infer audio transcribe для аудіо):
/model ollama/<model> є точним вибором користувача: якщо
налаштований baseUrl недоступний, наступна відповідь завершується помилкою провайдера,
а не непомітним переходом до іншої налаштованої моделі.
Ізольовані завдання Cron додають одну локальну перевірку безпеки перед початком ходу агента:
якщо вибрана модель відповідає локальному/приватно-мережевому/.local провайдеру Ollama
і /api/tags недоступний, OpenClaw записує цей запуск як
skipped, зазначаючи модель у тексті помилки. Ця перевірка кінцевої точки кешується на
5 хвилин для кожного хоста, тому повторювані завдання Cron для зупиненого демона не
запускають усі запити, приречені на помилку.
Перевірка наживо:
OPENCLAW_LIVE_OLLAMA_EMBEDDINGS=1, оскільки
хмарний ключ може не надавати доступ до /api/embed):
Локальний для Node інференс
Агенти можуть делегувати коротке завдання моделі Ollama на спареному настільному комп’ютері або серверному Node. Запит і відповідь передаються через наявне автентифіковане з’єднання Gateway/Node; запит виконується через власну loopback-кінцеву точку Ollama цього Node (http://127.0.0.1:11434).
Запустіть Ollama на Node
Підключіть хост Node
ollama.models і ollama.chat, знову перевірте openclaw nodes pending.Використовуйте його з агента
node_inference. Агенти спочатку викликають
action: "discover", а потім action: "run" із Node і моделлю з
цього результату (run може не вказувати Node, якщо підключено
рівно один придатний Node). Наприклад: «Вияви моделі Ollama на моїх Node, а потім використай
найшвидшу завантажену модель, щоб підсумувати цей текст»./api/tags, перевіряє можливості /api/show і використовує
/api/ps, коли він доступний, щоб першими ранжувати вже завантажені моделі. Воно повертає лише
локальні моделі, які Ollama позначає як придатні для чату (можливість completion) —
рядки Ollama Cloud і моделі лише для вбудовувань виключаються. Кожен запуск вимикає
міркування моделі та за замовчуванням обмежує вивід 512 токенами (жорстке обмеження 8192), якщо
виклик інструмента не запитує інше значення maxTokens; деякі моделі (наприклад GPT-OSS)
не підтримують вимкнення міркування й можуть усе одно виводити токени міркування.
Щоб Ollama продовжувала працювати на Node без надання агентам доступу до неї:
openclaw node restart або зупиніть і повторно запустіть openclaw node run
для сеансу на передньому плані). Node припинить оголошувати ollama.models і
ollama.chat; сама Ollama та провайдер Ollama у Gateway залишаться без змін.
Поверніть значення true і перезапустіть, щоб увімкнути знову; змінена поверхня
команд може знову потребувати схвалення openclaw nodes pending після повторного підключення.
Перевірте команди Node безпосередньо, без ходу агента:
--invoke-timeout обмежує час, протягом якого Node має виконати команду;
--timeout обмежує загальну тривалість виклику Gateway і має бути більшим.
Локальний для Node інференс завжди використовує власну loopback-кінцеву точку Node — він
не використовує повторно налаштований віддалений/хмарний models.providers.ollama.baseUrl.
Команди Node за замовчуванням доступні на хостах Node з macOS, Linux і Windows
та підпорядковуються звичайній політиці спарювання Node і команд.
Комп’ютерний зір та опис зображень
Вбудований plugin Ollama реєструє Ollama як провайдера розуміння медіа з підтримкою зображень, тому OpenClaw може спрямовувати явні запити на опис зображень і налаштовані типові моделі зображень через локальні або розміщені моделі комп’ютерного зору Ollama.--model має бути повним посиланням <provider/model>; якщо його задано, infer image describe спочатку намагається використати цю модель, а не пропускає опис для моделей,
які вже мають вбудовану підтримку комп’ютерного зору. Якщо виклик завершується помилкою, OpenClaw може продовжити
через agents.defaults.imageModel.fallbacks; помилки підготовки файлу/URL
спричиняють збій до спроби резервного варіанта. Використовуйте infer image describe для процесу
розуміння зображень OpenClaw і налаштованого imageModel; використовуйте infer model run --file для необробленої мультимодальної перевірки з власним запитом.
Щоб зробити Ollama типовим провайдером розуміння зображень для вхідних медіа:
ollama/<model>. Посилання imageModel без префікса, як-от
qwen2.5vl:7b, нормалізується до ollama/qwen2.5vl:7b лише тоді, коли саме ця модель
зазначена в models.providers.ollama.models із
input: ["text", "image"] і жоден інший налаштований провайдер зображень не надає
той самий ідентифікатор без префікса; інакше явно використовуйте префікс провайдера.
Повільні локальні моделі комп’ютерного зору можуть потребувати довшого тайм-ауту розуміння зображень, ніж
хмарні моделі, і можуть аварійно завершуватися на обладнанні з обмеженими ресурсами, якщо Ollama намагається
виділити повний заявлений контекст комп’ютерного зору моделі. Установіть тайм-аут
можливості й обмежте num_ctx:
image. models.providers.ollama.timeoutSeconds і далі керує
базовим обмеженням HTTP-запиту Ollama для звичайних викликів моделі.
Перевірка наживо:
models.providers.ollama.models вручну, явно позначте моделі
комп’ютерного зору:
/api/show.
Конфігурація
- Базова (неявне виявлення)
- Явна (моделі вручну)
- Власна базова URL-адреса
Поширені рецепти
Замініть ідентифікатори моделей точними назвами зollama list або
openclaw models list --provider ollama.
Локальна модель з автоматичним виявленням
Локальна модель з автоматичним виявленням
models.providers.ollama, якщо моделі не потрібно задавати вручну.Хост Ollama у LAN з моделями, заданими вручну
Хост Ollama у LAN з моделями, заданими вручну
contextWindow — це бюджет контексту OpenClaw; params.num_ctx надсилається до
Ollama. Узгоджуйте їх, якщо обладнання не може виконувати модель із повним
заявленим контекстом.Лише Ollama Cloud
Лише Ollama Cloud
ollama-cloud замість цієї структури див.
Ollama Cloud.Хмарні та локальні моделі через демон із виконаним входом
Хмарні та локальні моделі через демон із виконаним входом
Кілька хостів Ollama
Кілька хостів Ollama
ollama/) перед викликом Ollama, тому ollama-large/qwen3.5:27b
надходить до Ollama як qwen3.5:27b.Полегшений профіль локальної моделі
Полегшений профіль локальної моделі
compat.supportsTools: false, лише коли модель або сервер стабільно
зазнає помилки на схемах інструментів — це обмінює можливості агента на стабільність.
localModelLean вилучає ресурсомісткі інструменти браузера, cron, повідомлень, генерування
медіа, голосу та PDF із безпосереднього набору інструментів агента, якщо вони явно не потрібні,
і переміщує більші каталоги за Tool Search. Це не змінює контекст середовища виконання
Ollama чи режим мислення. Поєднуйте це з params.num_ctx і
params.thinking: false для невеликих моделей мислення в стилі Qwen, які зациклюються або
витрачають свій бюджет на приховані міркування.Вибір моделі
ollama-spark/qwen3:32b, OpenClaw видаляє цей префікс перед
викликом Ollama, надсилаючи qwen3:32b.
Для повільних локальних моделей надавайте перевагу налаштуванню на рівні провайдера, перш ніж
збільшувати час очікування всього середовища виконання агента:
timeoutSeconds охоплює HTTP-запит до моделі: установлення з’єднання, заголовки,
потокове передавання тіла й загальне переривання захищеного отримання. params.keep_alive
передається як верхньорівневий keep_alive у нативних запитах /api/chat; задайте його для
окремої моделі, коли час завантаження під час першого звернення є вузьким місцем.
Швидка перевірка
127.0.0.1 на хост baseUrl. Якщо curl
працює, а OpenClaw — ні, перевірте, чи Gateway працює на іншій
машині, у контейнері або під іншим обліковим записом служби.
Вебпошук Ollama
OpenClaw постачається з вебпошуком Ollama як провайдеромweb_search.
openclaw onboard або openclaw configure --section web чи задайте:
/api/experimental/web_search, а потім переходить до розміщеного шляху /api/web_search на тому самому хості;
локальний демон із виконаним входом зазвичай відповідає через локальний проксі. Прямі виклики
https://ollama.com завжди використовують розміщену кінцеву точку /api/web_search.
Розширена конфігурація
Застарілий режим, сумісний з OpenAI
Застарілий режим, сумісний з OpenAI
api: "openai-completions" для проксі за адресою
/v1/chat/completions:params: { streaming: false }.У цьому режимі OpenClaw типово додає options.num_ctx, щоб Ollama
не переходив непомітно до контексту на 4096 токенів. Якщо проксі відхиляє
невідомі поля options, вимкніть це:Контекстні вікна
Контекстні вікна
/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, які передаються як нативні /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 і num_thread.
Кілька ключів (format, keep_alive, truncate, shift) передаються як
верхньорівневі поля запиту, а не як вкладені options. OpenClaw передає
лише ці ключі запиту Ollama, тому параметри лише для середовища виконання, як-от
streaming, ніколи не надсилаються до Ollama. Використовуйте params.think (або
params.thinking), щоб задати верхньорівневий think; false вимикає мислення
на рівні API для моделей мислення в стилі Qwen.agents.defaults.models["ollama/<model>"].params.num_ctx для окремої моделі також
працює; явний запис моделі провайдера має пріоритет, якщо задано обидва.Керування мисленням
Керування мисленням
think, а не
options.think. Автоматично виявлені моделі, для яких /api/show повідомляє про
можливість thinking, надають /think low, /think medium, /think high
і /think max; моделі без мислення надають лише /think off.params.think/params.thinking можуть вимкнути або примусово ввімкнути
міркування API для певної моделі. OpenClaw зберігає цю явну конфігурацію,
коли активний запуск має лише неявне значення за замовчуванням off; команда середовища виконання
з режимом, відмінним від вимкненого, наприклад /think medium, усе одно має вищий пріоритет. Запит
із увімкненим міркуванням ніколи не надсилається моделі, явно позначеній
reasoning: false; запит think: false надсилається завжди.Моделі з міркуванням
Моделі з міркуванням
deepseek-r1, reasoning, reason або think за замовчуванням
вважаються здатними до міркування — додаткова конфігурація не потрібна:Вартість моделей
Вартість моделей
0 як для
автоматично виявлених, так і для визначених вручну моделей.Вбудовування пам’яті
Вбудовування пам’яті
/api/embed та, коли це можливо, об’єднує кілька фрагментів пам’яті
в один запит input.Коли proxy.enabled=true, запити вбудовування до точного локального
loopback-джерела хоста, отриманого з налаштованого baseUrl, використовують захищений
прямий шлях OpenClaw замість керованого проксі пересилання. Налаштоване
ім’я хоста має бути саме localhost або літералом loopback-IP-адреси — DNS-імена,
які лише розв’язуються в loopback-адресу, усе одно використовують шлях керованого проксі. Хости Ollama
у LAN, tailnet, приватній або публічній мережі завжди залишаються на
шляху керованого проксі, а переспрямування на інший хост або порт не успадковують
довіру. proxy.loopbackMode: "proxy" усе одно спрямовує loopback-трафік через
проксі; proxy.loopbackMode: "block" забороняє його до встановлення з’єднання —
див. Керований проксі.nomic-embed-text, qwen3-embedding та
mxbai-embed-large. Пакети документів залишаються необробленими, тому наявні індекси
не потребують міграції формату.Конфігурація потокового передавання
Конфігурація потокового передавання
/api/chat), який одночасно підтримує
потокове передавання та виклики інструментів — спеціальна конфігурація не потрібна.Для власних запитів керування міркуванням передається безпосередньо: /think off
і openclaw agent --thinking off надсилають верхньорівневий think: false, якщо
не налаштовано явний params.think/params.thinking; /think low|medium|high надсилають відповідний рядок інтенсивності; /think max відповідає
найвищій інтенсивності Ollama — think: "high".Усунення несправностей
Цикл аварійного завершення WSL2 (повторні перезапуски)
Цикл аварійного завершення WSL2 (повторні перезапуски)
ollama.service із Restart=always. Якщо ця служба
запускається автоматично й завантажує модель із підтримкою GPU під час запуску WSL2, Ollama може закріпити
пам’ять хоста під час завантаження; механізм повернення пам’яті Hyper-V не завжди може звільнити
ці сторінки, тому Windows може завершити роботу віртуальної машини WSL2, systemd перезапускає
Ollama, і цикл повторюється.Ознаки: повторні перезапуски або завершення WSL2, високе навантаження на CPU в app.slice чи
ollama.service одразу після запуску WSL2, а також SIGTERM від systemd, а не
від засобу завершення процесів через нестачу пам’яті Linux.OpenClaw записує попередження під час запуску, коли виявляє WSL2, увімкнений
ollama.service із Restart=always та видимі маркери CUDA.Спосіб усунення:%USERPROFILE%\.wslconfig, а потім виконайте
wsl --shutdown:Ollama не виявлено
Ollama не виявлено
OLLAMA_API_KEY (або профіль автентифікації) налаштовано,
а models.providers.ollama не визначено явно:Немає доступних моделей
Немає доступних моделей
models.providers.ollama:У з’єднанні відмовлено
У з’єднанні відмовлено
Віддалений хост працює з curl, але не з OpenClaw
Віддалений хост працює з curl, але не з OpenClaw
baseUrlуказує наlocalhost, але Gateway працює в Docker або на іншому хості.- URL-адреса використовує
/v1, через що вибирається поведінка, сумісна з OpenAI, замість власної поведінки Ollama. - Віддалений хост потребує змін у брандмауері або прив’язуванні до LAN.
- Модель є в демоні на вашому ноутбуці, але не у віддаленому демоні.
Модель виводить JSON інструменту як текст
Модель виводить JSON інструменту як текст
compat.supportsTools: false у записі цієї моделі та повторіть перевірку.Kimi або GLM повертає спотворені символи
Kimi або GLM повертає спотворені символи
Cloud + Local або Cloud only, а потім спробуйте новий
сеанс і резервну модель:Холодна локальна модель перевищує час очікування
Холодна локальна модель перевищує час очікування
timeoutSeconds також
подовжує захищений час очікування з’єднання для цього постачальника.Модель із великим контекстом працює надто повільно або вичерпує пам’ять
Модель із великим контекстом працює надто повільно або вичерпує пам’ять
params.num_ctx. Обмежте і бюджет OpenClaw, і контекст запиту Ollama,
щоб забезпечити передбачувану затримку до першого токена:contextWindow, якщо OpenClaw надсилає надто великий запит. Зменште
params.num_ctx, якщо контекст середовища виконання Ollama завеликий для машини.
Зменште maxTokens, якщо генерування триває надто довго.Пов’язані матеріали
Ollama Cloud
ollama-cloud.