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

Локальные модели вполне возможны. Но они также повышают требования к оборудованию, размеру контекста и защите от prompt injection — небольшие или агрессивно квантизованные карты обрезают контекст и ослабляют безопасность. Эта страница — практическое руководство для локальных стеков высокого уровня и пользовательских локальных серверов, совместимых с OpenAI. Для самого простого онбординга начните с LM Studio или Ollama и openclaw onboard.

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

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

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

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

Используйте Responses API (api: "openai-responses"), когда бэкенд его поддерживает (LM Studio поддерживает). В остальных случаях используйте Chat Completions (api: "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
• В LM Studio скачайте самую крупную доступную сборку модели (избегайте "small"/сильно квантизованных вариантов), запустите сервер и убедитесь, что http://127.0.0.1:1234/v1/models показывает ее в списке.
• Замените my-local-model на фактический ID модели, показанный в 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,          },        ],      },    },  },}

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

Поменяйте местами порядок основной модели и резервов; оставьте тот же блок providers и models.mode: "merge", чтобы можно было переключиться на Sonnet или Opus, когда локальная машина недоступна.

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

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

Другие OpenAI-совместимые локальные прокси

MLX (mlx_lm.server), vLLM, SGLang, LiteLLM, OAI-proxy или пользовательские Gateway работают, если они предоставляют точку доступа OpenAI-стиля /v1/chat/completions. Используйте адаптер Chat Completions, если бэкенд явно не документирует поддержку /v1/responses. Замените блок provider выше на вашу точку доступа и ID модели:

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

Если api опущен у пользовательского provider с baseUrl, OpenClaw по умолчанию использует openai-completions. Пользовательские/локальные записи provider доверяют своему точно настроенному источнику baseUrl для защищенных запросов к моделям, включая loopback, LAN, tailnet и private DNS hosts. Запросам к другим частным источникам по-прежнему нужен request.allowPrivateNetwork: true; источники metadata/link-local остаются заблокированными без явного включения. Установите false, чтобы отказаться от доверия точному источнику.

Значение models.providers.<id>.models[].id является локальным для provider. Не включайте туда префикс provider. Например, сервер MLX, запущенный с mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit, должен использовать этот ID каталога и ссылку на модель:

• 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"] для локальных или проксируемых vision-моделей, чтобы вложения изображений включались в ходы агента. Интерактивный онбординг пользовательского provider распознает распространенные ID vision-моделей и спрашивает только о неизвестных именах. Неинтерактивный онбординг использует то же распознавание; используйте --custom-image-input для неизвестных vision ID или --custom-text-input, когда модель с похожим на vision именем на вашей точке доступа работает только с текстом.

Оставьте models.mode: "merge", чтобы размещенные модели оставались доступными как резервы. Используйте models.providers.<id>.timeoutSeconds для медленных локальных или удаленных серверов моделей, прежде чем увеличивать agents.defaults.timeoutSeconds. Тайм-аут provider применяется только к HTTP-запросам модели, включая подключение, заголовки, потоковую передачу тела и общий защищенный fetch abort. Если тайм-аут агента или запуска ниже, увеличьте и этот предел, потому что тайм-ауты provider не могут продлить весь запуск агента.

Примечание о поведении для локальных/проксируемых бэкендов /v1:

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

Примечания о совместимости для более строгих OpenAI-совместимых бэкендов:

• Некоторые серверы принимают в 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.

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

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