LiteLLM Integration for OpenClaw

LiteLLM serves as an open-source gateway for LLMs, exposing a single API that covers more than 100 model providers. By placing OpenClaw behind LiteLLM, you gain centralized spend tracking, request logging, virtual keys with budget caps, and automatic backend switching, all without touching your existing OpenClaw configuration.

Quick start

First-time setup (suggested path)

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

When running non-interactively against a remote proxy, specify the proxy URL directly:

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"

Configuration by hand

Start LiteLLM Proxy

pip install 'litellm[proxy]'
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: "gpt-4o",
            name: "GPT-4o",
            reasoning: false,
            input: ["text", "image"],
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "litellm/claude-opus-4-6" },
    },
  },
}

The model that onboarding writes by default is litellm/claude-opus-4-6.

Image generation

LiteLLM can serve as the backend for the image_generate tool via the OpenAI-compatible /images/generations and /images/edits endpoints. The default image model is gpt-image-2; to pick a different one, adjust 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,
        },
      },
    },
  },
}

LiteLLM URLs that loop back locally (http://localhost:4000, 127.0.0.1, ::1, host.docker.internal) function without needing a global private-network override. If your proxy lives on a LAN, configure models.providers.litellm.request.allowPrivateNetwork: true, since the API key gets transmitted to that host.

Advanced

Virtual keys

Generate a key reserved for OpenClaw, complete with spending 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"
  }'

Then supply that key as LITELLM_API_KEY.

Model routing

Routing model traffic to various backends is something LiteLLM handles well. Set this up inside 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-4o
    litellm_params:
      model: gpt-4o
      api_key: os.environ/OPENAI_API_KEY

OpenClaw will keep sending requests for claude-opus-4-6; the actual routing is LiteLLM's responsibility.

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 assumes native OpenAI behavior is bypassed once a LiteLLM base URL is configured: service_tier is absent, Responses store is unavailable, prompt-cache hints are dropped, and OpenAI reasoning-effort payload shaping is skipped.
OpenClaw's hidden attribution headers (originator, version, User-Agent) are forwarded exclusively to confirmed native OpenAI endpoints, so they never appear on a custom LiteLLM base URL.

Note

For details on configuring providers generally and how failover behaves, refer to Model Providers.

LiteLLM Docs, The official LiteLLM documentation and API reference.
Model selection, Covers every provider, model references, and failover behavior.
Configuration, The complete configuration reference.
Models, Guidance on picking and setting up models.