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

​

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

​

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

​

LM Studio + велика локальна модель (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,
          },
        ],
      },
    },
  },
}

​

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

​

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

{
  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,
          },
        ],
      },
    },
  },
}

• models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"
• agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"

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

• Лише рядковий вміст: деякі сервери приймають у 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 увімкненим, щоб обмежити масштаб наслідків ін’єкції запитів.

​

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

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