Before any setup instructions, one thing you need to check.

LiteLLM PyPI versions 1.82.7 and 1.82.8 were compromised. On 24 March 2026 an attacker used stolen PyPI publishing credentials to push malicious releases, which were live for roughly 40 minutes before PyPI quarantined them. The payload was a litellm_init.pth file that executes automatically on every Python process start in any environment where the package is installed, then harvests SSH keys, cloud tokens, Kubernetes secrets, crypto wallets and .env files, and attempts lateral movement by deploying privileged pods in Kubernetes clusters.

Check what you have:

pip show litellm | grep -i version

If it reports 1.82.7 or 1.82.8, treat every credential reachable from that machine as exposed and rotate it. Details are in LiteLLM's own advisory and the upstream issue tracking the timeline. Pin a known-clean release rather than installing latest by reflex.

With that out of the way, the setup is straightforward.

Do you actually need this

Worth asking, because most people reading about LiteLLM do not need it.

If your provider already exposes an Anthropic-compatible endpoint, you need two environment variables and no proxy at all. That covers OpenCode Go, Z.ai's GLM plans and Kimi Code. We mapped the whole landscape in how to run Claude Code on a cheaper model.

LiteLLM earns its place when you need one of these: failover across several providers, per-developer usage attribution, audit logging for compliance, spend caps enforced in one place, or routing different request types to different models. Those are team problems. Solo, it is a process to keep alive for no benefit.

Configuration

Create a config.yaml with a model_list. This example uses complexity-based routing, sending easy requests to a cheap model and hard ones to an expensive one:

model_list:
  - model_name: claude-auto
    litellm_params:
      model: auto_router/complexity_router
      complexity_router_config:
        tiers:
          SIMPLE: claude-haiku-4-5
          MEDIUM: claude-sonnet-5
          COMPLEX: claude-sonnet-5
          REASONING: claude-opus-4-8
      complexity_router_default_model: claude-sonnet-5

Set a master key so the proxy is not open to anything that can reach the port:

export LITELLM_MASTER_KEY="sk-your-own-secret"

The model-name rule that breaks most setups

This one costs people an evening, and it is not intuitive.

Claude Code validates the model name client-side, before any request leaves your machine. The name must contain claude, anthropic, or a family name such as opus, sonnet, haiku, or fable.

So claude-auto and claude-smart-router are accepted. smart-router, auto, and a bare UUID are rejected. Including another vendor's name anywhere in the string also fails the check, regardless of what the model actually is.

If your requests are failing with nothing appearing in the proxy logs, this is almost certainly why. Nothing was sent.

Pointing Claude Code at the proxy

Three variables, plus one to enable model discovery:

export ANTHROPIC_BASE_URL=https://your-litellm-proxy.example.com
export ANTHROPIC_AUTH_TOKEN=sk-your-own-secret
export ANTHROPIC_MODEL=claude-auto
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

For anything beyond a quick test, put these in ~/.claude/settings.json under an env key instead. Shell exports die with the terminal, which is the single most common reason a working setup stops working after a reboot. The OpenCode Go post covers the permanent alternatives in detail.

In an organisation using managed settings, the exact model_name also has to be added to the availableModels allowlist before it becomes selectable.

When it breaks

Failures come from three places, and knowing which saves most of the debugging time:

  • The proxy is unreachable. Test it independently with curl before blaming Claude Code.
  • The auth token does not match the proxy config. ANTHROPIC_AUTH_TOKEN must equal what the proxy expects, usually LITELLM_MASTER_KEY or a key derived from it.
  • The model name is not exposed by your config, or fails the client-side naming rule above.

The structural cost is that you now have three components that can fail instead of one, and the failure can originate in Claude Code, in LiteLLM, or upstream at the provider. Anthropic's documentation makes the maintenance burden explicit: Claude Code adds capabilities with each release, and a gateway that does not forward them breaks the corresponding features. The same page states that Anthropic does not endorse, maintain or audit third-party gateways and does not support routing Claude Code to non-Claude models through one.

That is not an argument against doing it. It is an argument for knowing that your proxy is infrastructure with an owner, and the owner is you.

FAQ

Is LiteLLM safe to install?

Current releases are, but versions 1.82.7 and 1.82.8 were compromised in a March 2026 supply chain attack and must not be used. Those releases executed a malicious file on every Python process start and harvested SSH keys, cloud credentials, Kubernetes secrets and environment files. Check your installed version with pip show litellm, and rotate all reachable credentials if either version was ever present.

Do I need LiteLLM to use Claude Code with another provider?

Only if your provider does not expose an Anthropic-compatible endpoint. Providers such as OpenCode Go, Z.ai GLM and Kimi Code do expose one, so they need two environment variables and no proxy. LiteLLM is worth running when you need failover, per-developer usage attribution, audit logging or centralised spend caps.

Why does Claude Code reject my LiteLLM model name?

Because Claude Code validates model names before sending any request. The name must contain claude, anthropic, opus, sonnet, haiku, or fable. Names like auto or smart-router are rejected client-side, which is why nothing appears in your proxy logs. Rename the entry in config.yaml and the request goes through.

Which environment variables does Claude Code need for a proxy?

Set ANTHROPIC_BASE_URL to the proxy URL, ANTHROPIC_AUTH_TOKEN to the key the proxy expects, and ANTHROPIC_MODEL to the model name from your config.yaml. Add CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 to enable model discovery. Store them in ~/.claude/settings.json under env so they survive reboots.

Is running Claude Code through LiteLLM supported by Anthropic?

No. Anthropic's documentation states it does not endorse, maintain or audit third-party gateway products and does not support routing Claude Code to non-Claude models through any gateway. The setup works in practice, but breakage after a Claude Code release is yours to fix, since new client capabilities must be forwarded by the gateway to keep working.

Sources