Локальні моделі

Локальні моделі працюють, але висувають вищі вимоги до обладнання, розміру контексту та захисту від ін’єкцій у промпт: малі або агресивно квантовані моделі обрізають контекст і оминають фільтри безпеки на боці провайдера. На цій сторінці описано продуктивніші локальні стеки та власні сервери, сумісні з OpenAI. Щоб почати з найменшими зусиллями, скористайтеся LM Studio або Ollama і виконайте openclaw onboard.

Відомості про локальні сервери, які мають запускатися лише тоді, коли вони потрібні вибраній моделі, див. у розділі Сервіси локальних моделей.

Мінімальні вимоги до обладнання

Для комфортного циклу роботи агента орієнтуйтеся на щонайменше 2 Mac Studio у максимальній конфігурації або еквівалентну систему з GPU (приблизно від $30 тис.). Один GPU з 24 ГБ пам’яті придатний лише для легших промптів і працює з вищою затримкою. Завжди запускайте найбільший або повнорозмірний варіант, який можете розмістити, — малі або сильно квантовані контрольні точки підвищують ризик ін’єкцій у промпт (див. Безпека).

Вибір серверної платформи

Використовуйте api: "openai-responses", якщо серверна платформа його підтримує (LM Studio підтримує). Інакше використовуйте api: "openai-completions". Якщо для власного провайдера з baseUrl параметр api не вказано, OpenClaw типово використовує openai-completions.

LM Studio + велика локальна модель (Responses API)

Наразі це найкращий локальний стек. Завантажте велику модель у LM Studio (повнорозмірну збірку Qwen, DeepSeek або Llama), увімкніть локальний сервер (типово http://127.0.0.1:1234) і використовуйте Responses API, щоб міркування залишалися відокремленими від остаточного тексту.

{  agents: {    defaults: {      model: { primary: "lmstudio/my-local-model" },      models: {        "anthropic/claude-opus-4-6": { alias: "Opus" },        "lmstudio/my-local-model": { alias: "Local" },      },    },  },  models: {    mode: "merge",    providers: {      lmstudio: {        baseUrl: "http://127.0.0.1:1234/v1",        apiKey: "lmstudio",        api: "openai-responses",        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,          },        ],      },    },  },}

Контрольний список налаштування:

• Установіть LM Studio: https://lmstudio.ai
• Завантажте найбільшу доступну збірку моделі (уникайте «малих» або сильно квантованих варіантів), запустіть сервер і переконайтеся, що модель наведено за адресою http://127.0.0.1:1234/v1/models.
• Замініть my-local-model фактичним ідентифікатором моделі, показаним у LM Studio.
• Не вивантажуйте модель із пам’яті: холодне завантаження збільшує затримку запуску.
• Скоригуйте contextWindow/maxTokens, якщо ваша збірка LM Studio використовує інші значення.
• Для WhatsApp використовуйте Responses API, щоб надсилався лише остаточний текст.
• Залиште models.mode: "merge", щоб розміщені моделі й надалі були доступні як резервні.

Гібридна конфігурація: розміщена основна модель, локальна резервна

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["lmstudio/my-local-model", "anthropic/claude-opus-4-6"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "lmstudio/my-local-model": { alias: "Local" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },  models: {    mode: "merge",    providers: {      lmstudio: {        baseUrl: "http://127.0.0.1:1234/v1",        apiKey: "lmstudio",        api: "openai-responses",        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,          },        ],      },    },  },}

Щоб спочатку використовувати локальну модель, а розміщену — як резервну, поміняйте місцями порядок primary/fallbacks і залиште той самий блок providers та models.mode: "merge".

Регіональне розміщення та маршрутизація даних

Розміщені варіанти MiniMax/Kimi/GLM також доступні в OpenRouter із прив’язаними до регіону кінцевими точками (наприклад, розміщеними у США). Виберіть регіональний варіант, щоб зберігати трафік у вибраній юрисдикції, і залиште models.mode: "merge" для резервних моделей Anthropic/OpenAI. Виключно локальне використання все одно забезпечує найкращу приватність; регіональна маршрутизація через розміщеного провайдера — це компромісний варіант, коли потрібні можливості провайдера, але також необхідний контроль над потоком даних.

Інші локальні проксі, сумісні з OpenAI

MLX (mlx_lm.server), vLLM, SGLang, LiteLLM, OAI-proxy або будь-який власний Gateway працюватиме, якщо він надає кінцеву точку /v1/chat/completions у стилі OpenAI. Використовуйте openai-completions, якщо в документації серверної платформи явно не заявлено підтримку /v1/responses.

{  agents: {    defaults: {      model: { primary: "local/my-local-model" },    },  },  models: {    mode: "merge",    providers: {      local: {        baseUrl: "http://127.0.0.1:8000/v1",        apiKey: "sk-local",        api: "openai-completions",        timeoutSeconds: 300,        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 120000,            maxTokens: 8192,          },        ],      },    },  },}

Записи власних або локальних провайдерів довіряють точному джерелу налаштованого baseUrl для захищених запитів до моделей, зокрема вузлам зворотного зв’язку, локальної мережі, tailnet і приватного DNS. Джерела метаданих і локального каналу завжди блокуються незалежно від налаштувань. Для запитів до інших приватних джерел усе одно потрібно встановити models.providers.<id>.request.allowPrivateNetwork: true; установіть прапорець довіри в false, щоб вимкнути довіру до точного джерела.

models.providers.<id>.models[].id є локальним для провайдера — не додавайте префікс провайдера. Для сервера MLX, запущеного командою mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit:

• 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"] для локальних або проксійованих моделей із підтримкою зображень, щоб вкладення із зображеннями додавалися до ходів агента. Інтерактивне налаштування власного провайдера розпізнає поширені ідентифікатори моделей із підтримкою зображень і ставить запитання лише щодо невідомих назв; неінтерактивне налаштування використовує таке саме розпізнавання, яке можна перевизначити за допомогою --custom-image-input / --custom-text-input.

Для повільних локальних або віддалених серверів моделей використовуйте models.providers.<id>.timeoutSeconds, перш ніж збільшувати agents.defaults.timeoutSeconds. Тайм-аут провайдера охоплює встановлення з’єднання, заголовки, потокове передавання тіла та загальне переривання захищеного отримання лише для HTTP-запитів до моделі. Якщо тайм-аут агента або запуску менший, збільште і його, оскільки тайм-аут провайдера не може подовжити весь запуск.

Примітки щодо поведінки локальних або проксійованих серверних платформ /v1:

• OpenClaw розглядає їх як проксійовані маршрути, сумісні з OpenAI, а не як нативні кінцеві точки OpenAI.
• Формування запитів, призначене лише для нативного OpenAI, не застосовується: без service_tier, без Responses store, без формування корисного навантаження сумісності міркувань OpenAI та без підказок кешу промптів.
• Приховані заголовки атрибуції OpenClaw (originator, version, User-Agent) не додаються до власних URL-адрес проксі.

Перевизначення сумісності для суворіших серверних платформ, сумісних з OpenAI:

• Лише рядковий вміст: деякі сервери приймають у messages[].content лише рядки, а не структуровані масиви частин вмісту. Установіть models.providers.<provider>.models[].compat.requiresStringContent: true.

• Суворий набір ключів повідомлення: якщо сервер відхиляє записи повідомлень, що містять ключі, відмінні від role/content, установіть compat.strictMessageKeys: true.

• Текст інструмента у квадратних дужках: деякі локальні моделі виводять окремі текстові запити до інструментів у квадратних дужках, наприклад [tool_name], після якого йдуть JSON і [END_TOOL_REQUEST]. OpenClaw перетворює їх на справжні виклики інструментів лише тоді, коли назва точно збігається з інструментом, зареєстрованим для цього ходу; інакше текст залишається прихованим і непідтримуваним.

• Неструктурований текст, схожий на виклик інструмента: якщо модель виводить текст у форматі JSON/XML/ReAct, схожий на виклик інструмента, але він не був структурованим викликом, OpenClaw залишає його текстом і записує попередження з ідентифікатором запуску, провайдером/моделлю, виявленим шаблоном та назвою інструмента, якщо вона доступна. Це несумісність провайдера або моделі, а не завершений запуск інструмента.

• Примусове використання інструментів: якщо інструменти з’являються як текст асистента (необроблений JSON/XML/ReAct або порожній масив tool_calls), спочатку переконайтеся, що шаблон або аналізатор чату сервера підтримує виклики інструментів. Якщо аналізатор працює лише за примусового використання інструментів, перевизначте типове проксійоване значення tool_choice: "auto" для відповідної моделі:

  {  agents: {    defaults: {      models: {        "local/my-local-model": {          params: {            extra_body: {              tool_choice: "required",            },          },        },      },    },  },}

  Використовуйте це лише тоді, коли кожен звичайний хід має викликати інструмент. Замініть local/my-local-model точним посиланням із openclaw models list або задайте його через CLI:

  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge

• Додаткові рівні інтенсивності міркувань: якщо власна модель, сумісна з OpenAI, приймає рівні інтенсивності міркувань OpenAI поза межами вбудованого профілю, оголосіть їх у блоці сумісності моделі. Додавання "xhigh" робить його доступним для цього посилання на модель у /think xhigh, засобах вибору сеансу, перевірці Gateway і перевірці llm-task:

  {  models: {    providers: {      local: {        baseUrl: "http://127.0.0.1:8000/v1",        apiKey: "sk-local",        api: "openai-responses",        models: [          {            id: "gpt-5.4",            name: "GPT 5.4 via local proxy",            reasoning: true,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,            compat: {              supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],              reasoningEffortMap: { xhigh: "xhigh" },            },          },        ],      },    },  },}

Менші або суворіші серверні платформи

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

1. Переконайтеся, що локальна модель відповідає — без інструментів і без контексту агента:

   openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json

2. Підтвердьте маршрутизацію Gateway — надсилає лише запит, пропускаючи транскрипт, початкове завантаження AGENTS, формування контекстним рушієм, інструменти та вбудовані сервери MCP, але все одно перевіряє маршрутизацію Gateway, автентифікацію та вибір провайдера:

   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json

3. Спробуйте полегшений режим, якщо обидві перевірки успішні, але реальні ходи агента завершуються помилкою через неправильно сформовані виклики інструментів або завеликі запити: установіть agents.defaults.experimental.localModelLean: true. Цей режим вимикає ресурсомісткі інструменти браузера, cron, повідомлень, генерування медіа, голосу та PDF, якщо вони не потрібні явно, а більші каталоги інструментів типово приховує за структурованими засобами керування пошуком інструментів, залишаючи exec безпосередньо видимим. Докладніше про це та про те, як перевірити, чи режим увімкнено, див. у розділі Експериментальні функції -> Полегшений режим локальної моделі.

4. Повністю вимкніть інструменти як крайній захід, установивши models.providers.<provider>.models[].compat.supportsTools: false для цієї моделі — після цього агент працюватиме без викликів інструментів.

5. Після цього вузьке місце перебуває у висхідній системі. Якщо після ввімкнення полегшеного режиму та supportsTools: false бекенд усе ще відмовляє лише під час великих запусків OpenClaw, проблема, що залишилася, зазвичай полягає в самій моделі або сервері — контекстному вікні, пам’яті GPU, витісненні kv-кешу чи помилці бекенду, — а не в транспортному рівні OpenClaw.

Усунення несправностей

• Gateway не може підключитися до проксі? curl http://127.0.0.1:1234/v1/models.
• Модель LM Studio вивантажено? Завантажте її повторно; холодний запуск — поширена причина «зависання».
• Локальний сервер повідомляє terminated, ECONNRESET або закриває потік посеред ходу? OpenClaw записує в діагностику низькокардинальне значення model.call.error.failureKind, а також знімок RSS/купи процесу OpenClaw. У разі тиску на пам’ять у LM Studio/Ollama зіставте цю часову позначку із журналом сервера або журналом аварійного завершення/jetsam у macOS, щоб підтвердити, чи було завершено процес сервера моделі.
• Помилки контексту? OpenClaw визначає пороги попередньої перевірки контекстного вікна на основі виявленого вікна моделі (або обмеженого вікна, якщо agents.defaults.contextTokens зменшує його), показуючи попередження нижче 20% із мінімумом 8k і жорстко блокуючи нижче 10% із мінімумом 4k (з обмеженням до ефективного контекстного вікна, щоб завеликі метадані моделі не призводили до відхилення коректного користувацького обмеження). Зменште contextWindow або збільште обмеження контексту сервера/моделі.
• messages[].content ... expected a string? Додайте compat.requiresStringContent: true до запису цієї моделі.
• validation.keys або «message entries only allow role and content»? Додайте compat.strictMessageKeys: 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 увімкненим, щоб обмежити масштаб наслідків ін’єкції запитів.

Пов’язані матеріали

• Довідник із конфігурації
• Перемикання на резервну модель