Локальные модели

​

Минимальный уровень оборудования

​

Выберите бэкенд

​

Рекомендуется: 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
• В LM Studio скачайте самую крупную доступную сборку модели (избегайте “small”/сильно квантизованных вариантов), запустите сервер и убедитесь, что http://127.0.0.1:1234/v1/models показывает ее в списке.
• Замените my-local-model на фактический ID модели, показанный в LM Studio.
• Держите модель загруженной; холодная загрузка добавляет задержку запуска.
• Скорректируйте contextWindow/maxTokens, если ваша сборка LM Studio отличается.
• Для WhatsApp используйте Responses API, чтобы отправлялся только финальный текст.

​

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

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

​

Сначала локальная модель, с размещенной страховкой

​

Региональный хостинг / маршрутизация данных

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

​

Другие 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 обрабатывает их как proxy-style OpenAI-совместимые маршруты, а не как нативные точки доступа OpenAI
• формирование запросов, предназначенное только для нативного OpenAI, здесь не применяется: нет service_tier, нет Responses store, нет формирования payload для совместимости с OpenAI reasoning и нет подсказок prompt cache
• скрытые заголовки атрибуции OpenClaw (originator, version, User-Agent) не добавляются в эти пользовательские proxy URLs

• Некоторые серверы принимают в Chat Completions только строковый messages[].content, а не структурированные массивы частей содержимого. Для таких точек доступа задайте models.providers.<provider>.models[].compat.requiresStringContent: true.
• Некоторые локальные модели выводят отдельные заключенные в скобки текстовые запросы инструментов, например [tool_name], за которым следует JSON и [END_TOOL_REQUEST]. OpenClaw преобразует их в реальные вызовы инструментов только когда имя точно совпадает с зарегистрированным инструментом для хода; иначе блок считается неподдерживаемым текстом и скрывается из видимых пользователю ответов.
• Если модель выводит JSON, XML или текст в стиле ReAct, похожий на вызов инструмента, но provider не выдал структурированный вызов, OpenClaw оставляет это как текст и пишет предупреждение с run id, provider/model, обнаруженным паттерном и именем инструмента, когда оно доступно. Считайте это несовместимостью provider/model с вызовами инструментов, а не завершенным запуском инструмента.
• Если инструменты появляются как текст ассистента вместо запуска, например raw JSON, XML, синтаксис ReAct или пустой массив tool_calls в ответе provider, сначала проверьте, что сервер использует chat template/parser с поддержкой вызовов инструментов. Для OpenAI-совместимых бэкендов Chat Completions, у которых parser работает только при принудительном использовании инструментов, задайте переопределение запроса для отдельной модели вместо зависимости от текстового парсинга:
  {
    agents: {
      defaults: {
        models: {
          "local/my-local-model": {
            params: {
              extra_body: {
                tool_choice: "required",
              },
            },
          },
        },
      },
    },
  }
  
  Используйте это только для моделей/сессий, где каждый обычный ход должен вызывать инструмент. Это переопределяет стандартное proxy-значение OpenClaw tool_choice: "auto". Замените local/my-local-model на точную ссылку provider/model, показанную openclaw models list.
  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
  
• Если пользовательская OpenAI-совместимая модель принимает OpenAI reasoning efforts за пределами встроенного профиля, объявите их в блоке compat модели. Добавление "xhigh" здесь делает уровень доступным для /think xhigh, селекторов сессий, проверки Gateway и проверки llm-task для этой настроенной ссылки provider/model:
  {
    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. Он убирает три самых тяжелых инструмента по умолчанию (browser, cron, message) и по умолчанию скрывает более крупные каталоги инструментов за структурированными элементами управления поиском инструментов, кроме запусков, которым нужно сохранить семантику прямой доставки message. Полное объяснение, когда это использовать и как подтвердить, что режим включен, см. в Экспериментальные функции → Экономный режим локальной модели.
4. Полностью отключите инструменты как крайнее средство. Если экономного режима недостаточно, задайте models.providers.<provider>.models[].compat.supportsTools: false для этой записи модели. После этого агент будет работать на этой модели без вызовов инструментов.
5. После этого узкое место находится выше по стеку. Если бэкенд по-прежнему падает только на более крупных запусках OpenClaw после экономного режима и supportsTools: false, оставшаяся проблема обычно связана с вышестоящей моделью или емкостью сервера: контекстным окном, памятью GPU, вытеснением kv-cache или ошибкой бэкенда. На этом этапе это уже не транспортный слой OpenClaw.

​

Устранение неполадок

• Gateway может подключиться к прокси? curl http://127.0.0.1:1234/v1/models.
• Модель LM Studio выгружена? Перезагрузите ее; холодный запуск часто приводит к «зависанию».
• Локальный сервер сообщает terminated, ECONNRESET или закрывает поток в середине обращения? 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 в эту запись модели.
• OpenAI-совместимый сервер возвращает validation.keys или сообщает, что записи сообщений допускают только role и 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? Не добавляйте прокси, который слепо преобразует текст ассистента в выполнение инструментов. Сначала исправьте chat template/parser сервера. Если модель работает только при принудительном использовании инструментов, добавьте приведенное выше переопределение params.extra_body.tool_choice: "required" для отдельной модели и используйте эту запись модели только для сессий, где вызов инструмента ожидается на каждом обращении.
• Безопасность: локальные модели пропускают фильтры на стороне провайдера; держите агентов узко ограниченными и включайте Compaction, чтобы ограничить радиус поражения prompt injection.

​

Связанные материалы

• Справочник по конфигурации
• Переключение моделей при сбое