Configuración de la puerta de enlace LLM

Aprende cómo configurar Claude Code para trabajar con soluciones de puerta de enlace LLM. Cubre requisitos de puerta de enlace, configuración de autenticación, selección de modelos y configuración de puntos finales específicos del proveedor.

Las puertas de enlace LLM proporcionan una capa proxy centralizada entre Claude Code y los proveedores de modelos, a menudo proporcionando:

• Autenticación centralizada - Punto único para la gestión de claves API
• Seguimiento de uso - Monitorea el uso en equipos y proyectos
• Controles de costos - Implementa presupuestos y límites de velocidad
• Registro de auditoría - Rastrea todas las interacciones del modelo para cumplimiento normativo
• Enrutamiento de modelos - Cambia entre proveedores sin cambios de código

Esta página cubre los requisitos de puerta de enlace y la configuración para Claude Code CLI. Las implementaciones de Enterprise Desktop pueden configurar proveedores de puerta de enlace a través de configuración administrada. La aplicación Claude Desktop también puede ejecutarse contra una puerta de enlace autohospedada a través de la vista previa de investigación de Cowork en terceros, que utiliza sus propias claves de configuración.

Requisitos de la puerta de enlace

Para que una puerta de enlace LLM funcione con Claude Code, debe cumplir con los siguientes requisitos:

Formato de API

La puerta de enlace debe exponer a los clientes al menos uno de los siguientes formatos de API:

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

   • Debe reenviar encabezados de solicitud: anthropic-beta, anthropic-version

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

   • Debe preservar campos del cuerpo de la solicitud: anthropic_beta, anthropic_version

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

   • Debe reenviar encabezados de solicitud: anthropic-beta, anthropic-version

El incumplimiento de reenvío de encabezados o la preservación de campos del cuerpo puede resultar en funcionalidad reducida o incapacidad de usar características de Claude Code.

Encabezados de solicitud

Claude Code incluye los siguientes encabezados en solicitudes de API:

Ambos encabezados de ID de agente son identificadores efímeros por generación, no identificadores persistentes de usuario o dispositivo.

Claude Code también antepone un bloque de atribución corto al mensaje del sistema que contiene la versión del cliente y una huella digital derivada de la conversación. La API de Anthropic elimina este bloque antes de procesarlo, por lo que no afecta el almacenamiento en caché de solicitudes de primer nivel. Si su puerta de enlace implementa su propio caché de solicitudes con clave en el cuerpo de la solicitud completa, establezca CLAUDE_CODE_ATTRIBUTION_HEADER=0 para omitirlo.

Configuración

Selección de modelo

Por defecto, Claude Code utiliza nombres de modelo estándar para el formato de API seleccionado.

Cuando ANTHROPIC_BASE_URL apunta a una puerta de enlace que expone el formato de Mensajes de Anthropic, Claude Code puede consultar el punto final /v1/models de la puerta de enlace al inicio y añadir los modelos devueltos al selector /model. Establezca CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 para habilitar esto. El descubrimiento está desactivado por defecto para que las puertas de enlace respaldadas por una clave de API compartida no expongan todos los modelos a los que la clave puede acceder a cada usuario. Cada entrada descubierta se etiqueta como "Desde puerta de enlace" y utiliza el campo display_name de la respuesta cuando se proporciona uno. Esto requiere Claude Code v2.1.129 o posterior.

El descubrimiento se aplica solo al formato de Mensajes de Anthropic. No se ejecuta para puntos finales de paso a través de Bedrock o Vertex, y no se ejecuta cuando ANTHROPIC_BASE_URL no está configurado o apunta a api.anthropic.com.

La solicitud de descubrimiento se autentica de la misma manera que las solicitudes de inferencia: envía ANTHROPIC_AUTH_TOKEN como un token portador, o ANTHROPIC_API_KEY como el encabezado x-api-key cuando no hay un token de autenticación configurado, junto con cualquier encabezado de ANTHROPIC_CUSTOM_HEADERS. Solo se añaden al selector los modelos cuyo ID comienza con claude o anthropic. Los resultados se almacenan en caché en ~/.claude/cache/gateway-models.json y se actualizan en cada inicio. Si la solicitud falla o la puerta de enlace no implementa /v1/models, el selector vuelve a la lista en caché del inicio anterior o a la lista de modelos integrada.

Si su puerta de enlace utiliza nombres de modelo que no coinciden con el filtro de descubrimiento, utilice las variables de entorno documentadas en Configuración de modelo para añadirlos manualmente.

Configuración de LiteLLM

Requisitos previos

• Claude Code actualizado a la última versión
• Servidor Proxy de LiteLLM implementado y accesible
• Acceso a modelos Claude a través de su proveedor elegido

Configuración básica de LiteLLM

Configure Claude Code:

Métodos de autenticación

Clave API estática

Método más simple usando una clave API fija:

# Establecer en el entorno
export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key

# O en la configuración de Claude Code
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key"
  }
}

Este valor se enviará como encabezado Authorization.

Clave API dinámica con ayudante

Para claves rotativas o autenticación por usuario:

1. Cree un script ayudante de clave API:

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

# Ejemplo: Obtener clave del almacén
vault kv get -field=api_key secret/litellm/claude-code

# Ejemplo: Generar token JWT
jwt encode \
  --secret="${JWT_SECRET}" \
  --exp="+1h" \
  '{"user":"'${USER}'","team":"engineering"}'

2. Configure la configuración de Claude Code para usar el ayudante:

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

3. Establezca el intervalo de actualización de token:

# Actualizar cada hora (3600000 ms)
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000

Este valor se enviará como encabezados Authorization y X-Api-Key. El apiKeyHelper tiene menor precedencia que ANTHROPIC_AUTH_TOKEN o ANTHROPIC_API_KEY.

Punto final unificado (recomendado)

Usando el punto final de formato Anthropic de LiteLLM:

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

Beneficios del punto final unificado sobre puntos finales de paso directo:

• Equilibrio de carga
• Alternativas
• Soporte consistente para seguimiento de costos y seguimiento de usuario final

Puntos finales de paso directo específicos del proveedor (alternativa)

API de Claude a través de LiteLLM

Usando punto final de paso directo:

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

Amazon Bedrock a través de LiteLLM

Usando punto final de paso directo:

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 a través de LiteLLM

Usando punto final de paso directo:

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

Plataforma Claude en AWS a través de una puerta de enlace

Enrute a una puerta de enlace que reenvía al punto final de Plataforma Claude en 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

Para obtener información más detallada, consulte la documentación de LiteLLM.

Recursos adicionales

• Documentación de LiteLLM
• Configuración de Claude Code
• Configuración de red empresarial
• Descripción general de integraciones de terceros