Home › Sources › LLM gateway configuration

LLM gateway configuration

Tags

official-docs claude-code-cli

Content

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.

LLM gateway configuration

Learn how to configure Claude Code to work with LLM gateway solutions. Covers gateway requirements, authentication configuration, model selection, and provider-specific endpoint setup.

LLM gateways provide a centralized proxy layer between Claude Code and model providers, often providing:

Gateway requirements

For an LLM gateway to work with Claude Code, it must meet the following requirements:

API format

The gateway must expose to clients at least one of the following API formats:

  1. Anthropic Messages: /v1/messages, /v1/messages/count_tokens

  2. Must forward request headers: anthropic-beta, anthropic-version

  3. Bedrock InvokeModel: /invoke, /invoke-with-response-stream

  4. Must preserve request body fields: anthropic_beta, anthropic_version

  5. Vertex rawPredict: :rawPredict, :streamRawPredict, /count-tokens:rawPredict

  6. Must forward request headers: anthropic-beta, anthropic-version

Failure to forward headers or preserve body fields may result in reduced functionality or inability to use Claude Code features.

Claude Code determines which features to enable based on the API format. When using the Anthropic Messages format with Bedrock or Vertex, you may need to set environment variable CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.

Request headers

Claude Code includes the following headers on every API request:

Header Description
X-Claude-Code-Session-Id A unique identifier for the current Claude Code session. Proxies can use this to aggregate all API requests from a single session without parsing the request body.

Configuration

Model selection

By default, Claude Code will use standard model names for the selected API format.

If you have configured custom model names in your gateway, use the environment variables documented in Model configuration to match your custom names.

LiteLLM configuration

LiteLLM PyPI versions 1.82.7 and 1.82.8 were compromised with credential-stealing malware. Do not install these versions. If you have already installed them:

LiteLLM is a third-party proxy service. Anthropic doesn't endorse, maintain, or audit LiteLLM's security or functionality. This guide is provided for informational purposes and may become outdated. Use at your own discretion.

Prerequisites

Basic LiteLLM setup

Configure Claude Code:

Authentication methods

Static API key

Simplest method using a fixed API key:

```bash theme={null}

Set in environment

export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key

Or in Claude Code settings

{ "env": { "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key" } }


This value will be sent as the `Authorization` header.

##### Dynamic API key with helper

For rotating keys or per-user authentication:

1. Create an API key helper script:

```bash theme={null}
#!/bin/bash
# ~/bin/get-litellm-key.sh

# Example: Fetch key from vault
vault kv get -field=api_key secret/litellm/claude-code

# Example: Generate JWT token
jwt encode \
  --secret="${JWT_SECRET}" \
  --exp="+1h" \
  '{"user":"'${USER}'","team":"engineering"}'
  1. Configure Claude Code settings to use the helper:

```json theme={null} { "apiKeyHelper": "~/bin/get-litellm-key.sh" }


3. Set token refresh interval:

```bash theme={null}
# Refresh every hour (3600000 ms)
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000

This value will be sent as Authorization and X-Api-Key headers. The apiKeyHelper has lower precedence than ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY.

Using LiteLLM's Anthropic format endpoint:

```bash theme={null} export ANTHROPIC_BASE_URL=https://litellm-server:4000


**Benefits of the unified endpoint over pass-through endpoints:**

* Load balancing
* Fallbacks
* Consistent support for cost tracking and end-user tracking

#### Provider-specific pass-through endpoints (alternative)

##### Claude API through LiteLLM

Using [pass-through endpoint](https://docs.litellm.ai/docs/pass_through/anthropic_completion):

```bash theme={null}
export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic
Amazon Bedrock through LiteLLM

Using pass-through endpoint:

```bash theme={null} export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 export CLAUDE_CODE_USE_BEDROCK=1


##### Google Vertex AI through LiteLLM

Using [pass-through endpoint](https://docs.litellm.ai/docs/pass_through/vertex_ai):

```bash theme={null}
export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5

For more detailed information, refer to the LiteLLM documentation.

Additional resources