Конфигурация LLM gateway

Узнайте, как настроить Claude Code для работы с решениями LLM gateway. Охватывает требования к шлюзу, конфигурацию аутентификации, выбор модели и настройку конечных точек для конкретных поставщиков.

LLM gateways предоставляют централизованный прокси-слой между Claude Code и поставщиками моделей, часто предоставляя:

• Централизованная аутентификация - Единая точка управления ключами API
• Отслеживание использования - Мониторинг использования в командах и проектах
• Контроль затрат - Реализация бюджетов и ограничений скорости
• Логирование аудита - Отслеживание всех взаимодействий с моделью для соответствия требованиям
• Маршрутизация моделей - Переключение между поставщиками без изменения кода

На этой странице рассматриваются требования к шлюзу и конфигурация для Claude Code CLI. Развертывания Enterprise Desktop могут настраивать поставщиков шлюза через управляемые параметры. Приложение Claude Desktop также может работать с самостоятельно размещенным шлюзом через Cowork on 3P research preview, который использует свои собственные ключи конфигурации.

Требования к шлюзу

Чтобы LLM gateway работал с Claude Code, он должен соответствовать следующим требованиям:

Формат API

Шлюз должен предоставлять клиентам по крайней мере один из следующих форматов API:

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

   • Должен перенаправлять заголовки запроса: anthropic-beta, anthropic-version

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

   • Должен сохранять поля тела запроса: anthropic_beta, anthropic_version

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

   • Должен перенаправлять заголовки запроса: anthropic-beta, anthropic-version

Невозможность перенаправления заголовков или сохранения полей тела может привести к снижению функциональности или невозможности использования функций Claude Code.

Заголовки запроса

Claude Code включает следующие заголовки в каждый запрос API:

Оба заголовка идентификатора агента являются эфемерными идентификаторами для каждого создания, а не постоянными идентификаторами пользователя или устройства.

Claude Code также добавляет короткий блок атрибуции в системный запрос, содержащий версию клиента и отпечаток, полученный из разговора. API Anthropic удаляет этот блок перед обработкой, поэтому он не влияет на кэширование запросов первой стороны. Если ваш шлюз реализует собственный кэш запросов, основанный на полном теле запроса, установите CLAUDE_CODE_ATTRIBUTION_HEADER=0, чтобы опустить его.

Конфигурация

Выбор модели

По умолчанию Claude Code использует стандартные имена моделей для выбранного формата API.

Когда ANTHROPIC_BASE_URL указывает на шлюз, который предоставляет формат Anthropic Messages, Claude Code может запросить конечную точку /v1/models шлюза при запуске и добавить возвращённые модели в средство выбора /model. Установите CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, чтобы включить это. Обнаружение отключено по умолчанию, чтобы шлюзы, поддерживаемые общим ключом API, не раскрывали каждому пользователю все модели, к которым может получить доступ ключ. Каждая обнаруженная запись помечена как "From gateway" и использует поле display_name из ответа, если оно предоставлено. Это требует Claude Code версии 2.1.129 или более поздней.

Обнаружение применяется только к формату Anthropic Messages. Оно не выполняется для конечных точек Bedrock или Vertex pass-through, и оно не выполняется, когда ANTHROPIC_BASE_URL не установлен или указывает на api.anthropic.com.

Запрос обнаружения аутентифицируется так же, как запросы вывода: он отправляет ANTHROPIC_AUTH_TOKEN как токен bearer, или ANTHROPIC_API_KEY как заголовок x-api-key, когда токен аутентификации не установлен, вместе с любыми заголовками из ANTHROPIC_CUSTOM_HEADERS. Только модели, чьи идентификаторы начинаются с claude или anthropic, добавляются в средство выбора. Результаты кэшируются в ~/.claude/cache/gateway-models.json и обновляются при каждом запуске. Если запрос не удаётся или шлюз не реализует /v1/models, средство выбора возвращается к кэшированному списку из предыдущего запуска или к встроенному списку моделей.

Если ваш шлюз использует имена моделей, которые не соответствуют фильтру обнаружения, используйте переменные окружения, описанные в Конфигурация модели, чтобы добавить их вручную.

Конфигурация LiteLLM

Предварительные требования

• Claude Code обновлен до последней версии
• LiteLLM Proxy Server развернут и доступен
• Доступ к моделям Claude через выбранного поставщика

Базовая настройка LiteLLM

Конфигурация Claude Code:

Методы аутентификации

Статический ключ API

Самый простой метод с использованием фиксированного ключа API:

# Установить в окружении
export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key

# Или в настройках Claude Code
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key"
  }
}

Это значение будет отправлено как заголовок Authorization.

Динамический ключ API с помощником

Для ротации ключей или аутентификации для каждого пользователя:

1. Создайте скрипт помощника ключа API:

#!/bin/bash
# ~/bin/get-litellm-key.sh

# Пример: Получить ключ из хранилища
vault kv get -field=api_key secret/litellm/claude-code

# Пример: Сгенерировать JWT токен
jwt encode \
  --secret="${JWT_SECRET}" \
  --exp="+1h" \
  '{"user":"'${USER}'","team":"engineering"}'

2. Настройте параметры Claude Code для использования помощника:

{
  "apiKeyHelper": "~/bin/get-litellm-key.sh"
}

3. Установите интервал обновления токена:

# Обновлять каждый час (3600000 мс)
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000

Это значение будет отправлено как заголовки Authorization и X-Api-Key. apiKeyHelper имеет более низкий приоритет, чем ANTHROPIC_AUTH_TOKEN или ANTHROPIC_API_KEY.

Унифицированная конечная точка (рекомендуется)

Использование конечной точки формата Anthropic LiteLLM:

export ANTHROPIC_BASE_URL=https://litellm-server:4000

Преимущества унифицированной конечной точки над сквозными конечными точками:

• Балансировка нагрузки
• Резервные варианты
• Последовательная поддержка отслеживания затрат и отслеживания конечного пользователя

Конечные точки сквозного прохода для конкретных поставщиков (альтернатива)

Claude API через LiteLLM

Использование сквозной конечной точки:

export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic

Amazon Bedrock через LiteLLM

Использование сквозной конечной точки:

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 через LiteLLM

Использование сквозной конечной точки:

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

Claude Platform on AWS через шлюз

Маршрутизация на шлюз, который перенаправляет на конечную точку Claude Platform on AWS:

export ANTHROPIC_AWS_BASE_URL=https://litellm-server:4000/anthropic-aws
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1

Для получения более подробной информации обратитесь к документации LiteLLM.

Дополнительные ресурсы

• Документация LiteLLM
• Параметры Claude Code
• Конфигурация корпоративной сети
• Обзор интеграций третьих сторон