Настройка LLM в OpenClaw: провайдеры, Ollama и LM Studio

Чтобы подключить LLM к OpenClaw, выполните openclaw onboard на машине, где работает Gateway, выберите провайдера и способ авторизации, затем установите доступную модель командой openclaw models set PROVIDER/MODEL. Для локальной работы подойдут отдельные подключения Ollama, LM Studio или vLLM: их адреса API и правила обнаружения моделей различаются. После настройки проверьте не только каталог, но и ответ выбранной модели, а затем безопасный вызов инструмента.

Если у вас уже есть работающая конфигурация, начните с openclaw models status и /model status в нужном чате. Добавление аккаунта не обязательно меняет модель по умолчанию, а изменение модели по умолчанию не снимает закреплённый выбор в старой сессии. Это частая причина ситуации «подключил новую модель, но отвечает прежняя».

Ниже приведён порядок настройки по официальной документации, проверенной 4 октября 2026 года. Команды вызова модели и проверки авторизации здесь не выполнялись на реальных аккаунтах; успешный результат нужно подтвердить на вашем Gateway.

Что выбрать: облачный API или локальный сервер

Выбирайте подключение по тому, где должна выполняться модель и какой аккаунт будет оплачивать запросы. Название модели не отвечает на эти вопросы. Например, Claude через API Anthropic, нативный Claude CLI и Claude через Bedrock используют разные способы доступа.

Локальная модель позволяет выполнять инференс на вашем оборудовании. Но размер модели в миллиардах параметров не определяет требования к памяти сам по себе: важны квантизация, длина контекста, реализация сервера и одновременно загруженные модели. Начните с модели, которую ваш сервер действительно может загрузить с нужным контекстом, затем проверьте небольшой рабочий сценарий. Универсальной таблицы «16 ГБ = такая модель и такая скорость» для OpenClaw нет.

Если данные должны оставаться внутри вашей инфраструктуры, проверяйте весь рабочий процесс: инструменты, плагины, поиск, эмбеддинги памяти, вспомогательные модели и резервные облачные подключения тоже могут отправлять данные наружу. В Ollama режим Cloud + Local и модели с суффиксом :cloud включают удалённый инференс. Локальный адрес сервера сам по себе не означает локальную обработку каждого запроса. Правила режимов Ollama.

Настройте аккаунт и модель на правильной машине

Все следующие команды OpenClaw выполняйте от имени пользователя, под которым работает служба Gateway. Если сервер моделей запущен на ноутбуке, а Gateway — в контейнере или на другом компьютере, подключение нужно проверить из среды Gateway. Адрес «этого компьютера» внутри контейнера относится к контейнеру.

Сначала посмотрите текущую конфигурацию:

openclaw --version
openclaw gateway status
openclaw models status

Затем запустите интерактивный мастер:

openclaw onboard

Выберите встроенного провайдера, подключите аккаунт или сервер и завершите выбор модели. Для добавления поддерживаемого аккаунта в панели доступен Settings → Models → Connect provider. Этот вход сохраняет подключение; Test & use предназначен для проверки модели и её выбора. Инструкция подключения аккаунтов.

После завершения мастера посмотрите доступные модели:

openclaw models list
openclaw models status

Чтобы намеренно изменить глобальную модель по умолчанию, выполните openclaw models set с точной ссылкой из каталога. Например, если в вашем локальном каталоге есть ollama/gemma4:

openclaw models set ollama/gemma4

Здесь gemma4 — пример из официальной инструкции, а не обещание подходящего размера или качества для вашего компьютера. Не выбирайте модель только потому, что её имя есть в примере.

Не смешивайте токен Gateway и ключ модели

Токен Gateway разрешает клиенту подключаться к OpenClaw. Ключ API или вход провайдера разрешает вызывать модель. Это разные учётные данные: успешное подключение панели не доказывает, что модель принимает ключ.

Для постоянно работающей службы удобно сохранять доступ через мастер. Если используете переменную окружения, убедитесь, что её видит именно процесс службы: export в отдельном терминале не меняет окружение уже запущенного Gateway. Официальная инструкция также описывает ~/.openclaw/.env для учётных данных, которые должна читать служба, с последующим перезапуском. Авторизация Gateway и моделей.

В текущей версии общие учётные данные хранятся в SQLite, а агент может иметь локальное переопределение. Старый auth-profiles.json не следует копировать между агентами как действующее хранилище. При диагностике явно укажите нужного агента:

openclaw models status --agent main --json

Замените main вашим идентификатором. Эта команда показывает настройки и авторизацию агента, а /model status в чате — выбор конкретной сессии. Правила хранения, справочник статуса.

Подключение облачных моделей: точный способ доступа важнее названия

Для нового подключения используйте встроенный вариант провайдера. Произвольная замена baseUrl может превратить нативное подключение в совместимый API с другими возможностями.

В текущем OpenClaw openai — канонический провайдер и для API-ключа, и для входа ChatGPT/Codex. Старые ссылки openai-codex/* относятся к конфигурации, которую переносит openclaw doctor --fix. Префикс openai/* сам по себе не выбирает Codex и не определяет способ оплаты. На подходящем официальном HTTPS-подключении Codex может выбираться автоматически; совместимый прокси не наследует это поведение. Настройка OpenAI, разделение провайдера и runtime.

На сервере без удобного браузерного обратного вызова для OpenAI предусмотрен вход по коду устройства:

openclaw models auth login --provider openai --device-code
openclaw models list --provider openai

Наличие подписки не гарантирует доступ к любой модели. Выбирайте точный ID из каталога вошедшего аккаунта. Добавление или повторный вход сохраняет существующую модель по умолчанию, если вы отдельно не выбрали её замену.

Для Claude CLI предварительно проверьте на машине Gateway:

claude --version
claude auth status --text

Если вход отсутствует, выполните claude auth login от имени пользователя службы, затем выберите Claude CLI через openclaw onboard. Нативным входом управляет Claude Code; это отдельный способ выполнения, а не копия ключа Anthropic. Для постоянно работающего сервера официальная инструкция рекомендует ключ API как наиболее предсказуемый вариант. Подключение Anthropic.

Для Gemini используйте поддерживаемый ключ AI Studio либо отдельно настроенный Vertex. Нативный google-gemini-cli — настройка способа выполнения канонической модели google/*; новый вход Gemini CLI/Antigravity OAuth текущий мастер не предлагает. Bedrock тоже нельзя настроить ключом Anthropic: он использует подключение AWS. Google, Bedrock.

Как подключить Ollama локально

Для первого подключения установите Ollama с официальной страницы загрузки на той же машине, где будет доступен сервер модели. Убедитесь, что приложение или служба Ollama запущены. Если используете ручной запуск и сервер ещё не работает, выполните ollama serve в отдельном терминале.

Посмотрите установленные и загруженные модели:

ollama list
ollama ps

Если нужной модели нет на диске, загрузите выбранную модель. Пример из документации:

ollama pull gemma4

Загрузка потребует места на диске и доступа к источнику весов. Установленная модель ещё не обязательно загружена в память.

На машине Gateway запустите:

openclaw onboard

Выберите Ollama → Local only, подтвердите адрес своего сервера и выберите модель. Для сервера на той же машине мастер предлагает локальное подключение; для сервера в сети нужен адрес, реально доступный из среды Gateway.

На свежей автоматической настройке OpenClaw сначала рассматривает модели, уже загруженные в память по /api/ps. Через /api/show он проверяет поддержку инструментов и контекст не меньше 16K. Установленная, но простаивающая модель не становится автоматическим кандидатом. В настольной настройке можно явно выбрать Choose connection → Local only: этот путь позволяет подготовить подходящую установленную модель к проверке. Мастер сохраняет выбранное подключение после настоящего ответа модели, а не после одного обнаружения. Условия первоначальной настройки Ollama.

После мастера проверьте результат:

openclaw models list --provider ollama
openclaw models status

Для ручного подключения Ollama на той же машине официальная инструкция допускает маркер:

export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4

Этот пример предполагает установленную gemma4, работающий сервер и окружение, доступное нужному процессу. ollama-local — несекретный маркер для локального или частного сетевого сервера, а не ключ к публичному Ollama Cloud. Публичный удалённый сервер и ollama.com требуют настоящих учётных данных; для прямого облачного подключения предусмотрен отдельный провайдер ollama-cloud.

Почему Ollama не видит модель или не вызывает инструменты

Общее обнаружение каталога и первоначальный автоматический выбор — разные процедуры. Неявный каталог использует /api/tags и /api/show. Непустой список models.providers.ollama.models включает ручное описание моделей и отключает такое обнаружение. Проверьте точное имя и тег из ollama list; не подменяйте их похожим названием с сайта модели. Обнаружение Ollama.

Для нативного Ollama используйте api: "ollama" и базовый адрес без /v1. Нативные запросы идут через /api/chat и поддерживают потоковый вывод вместе с вызовами инструментов. Старый совместимый режим /v1 имеет другие ограничения; совет «выключить streaming для любого Ollama» неверен. Конфигурация, потоковый вывод.

Как подключить LM Studio и нужен ли ему API key

Если авторизация сервера LM Studio отключена, оставьте ключ пустым в мастере OpenClaw. Если включена, используйте токен этого сервера через LM_API_TOKEN. Не вставляйте ключ OpenAI только потому, что LM Studio предоставляет совместимый API. Официальная инструкция LM Studio.

Установите LM Studio или его headless-вариант llmster, скачайте подходящую модель и запустите сервер. При доступном CLI lms:

lms server start --port 1234

Для headless-демона инструкция также предусматривает lms daemon up. Затем на машине Gateway выполните:

openclaw onboard

Выберите LM Studio, укажите адрес запущенного сервера, настройте ключ только при включённой авторизации и выберите модель в Default model. Если приложение и Gateway находятся на одной машине, используйте предложенное локальное подключение.

LM Studio обнаруживает модели через нативный /api/v1/models и загружает их через /api/v1/models/load; обычный инференс выполняется через совместимый /v1/chat/completions. Поэтому /v1 в адресе инференса LM Studio нужно сохранять — правило Ollama «без /v1» сюда не переносится.

Ключ модели LM Studio может содержать собственный слэш, например qwen/qwen3.5-9b. OpenClaw добавляет перед ним свой префикс:

openclaw models list --provider lmstudio
openclaw models set lmstudio/qwen/qwen3.5-9b

Пример применим только если сервер возвращает этот ключ. Используйте значение key из нативного каталога LM Studio или точную ссылку, показанную мастером и каталогом OpenClaw.

Автоматический выбор требует модели, для которой LM Studio сообщает обучение работе с инструментами и эффективный контекст не меньше 16K. У уже загруженной модели учитывается контекст загруженного экземпляра, даже если паспорт модели обещает больше. Если подходящая модель не предлагается, проверьте контекст и поддержку инструментов, а не только наличие файла весов.

По умолчанию OpenClaw предварительно загружает модель. Если хотите, чтобы загрузкой управляли LM Studio JIT, время простоя TTL и автоудаление из памяти, настройка models.providers.lmstudio.params.preload: false отключает эту предварительную загрузку. Это выбор управления памятью, а не исправление любой ошибки подключения.

LM Studio на другом компьютере

Сервер должен слушать доступный сетевой интерфейс, а не только локальные подключения на своей машине. Проверьте привязку сервера, разрешённый доступ и доступность порта с машины Gateway. Простая замена имени в конфигурации не меняет привязку LM Studio.

Например, следующий фрагмент относится к сети, где имя gpu-box.local действительно разрешается в адрес сервера, сервер доступен Gateway на порту 1234 и авторизация LM Studio отключена:

{
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://gpu-box.local:1234/v1",
        apiKey: "lmstudio",
        api: "openai-completions",
        models: [{ id: "qwen/qwen3.5-9b" }],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "lmstudio/qwen/qwen3.5-9b" },
    },
  },
}

Это фрагмент для объединения с существующей конфигурацией, не весь файл OpenClaw. Замените имя сервера и ID модели своими проверенными значениями. При включённой авторизации вместо маркера нужен действующий токен LM Studio. Проверить нативный каталог для данного сетевого примера можно с машины Gateway:

curl --fail http://gpu-box.local:1234/api/v1/models

Ответ каталога подтверждает сетевую доступность и список моделей, но ещё не доказывает успешное выполнение агентной задачи.

vLLM и собственный совместимый API

Если vLLM уже установлен и обслуживает модель, OpenClaw подключается к нему как vllm через api: "openai-completions". Сервер должен предоставлять /v1/models и /v1/chat/completions.

Для неявного обнаружения моделей стандартного локального сервера задайте VLLM_API_KEY. Если сервер не проверяет авторизацию, допустим несекретный маркер:

export VLLM_API_KEY="vllm-local"
openclaw models list --provider vllm

Если сервер требует ключ, используйте настоящий ключ именно vLLM. Затем задайте openclaw models set с префиксом vllm/ и точным ID из каталога. Для другого адреса, порта или ручных моделей требуется запись models.providers.vllm с /v1 в baseUrl. Подключение vLLM.

Для собственного прокси используйте отдельный ID провайдера в models.providers, укажите его baseUrl, соответствующий адаптер api, учётные данные и точные models[].id. Запись только в agents.defaults.models даёт псевдоним или параметры, но не регистрирует новую модель для выполнения. Совместимый API не наследует все нативные возможности OpenAI или Anthropic. Собственные провайдеры.

Не добавляйте предполагаемые возможности «на всякий случай». contextWindow описывает собственное окно модели, contextTokens ограничивает активный вход OpenClaw, maxTokens ограничивает выход. Они должны соответствовать реальному серверу. Значение cost: 0 в метаданных не подтверждает нулевую оплату.

Отдельно проверьте вызовы инструментов. vLLM нужны подходящие модели, парсер вызовов и шаблон чата. Напечатанный моделью JSON с именем инструмента — ещё не структурированный вызов, который OpenClaw может выполнить. Не переносите tool_choice: "required" из инструкции для другой комбинации модели и сервера как универсальное исправление.

Модель по умолчанию, выбор в сессии и резервные модели

Модель по умолчанию и явно выбранная модель в чате имеют разные правила отказа. Это важно и для диагностики, и для конфиденциальности.

Сначала OpenClaw применяет ограниченное восстановление подходящих временных ошибок и ротацию учётных данных внутри провайдера. Затем, если политика разрешает, переходит к следующей модели. В текущем поведении успешный резерв используется для данного хода, не заменяя выбранную модель сессии навсегда. Тайм-аут всего запуска, отмена или исчерпание ограничений могут остановить цепочку. Текущие правила переключения.

Посмотреть или дополнить глобальную цепочку можно командами:

openclaw models fallbacks list
openclaw models fallbacks add ollama/gemma4
openclaw models status

Добавляйте ollama/gemma4 только после настройки и проверки этой модели. Для агента со своей основной моделью отдельно задайте его model.fallbacks; пустой массив [] явно отключает переключение. Глобальные команды управления defaults не заменяют настройку такого агента.

В активном чате проверьте и при необходимости снимите старый выбор:

/model status
/model default

Если хотите испытать конкретную локальную модель без скрытого облачного резерва, выберите её явно, например /model ollama/gemma4, и подтвердите выбор через /model status. Это не гарантирует отсутствие внешних обращений других компонентов OpenClaw, но делает выбор самой модели строгим.

Резервная цепочка не распределяет простые задачи на дешёвые модели автоматически и не гарантирует непрерывную работу. Для намеренного разделения затрат выбирайте модель явно или настраивайте отдельных агентов. Если резерв облачный, содержимое запроса при переключении может обрабатываться вне вашего локального сервера. Если перед отказом уже был запущен инструмент, проверьте его результат перед повтором задания.

Как проверить настройку: каталог, ответ и инструмент

Проверяйте последовательно: каждый следующий шаг подтверждает то, чего не доказал предыдущий.

1. Сервер и каталог. Для Ollama посмотрите ollama list и ollama ps на машине сервера; для LM Studio убедитесь, что сервер запущен. На машине Gateway выполните openclaw models list --provider ollama или соответствующий вариант для lmstudio/vllm. Строка каталога подтверждает наличие описания модели, а не успешный запрос.
2. Агент и сессия. Выполните openclaw models status --agent main --json, заменив main нужным ID. В соответствующем чате отправьте /model status. Сопоставьте модель, аккаунт и способ выполнения. Статус без пробы не вызывает модель.
3. Короткий ответ. В этой же сессии попросите: «Ответь одним словом: готово». Убедитесь, что ответила выбранная модель. Запрос к облачной модели может расходовать оплачиваемые токены; при использовании модели по умолчанию посмотрите, не ответил ли резерв.
4. Безопасный инструмент. Создайте в отдельной тестовой папке файл openclaw-check.txt с известной вам строкой. Если агенту разрешён доступ к этой папке и инструмент чтения, попросите: «Прочитай openclaw-check.txt с помощью инструмента, верни его содержимое и ничего не меняй». Проверьте событие реального вызова инструмента и совпадение текста. Рассказ модели «я прочитал файл» без выполненного вызова не является успехом.

Если короткий ответ работает, а чтение файла нет, проверьте права и доступность инструмента, затем поддержку структурированных вызовов у модели и сервера. Только после этого переходите к небольшому рабочему заданию. Такой тест не измеряет скорость или качество модели в общем, зато отделяет подключение от работы агента.

Для узкой проверки только текста Ollama документация предлагает:

openclaw infer model run \
  --local \
  --model ollama/gemma4 \
  --prompt "Reply with exactly: pong" \
  --json

Пример предполагает настроенную и доступную модель. Этот путь не загружает инструменты чата, память и контекст сессии. Успешный pong не заменяет проверку чтения файла. Область такой проверки.

Когда нужна отдельная проверка авторизации через --probe

openclaw models status --check проверяет состояние авторизации и способа выполнения, но код 0 не доказывает успешный вызов. --probe делает реальные запросы и может расходовать токены или затрагивать лимиты. По текущей инструкции CLI, прямая проба требует исключительного доступа к каталогу состояния: сначала остановите Gateway.

Например, для проверки настроенного OpenAI у агента main:

openclaw gateway stop
openclaw models status --agent main --probe --probe-provider openai --probe-concurrency 1
openclaw gateway start

Выберите время, когда допустима остановка службы. Дождитесь завершения команды и очистки её временного состояния перед запуском Gateway. Затем вернитесь в исходную сессию: отдельная проба не проверяет её закреплённый выбор модели.

Если не работает: найдите первый неудачный этап

Не удаляйте ограничения доступа только ради исчезновения сообщения Model is not allowed. agents.defaults.models хранит псевдонимы и параметры; текущий явный список разрешений находится в modelPolicy.allow. При этом разрешённое имя ещё не доказывает доступ аккаунта или совместимость runtime. Правила выбора моделей.

Если ошибка относится к авторизации, переходите к диагностике OpenClaw 401 и отсутствующего заголовка авторизации. Там отдельно разобраны Gateway, общий профиль, локальное переопределение и нативный Claude CLI. Сначала определите, кто отказал, затем меняйте соответствующий источник учётных данных.

Часто задаваемые вопросы

Можно ли запустить OpenClaw полностью с локальной LLM?

Да, можно выбрать локальную модель Ollama, LM Studio или vLLM и проверить её работу с инструментами. Для локального инференса сервер и веса должны быть доступны Gateway. Если цель — отсутствие внешних обращений всей системы, отдельно проверьте инструменты, память, вспомогательные модели и облачные резервы; выбор локальной LLM этого сам по себе не подтверждает.

Какой API key нужен для LM Studio в OpenClaw?

Токен самого LM Studio, если авторизация его сервера включена. При отключённой авторизации оставьте поле ключа пустым в интерактивной настройке. Для авторизованного сервера используется LM_API_TOKEN. Ключ OpenAI не требуется только из-за совместимого протокола. Правила LM Studio.

Почему Ollama есть в списке, но мастер не выбирает модель?

Каталог установленных моделей и свежий автоматический выбор различаются. Автоматический путь рассматривает уже загруженные модели с подтверждёнными tools и контекстом от 16K. Для подходящей установленной, но незагруженной модели в настольной настройке выберите Choose connection → Local only. Также проверьте ручной список models.providers.ollama.models, который при непустом значении отключает общее обнаружение. Настройка, каталог.

Почему после models set в чате осталась старая модель?

Изменение глобальной модели по умолчанию не снимает закрепление с существующей сессии. Посмотрите /model status, затем используйте /model default, если хотите вернуться к настроенному выбору. Не требуется повторно входить в аккаунт только ради снятия такого закрепления. Выбор моделей.

Переключится ли явно выбранная локальная модель на облако при отказе?

Точный выбор через /model строгий: отказ выбранной модели отображается вместо скрытого ответа от другой. Настроенная модель по умолчанию может использовать свою резервную цепочку. Поэтому проверяйте источник выбора, а не только имя модели и наличие fallbacks в файле. Правила отказа.

Сколько памяти нужно и какая модель быстрее?

Требования зависят от весов, квантизации, контекста и сервера. Загрузите выбранную конфигурацию, проверьте потребление памяти и выполните короткий ответ плюс реальное чтение тестового файла. В этом руководстве нет измерений скорости или оснований обещать фиксированное число токенов в секунду для вашего оборудования.