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

​

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

​

Выбор бэкенда

​

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 или «записи сообщений допускают только 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? Не добавляйте прокси, который вслепую преобразует текст ответа ассистента в выполнение инструментов, — сначала исправьте шаблон чата или парсер сервера. Если модель работает только при принудительном использовании инструментов, добавьте указанное выше переопределение params.extra_body.tool_choice: "required" и используйте эту запись модели только для сеансов, в которых вызов инструмента ожидается при каждом обращении.
• Безопасность: локальные модели не используют фильтры на стороне провайдера. Ограничивайте область действий агентов и не отключайте Compaction, чтобы уменьшить потенциальный ущерб от внедрения инструкций в запрос.

​

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

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