OpenClawDocs
On this page

On this page

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

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

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: "gpt-6-astra",            name: "GPT-6 Astra",            reasoning: true,            input: ["text", "image"],            contextWindow: 1050000,            maxTokens: 128000,          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "litellm/claude-opus-4-6" },    },  },}

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

    In merge mode, onboarding with an explicit proxy URL preserves any authored provider models and otherwise leaves the provider model list empty for discovery. Run openclaw models list --provider litellm --refresh --json to list the proxy's models. With models.mode: "replace", discovery is disabled, so onboarding keeps the documented default in the provider model list while preserving existing model definitions.

    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.

    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?