Claude Code con LiteLLM: Guía de configuración + Cuándo usar TrueFoundry AI Gateway

Claude Code viene bloqueado por defecto con la API de Anthropic. Eso está bien para desarrolladores individuales, pero en el momento en que tienes un equipo, necesitas controles de costes, visibilidad de uso y acceso a modelos más allá del catálogo de Anthropic. Eso es exactamente lo que te ofrece un AI gateway.

LiteLLM es la opción de código abierto más popular para esto. Apunta Claude Code a un proxy de LiteLLM y podrás enrutar a Bedrock, Vertex AI, Azure OpenAI o cualquier proveedor sin tocar cómo se comporta Claude Code en la terminal. Sin embargo, la arquitectura autogestionada de LiteLLM crea una sobrecarga real a escala, y sus carencias en funcionalidades empresariales se hacen evidentes rápidamente.

Esta guía cubre ambas vías: cómo configurar Claude Code con LiteLLM hoy mismo y cuándo tiene más sentido para tu equipo cambiar a TrueFoundry AI Gateway.

¿Por qué conectar Claude Code a un AI Gateway?

Claude Code expone una única variable de entorno, ANTHROPIC_BASE_URL, que redirige todo su tráfico de API a cualquier endpoint que admita la API de Anthropic Messages. Configura esa variable con la URL de un gateway y cada petición que haga Claude Code fluirá a través de tu infraestructura en lugar de ir directamente a api.anthropic.com.

Esa única variable desbloquea cuatro cosas que las claves API individuales no pueden darte:

• Visibilidad de costes. Las claves directas de Anthropic generan un gasto que es invisible hasta que llega tu factura mensual. Un gateway intercepta cada petición y te ofrece atribución por desarrollador, por equipo o por proyecto en tiempo real.
• Acceso multiproveedor. Enruta tareas de nivel Opus al mejor modelo pionero disponible y tareas de nivel Haiku a alternativas más económicas sin cambiar ni una sola línea en Claude Code.
• Credenciales centralizadas. Sin claves API directas de Anthropic almacenadas en archivos .bash_profile en los portátiles de los desarrolladores. El gateway conserva las credenciales de los proveedores; los desarrolladores se autentican en el gateway con claves virtuales con alcance limitado.
• Fiabilidad. Enrutamiento de conmutación por error (fallback) automático cuando Anthropic alcanza límites de frecuencia o sufre una interrupción. Claude Code nunca necesita enterarse de que se ha producido una conmutación por error.

La cuestión no es si debes usar un gateway. La cuestión es cuál utilizar.

Cómo se conecta Claude Code a cualquier Gateway

El mecanismo es el mismo independientemente de si estás utilizando LiteLLM, TrueFoundry o cualquier otro proxy compatible con Anthropic. Dos variables de entorno lo controlan todo:‍


Para una configuración persistente entre sesiones, escribe lo siguiente en el archivo settings.json de Claude Code:

El archivo de configuración se encuentra en ~/.claude/settings.json (global del usuario) o en .claude/settings.json en la raíz de tu proyecto (compartido con el equipo). Para despliegues en equipo, el archivo a nivel de proyecto es la elección correcta: garantiza que cada desarrollador del proyecto utilice la misma configuración de gateway sin necesidad de realizar ajustes en cada máquina.

A partir de este punto, Claude Code no tiene forma de saber que está hablando con un gateway en lugar de hacerlo directamente con Anthropic. Todo (el streaming, el uso de herramientas, los alias de modelos, las conversaciones de varios turnos) funciona exactamente igual que antes.

Configuración de Claude Code con LiteLLM

LiteLLM se ejecuta como un proxy local o autoalojado que traduce la API de Anthropic Messages al formato que espere cada proveedor ascendente. Esta es la configuración estándar.

Paso 1: Instala LiteLLM y escribe tu configuración

Crea un archivo litellm-config.yaml que defina tu lista de modelos. Una configuración mínima con Anthropic directo y AWS Bedrock como fallback tiene el siguiente aspecto:

Exporta tus claves e inicia el proxy:‍


Paso 2: Apunta Claude Code a LiteLLM‍


O para una configuración permanente del equipo en .claude/settings.json:‍


Ejecuta claude en tu terminal. Claude Code se conecta a través de LiteLLM, y LiteLLM reenvía la petición a Anthropic (o al proveedor que hayas configurado).

Paso 3: Añade Bedrock, Vertex u otros proveedores

La razón principal por la que los equipos añaden LiteLLM es para enrutar a AWS Bedrock (para inferencia residente en VPC) o Google Vertex AI (para flujos de trabajo nativos de GCP). Añade proveedores a tu lista de modelos:‍


Nota sobre Bedrock y cabeceras experimentales: Claude Code adjunta cabeceras experimentales anthropic-beta en cada petición. Bedrock no las acepta todas y puede devolver un error 400 invalid beta flag. Configura CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 en el bloque env de tu ~/.claude/settings.json cuando enrutes a través de Bedrock.

Limitaciones de LiteLLM a escala empresarial

LiteLLM funciona bien para desarrolladores individuales y equipos pequeños. A medida que las organizaciones crecen, varios vacíos se vuelven significativos:

Sobrecarga de latencia. LiteLLM añade una sobrecarga de proxy medible bajo carga concurrente. En las sesiones de Claude Code, donde una sola tarea de codificación genera docenas de llamadas API secuenciales, esto se acumula. A un número elevado de RPS, LiteLLM sufre sin un escalado horizontal que requiere una configuración manual de Kubernetes.

Sin RBAC nativo. El sistema de claves virtuales de LiteLLM es básico. Garantizar que el Equipo A solo pueda acceder a los modelos de Claude mientras que el Equipo B pueda usar cualquier proveedor, o que la clave de un contratista expire tras 30 días, requiere un middleware personalizado sobre LiteLLM.

Carga de infraestructura autogestionada. LiteLLM es de código abierto. Cada actualización, migración de Postgres, configuración de caché de Redis y certificado SSL es responsabilidad de tu equipo. Para equipos de plataforma que ya están al límite, esto se convierte en una carga de mantenimiento sustancial.

El control de presupuestos es limitado. LiteLLM admite límites de presupuesto por clave, pero los límites proactivos por desarrollador con alertas en tiempo real antes de alcanzar el límite requieren herramientas adicionales.

Carencias de cumplimiento normativo. Las cargas de trabajo reguladas por SOC 2, HIPAA y GDPR necesitan registros de auditoría, historial de peticiones inmutable y controles de residencia de datos. Estos elementos no están integrados en el nivel de código abierto de LiteLLM.

Para los equipos que ejecutan LiteLLM en producción y se topan con estos límites, la publicación sobre alternativas a LiteLLM cubre todo el panorama. La versión corta: TrueFoundry AI Gateway está diseñado específicamente para el caso de uso empresarial para el que LiteLLM nunca fue concebido.

Claude Code con TrueFoundry AI Gateway

TrueFoundry AI Gateway es un endpoint compatible con Anthropic listo para usar. El mismo mecanismo de ANTHROPIC_BASE_URL que conecta Claude Code a LiteLLM lo conecta a TrueFoundry: sin cambios en el funcionamiento de Claude Code, sin nuevos SDK y sin reescrituras en el lado del cliente.

La diferencia reside en lo que ocurre en la capa del gateway. TrueFoundry se ejecuta en tu VPC, gestiona entre 3 y 4 ms de sobrecarga de gateway a más de 350 RPS en un solo vCPU y viene equipado de serie con RBAC, control de presupuestos, registros de auditoría y enrutamiento multiproveedor, sin necesidad de integraciones adicionales que requieran configuraciones personalizadas.

Paso 1: Obtén la URL de tu Gateway de TrueFoundry y tu clave virtual

Inicia sesión en tu panel de control de TrueFoundry. Navega a AI Gateway → Virtual Keys y crea una clave con alcance limitado para tu equipo o proyecto. Obtendrás:

• Una URL de plano de control con el formato https://<your-org>.truefoundry.cloud/api/llm/v1
• Una clave virtual (con alcance limitado a modelos específicos, proveedores y límites de presupuesto opcionales)

Paso 2: Conecta Claude Code a TrueFoundry‍


Para una configuración persistente a nivel de proyecto, añade lo siguiente a .claude/settings.json:‍


Ejecuta claude — Claude Code ahora fluye a través de TrueFoundry. Cada petición se registra, se atribuye y se rige por las políticas que has establecido en esa clave virtual.

Paso 3: Configura proveedores y enrutamiento de modelos en el Dashboard

A diferencia de la configuración con archivos YAML de LiteLLM, la configuración de proveedores en TrueFoundry se realiza en el panel del Gateway. Añade tu cuenta de Anthropic, conecta las credenciales de AWS Bedrock o Google Vertex y define alias de modelos, todo desde una interfaz de usuario que tu equipo de plataforma gestiona de forma centralizada.

Los alias de modelos integrados en Claude Code (opus, sonnet, haiku) se asignan limpiamente a los modelos virtuales de TrueFoundry. Configura la asignación una vez en el panel y cada desarrollador que utilice el .claude/settings.json del proyecto obtendrá el enrutamiento correcto del modelo automáticamente, sin tocar las variables de entorno en las máquinas individuales.

Lo que desbloqueas: Flujos de trabajo empresariales para Claude Code

Una vez que Claude Code se enruta a través de TrueFoundry, quedan disponibles cinco capacidades que no existen con el acceso directo a Anthropic ni con el LiteLLM básico:

Control de costes. Establece presupuestos diarios de tokens por desarrollador o por equipo directamente en las claves virtuales. El gateway aplica los límites de forma proactiva: las peticiones que superen el presupuesto devuelven un error antes de generar gasto, en lugar de notificártelo después de que llegue la factura.

Observabilidad. Cada petición de Claude Code se rastrea de principio a fin: qué desarrollador la envió, qué modelo la gestionó, cuántos tokens se consumieron y cuánto costó. TrueFoundry cumple con OpenTelemetry y se integra con Grafana, Datadog o Prometheus sin instrumentación adicional.

Seguridad y gobernanza. Las claves virtuales reemplazan las claves API directas de Anthropic en las máquinas de los desarrolladores. Cuando un ingeniero deja la organización, revocas su clave en un solo lugar. Las credenciales subyacentes de Anthropic nunca salen del gestor de secretos del gateway. Para las empresas que requieren la integración de Claude Code con SSO y una configuración impuesta por MDM, el gateway de TrueFoundry es la capa de aplicación de políticas.

Acceso multiproveedor. Claude Code habla con un solo endpoint. Detrás de ese endpoint, TrueFoundry enruta a Anthropic directo, AWS Bedrock, Google Vertex AI, Azure OpenAI o modelos locales (on-premise), según las políticas que definas. Cambia de proveedor sin tocar la máquina de un solo desarrollador.

Fiabilidad. El enrutamiento de conmutación por error automático gestiona los límites de frecuencia de Anthropic de forma transparente. Si el proveedor principal devuelve un error 429 o 503, el gateway reintenta la petición contra un fallback configurado antes de que Claude Code vea un error. Para los flujos de trabajo de desarrollo que no pueden permitirse interrupciones, esta es la diferencia entre un inconveniente menor y un sprint bloqueado.

LiteLLM frente a TrueFoundry para Claude Code

LiteLLM es un proxy excelente para desarrolladores individuales o equipos pequeños que realizan experimentos. TrueFoundry está diseñado para el escenario en el que Claude Code es una herramienta para todo el equipo y el equipo de plataforma necesita gobernarlo sin tener que construir esa capa de gobernanza por sí mismo.

Preguntas frecuentes

P: ¿Cómo usar Claude Code con LiteLLM?

‍Instala LiteLLM con pip install litellm[proxy], escribe un archivo litellm-config.yaml definiendo tus modelos e inicia el proxy con litellm --config. Luego configura ANTHROPIC_BASE_URL=http://localhost:4000 y ANTHROPIC_AUTH_TOKEN con tu clave maestra de LiteLLM antes de ejecutar claude. Toda la configuración se detalla en la sección paso a paso anterior.

P: ¿Es TrueFoundry una alternativa directa (drop-in) a LiteLLM para Claude Code?

‍Sí. TrueFoundry AI Gateway expone un endpoint compatible con Anthropic, por lo que cambiar de LiteLLM a TrueFoundry requiere modificar solo una línea: actualiza ANTHROPIC_BASE_URL con la URL de tu gateway de TrueFoundry y sustituye el token de autenticación. Claude Code no nota la diferencia. Lo que cambia es todo lo que hay detrás del gateway: observabilidad, controles de costes, RBAC e infraestructura gestionada.

P: ¿Cuánta latencia añade TrueFoundry AI Gateway a las peticiones de Claude Code?

‍Aproximadamente ~3–4 ms de sobrecarga de gateway, gestionando más de 350 RPS en un solo vCPU. Considerando los tiempos de respuesta de Claude Code (medidos en segundos, no en milisegundos), el gateway no añade una latencia perceptible a la experiencia del desarrollador.

P: ¿Puedo desplegar TrueFoundry en mi propia VPC o en instalaciones locales (on-premises)?

‍Sí. TrueFoundry se ejecuta en tu VPC, on-prem, en entornos aislados (air-gapped), híbridos o en múltiples nubes: ningún dato sale de tu infraestructura. Esta es la razón principal por la que las empresas reguladas eligen TrueFoundry frente a gateways exclusivamente SaaS o LiteLLM autogestionado.

Conclusión

LiteLLM es un primer paso probado para conectar Claude Code a múltiples proveedores de IA. Si eres un desarrollador individual o un equipo pequeño realizando experimentos, es una opción sólida que te permite obtener enrutamiento multiproveedor con unas pocas líneas de configuración YAML.

Cuando Claude Code se convierte en una herramienta de equipo (cuando necesitas aplicar presupuestos, auditar el uso, gobernar el acceso y cumplir con requisitos normativos sin construir esa infraestructura tú mismo), la complejidad de configuración y las carencias de funciones de un LiteLLM autogestionado representan un coste real. TrueFoundry AI Gateway es el endpoint compatible con Anthropic listo para usar que gestiona todo eso con solo cambiar una variable de entorno.

Comienza a enrutar Claude Code a través de TrueFoundry AI Gateway → truefoundry.com/ai-gateway