LiteLLM Proxy Setup for OpenClaw

LiteLLM is an open-source gateway for LLMs that exposes one unified API across more than 100 model providers. Sending OpenClaw traffic through LiteLLM gives you centralized cost tracking, logging, virtual keys with spend limits, and backend failover, and none of it requires edits to your OpenClaw config.

Quick start

Onboarding (recommended)

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

During onboarding you are asked for the proxy base URL. Keep the http://localhost:4000 default by pressing Enter, or type in the URL of your own proxy. Once the API key is entered, pick a model from those the proxy advertises at its /v1/models endpoint. The first model in that list is preselected by default, and a model ID can also be typed in by hand. Should discovery fail, onboarding reports the reason and requests a manual ID. When the configuration changes while credentials are still being prepared, setup halts before the discovery request goes out. Run onboarding again with the updated configuration.

To set up non-interactively against a remote proxy, supply the proxy URL explicitly:

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"

Manual setup

Start LiteLLM Proxy

Because LiteLLM contacts the upstream provider for you, export that provider's key before launching it, using ANTHROPIC_API_KEY for the model below. Multi-backend arrangements are covered in Model routing.

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

Point OpenClaw to LiteLLM

export LITELLM_API_KEY="your-litellm-key"
openclaw

Configuration

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

When onboarding runs interactively, the chosen model is saved as litellm/<model-id>, and any model settings you authored are retained if that ID is already configured. Re-authentication preserves an existing default model and makes the selected model available. The litellm/claude-opus-4-6 default is kept for non-interactive onboarding. To change it after setup:

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

In both merge and replace modes, interactive setup records the selected model while leaving authored provider models intact. With an explicit proxy URL, non-interactive setup leaves the model list available for discovery in merge mode, whereas replace mode keeps its documented default. Refresh the proxy's model list by running openclaw models list --provider litellm --refresh --json.

Re-running authentication also folds case-variant provider keys, for example LiteLLM and litellm, into a single canonical row, and authored provider options and model settings survive, including when a saved sign-in is activated. When --custom-base-url is omitted during non-interactive reauthentication, the configured proxy URL is kept, even if the existing provider key uses different casing.

Image generation

The image_generate tool can be backed by LiteLLM through the OpenAI-compatible /images/generations and /images/edits routes. gpt-image-2 is the default image model; set another one under agents.defaults.mediaModels.image:

{
  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) are accepted without a global private-network override. When the proxy is hosted on a LAN, set models.providers.litellm.request.allowPrivateNetwork: true, since the API key travels to that host.

Backends that reply with image URLs (data[].url, such as dall-e-3) behave the same as base64 results: OpenClaw fetches those URLs from the configured provider origin on its own. Any other private image host, including a different port on loopback, needs models.providers.litellm.request.allowPrivateNetwork: true. Every redirect hop is checked. Downloads inherit the request deadline and the image size cap from agents.defaults.mediaMaxMb, and neither the LiteLLM API key nor configured HTTP credentials are sent to the image host.

Advanced

Virtual keys

For OpenClaw, create a dedicated key that carries spend limits:

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"
  }'

That generated key goes in as LITELLM_API_KEY.

Model routing

Model requests can be sent by LiteLLM to different backends. Set this up in your LiteLLM config.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 continues to request claude-opus-4-6, while the routing is left to LiteLLM.

Viewing usage

# Key info
curl "http://localhost:4000/key/info" \
  -H "Authorization: Bearer sk-litellm-key"

# Spend logs
curl "http://localhost:4000/spend/logs" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

Proxy behavior notes

By default, LiteLLM listens on http://localhost:4000.
OpenClaw reaches LiteLLM through its proxy-style OpenAI-compatible /v1 endpoint.
Request shaping that is native-OpenAI-only is not applied when a LiteLLM base URL is configured: there is no service_tier, no Responses store, no prompt-cache hints, and no OpenAI reasoning-effort payload shaping.
The hidden OpenClaw attribution headers (originator, version, User-Agent) are injected only toward verified native OpenAI endpoints, so a custom LiteLLM base URL does not receive them.

Note

General provider configuration and failover behavior are described in Model Providers.

LiteLLM Docs, The official LiteLLM documentation and API reference.
Model selection, A survey of all providers, model refs, and failover behavior.
Configuration, The complete config reference.
Models: Guidance on picking and setting up models.