Как добавить пользовательские модели в OpenClaw: полное руководство по настройке (2026)

OpenClaw поставляется со встроенной поддержкой четырнадцати провайдеров, включая OpenAI, Anthropic, Google Gemini и OpenRouter, но настоящая мощь раскрывается при добавлении собственных. Будь то подключение приватного развёртывания vLLM за корпоративным файрволом, маршрутизация через LiteLLM для единого биллинга нескольких поставщиков ИИ или интеграция совершенно нового провайдера вроде Moonshot AI Kimi K2.5 до выхода официальной поддержки в очередном релизе -- конфигурация models.providers в файле openclaw.json делает всё это возможным с помощью нескольких строк JSON. В данном руководстве подробно разбирается каждый параметр конфигурации с понятными пояснениями, приводятся проверенные и работающие примеры для пяти различных типов провайдеров от облачных API до локальных серверов инференса, а также описываются шаги по устранению наиболее распространённых ошибок, которые ни один другой ресурс не объединяет в одном месте. К концу этого руководства вы будете точно знать, как добавить любую OpenAI-совместимую или Anthropic-совместимую модель в OpenClaw, настроить мультимодельную маршрутизацию для оптимизации затрат и отладить проблемы конфигурации при их возникновении.

Что такое пользовательские провайдеры моделей в OpenClaw?

Система моделей OpenClaw разделяет провайдеров на две категории. Встроенные провайдеры входят в каталог pi-ai, который поставляется с каждой установкой. Среди них -- OpenAI, Anthropic, Google Gemini, Google Vertex, OpenCode Zen, Z.AI (GLM), Vercel AI Gateway, OpenRouter, xAI, Groq, Cerebras, Mistral и GitHub Copilot. Для этих провайдеров достаточно задать учётные данные для аутентификации и выбрать модель -- дополнительная настройка не требуется. Одна команда вроде openclaw onboard --auth-choice openai-api-key полностью выполняет всю настройку.

Пользовательские провайдеры моделей, напротив, представляют собой всё, что выходит за рамки встроенного каталога. Они требуют явной настройки через секцию models.providers в файле openclaw.json. Сюда входят облачные API-сервисы, такие как Moonshot AI (Kimi), MiniMax и Alibaba Model Studio. Также это охватывает локальные среды инференса -- Ollama, vLLM, LM Studio и text-generation-webui. Прокси- и шлюзовые сервисы, например LiteLLM, агрегирующие несколько провайдеров за единой конечной точкой, тоже относятся к этой категории. Корпоративные развёртывания, предоставляющие OpenAI-совместимые или Anthropic-совместимые конечные точки, аналогично квалифицируются как пользовательские.

Решение о том, нужен ли вам пользовательский провайдер, принимается просто. Если целевой провайдер присутствует в списке встроенных выше, используйте путь встроенной конфигурации -- запись в models.providers не нужна, только аутентификация и выбор модели. Если ваш провайдер предоставляет OpenAI-совместимый API автодополнения чата, настройте его как пользовательский провайдер с api: "openai-completions". Если он использует Anthropic-совместимый API сообщений, укажите api: "anthropic-messages". Если провайдер не поддерживает ни один формат нативно, направьте его через OpenRouter или LiteLLM в качестве посредника, который автоматически преобразует формат запросов. Для более подробного ознакомления с первоначальной настройкой провайдеров, включая Ollama и облачных провайдеров, обратитесь к нашему полному руководству по настройке LLM в OpenClaw.

Практическая ценность пользовательских провайдеров выходит далеко за рамки простого добавления новых моделей. Команды часто используют пользовательские конфигурации для подключения к внутренним API-шлюзам, обеспечивающим организационные лимиты запросов и аудит-логирование. Стартапы маршрутизируют через оптимизированные по стоимости прокси-сервисы, объединяющие биллинг нескольких поставщиков ИИ в один счёт. Разработчики, заботящиеся о конфиденциальности, настраивают локальные конечные точки инференса, гарантирующие, что данные не покидают их сеть. А ранние последователи используют пользовательских провайдеров для доступа к только что выпущенным моделям -- таким как Moonshot AI Kimi K2.5 или MiniMax M2.1 -- за недели до появления официальной поддержки в OpenClaw. Конфигурация models.providers -- это механизм, который делает OpenClaw по-настоящему модельно-агностичным, а не привязанным к фиксированному набору поддерживаемых сервисов.

Как работает система моделей OpenClaw

Понимание трёх ключевых концепций сэкономит вам часы отладки при настройке пользовательских провайдеров. Первая концепция -- формат ссылки на модель. Каждая модель в OpenClaw использует формат провайдер/идентификатор-модели, где OpenClaw разделяет строку по первому прямому слэшу, отделяя имя провайдера от идентификатора модели. Когда вы набираете /model moonshot/kimi-k2.5 в сессии чата, OpenClaw понимает, что запрос нужно направить провайдеру «moonshot» и запросить модель «kimi-k2.5». Для моделей, идентификаторы которых содержат дополнительные слэши, например в стиле OpenRouter -- openrouter/anthropic/claude-sonnet-4-5, разделение всё равно происходит по первому слэшу: «openrouter» становится провайдером, а «anthropic/claude-sonnet-4-5» -- идентификатором модели.

Вторая концепция -- приоритет выбора модели. OpenClaw определяет, какую модель использовать, через определённый каскад. Сначала берётся основная модель, заданная в agents.defaults.model.primary. Если она недоступна из-за ошибки аутентификации или ограничения частоты запросов, система перебирает упорядоченный список резервных моделей из agents.defaults.model.fallbacks. Если основная модель не может принимать изображения, но текущая задача требует возможностей обработки визуальной информации, OpenClaw автоматически переключается на модель для изображений, определённую в agents.defaults.imageModel.primary. Этот каскад означает, что можно настроить доступную основную модель для большинства задач, сохранив при этом премиум-модель в качестве резервного варианта для сложных рассуждений.

Третья концепция -- белый список моделей. Когда вы настраиваете agents.defaults.models в файле openclaw.json, он становится строгим белым списком. Любая модель, не указанная в нём, будет отклонена с ошибкой «Model 'provider/model' is not allowed.» Такое поведение спроектировано намеренно для корпоративных сред, где администраторам необходимо контролировать, к каким моделям имеют доступ пользователи. Если вы столкнулись с этой ошибкой после добавления пользовательского провайдера, нужно добавить новую модель в этот белый список. Альтернативно, полное удаление ключа agents.defaults.models отключает проверку белого списка и разрешает любую настроенную модель. Команда openclaw models status показывает выбранную основную модель, резервные варианты, модель для изображений и обзор аутентификации, что делает её лучшей отправной точкой для диагностики проблем конфигурации.

Интерфейс командной строки предоставляет исчерпывающий набор команд для управления моделями во время работы без ручного редактирования файлов конфигурации. Команда openclaw models list отображает все настроенные модели, причём флаг --all показывает полный каталог, а --provider <имя> фильтрует по конкретному провайдеру. Команда openclaw models set <провайдер/модель> немедленно меняет основную модель, а openclaw models set-image <провайдер/модель> настраивает модель с поддержкой изображений, используемую при необходимости визуального ввода. Управление псевдонимами через openclaw models aliases list|add|remove позволяет создавать ярлыки вроде «opus» или «kimi», которые сопоставляются с полными ссылками на модели, сокращая объём ввода в повседневной работе. Управление резервными моделями через openclaw models fallbacks list|add|remove|clear и openclaw models image-fallbacks list|add|remove|clear даёт полный контроль над цепочкой переключения при отказе. Пожалуй, наиболее полезна для отладки пользовательских провайдеров команда openclaw models scan, которая проверяет доступные модели с возможностью проведения онлайн-тестов поддержки инструментов и обработки изображений в реальном времени.

Полный справочник по конфигурации models.providers

Секция models.providers в файле openclaw.json -- это место, где находятся все определения пользовательских провайдеров. Конфигурация следует определённой структуре с обязательными и необязательными параметрами. Понимание каждого параметра предотвращает наиболее распространённые ошибки конфигурации.

Структура верхнего уровня оборачивает определения провайдеров внутри models.providers с необязательным полем mode, которое контролирует взаимодействие пользовательских провайдеров со встроенным каталогом. Установка mode: "merge" объединяет ваших пользовательских провайдеров со встроенными -- это рекомендуемый подход для большинства пользователей. Без этого поля пользовательские провайдеры полностью заменяют каталог -- такое поведение требуется крайне редко.

Каждое определение провайдера требует трёх параметров. Параметр baseUrl указывает конечную точку API, на которую OpenClaw отправляет запросы, например https://api.moonshot.ai/v1 для Moonshot AI или http://localhost:1234/v1 для локального экземпляра LM Studio. Параметр apiKey отвечает за аутентификацию и поддерживает ссылки на переменные окружения с помощью синтаксиса ${VAR_NAME}, то есть "${MOONSHOT_API_KEY}" указывает OpenClaw считывать ключ из переменной окружения MOONSHOT_API_KEY, а не хранить учётные данные в открытом виде. Параметр api объявляет совместимость протокола и принимает значения "openai-completions" для OpenAI-совместимых конечных точек или "anthropic-messages" для Anthropic-совместимых.

Массив models внутри каждого провайдера определяет, какие модели доступны. Каждая запись модели требует только id и name, однако необязательные поля позволяют объявить возможности, которые OpenClaw использует для принятия решений о маршрутизации. Поле reasoning (булево, по умолчанию false) указывает, поддерживает ли модель цепочку рассуждений. Поле input (массив, по умолчанию ["text"]) объявляет принимаемые типы входных данных -- добавьте "image" для моделей с поддержкой визуального ввода. Объект cost с полями input, output, cacheRead и cacheWrite (все по умолчанию 0) обеспечивает отслеживание затрат и оптимизацию при установке точных цен за токен. Поле contextWindow (по умолчанию 200000) задаёт максимальную длину контекста в токенах, а maxTokens (по умолчанию 8192) контролирует максимальную длину вывода. Хотя у этих необязательных полей есть разумные значения по умолчанию, установка явных значений, соответствующих реальным возможностям вашей модели, предотвращает скрытые проблемы вроде усечения контекста или неправильных расчётов стоимости.

Ниже представлена полная структура конфигурации со всеми аннотированными параметрами:

json5
{
  models: {
    mode: "merge",
    providers: {
      "provider-name": {
        baseUrl: "https://api.example.com/v1",
        apiKey: "${API_KEY_ENV_VAR}",
        api: "openai-completions",
        models: [
          {
            id: "model-id",
            name: "Display Name",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

Выбор правильного типа api критически важен и полностью зависит от формата конечной точки вашего провайдера. Используйте "openai-completions" для любого провайдера, принимающего формат запросов OpenAI chat completions -- это охватывает подавляющее большинство сторонних провайдеров, включая Moonshot AI, vLLM, LM Studio, LiteLLM, Ollama, Groq-совместимые конечные точки и большинство серверов инференса на собственном хостинге. Используйте "anthropic-messages" конкретно для провайдеров, реализующих формат API сообщений Anthropic, куда в настоящее время входят Kimi Coding и Synthetic. Если сомневаетесь, проверьте документацию вашего провайдера: описывают ли они свой API как «OpenAI-compatible» или «Anthropic-compatible» -- если используется путь /v1/chat/completions, выбирайте openai-completions.

Следующая таблица быстрого справочника сопоставляет распространённых провайдеров с правильным типом API, уберегая вас от самой частой ошибки конфигурации:

Настройка облачных и API-провайдеров (пошагово)

В этом разделе представлены проверенные, рабочие конфигурации для пяти различных сценариев работы с облачными и API-провайдерами. Каждый пример включает полный фрагмент openclaw.json, необходимую переменную окружения и команды верификации.

Moonshot AI (Kimi K2.5) использует OpenAI-совместимые конечные точки и предлагает одну из наиболее мощных моделей рассуждений в открытой экосистеме. Kimi K2.5 поддерживает как стандартный, так и режим размышления, с вариантами моделей kimi-k2.5, kimi-k2-thinking и kimi-k2-turbo-preview. Конфигурация из официальной документации OpenClaw (docs.openclaw.ai, февраль 2026) выглядит так:

json5
{
  agents: {
    defaults: { model: { primary: "moonshot/kimi-k2.5" } },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [{ id: "kimi-k2.5", name: "Kimi K2.5" }],
      },
    },
  },
}

После сохранения конфигурации экспортируйте ваш API-ключ командой export MOONSHOT_API_KEY='sk-...' в профиле оболочки (добавьте в ~/.zshrc на macOS или ~/.bash_profile на Linux), затем примените файл командой source ~/.zshrc. Проверьте настройку с помощью openclaw models list --provider moonshot, чтобы убедиться, что модель появилась в списке доступных, и запустите openclaw models status --probe для выполнения теста подключения в реальном времени, подтверждающего валидность API-ключа и корректность ответа модели. Эта двухэтапная верификация выявляет как ошибки конфигурации (неправильное имя провайдера, отсутствующая запись модели), так и ошибки аутентификации (невалидный ключ, просроченные учётные данные) до того, как вы попытаетесь использовать модель в реальной сессии.

Synthetic (Anthropic-совместимый) предоставляет доступ к моделям вроде MiniMax M2.1 через Anthropic-совместимую API-конечную точку. Это хороший пример того, когда следует использовать тип API anthropic-messages. Конфигурация следует той же структуре, но с альтернативным протоколом:

json5
{
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [{ id: "hf:MiniMaxAI/MiniMax-M2.1", name: "MiniMax M2.1" }],
      },
    },
  },
}

Alibaba Model Studio (Qwen) требует выбора региона конечной точки, что влияет на скорость ответа, доступные модели и лимиты запросов. Доступны три региона: Сингапур (ap-southeast-1), Виргиния (us-east-1) и Пекин (cn-beijing), каждый из которых требует отдельных API-ключей из Model Studio Console. Для международных пользователей OpenAI-совместимая конечная точка по адресу https://coding-intl.dashscope.aliyuncs.com/v1 обеспечивает наименьшую задержку за пределами Китая. Конфигурация включает явные значения стоимости и окна контекста для точного отслеживания затрат:

json5
{
  models: {
    mode: "merge",
    providers: {
      dashscope: {
        baseUrl: "https://coding-intl.dashscope.aliyuncs.com/v1",
        apiKey: "${DASHSCOPE_API_KEY}",
        api: "openai-completions",
        models: [{
          id: "qwen3-max-2026-01-23",
          name: "Qwen3 Max",
          contextWindow: 262144,
          maxTokens: 32768,
        }],
      },
    },
  },
}

Прокси-сервисы API, такие как laozhang.ai, предоставляют единую конечную точку, маршрутизирующую запросы к нескольким вышестоящим провайдерам через один API-ключ. Это упрощает биллинг и избавляет от необходимости управлять учётными данными для каждого провайдера по отдельности. Поскольку большинство прокси-сервисов реализуют OpenAI-совместимый формат, конфигурация следует стандартному шаблону -- просто замените baseUrl на конечную точку прокси и используйте их единый API-ключ. Для пользователей, сравнивающих стоимость моделей у разных провайдеров, ознакомьтесь с нашим руководством по подробному сравнению Claude Opus 4 и Sonnet 4, чтобы понять компромиссы между производительностью и ценой.

Qwen OAuth (бесплатный уровень) предлагает уникальный путь аутентификации, не требующий API-ключей. Вместо этого Qwen предоставляет OAuth-поток через встроенный плагин. Активируйте и аутентифицируйтесь двумя командами:

bash
openclaw plugins enable qwen-portal-auth
openclaw models auth login --provider qwen-portal --set-default

Это даёт доступ к qwen-portal/coder-model и qwen-portal/vision-model бесплатно, что является отличным вариантом для рабочих процессов разработки и тестирования. OAuth-подход означает отсутствие API-ключа, который нужно хранить или ротировать, что снижает накладные расходы на безопасность для индивидуальных разработчиков, желающих поэкспериментировать с моделями Qwen без оформления платного плана. Обратите внимание, что бесплатный уровень имеет лимиты использования, соответствующие разработке, -- для производственных нагрузок следует использовать конфигурацию DashScope на основе API-ключей, описанную выше, для более высокой пропускной способности и гарантированной доступности.

Подключение локальных моделей (Ollama, vLLM, LM Studio, LiteLLM)

Локальное выполнение моделей устраняет затраты на API, сохраняет данные на вашем компьютере и полностью снимает проблемы с ограничениями частоты запросов. Компромисс -- требования к оборудованию: локальный инференс нуждается в достаточном объёме оперативной памяти и, в идеале, в видеокарте. OpenClaw поддерживает четыре основные локальные среды инференса, каждая из которых обладает своими преимуществами для различных рабочих процессов.

Ollama -- самый быстрый путь к локальному инференсу и единственная среда выполнения, которую OpenClaw обнаруживает автоматически. Когда Ollama работает по адресу http://127.0.0.1:11434/v1, OpenClaw обнаруживает её без какой-либо конфигурации models.providers. Установите Ollama, загрузите модель командой ollama pull llama3.3 и задайте её как основную:

json5
{
  agents: {
    defaults: { model: { primary: "ollama/llama3.3" } },
  },
}

Для моделей, которым полезен расширенный контекст или определённая квантизация, библиотека моделей Ollama предоставляет десятки вариантов. Рекомендуемые модели для задач программирования в OpenClaw включают qwen3-coder для генерации кода и glm-4.7 для общих рассуждений -- обе требуют минимальное контекстное окно в 64K токенов для эффективной работы агента. При выборе между размерами моделей тщательно учитывайте сложность задачи. Модель с 8 миллиардами параметров эффективно обрабатывает быстрые автодополнения и простые запросы на скромном оборудовании, тогда как модели с 70 миллиардами параметров приближаются к облачному качеству рассуждений, но требуют значительно большего объёма видеопамяти. Формат квантизации Q4_K_M предлагает лучший баланс между сохранением качества и экономией памяти для большинства локальных развёртываний -- он снижает требования к видеопамяти примерно на 60% по сравнению с полноточными весами, сохраняя при этом 95% и более исходной способности модели на бенчмарках программирования.

vLLM нацелен на производственные развёртывания, где важна пропускная способность. Он работает в 24 раза быстрее, чем Hugging Face Transformers, благодаря непрерывной пакетной обработке и PagedAttention, что делает его идеальным для мультиагентных развёртываний, генерирующих сотни запросов в минуту. Конечная точка по умолчанию -- http://localhost:8000/v1, используется стандартный OpenAI-совместимый формат:

json5
{
  models: {
    mode: "merge",
    providers: {
      vllm: {
        baseUrl: "http://localhost:8000/v1",
        apiKey: "not-needed",
        api: "openai-completions",
        models: [{
          id: "meta-llama/Llama-3.1-70B-Instruct",
          name: "Llama 3.1 70B",
          contextWindow: 131072,
          maxTokens: 16384,
        }],
      },
    },
  },
}

Один критически важный момент для развёртываний в Docker: замените localhost на host.docker.internal (Docker Desktop) или на IP-адрес машины в локальной сети, когда vLLM и OpenClaw работают в отдельных контейнерах. Флаг --network=host является альтернативным, но менее портируемым решением. Для производственных развёртываний vLLM активируйте непрерывную пакетную обработку с помощью --enable-chunked-prefill и рассмотрите установку --max-model-len в соответствии с требованиями к контексту OpenClaw -- vLLM выделяет видеопамять на основе этого значения, поэтому установка 65536 вместо максимальных 131072 модели может вдвое сократить требования к видеопамяти, при этом всё ещё поддерживая типичные потребности OpenClaw в контексте.

LM Studio предоставляет графический интерфейс для загрузки, конвертации и обслуживания моделей. Визуальный интерфейс делает его лучшим выбором для пользователей, которые хотят поэкспериментировать с различными моделями перед фиксацией конфигурации. Официальная документация OpenClaw (docs.openclaw.ai, февраль 2026) предоставляет следующий шаблон конфигурации:

json5
{
  agents: {
    defaults: {
      model: { primary: "lmstudio/minimax-m2.1-gs32" },
      models: { "lmstudio/minimax-m2.1-gs32": { alias: "Minimax" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "LMSTUDIO_KEY",
        api: "openai-completions",
        models: [{
          id: "minimax-m2.1-gs32",
          name: "MiniMax M2.1",
          reasoning: false,
          input: ["text"],
          cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
          contextWindow: 200000,
          maxTokens: 8192,
        }],
      },
    },
  },
}

LiteLLM служит иной цели, чем остальные три среды выполнения. Вместо локального запуска инференса он действует как прокси, предоставляющий единый OpenAI-совместимый интерфейс к нескольким вышестоящим провайдерам. Это делает его мощным инструментом для сценариев мультимодельной маршрутизации, где вы хотите переключаться между облачными и локальными моделями через единую конечную точку по адресу http://localhost:4000/v1. Настраивайте его с тем же типом API openai-completions и определяйте каждую модель, которую обслуживает ваш экземпляр LiteLLM. Особое преимущество LiteLLM в связке с OpenClaw -- балансировка нагрузки и управление лимитами запросов между несколькими аккаунтами провайдеров. Если у вас есть API-ключи для OpenAI и Anthropic одновременно, LiteLLM может автоматически направлять запросы к провайдеру, имеющему свободную ёмкость, фактически удваивая потолок пропускной способности без каких-либо изменений в конфигурации OpenClaw помимо указания на прокси-конечную точку LiteLLM.

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

Требования к оборудованию значительно различаются в зависимости от размера модели. Модель с 8 миллиардами параметров, такая как Llama 3.1 8B или Mistral 7B, комфортно работает на 8 ГБ видеопамяти (RTX 3060). Модель с 34 миллиардами параметров требует 20-24 ГБ видеопамяти (RTX 3090 или RTX 4090) с квантизацией. Модели с 70 миллиардами параметров нуждаются в 40-48 ГБ видеопамяти (A100 40 ГБ или конфигурации с двумя GPU) для приемлемой скорости инференса. Для пользователей Mac чипы M4 с унифицированной памятью предоставляют экономичный вариант -- Mac Mini M4 с 16 ГБ обрабатывает модели 7-8B со скоростью 15-20 токенов в секунду (marc0.dev, февраль 2026).

Продвинутая мультимодельная маршрутизация и безопасность

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

Практическая трёхуровневая конфигурация маршрутизации назначает модели в зависимости от сложности задачи. Используйте премиум-модель вроде anthropic/claude-opus-4-6 для сложных рассуждений и архитектурных решений -- Claude Opus 4.5 стоит $15/$75 за миллион токенов ввода/вывода (haimaker.ai, февраль 2026), но справляется с редактированием нескольких файлов и сложной отладкой лучше любой альтернативы. Направляйте повседневную работу по написанию кода на модель среднего уровня, например moonshot/kimi-k2.5 или anthropic/claude-sonnet-4-5 по $3/$15 за миллион токенов, что покрывает подавляющее большинство задач по генерации и ревью кода. Назначайте проверки состояния, поиск файлов и простые автодополнения бюджетным моделям вроде google/gemini-3-flash-lite по $0,50 за миллион токенов или DeepSeek V3.2 по $0,53 за миллион токенов -- что представляет 60-кратную экономию по сравнению с Opus для рутинных операций (velvetshark.com, февраль 2026). Экономия растёт быстро: лёгкие пользователи сообщают о примерно 65% ежемесячной экономии (~$130/мес.), тогда как активные пользователи с полноценной трёхуровневой маршрутизацией экономят более $600/мес. по сравнению с конфигурацией на одной модели. Конфигурация цепочки резервных моделей обеспечивает непрерывную работу даже при сбоях отдельных провайдеров:

json5
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: [
          "moonshot/kimi-k2.5",
          "openai/gpt-5.1-codex",
          "ollama/llama3.3"
        ]
      },
    },
  },
}

Этот каскад означает, что если Anthropic достигнет лимитов, запросы автоматически перенаправляются на Moonshot, затем на OpenAI, затем на локальный экземпляр Ollama -- гарантируя, что ваш агент никогда не прекратит работу. Для команд, управляющих стратегиями управления токенами и оптимизации затрат, этот подход обеспечивает экономию 50-65% по сравнению с выполнением всего на одной премиум-модели.

Переопределение моделей на уровне отдельных агентов расширяет модель маршрутизации ещё дальше. Конфигурация agents.list[].model позволяет назначать конкретные модели отдельным агентам в экосистеме OpenClaw, так что агент ревью кода может использовать Opus для тщательности, а агент поиска файлов -- локальную модель для скорости. Именно этот гранулярный контроль назначения моделей по типу задачи отличает базовую конфигурацию от по-настоящему оптимизированной мультимодельной установки.

Безопасность заслуживает осознанного внимания при настройке пользовательских провайдеров. Самая важная практика -- хранение API-ключей в переменных окружения, а не непосредственно в openclaw.json. Последовательно используйте синтаксис ${VAR_NAME}, чтобы учётные данные никогда не появлялись в конфигурационных файлах, которые могут быть закоммичены в систему контроля версий. Для корпоративных развёртываний белый список моделей обеспечивает контроль доступа -- установите agents.defaults.models для явного перечисления разрешённых моделей, и любая не указанная модель будет отклонена. Команда openclaw models status показывает статус аутентификации для всех настроенных провайдеров, помогая проверить корректность загрузки учётных данных без раскрытия фактических значений ключей. При использовании laozhang.ai или аналогичных прокси-сервисов один API-ключ заменяет множество учётных данных провайдеров, сокращая поверхность управления учётными данными и предоставляя доступ к десяткам вышестоящих моделей через единую конечную точку.

Для команд, использующих общую конфигурацию OpenClaw, рассмотрите полное разделение учётных данных аутентификации и структурной конфигурации. Храните openclaw.json в системе контроля версий с заполнителями ${VAR_NAME} для всех API-ключей и распространяйте фактические учётные данные через менеджер секретов или командное хранилище паролей. Этот паттерн гарантирует, что новые члены команды могут клонировать репозиторий и начать работу, просто установив переменные окружения, без риска попадания учётных данных в историю git. Белый список моделей в agents.defaults.models добавляет ещё один уровень управления, ограничивая модели, которые могут активировать члены команды, предотвращая случайное использование дорогих премиум-моделей для задач, с которыми бюджетная модель справляется не хуже. Объедините это с отслеживанием затрат, обеспечиваемым точными значениями cost в определениях моделей, и вы получите видимость расходов по каждой модели для всей команды без необходимости использования внешних инструментов мониторинга.

Устранение неполадок пользовательских моделей

Конфигурации пользовательских моделей вводят режимы сбоев, отличающиеся от встроенных провайдеров. Ниже описаны наиболее распространённые ошибки, их причины и точные шаги по их устранению. Начинайте каждую сессию отладки командой openclaw models status --probe, которая выполняет тестирование подключения в реальном времени ко всем настроенным провайдерам и выявляет проблемы аутентификации, маршрутизации и соединения в одном выводе.

«Model 'provider/model' is not allowed» появляется, когда активен белый список моделей, а ваша пользовательская модель в него не включена. Это наиболее часто сообщаемая проблема при добавлении новых провайдеров. Исправление требует добавления вашей модели в белый список agents.defaults.models:

json5
{
  agents: {
    defaults: {
      models: {
        "moonshot/kimi-k2.5": { alias: "Kimi" },
        // ... добавьте вашу пользовательскую модель здесь
      },
    },
  },
}

Альтернативно, полностью удалите ключ agents.defaults.models для отключения белого списка. Это подходит для персональных установок, но не рекомендуется для командных сред, где доступ к моделям должен контролироваться.

«Connection refused» или «ECONNREFUSED» возникает, когда OpenClaw не может связаться с настроенным baseUrl. Для локальных сред выполнения убедитесь, что сервер действительно запущен -- curl http://localhost:11434/v1/models для Ollama, curl http://localhost:1234/v1/models для LM Studio, curl http://localhost:8000/v1/models для vLLM. Если команда curl тоже завершается неудачей, сервер инференса не запущен или слушает на другом порту. Для развёртываний в Docker помните, что localhost внутри контейнера обозначает сам контейнер, а не хост-машину -- используйте host.docker.internal или IP-адрес хоста.

«Invalid API key» или «401 Unauthorized» означает, что учётные данные аутентификации отсутствуют или неверны. Сначала проверьте, установлена ли переменная окружения, командой echo $YOUR_API_KEY_VAR -- пустой ответ означает, что переменная не экспортирована в текущей сессии оболочки. Убедитесь, что инструкция export находится в ~/.zshrc или ~/.bash_profile и что вы применили файл после редактирования. При использовании синтаксиса ${VAR_NAME} в openclaw.json убедитесь, что имя переменной совпадает точно -- ${MOONSHOT_API_KEY} требует export MOONSHOT_API_KEY='sk-...', а не MOONSHOT_KEY или moonshot_api_key. Для более подробной отладки API-ключей ознакомьтесь с нашим руководством по устранению ошибок аутентификации API-ключей OpenClaw.

«Unknown provider» или «Provider not found» обычно означает, что имя провайдера в ссылке на модель не совпадает ни с одним встроенным или пользовательским определением провайдера. Убедитесь, что ключ провайдера в models.providers точно совпадает с тем, что вы используете в ссылке на модель -- если вы определяете providers: { "my-llm": { ... } }, ссылка на модель должна быть my-llm/model-id, а не myllm/model-id или myLLM/model-id.

«Tool calling failed» или «Structured output not supported» указывает, что модель не поддерживает формат вызова функций, который OpenClaw использует для взаимодействия с инструментами. Не все модели поддерживают структурированные вызовы инструментов -- только модели, специально обученные для вызова функций (такие как Llama 3.1, Mistral с поддержкой function calling, варианты GPT и варианты Claude), надёжно работают с системой инструментов OpenClaw. Установите reasoning: false в определении модели для моделей, не обладающих этой возможностью, и рассмотрите их использование только для простых задач автодополнения, а не в качестве основных моделей агента. Команда openclaw models status --probe тестирует поддержку инструментов напрямую.

«Gateway timeout» или медленные ответы указывают либо на сетевую задержку, либо на перегруженный сервер инференса. Для локальных моделей убедитесь, что модель полностью загружена в память -- первый запрос после загрузки большой модели может занять 30-60 секунд. При необходимости увеличьте тайм-аут шлюза в конфигурации. Для облачных провайдеров с постоянными ограничениями частоты запросов настройте резервные варианты для распределения нагрузки между провайдерами. Наше руководство по устранению ошибок ограничения частоты запросов описывает конкретные стратегии обработки ошибок 429 у различных провайдеров.

Ошибки синтаксиса конфигурации особенно коварны, потому что могут помешать запуску всего шлюза. Парсер конфигурации OpenClaw строг -- лишние запятые, отсутствие кавычек вокруг строковых значений или неправильная вложенность вызовут молчаливый сбой, при котором шлюз запускается, но игнорирует неправильно оформленное определение провайдера. Команда openclaw doctor предоставляет комплексную диагностику, проверяющую синтаксис конфигурационного файла, подключение к провайдерам, доступность моделей и статус аутентификации. Запускайте её всякий раз, когда изменение конфигурации приводит к неожиданному поведению -- она выявляет проблемы, которые ручная проверка часто пропускает, включая строгую JSON-валидацию, при которой «конфигурация Moltbot [OpenClaw] строго валидируется. Некорректные или лишние поля могут привести к сбою шлюза» (Alibaba Cloud Community, февраль 2026). Полезный паттерн отладки -- начать с минимальной конфигурации -- baseUrl, apiKey, api и одна модель только с id и name -- убедиться, что она работает с помощью openclaw models list --provider yourprovider, а затем постепенно добавлять необязательные поля вроде cost, contextWindow и reasoning, тестируя после каждого добавления.

Когда ничего другое не помогает, трёхшаговая последовательность диагностики решает большинство оставшихся проблем. Во-первых, запустите openclaw models status --probe для тестирования подключения и аутентификации всех провайдеров. Во-вторых, проверьте логи шлюза на наличие конкретных сообщений об ошибках, которые CLI может не отображать. В-третьих, протестируйте конечную точку провайдера напрямую с помощью curl -- curl -X POST http://your-endpoint/v1/chat/completions -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" -d '{"model":"model-id","messages":[{"role":"user","content":"test"}]}' -- чтобы изолировать, находится ли проблема в конфигурации OpenClaw или в самом провайдере.

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

Можно ли использовать дообученную модель с OpenClaw? Да, при условии, что модель обслуживается через OpenAI-совместимую или Anthropic-совместимую API-конечную точку. Дообученные модели, размещённые на vLLM, Ollama (через пользовательские Modelfile) или любом сервере инференса с предоставлением стандартной конечной точки chat completions, работают с конфигурацией models.providers. Установите в поле id точный идентификатор модели, который ожидает ваш сервер, и настройте contextWindow и maxTokens в соответствии с фактическими возможностями дообученной модели.

Как переключаться между пользовательскими моделями во время сессии чата? Используйте команду /model, за которой следует полная ссылка провайдер/модель. Например, /model moonshot/kimi-k2.5 переключает на Kimi K2.5, а /model ollama/llama3.3 -- на локальную Llama. Команда /model list показывает все доступные модели, а /model status отображает текущий выбор. Перезапуск не требуется -- переключение вступает в силу со следующего сообщения.

Что произойдёт, если мой пользовательский провайдер упадёт во время выполнения задачи? Система переключения при отказе OpenClaw активируется автоматически. Если вы настроили agents.defaults.model.fallbacks, запросы направляются к следующему доступному провайдеру в цепочке. Без резервных вариантов текущий запрос завершится ошибкой, и вы сможете вручную переключить модель командой /model. Для производственной надёжности всегда настраивайте как минимум две резервные модели от разных провайдеров.

Есть ли ограничение на количество пользовательских провайдеров? Жёсткого ограничения на число провайдеров в models.providers не существует. Практические соображения включают потребление памяти для поддержания пулов соединений и сложность управления многими API-ключами. Большинству пользователей достаточно трёх-пяти пользовательских провайдеров, охватывающих сочетание облачных API, локальной среды выполнения и прокси-сервиса, -- это обеспечивает достаточную гибкость без избыточных накладных расходов на управление.

Работает ли models.providers с веб-интерфейсом и мобильными приложениями OpenClaw? Да. Конфигурация models.providers в файле openclaw.json применяется глобально ко всем интерфейсам OpenClaw, включая CLI, веб-интерфейс (доступный через openclaw dashboard) и любые подключённые чат-платформы вроде Discord или Telegram. Панель управления по адресу http://127.0.0.1:18789/ предоставляет визуальный способ тестирования пользовательских провайдеров перед их развёртыванием в производственных каналах. Это означает, что вы можете настроить пользовательского провайдера один раз в JSON-файле и немедленно использовать его из любого интерфейса, включая программный доступ через API шлюза. Изменения конфигурации вступают в силу после перезапуска шлюза командой openclaw gateway restart -- нет необходимости в переустановке или повторной настройке при добавлении новых провайдеров к существующей установке.