OpenClaw custom model setup: models.providers, auth profiles и fallbacks

Настройка custom model в OpenClaw — это задача маршрутизации, а не копирование названия модели. Нужно доказать четыре вещи: provider auth работает, OpenClaw видит provider/model catalog, выбранный provider/model ref ведет в нужный endpoint, а fallback route протестирован на реальной задаче. Model IDs, base URL, prices, context windows и tool support меняются, поэтому безопасная статья должна давать форму конфигурации и процедуру проверки, а не выдавать старую provider table за постоянный контракт.

Когда нужен custom provider

Если целевой provider уже есть в текущем built-in catalog OpenClaw и вам не нужно менять base URL, headers или model list, используйте built-in onboarding/auth flow. Это снижает риск ошибок merge, allowlist, secret loading и route naming.

Custom provider нужен, когда вы подключаете:

• внутренний company gateway или LiteLLM/proxy;
• OpenAI-compatible third-party API;
• Anthropic-compatible proxy;
• Ollama, vLLM, LM Studio, llama.cpp или другой local/self-hosted runtime;
• явный allowlist, fallback, capabilities, cost fields или собственное имя route.

Правило выбора простое: endpoint принимает OpenAI chat completions semantics — настраивайте как OpenAI-compatible. Endpoint принимает Anthropic messages semantics — используйте Anthropic-compatible. Если endpoint не поддерживает ни один формат, сначала поставьте gateway/adapter.

Три понятия модели в OpenClaw

Model ref имеет вид provider/model-id. OpenClaw делит строку по первому slash. Если model ID сам содержит slashes, provider prefix должен оставаться явным, иначе route будет трудно диагностировать.

Primary и fallback — это рабочие маршруты. Fallback полезен только если backup route уже authenticated, allowed, has quota и поддерживает те же tools, context, attachments и output requirements. Text-only fallback не заменит route, которому нужны images или structured tool calls.

Allowlist может отклонить модель. Если agents.defaults.models или похожий allowlist активен, новая модель может быть описана в models.providers, но все равно получить Model 'provider/model' is not allowed. В таком случае сначала проверяйте allowlist, затем auth.

Безопасная форма models.providers

Ниже форма конфигурации. Перед использованием замените provider id, base URL, env name и model ID значениями из текущей документации provider и вашего аккаунта.

json5
{
  agents: {
    defaults: {
      model: { primary: "providerid/provider-model-id" }
    }
  },
  models: {
    mode: "merge",
    providers: {
      providerid: {
        baseUrl: "https://api.example.com/v1",
        apiKey: "${PROVIDER_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "provider-model-id",
            name: "Provider Model Name",
            input: ["text"]
          }
        ]
      }
    }
  }
}

api определяется protocol shape, а не брендом. Если minimal curl example вызывает /v1/chat/completions или OpenAI-compatible SDK, чаще всего нужен openai-completions. Если endpoint требует Anthropic messages payload, нужен anthropic-messages.

Cost, contextWindow, maxTokens, cache и capability fields полезны для routing и budget decisions только если вы проверили их сегодня. Просроченные цены или неверное окно опаснее пустого поля, потому что они вводят fallback и cost tracking в заблуждение.

Проверка после добавления provider

После сохранения config не запускайте production agent сразу. Проверьте:

bash
openclaw models list --provider providerid
openclaw models status
openclaw logs --follow

Если версия поддерживает live probe, проверьте connection, tool support и vision input. Secret должен быть доступен тому процессу, который запускает gateway, а не только вашему interactive shell. Docker, systemd, LaunchAgent и CI могут иметь отдельные environment sources.

Если provider curl example не работает, исправляйте provider key, base URL, model ID или сеть. Если curl работает, а OpenClaw нет, проверяйте model ref, allowlist, generated models.json, merge/replace behavior и gateway process environment.

Cloud API, gateways и proxies

OpenAI-compatible cloud или gateway endpoint полезен для unified billing, fallback, budget routing, audit logs или упрощенного multi-provider access. Но gateway не является official upstream pricing и не создает extra quota. Каждый upstream route сохраняет своего billing owner, rate limits, model coverage, tool behavior и context window.

laozhang.ai и похожие provider-gateways стоит добавлять только когда задача читателя — multi-provider routing, cost control, fallback или simplified access. Перед production use проверьте current endpoint, model ID, price, quota behavior, context window и tool support. Не пишите, что gateway "guarantees availability", "unlocks unlimited speed" или "doubles quota".

OAuth, plugin-backed routes, free tiers и regional endpoints — volatile facts. Описывайте их как executable route только если текущие OpenClaw provider docs это поддерживают и вы проверили auth + models status в своей среде.

Local models: Ollama, vLLM, LM Studio, LiteLLM

Local models могут снизить provider API spend и оставить больше данных на машине, но ограничение переносится на hardware, latency, context, tool-call quality и maintenance. Не описывайте local как free, unlimited или automatically production-ready.

Ollama подходит для быстрых local experiments. Некоторые версии OpenClaw могут обнаружить local Ollama route автоматически; если нет, добавьте его явно как OpenAI-compatible local provider. Model ID должен идти из вашего current Ollama catalog и проверяться на реальных tasks.

json5
{
  agents: {
    defaults: { model: { primary: "ollama/local-model-id" } }
  }
}

vLLM подходит, когда вы управляете GPU server, batching и throughput. http://localhost:8000/v1 — common shape, not guaranteed endpoint. В Docker localhost часто означает сам container, поэтому используйте service name, host.docker.internal или reachable host address. Model length, batching и memory flags настраивайте по текущим vLLM docs и своему hardware.

LM Studio удобен для desktop testing. Provider/model id должен соответствовать реально загруженной модели; не копируйте contextWindow или maxTokens из шаблона как факт.

LiteLLM — proxy, а не local inference runtime. Он может объединить endpoints, logs, budgets и routing policies, но не создает quota и не гарантирует fallback success. В catalog добавляйте только модели, которые реально обслуживает ваша LiteLLM instance.

Fallback и безопасность

Практичный fallback config распределяет routes по task risk: сильная модель для architecture/security/multi-file changes; cheaper/local route для summaries и low-risk edits; gateway route для verified multi-provider fallback.

json5
{
  agents: {
    defaults: {
      model: {
        primary: "primary-provider/primary-model",
        fallbacks: [
          "fallback-provider/fallback-model",
          "gateway-provider/gateway-model"
        ]
      }
    }
  }
}

Fallback — это controlled degradation, not success guarantee. Он не исправляет invalid credentials, unsupported beta flags, broken hub download и не делает все модели совместимыми по context, attachments и tools.

API keys не должны лежать напрямую в openclaw.json. Используйте ${VAR_NAME}, secret manager, Docker secrets или team vault. В shared config храните structure в version control, а secrets отдельно. Allowlist ограничивает activation; cost fields используйте как routing hints только после проверки current prices.

Частые ошибки

Model 'provider/model' is not allowed: allowlist не содержит новый model ref. Добавьте его в current allowlist или явно отключите allowlist в personal setup.

Connection refused или ECONNREFUSED: OpenClaw не видит baseUrl. Сначала проверьте provider curl example или /v1/models. В Docker подтвердите, куда указывает localhost.

Invalid API key или 401 Unauthorized: secret не попал в gateway process, variable name не совпадает, key revoked, base URL указывает не туда или модель недоступна аккаунту.

Unknown provider: provider name в model ref не совпадает с ключом в models.providers. my-llm/model, myllm/model и myLLM/model — разные routes.

Tool calling failed: модель или proxy не поддерживает structured tool calls, которые нужны OpenClaw. Не делайте такую модель primary agent route, если задача сложнее simple completion.

Slow response или timeout: причина может быть в cold local model, недостаточном hardware, network latency, provider queue, слишком большом context или upstream throttling. Увеличивайте timeout только после проверки route.

FAQ

Можно ли использовать fine-tuned model?

Да, если она обслуживается через OpenAI-compatible или Anthropic-compatible endpoint, а id, context, output limit и tool support проверены в текущей среде.

Как переключить model во время chat session?

Используйте /model с полным provider/model ref и проверьте availability через /model list или current models commands. Мгновенность переключения зависит от версии OpenClaw и состояния текущего run.

Что если custom provider упадет во время задачи?

Только configured, authenticated и tested fallback может подхватить route. Без fallback текущий request failed, и нужно manually switch route или repair provider.

Сколько custom providers можно добавить?

Это operational question, не число. Больше providers означает больше keys, logs, costs, model IDs, allowlists и incident branches. Добавляйте только routes, которые вы можете тестировать и мониторить.

models.providers работает вне CLI?

Если surface использует тот же gateway/config для resolving models, он должен видеть provider config. Но dashboard, channel, API client и reload behavior зависят от версии. После изменения проверяйте именно тот surface, который будет использовать route.