chore(i18n): refresh uk translations

This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-30 07:39:25 +00:00
parent 3e2ecde215
commit eaff074886

View File

@ -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.
<Warning>
**Користувачі 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).
</Warning>
## Рекомендовано: 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.<id>.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.<id>.timeoutSeconds` для повільних локальних або віддалених
серверів моделей перед підвищенням `agents.defaults.timeoutSeconds`. Тайм-аут provider
застосовується лише до HTTP-запитів моделі, включно з підключенням, headers, body streaming
і загальним guarded-fetch abort.
серверів моделей перед підвищенням `agents.defaults.timeoutSeconds`. Таймаут provider
застосовується лише до HTTP-запитів моделі, включно з connect, headers, body streaming
і повним guarded-fetch abort.
<Note>
Для власних 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.
</Note>
Примітка щодо поведінки для локальних/проксійованих `/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.<provider>.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 <provider/model> --prompt "Reply with exactly: pong" --json
```
Щоб перевірити маршрут Gateway без повної форми промпта агента, використовуйте
Щоб перевірити маршрут Gateway без повної agent prompt shape, використовуйте
натомість Gateway model probe:
```bash
openclaw infer model run --gateway --model <provider/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.<provider>.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)