LiteLLM Provider

기준일: 2026-07-26
난이도: 중급
공식 기준: LiteLLM

개요

이 페이지는 OpenClaw LiteLLM provider의 인증, 모델 ref, 온보딩 플래그, 설정 키를 공식 문서 기준으로 정리합니다.

공식 요약: Run OpenClaw through LiteLLM Proxy for unified model access and cost tracking

model ref는 보통 provider/model 형식입니다. API key·endpoint·model id는 아래 원문 값을 그대로 쓰세요. 임의로 키나 엔드포인트를 만들지 마세요.

공식 문서 기반 상세

아래는 공식 providers/litellm 문서를 Mintlify 컴포넌트만 정리하고 공통 제목을 한국어로 맞춘 내용입니다. 설정 키, env, model ref, CLI 플래그는 원문 그대로 유지합니다.

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.

빠른 시작

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

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

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





  

Start LiteLLM Proxy

    ```bash
    pip install 'litellm[proxy]'
    litellm --model claude-opus-4
    ```
  

  

Point OpenClaw to LiteLLM

    ```bash
    export LITELLM_API_KEY="your-litellm-key"
    openclaw
    ```
  

설정

{
  models: {
    providers: {
      litellm: {
        baseUrl: "http://localhost:4000",
        apiKey: "${LITELLM_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "claude-opus-4",
            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" },
    },
  },
}

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

이미지 생성

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:

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

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
    litellm_params:
      model: claude-opus-4
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: gpt-4o
    litellm_params:
      model: gpt-4o
      api_key: os.environ/OPENAI_API_KEY
```

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

Viewing usage

```bash
# 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

- 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.

For general provider configuration and failover behavior, see Model Providers.

관련 문서

Official LiteLLM documentation and API reference.


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


Full config reference.


How to choose and configure models.

검증 체크리스트

• openclaw models list --provider litellm 로 모델이 보이는지 확인
• 기본 model alias를 agents.defaults.model.primary에 설정했는지 확인
• API key / OAuth / 로컬 런타임 인증 경로를 공식 문서와 대조했는지 확인
• failover 시 데이터가 다른 provider로 이동할 수 있는지 검토

관련

• Provider 목록 인덱스
• 로컬 모델과 Provider
• 공식: Provider directory, Model providers