Providers

LiteLLM

LiteLLM is an open-source LLM gateway with a unified API to 100+ model providers. Route OpenClaw through LiteLLM for centralized cost tracking, logging, virtual keys with spend limits, and backend failover without changing OpenClaw config.

Quick start

Onboarding (recommended)

bash

openclaw onboard --auth-choice litellm-api-key

Onboarding prompts for the proxy base URL. Press Enter to keep the http://localhost:4000 default, or enter your proxy's URL. After the API key, choose a model returned by the proxy's /v1/models endpoint. The first advertised model is selected by default; you can also enter a model ID manually. If discovery fails, onboarding shows the reason and asks for a manual ID. If the configuration changes while credentials are being prepared, setup stops before sending the discovery request. Rerun onboarding with the updated configuration.

For non-interactive setup against a remote proxy, pass the proxy URL explicitly:

bash

openclaw onboard --non-interactive --accept-risk --skip-health --auth-choice litellm-api-key \  --litellm-api-key "$LITELLM_API_KEY" --custom-base-url "https://litellm.example/v1"

The URL must be a full http:// or https:// URL. Non-interactive setup reports an invalid proxy URL and exits with status 1 without saving credentials or configuration.

Manual setup

Start LiteLLM Proxy

LiteLLM calls the upstream provider on your behalf, so export that provider's key before starting it — ANTHROPIC_API_KEY for the model below. See Model routing for multi-backend setups.

bash

pip install 'litellm[proxy]'export ANTHROPIC_API_KEY=sk-ant-...litellm --model claude-opus-4-6

Point OpenClaw to LiteLLM

bash

export LITELLM_API_KEY="your-litellm-key"openclaw

Configuration

json5

{  models: {    providers: {      litellm: {        baseUrl: "http://localhost:4000",        apiKey: "${LITELLM_API_KEY}",        api: "openai-completions",        models: [          {            id: "claude-opus-4-6",            name: "Claude Opus 4.6",            reasoning: true,            input: ["text", "image"],            contextWindow: 200000,            maxTokens: 64000,          },          {            id: "local-qwen",            name: "Local Qwen",            reasoning: false,            input: ["text"],            contextWindow: 32768,            maxTokens: 4096,          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "litellm/claude-opus-4-6" },    },  },}

Interactive onboarding saves the chosen model as litellm/<model-id> and keeps authored model settings when that ID is already configured. Re-authentication keeps an existing default model and makes the selected model available. Non-interactive onboarding retains its litellm/claude-opus-4-6 default. To change it after setup:

bash

openclaw models list --provider litellm --refresh --jsonopenclaw models set litellm/your-model-id

Interactive setup records the selected model in both merge and replace modes while preserving authored provider models. Non-interactive setup with an explicit proxy URL leaves the model list available for discovery in merge mode; replace mode keeps its documented default. Run openclaw models list --provider litellm --refresh --json to refresh the proxy's model list.

Re-running authentication also combines case-variant provider keys, such as LiteLLM and litellm, into one canonical row while preserving authored provider options and model settings, including when activating a saved sign-in. Non-interactive reauthentication without --custom-base-url keeps the configured proxy URL, including when the existing provider key uses different casing.

Image generation

LiteLLM can back the image_generate tool through OpenAI-compatible /images/generations and /images/edits routes. Default image model is gpt-image-2; configure a different one under agents.defaults.mediaModels.image:

json5

{  models: {    providers: {      litellm: {        baseUrl: "http://localhost:4000",        apiKey: "${LITELLM_API_KEY}",      },    },  },  agents: {    defaults: {      mediaModels: {        image: {          primary: "litellm/gpt-image-2",          timeoutMs: 180000,        },      },    },  },}

Loopback LiteLLM URLs (http://localhost:4000, 127.0.0.1, ::1, host.docker.internal) work without a global private-network override. For a LAN-hosted proxy, set models.providers.litellm.request.allowPrivateNetwork: true because the API key is sent to that host.

Backends that answer with image URLs (data[].url, for example dall-e-3) work like base64 results: OpenClaw downloads URLs at the configured provider origin automatically. Other private image hosts (including another port on loopback) require models.providers.litellm.request.allowPrivateNetwork: true. Redirects are checked at every hop. Downloads share the request deadline and the image size cap from agents.defaults.mediaMaxMb, without sending the LiteLLM API key or configured HTTP credentials to the image host.

Advanced

Virtual keys

Create a dedicated key for OpenClaw with spend limits:

bash

curl -X POST "http://localhost:4000/key/generate" \  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \  -H "Content-Type: application/json" \  -d '{    "key_alias": "openclaw",    "max_budget": 50.00,    "budget_duration": "monthly"  }'

Use the generated key as LITELLM_API_KEY.

Model routing

LiteLLM can route model requests to different backends. Configure in your LiteLLM config.yaml:

yaml

model_list:  - model_name: claude-opus-4-6    litellm_params:      model: claude-opus-4-6      api_key: os.environ/ANTHROPIC_API_KEY   - model_name: gpt-6-astra    litellm_params:      model: gpt-6-astra      api_key: os.environ/OPENAI_API_KEY

OpenClaw keeps requesting claude-opus-4-6; LiteLLM handles the routing.

Viewing usage

bash

# Key infocurl "http://localhost:4000/key/info" \  -H "Authorization: Bearer sk-litellm-key" # Spend logscurl "http://localhost:4000/spend/logs" \  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

Proxy behavior notes

LiteLLM runs on http://localhost:4000 by default.
OpenClaw connects through LiteLLM's proxy-style OpenAI-compatible /v1 endpoint.
Native-OpenAI-only request shaping does not apply through a configured LiteLLM base URL: no service_tier, no Responses store, no prompt-cache hints, no OpenAI reasoning-effort payload shaping.
Hidden OpenClaw attribution headers (originator, version, User-Agent) are only sent to verified native OpenAI endpoints, so they are not injected on a custom LiteLLM base URL.

LiteLLM Docs

Official LiteLLM documentation and API reference.

Model selection

Overview of all providers, model refs, and failover behavior.

Configuration

Full config reference.

Models

How to choose and configure models.

Was this useful?