diff --git a/docs/uk/gateway/local-models.md b/docs/uk/gateway/local-models.md index 5204bf572..2aa64ade8 100644 --- a/docs/uk/gateway/local-models.md +++ b/docs/uk/gateway/local-models.md @@ -1,30 +1,30 @@ --- read_when: - - Ви хочете обслуговувати моделі зі свого власного GPU-сервера + - Ви хочете обслуговувати моделі з власної машини з GPU - Ви налаштовуєте LM Studio або проксі, сумісний з OpenAI - Вам потрібні найбезпечніші рекомендації щодо локальної моделі -summary: Запускайте OpenClaw на локальних LLM (LM Studio, vLLM, LiteLLM, власні кінцеві точки OpenAI) +summary: Запускайте OpenClaw на локальних великих мовних моделях (LM Studio, vLLM, LiteLLM, користувацькі кінцеві точки OpenAI) title: Локальні моделі x-i18n: - generated_at: "2026-04-29T10:40:32Z" + generated_at: "2026-04-30T07:38:24Z" model: gpt-5.5 provider: openai - source_hash: 2ec1be4eac371328c1efe80b71450019f68fb1114df90db1532a4ff72bfa0ab1 + source_hash: 283da11a7896c670d3a249eeb957a252cbda7f7457bd814bb0796f3ca9956723 source_path: gateway/local-models.md workflow: 16 --- -Локально можливо, але OpenClaw очікує великий контекст і сильний захист від prompt injection. Малі карти обрізають контекст і погіршують безпеку. Орієнтуйтеся високо: **≥2 максимально укомплектовані Mac Studios або еквівалентна GPU-система (~$30k+)**. Один GPU на **24 GB** працює лише для легших промптів із більшою затримкою. Використовуйте **найбільший / повнорозмірний варіант моделі, який можете запустити**; агресивно квантизовані або “малі” checkpoints підвищують ризик prompt injection (див. [Безпека](/uk/gateway/security)). +Локальний запуск можливий, але OpenClaw очікує великий контекст і сильний захист від prompt injection. Малі карти обрізають контекст і погіршують безпеку. Цільтеся високо: **≥2 максимально укомплектовані Mac Studio або еквівалентна GPU-система (~$30k+)**. Один GPU на **24 GB** підходить лише для легших промптів із вищою затримкою. Використовуйте **найбільший / повнорозмірний варіант моделі, який можете запустити**; агресивно квантизовані або “малі” checkpoints підвищують ризик prompt injection (див. [Безпека](/uk/gateway/security)). -Якщо вам потрібне локальне налаштування з найменшим тертям, почніть із [LM Studio](/uk/providers/lmstudio) або [Ollama](/uk/providers/ollama) і `openclaw onboard`. Ця сторінка — практичний посібник для потужніших локальних стеків і власних локальних серверів, сумісних з OpenAI. +Якщо вам потрібне локальне налаштування з найменшим тертям, почніть з [LM Studio](/uk/providers/lmstudio) або [Ollama](/uk/providers/ollama) і `openclaw onboard`. Ця сторінка — позиційний посібник для висококласних локальних стеків і власних локальних серверів, сумісних з OpenAI. -**Користувачі WSL2 + Ollama + NVIDIA/CUDA:** офіційний інсталятор Ollama для Linux вмикає systemd-сервіс із `Restart=always`. У GPU-налаштуваннях WSL2 автозапуск може перезавантажити останню модель під час запуску системи й закріпити пам’ять хоста. Якщо ваша WSL2 VM багаторазово перезапускається після ввімкнення Ollama, див. [цикл аварійного перезапуску WSL2](/uk/providers/ollama#wsl2-crash-loop-repeated-reboots). +**Користувачі WSL2 + Ollama + NVIDIA/CUDA:** офіційний Linux-інсталятор Ollama вмикає systemd-сервіс із `Restart=always`. У WSL2 GPU-налаштуваннях автозапуск може повторно завантажити останню модель під час boot і закріпити пам’ять хоста. Якщо ваша WSL2 VM неодноразово перезапускається після ввімкнення Ollama, див. [цикл падіння WSL2](/uk/providers/ollama#wsl2-crash-loop-repeated-reboots). ## Рекомендовано: LM Studio + велика локальна модель (Responses API) -Найкращий поточний локальний стек. Завантажте велику модель у LM Studio (наприклад, повнорозмірну збірку Qwen, DeepSeek або Llama), увімкніть локальний сервер (типово `http://127.0.0.1:1234`) і використовуйте Responses API, щоб тримати міркування окремо від фінального тексту. +Найкращий поточний локальний стек. Завантажте велику модель у LM Studio (наприклад, повнорозмірну збірку Qwen, DeepSeek або Llama), увімкніть локальний сервер (типово `http://127.0.0.1:1234`) і використовуйте Responses API, щоб тримати reasoning окремо від фінального тексту. ```json5 { @@ -64,15 +64,15 @@ x-i18n: **Контрольний список налаштування** - Установіть LM Studio: [https://lmstudio.ai](https://lmstudio.ai) -- У LM Studio завантажте **найбільшу доступну збірку моделі** (уникайте “малих”/сильно квантизованих варіантів), запустіть сервер, підтвердьте, що `http://127.0.0.1:1234/v1/models` її показує. -- Замініть `my-local-model` фактичним ID моделі, показаним у LM Studio. -- Тримайте модель завантаженою; холодне завантаження додає затримку старту. +- У LM Studio завантажте **найбільшу доступну збірку моделі** (уникайте “малих”/сильно квантизованих варіантів), запустіть сервер і підтвердьте, що `http://127.0.0.1:1234/v1/models` показує її у списку. +- Замініть `my-local-model` на фактичний ID моделі, показаний у LM Studio. +- Тримайте модель завантаженою; холодне завантаження додає затримку запуску. - Налаштуйте `contextWindow`/`maxTokens`, якщо ваша збірка LM Studio відрізняється. -- Для WhatsApp дотримуйтеся Responses API, щоб надсилався лише фінальний текст. +- Для WhatsApp дотримуйтеся Responses API, щоб надсилати лише фінальний текст. -Тримайте розміщені моделі налаштованими навіть під час локального запуску; використовуйте `models.mode: "merge"`, щоб резервні варіанти лишалися доступними. +Тримайте hosted-моделі налаштованими навіть під час локального запуску; використовуйте `models.mode: "merge"`, щоб fallback-и залишалися доступними. -### Гібридна конфігурація: розміщена основна, локальна резервна +### Гібридна конфігурація: hosted основна, локальна fallback ```json5 { @@ -113,21 +113,22 @@ x-i18n: } ``` -### Насамперед локально, з розміщеною захисною сіткою +### Локальна основна з hosted підстрахуванням -Поміняйте порядок основної та резервної моделей; залиште той самий блок providers і `models.mode: "merge"`, щоб можна було перейти на Sonnet або Opus, коли локальна машина недоступна. +Поміняйте місцями порядок основної моделі та fallback; залиште той самий блок providers і `models.mode: "merge"`, щоб можна було відкотитися до Sonnet або Opus, коли локальна машина недоступна. -### Регіональне розміщення / маршрутизація даних +### Регіональний hosting / маршрутизація даних -- Розміщені варіанти MiniMax/Kimi/GLM також існують на OpenRouter з прив’язаними до регіону endpoint-ами (наприклад, розміщеними в США). Виберіть там регіональний варіант, щоб утримувати трафік у вибраній юрисдикції, водночас використовуючи `models.mode: "merge"` для резервних варіантів Anthropic/OpenAI. -- Варіант лише локально лишається найсильнішим шляхом для приватності; розміщена регіональна маршрутизація — це компроміс, коли потрібні можливості провайдера, але ви хочете контролювати потік даних. +- Hosted-варіанти MiniMax/Kimi/GLM також доступні на OpenRouter із region-pinned endpoints (наприклад, hosted у США). Виберіть там регіональний варіант, щоб утримувати трафік у вибраній юрисдикції, і водночас використовуйте `models.mode: "merge"` для fallback-ів Anthropic/OpenAI. +- Тільки локальний режим залишається найсильнішим шляхом приватності; hosted регіональна маршрутизація — це середній варіант, коли вам потрібні можливості провайдера, але потрібен контроль над потоком даних. ## Інші локальні проксі, сумісні з OpenAI MLX (`mlx_lm.server`), vLLM, SGLang, LiteLLM, OAI-proxy або власні -gateways працюють, якщо вони надають endpoint OpenAI-стилю `/v1/chat/completions`. -Використовуйте адаптер Chat Completions, якщо бекенд явно не документує -підтримку `/v1/responses`. Замініть блок provider вище на ваш endpoint і ID моделі: +gateways працюють, якщо вони відкривають OpenAI-style `/v1/chat/completions` +endpoint. Використовуйте адаптер Chat Completions, якщо backend явно не +документує підтримку `/v1/responses`. Замініть наведений вище блок provider на ваш +endpoint і ID моделі: ```json5 { @@ -162,66 +163,66 @@ gateways працюють, якщо вони надають endpoint OpenAI-ст ``` Якщо `api` пропущено у власному provider з `baseUrl`, OpenClaw типово використовує -`openai-completions`. Loopback endpoint-и, як-от `127.0.0.1`, автоматично -вважаються довіреними; endpoint-и LAN, tailnet і приватного DNS усе ще потребують +`openai-completions`. Loopback endpoints, такі як `127.0.0.1`, вважаються довіреними +автоматично; LAN, tailnet і private DNS endpoints усе ще потребують `request.allowPrivateNetwork: true`. Значення `models.providers..models[].id` є локальним для provider. Не додавайте туди префікс provider. Наприклад, сервер MLX, запущений із -`mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit`, має використовувати -такий catalog id і model ref: +`mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit`, має використовувати цей +catalog id і model ref: - `models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"` - `agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"` -Установіть `input: ["text", "image"]` для локальних або проксійованих vision-моделей, щоб -зображення-вкладення додавалися в ходи агента. Інтерактивне onboarding власного provider -визначає поширені ID vision-моделей і питає лише про невідомі назви. -Неінтерактивне onboarding використовує те саме визначення; використовуйте `--custom-image-input` -для невідомих vision ID або `--custom-text-input`, коли модель із назвою, схожою на відому, +Установіть `input: ["text", "image"]` для локальних або proxied vision-моделей, щоб image +attachments вставлялися в agent turns. Інтерактивне onboarding власного provider +виводить поширені ID vision-моделей і запитує лише невідомі імена. +Неінтерактивне onboarding використовує те саме виведення; використовуйте `--custom-image-input` +для невідомих vision ID або `--custom-text-input`, коли модель, що виглядає відомою, є text-only за вашим endpoint. -Тримайте `models.mode: "merge"`, щоб розміщені моделі лишалися доступними як резервні. +Тримайте `models.mode: "merge"`, щоб hosted-моделі залишалися доступними як fallback-и. Використовуйте `models.providers..timeoutSeconds` для повільних локальних або віддалених -серверів моделей перед підвищенням `agents.defaults.timeoutSeconds`. Тайм-аут provider -застосовується лише до HTTP-запитів моделі, включно з підключенням, headers, body streaming -і загальним guarded-fetch abort. +серверів моделей перед підвищенням `agents.defaults.timeoutSeconds`. Таймаут provider +застосовується лише до HTTP-запитів моделі, включно з connect, headers, body streaming +і повним guarded-fetch abort. -Для власних provider, сумісних з OpenAI, збереження несекретного локального маркера, як-от `apiKey: "ollama-local"`, приймається, коли `baseUrl` вказує на loopback, приватну LAN, `.local` або bare hostname. OpenClaw обробляє його як валідні локальні облікові дані, а не повідомляє про відсутній ключ. Використовуйте справжнє значення для будь-якого provider, який приймає публічний hostname. +Для власних провайдерів, сумісних з OpenAI, збереження несекретного локального маркера, такого як `apiKey: "ollama-local"`, приймається, коли `baseUrl` резолвиться в loopback, private LAN, `.local` або bare hostname. OpenClaw трактує його як дійсні локальні облікові дані замість повідомлення про відсутній ключ. Використовуйте справжнє значення для будь-якого provider, який приймає public hostname. -Примітка щодо поведінки для локальних/проксійованих `/v1` бекендів: +Нотатка про поведінку для локальних/proxied `/v1` backend-ів: -- OpenClaw обробляє їх як proxy-style маршрути, сумісні з OpenAI, а не як нативні - endpoint-и OpenAI -- нативне лише для OpenAI формування запитів тут не застосовується: без - `service_tier`, без Responses `store`, без формування payload для OpenAI reasoning-compat - і без підказок prompt-cache +- OpenClaw трактує їх як proxy-style OpenAI-compatible routes, а не native + OpenAI endpoints +- native OpenAI-only request shaping тут не застосовується: без + `service_tier`, без Responses `store`, без OpenAI reasoning-compat payload + shaping і без prompt-cache hints - приховані attribution headers OpenClaw (`originator`, `version`, `User-Agent`) - не додаються до цих власних proxy URL + не вставляються на ці власні proxy URLs -Примітки щодо сумісності для суворіших бекендів, сумісних з OpenAI: +Нотатки сумісності для суворіших backend-ів, сумісних з OpenAI: -- Деякі сервери приймають у Chat Completions лише рядковий `messages[].content`, а не - структуровані масиви content-part. Установіть +- Деякі сервери приймають лише рядковий `messages[].content` у Chat Completions, а не + structured content-part arrays. Установіть `models.providers..models[].compat.requiresStringContent: true` для - таких endpoint-ів. -- Деякі локальні моделі виводять окремі інструментальні запити в квадратних дужках як текст, наприклад - `[tool_name]`, за яким іде JSON і `[END_TOOL_REQUEST]`. OpenClaw перетворює - їх на справжні виклики інструментів лише коли назва точно збігається із зареєстрованим - інструментом для цього ходу; інакше блок обробляється як непідтримуваний текст і - приховується з видимих для користувача відповідей. -- Якщо модель виводить JSON, XML або ReAct-style текст, схожий на виклик інструмента, - але provider не видав структурований виклик, OpenClaw залишає це як - текст і записує попередження з run id, provider/model, виявленим шаблоном і - назвою інструмента, коли вона доступна. Вважайте це несумісністю tool-call - provider/model, а не завершеним запуском інструмента. -- Якщо інструменти з’являються як текст асистента замість виконання, наприклад сирий JSON, + таких endpoints. +- Деякі локальні моделі виводять окремі bracketed tool requests як текст, наприклад + `[tool_name]`, далі JSON і `[END_TOOL_REQUEST]`. OpenClaw підвищує + їх до справжніх tool calls лише тоді, коли ім’я точно збігається із зареєстрованим + інструментом для цього turn; інакше блок трактується як непідтримуваний текст і + приховується з видимих користувачу відповідей. +- Якщо модель виводить JSON, XML або ReAct-style текст, що схожий на tool call, + але provider не вивів structured invocation, OpenClaw залишає це як + текст і записує warning з run id, provider/model, виявленим pattern і + назвою інструмента, коли вона доступна. Розглядайте це як несумісність tool-call + provider/model, а не як завершений запуск інструмента. +- Якщо інструменти з’являються як assistant text замість запуску, наприклад raw JSON, XML, ReAct syntax або порожній масив `tool_calls` у відповіді provider, - спершу перевірте, що сервер використовує chat template/parser із підтримкою tool-call. Для - OpenAI-compatible Chat Completions бекендів, parser яких працює лише коли використання інструментів - примусове, задайте per-model request override замість покладання на текстовий + спочатку перевірте, що сервер використовує chat template/parser із підтримкою tool-call. Для + backend-ів OpenAI-compatible Chat Completions, чий parser працює лише коли tool + use примусовий, установіть per-model request override замість покладання на text parsing: ```json5 @@ -242,19 +243,19 @@ gateways працюють, якщо вони надають endpoint OpenAI-ст } ``` - Використовуйте це лише для моделей/сесій, де кожен звичайний хід має викликати інструмент. + Використовуйте це лише для моделей/сесій, де кожен звичайний turn має викликати інструмент. Це перевизначає типове proxy-значення OpenClaw `tool_choice: "auto"`. - Замініть `local/my-local-model` точним provider/model ref, показаним + Замініть `local/my-local-model` на точний provider/model ref, показаний `openclaw models list`. ```bash openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge ``` -- Якщо власна модель, сумісна з OpenAI, приймає OpenAI reasoning efforts поза - вбудованим профілем, оголосіть їх у model compat block. Додавання `"xhigh"` - тут робить рівень доступним для `/think xhigh`, session pickers, валідації Gateway і валідації `llm-task` - для налаштованого provider/model ref: +- Якщо власна модель, сумісна з OpenAI, приймає OpenAI reasoning efforts поза межами + вбудованого profile, оголосіть їх у model compat block. Додавання `"xhigh"` + тут робить так, що `/think xhigh`, session pickers, валідація Gateway і валідація `llm-task` + показують рівень для цього налаштованого provider/model ref: ```json5 { @@ -285,64 +286,64 @@ gateways працюють, якщо вони надають endpoint OpenAI-ст } ``` -- Деякі менші або суворіші локальні бекенди нестабільні з повною - формою промпта agent-runtime OpenClaw, особливо коли включено схеми інструментів. Спершу - перевірте шлях provider за допомогою легкого локального probe: +- Деякі менші або суворіші локальні backend-и нестабільні з повною + agent-runtime prompt shape OpenClaw, особливо коли включені tool schemas. Спочатку + перевірте provider path за допомогою lean local probe: ```bash openclaw infer model run --local --model --prompt "Reply with exactly: pong" --json ``` - Щоб перевірити маршрут Gateway без повної форми промпта агента, використовуйте + Щоб перевірити маршрут Gateway без повної agent prompt shape, використовуйте натомість Gateway model probe: ```bash openclaw infer model run --gateway --model --prompt "Reply with exactly: pong" --json ``` - І локальний, і Gateway model probes надсилають лише наданий промпт. Gateway - probe усе ще перевіряє маршрутизацію Gateway, auth і вибір provider, - але навмисно пропускає попередній transcript сесії, контекст AGENTS/bootstrap, - складання context-engine, інструменти та bundled MCP servers. + І локальна, і Gateway model probes надсилають лише наданий prompt. Gateway + probe все ще перевіряє Gateway routing, auth і provider selection, + але навмисно пропускає попередній session transcript, AGENTS/bootstrap context, + context-engine assembly, tools і bundled MCP servers. - Якщо це спрацьовує, але звичайні ходи агента OpenClaw завершуються помилкою, спершу спробуйте + Якщо це спрацьовує, але звичайні ходи агента OpenClaw завершуються з помилкою, спершу спробуйте `agents.defaults.experimental.localModelLean: true`, щоб прибрати важкі типові інструменти, як-от `browser`, `cron` і `message`; це експериментальний - прапорець, а не стабільне налаштування типового режиму. Див. + прапорець, а не стабільне налаштування режиму за замовчуванням. Див. [Експериментальні функції](/uk/concepts/experimental-features). Якщо це все одно не допомагає, спробуйте `models.providers..models[].compat.supportsTools: false`. -- Якщо бекенд усе ще дає збій лише на більших запусках OpenClaw, решта проблеми - зазвичай полягає в місткості upstream моделі/сервера або в помилці бекенда, а не в - транспортному рівні OpenClaw. +- Якщо бекенд усе ще дає збій лише на більших запусках OpenClaw, решта проблем + зазвичай пов’язана з потужністю зовнішньої моделі/сервера або помилкою бекенду, а не з + транспортним шаром OpenClaw. ## Усунення несправностей - Gateway може дістатися до проксі? `curl http://127.0.0.1:1234/v1/models`. -- Модель LM Studio вивантажено? Перезавантажте її; холодний старт є поширеною причиною “зависання”. +- Модель LM Studio вивантажена? Перезавантажте її; холодний старт часто спричиняє “зависання”. - Локальний сервер повідомляє `terminated`, `ECONNRESET` або закриває потік посеред ходу? - OpenClaw записує низькокардинальний `model.call.error.failureKind` плюс знімок - RSS/heap процесу OpenClaw у діагностиці. Для браку памʼяті в LM Studio/Ollama - зіставте цю часову мітку з журналом сервера або журналом аварій macOS / - jetsam, щоб підтвердити, чи було сервер моделі завершено примусово. -- OpenClaw попереджає, коли виявлене контекстне вікно менше за **32k**, і блокує роботу нижче **16k**. Якщо ви натрапили на цю попередню перевірку, збільште ліміт контексту сервера/моделі або виберіть більшу модель. + OpenClaw записує низькокардинальний `model.call.error.failureKind` разом зі + знімком RSS/heap процесу OpenClaw у діагностиці. Для тиску на пам’ять LM Studio/Ollama + зіставте цю позначку часу з журналом сервера або журналом аварій macOS / + jetsam, щоб підтвердити, чи сервер моделі було завершено. +- OpenClaw виводить порогові значення попередньої перевірки контекстного вікна з виявленого вікна моделі або з необмеженого вікна моделі, коли `agents.defaults.contextTokens` зменшує ефективне вікно. Він попереджає нижче 20% з мінімумом **8k**. Жорсткі блокування використовують поріг 10% з мінімумом **4k**, обмежений ефективним контекстним вікном, щоб завеликі метадані моделі не могли відхилити інакше допустиме користувацьке обмеження. Якщо ви натрапили на цю попередню перевірку, збільште ліміт контексту сервера/моделі або виберіть більшу модель. - Помилки контексту? Зменште `contextWindow` або збільште ліміт сервера. - OpenAI-сумісний сервер повертає `messages[].content ... expected a string`? - Додайте `compat.requiresStringContent: true` до запису цієї моделі. -- Прямі крихітні виклики `/v1/chat/completions` працюють, але `openclaw infer model run --local` - дає збій на Gemma або іншій локальній моделі? Спершу перевірте URL постачальника, посилання на модель, маркер автентифікації - та журнали сервера; локальний `model run` не включає інструменти агента. - Якщо локальний `model run` спрацьовує, але більші ходи агента дають збій, зменште - поверхню інструментів агента за допомогою `localModelLean` або `compat.supportsTools: false`. -- Виклики інструментів відображаються як сирий текст JSON/XML/ReAct або постачальник повертає - порожній масив `tool_calls`? Не додавайте проксі, який сліпо перетворює текст - асистента на виконання інструментів. Спершу виправте шаблон чату/парсер сервера. Якщо - модель працює лише коли використання інструментів примусове, додайте наведене вище помодельне - перевизначення `params.extra_body.tool_choice: "required"` і використовуйте цей запис моделі - лише для сеансів, де виклик інструмента очікується на кожному ході. -- Безпека: локальні моделі пропускають фільтри на боці постачальника; тримайте агентів вузько сфокусованими й увімкніть Compaction, щоб обмежити радіус ураження prompt injection. + Додайте `compat.requiresStringContent: true` до цього запису моделі. +- Прямі маленькі виклики `/v1/chat/completions` працюють, але `openclaw infer model run --local` + завершується з помилкою на Gemma або іншій локальній моделі? Спершу перевірте URL провайдера, посилання на модель, маркер автентифікації + і журнали сервера; локальний `model run` не містить інструментів агента. + Якщо локальний `model run` успішний, але більші ходи агента завершуються з помилкою, зменште поверхню + інструментів агента за допомогою `localModelLean` або `compat.supportsTools: false`. +- Виклики інструментів з’являються як сирий текст JSON/XML/ReAct, або провайдер повертає + порожній масив `tool_calls`? Не додавайте проксі, який сліпо перетворює текст асистента + на виконання інструментів. Спершу виправте чат-шаблон/парсер сервера. Якщо + модель працює лише тоді, коли використання інструментів примусове, додайте наведене вище перевизначення для окремої моделі + `params.extra_body.tool_choice: "required"` і використовуйте цей запис моделі + лише для сесій, де виклик інструмента очікується на кожному ході. +- Безпека: локальні моделі оминають фільтри на боці провайдера; тримайте агентів вузькоспеціалізованими й Compaction увімкненою, щоб обмежити радіус ураження ін’єкцій у промпт. -## Повʼязане +## Пов’язане -- [Довідник із конфігурації](/uk/gateway/configuration-reference) +- [Довідник конфігурації](/uk/gateway/configuration-reference) - [Відмовостійке перемикання моделей](/uk/concepts/model-failover)