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

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

Сведения о локальных серверах, которые должны запускаться только тогда, когда они нужны выбранной модели, см. в разделе Сервисы локальных моделей.

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

Для комфортного цикла работы агента ориентируйтесь на 2 или более Mac Studio в максимальной конфигурации либо эквивалентную систему с GPU (~$30k+). Один GPU с 24 GB справляется только с более простыми промптами и с большей задержкой. Всегда запускайте самый крупный / полноразмерный вариант, который позволяет ваше оборудование — небольшие или сильно квантованные контрольные точки повышают риск внедрения промптов (см. раздел Безопасность).

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

Используйте api: "openai-responses", если бэкенд это поддерживает (LM Studio поддерживает). В противном случае используйте api: "openai-completions". Если api не указан для пользовательского провайдера с baseUrl, 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 для защищенных запросов к моделям, включая loopback, LAN, tailnet и хосты частной DNS. Источники метаданных/link-local всегда блокируются независимо от настроек. Для запросов к другим частным источникам по-прежнему требуется 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 или «записи сообщений допускают только 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, чтобы уменьшить потенциальный ущерб от внедрения инструкций в запрос.

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

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