Ollama

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

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

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

auth-profiles.json зберігає облікові дані для ідентифікатора провайдера. Розміщуйте налаштування кінцевої точки (baseUrl, api, ідентифікатори моделей, заголовки, тайм-аути) у models.providers.<id>. Старі пласкі файли профілів автентифікації, як-от { "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 і типово не надсилається на локальні або самостійно розміщені хости.

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

ollama serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw 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 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"],      },    },  },}

Використовуйте власні ідентифікатори провайдерів, коли маєте більше ніж один сервер 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"],      },    },  },}

Коли OpenClaw надсилає запит, префікс активного провайдера вилучається, тож 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 та інструменти повідомлень із прямої поверхні агента й за замовчуванням переносить більші каталоги за структуровані елементи керування Tool Search, окрім випадків, коли запуск має зберегти семантику прямої доставки повідомлень, але це не змінює контекст середовища виконання Ollama або режим мислення. Поєднуйте це з явними params.num_ctx і params.thinking: false для малих моделей мислення в стилі Qwen, які зациклюються або витрачають бюджет відповіді на приховане міркування.

Якщо натомість потрібно використати сумісну з OpenAI кінцеву точку (наприклад, за проксі, який підтримує лише формат 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 — це бюджет підказки й Compaction в OpenClaw. Нативні запити Ollama залишають options.num_ctx незаданим, якщо ви явно не налаштуєте params.num_ctx, тож Ollama може застосувати власне типове значення моделі, OLLAMA_CONTEXT_LENGTH або типове значення на основі VRAM. Щоб обмежити або примусово задати контекст виконання Ollama для окремого запиту без перебудови Modelfile, задайте params.num_ctx; недійсні, нульові, від’ємні та нескінченні значення ігноруються. Якщо ви оновили старішу конфігурацію, яка використовувала лише contextWindow або maxTokens, щоб примусово задати контекст нативного запиту Ollama, запустіть openclaw doctor --fix, щоб скопіювати ці явні бюджети провайдера або моделі в params.num_ctx. OpenAI-сумісний адаптер Ollama досі типово вставляє options.num_ctx із налаштованого params.num_ctx або contextWindow; вимкніть це за допомогою injectNumCtxForOpenAICompat: false, якщо ваш upstream відхиляє options.

Записи нативних моделей Ollama також приймають поширені параметри виконання Ollama в params, зокрема temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread і use_mmap. OpenClaw пересилає лише ключі запитів Ollama, тому параметри виконання 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 offopenclaw agent --model ollama/gemma4 --thinking low

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

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

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

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

ollama pull deepseek-r1:32b

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

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

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

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

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

Інтеграція Ollama в OpenClaw типово використовує нативний 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-модуль 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=5mollama 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 installedollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Or another model

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

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

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

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

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

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

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

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

{  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 і, за бажання, попросіть Ollama тримати модель завантаженою між ходами:

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

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

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