Proxy de Claude Code: Enruta Claude, GPT-5 y Gemini a través de TrueFoundry AI Gateway

Introducción

Claude Code es el asistente de programación con IA más potente disponible en la actualidad. Los ingenieros que lo adoptan rara vez vuelven atrás. Sin embargo, cuando decenas o cientos de ingenieros empiezan a utilizarlo al mismo tiempo, surge un nuevo problema: Claude Code, por defecto, se comunica directamente con la API de Anthropic. Cada desarrollador se autentica con su propia clave, utiliza exclusivamente modelos de Anthropic y genera un gasto en la API que es completamente invisible para el equipo de plataforma hasta que llega la factura mensual.

Un proxy de Claude Code es la solución. Al apuntar Claude Code a un punto de enlace de proxy en lugar de hacerlo directamente a Anthropic, obtienes un punto de control centralizado para cada llamada a modelos en toda tu organización de ingeniería: visibilidad sobre quién gasta qué, la capacidad de aplicar límites presupuestarios antes de que se superen, acceso a modelos de cualquier proveedor (GPT-5, Gemini 2.5 Pro, Llama a través de Bedrock) mediante la misma interfaz que Claude Code ya conoce, y la posibilidad de desplegar la configuración del gateway una sola vez y hacer que se aplique a todos los desarrolladores sin tocar sus equipos individuales.

TrueFoundry AI Gateway es el proxy de Claude Code de nivel empresarial. Es un punto de enlace compatible con Anthropic listo para usar al que Claude Code se conecta con un simple cambio de variable de entorno. Una vez conectado, cada solicitud de Claude Code fluye a través del gateway, lo que te proporciona observabilidad, control de costes, enrutamiento multimodelo y políticas de seguridad empresarial que se aplican a toda la organización, no solo a los desarrolladores que se acuerden de configurarlas.

Esta guía explica exactamente qué hace un proxy de Claude Code, por qué TrueFoundry AI Gateway es la opción adecuada para los equipos de ingeniería de nivel empresarial y cómo configurarlo, incluyendo tanto los flujos de clave de API estándar como los de la suscripción Claude Max.

¿Qué es un proxy de Claude Code?

Claude Code incluye una única opción de configuración para cambiar su backend: la variable de entorno ANTHROPIC_BASE_URL. Cuando se establece, Claude Code envía todas sus solicitudes de API (mensajes, llamadas a modelos, respuestas en streaming) a esa URL en lugar de a https://api.anthropic.com.

Esa única variable es la base de cualquier proxy de Claude Code. Un proxy es cualquier servidor que:

1. Acepta solicitudes de API en formato Anthropic procedentes de Claude Code
2. Añade controles, enrutamiento u observabilidad en la capa de proxy
3. Reenvía las solicitudes al proveedor de modelos real (Anthropic, OpenAI, Google, Bedrock, en local)
4. Devuelve las respuestas a Claude Code en el formato esperado

El proxy más sencillo posible es un proxy inverso con registro de actividad (logging). El más sofisticado es un AI gateway empresarial que gestiona la autenticación, la aplicación de presupuestos, el enrutamiento de modelos entre proveedores, el almacenamiento en caché semántico, las barreras de protección (guardrails) y auditorías completas; todo ello de forma transparente, sin cambios en el comportamiento de Claude Code para el desarrollador.

¿Por qué los equipos construyen u adoptan un proxy de Claude Code?

• Control de costes: Varios desarrolladores utilizando Claude Code con claves individuales de Anthropic generan un gasto que es invisible hasta el final del mes. Un proxy intercepta cada solicitud y aplica límites diarios por desarrollador antes de que los costes superen el presupuesto.
• Acceso multimodelo: La interfaz de Claude Code es potente, pero los modelos de Claude no siempre son la opción mejor o más rentable para cada tarea. Un proxy te permite enrutar tareas de nivel Haiku a GPT-4o-mini o Gemini Flash, y tareas de nivel Opus al mejor modelo disponible sin realizar cambios en el cliente.
• Seguridad empresarial: Las claves de API directas en portátiles de desarrolladores son un riesgo de seguridad. Un proxy centraliza las credenciales: los desarrolladores se autentican en el proxy y el proxy guarda las claves del proveedor. Ninguna clave de Anthropic necesita estar guardada en el equipo de un desarrollador.
• Gobernanza a nivel de equipo: Los desarrolladores individuales pueden configurar su propio ANTHROPIC_BASE_URL. Sin embargo, aplicarlo en todo un equipo requiere un mecanismo de despliegue centralizado: MDM, ajustes gestionados por servidor o un .claude/settings.json de proyecto compartido guardado en el control de versiones.

Por qué TrueFoundry AI Gateway es el proxy de Claude Code adecuado

Hay tres formas de utilizar un proxy para Claude Code: crear el tuyo propio, usar un proxy inverso sencillo o utilizar un AI gateway diseñado específicamente para este fin. Crear el tuyo propio implica asumir el mantenimiento, la seguridad y la fiabilidad de un API gateway en producción. Un proxy inverso sencillo añade registros pero ninguno de los controles. TrueFoundry AI Gateway te ofrece todo lo que un equipo de ingeniería empresarial necesita sin tener que construirlo ni mantenerlo.

TrueFoundry AI Gateway es una capa de proxy unificada entre Claude Code y tus proveedores de modelos. Acepta el mismo formato de API de Anthropic que Claude Code ya utiliza, de modo que Claude Code no necesita saber que se está comunicando con un gateway en lugar de hacerlo directamente con Anthropic. Tras el gateway, puedes conectar cualquier proveedor: Anthropic directo, AWS Bedrock, Google Vertex AI, Azure OpenAI, OpenAI o tus propios modelos locales (on-premise).

Esto es lo que realmente ve Claude Code:

Cada solicitud de Claude Code que fluye a través de TrueFoundry obtiene automáticamente:

Sobrecarga del gateway de ~3–4 ms p95, 350+ RPS en una sola vCPU. Con los tiempos de respuesta de Claude Code (segundos, no milisegundos), el gateway no añade ninguna latencia perceptible.

Paso 1: Apuntar Claude Code a TrueFoundry AI Gateway

La configuración principal se realiza mediante una única variable de entorno:

Para una configuración persistente, que es lo ideal en entornos de producción, edita el archivo settings.json de Claude Code. Se admiten dos rutas:

• Global (se aplica a todos los proyectos): ~/.claude/settings.json
• Específica de proyecto (guardada en el control de versiones): .claude/settings.json en el directorio de tu proyecto

Configuración estándar con clave de API

Utiliza esta opción cuando los desarrolladores se autentican con una clave de API de TrueFoundry (el patrón empresarial recomendado: sin claves de Anthropic en los equipos de los desarrolladores):‍

Función de cada campo:

• ANTHROPIC_BASE_URL: redirige todas las solicitudes de Claude Code a TrueFoundry
• ANTHROPIC_AUTH_TOKEN: clave de API de TrueFoundry; autentica al desarrollador en el gateway (reemplaza a la clave de API de Anthropic)
• ANTHROPIC_MODEL: el modelo por defecto para las sesiones de Claude Code
• ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL: asignan los alias de modelo integrados de Claude Code (/model opus, /model sonnet, /model haiku) a tus modelos configurados en TrueFoundry
• CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: deshabilita las funciones experimentales de Claude Code para garantizar un comportamiento estable del gateway
• ANTHROPIC_CUSTOM_HEADERS: reenvía el encabezado x-tfy-anthropic-beta a Anthropic para funciones beta como la gestión de contexto

Importante: Claude Code detecta las capacidades del modelo (pensamiento extendido, ToolSearch, bloques de herramientas beta) haciendo coincidir cadenas de texto con la ID del modelo. Asegúrate de que ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL y ANTHROPIC_DEFAULT_HAIKU_MODEL contengan una ID de modelo de Anthropic reconocible como claude-opus-4-7, claude-sonnet-4-6 o claude-haiku-4-5. Si estás utilizando un Virtual Model de TrueFoundry, asegúrate de que su nombre visible contenga la ID del modelo subyacente (p. ej., your-account/claude-haiku-4-5) para que la coincidencia de cadenas de texto se realice correctamente.

Configuración de la suscripción Claude Code Max

Si tu equipo utiliza suscripciones Claude Code Max, Claude Code reserva el encabezado Authorization para la autenticación de la cuenta de Anthropic. En su lugar, utiliza x-tfy-api-key en ANTHROPIC_CUSTOM_HEADERS:‍

Por qué este patrón es adecuado para los usuarios de Max:

• Mantienes tu suscripción Anthropic Max para la autenticación de sesiones de Claude Code: el encabezado Authorization fluye a Anthropic tal cual
• TrueFoundry se autentica por separado mediante x-tfy-api-key: el gateway gobierna la solicitud mientras Anthropic gestiona el cobro mediante tu suscripción
• Obtienes una gobernanza centralizada (visibilidad, cuotas, RBAC, registros, guardrails) sin modificar tu flujo de trabajo diario en Claude Code

Consulta la documentación de Claude Code en TrueFoundry para ver la guía de integración completa y la integración de Claude Code Max para la variante de suscripción Max.

Paso 2: Usar GPT-5, Gemini y cualquier modelo a través de Claude Code

Aquí es donde un proxy de Claude Code pasa de ser práctico a transformador. Una vez que Claude Code se enruta a través de TrueFoundry, puede acceder a cualquier modelo de cualquier proveedor, no solo de Anthropic. Añades las cuentas de los proveedores en el panel de control de TrueFoundry AI Gateway (OpenAI, Google Vertex AI, AWS Bedrock, Azure OpenAI, xAI o tu propio despliegue local) y esos modelos pasan a estar disponibles en el mismo punto de enlace del gateway.

Apuntar los alias de Claude Code a modelos que no sean de Anthropic

Para utilizar GPT-5 en la ranura "opus" de Claude Code (tu nivel de modelo con mayor capacidad), solo tienes que actualizar el alias del modelo:

En esta configuración:

• /model opus → GPT-5 (para tareas complejas de arquitectura y planificación)
• /model sonnet → Claude Sonnet 4 (para tareas de programación estándar)
• /model haiku → Gemini 2.5 Flash (para tareas rápidas y ligeras como validación de correo electrónico, búsquedas rápidas)

La experiencia del desarrollador es idéntica. Los desarrolladores siguen utilizando /model opus o --model haiku. No necesitan saber qué proveedor está detrás de cada alias ni gestionar credenciales para OpenAI o Google.

Uso de Virtual Models para un enrutamiento avanzado

Los Virtual Models de TrueFoundry te permiten crear un identificador de modelo único que enruta las solicitudes entre múltiples proveedores basándose en ponderación, prioridad o latencia. Apunta un alias de modelo de Claude Code a un modelo virtual y el gateway gestionará la lógica de enrutamiento de forma transparente.

Ejemplo: Conmutación por error basada en prioridad entre proveedores

Si tu cuenta principal de Anthropic alcanza los límites de tarifa, recurre automáticamente a Bedrock Claude y luego a GPT-4, sin que ningún desarrollador lo note:

Ejemplo: Evaluación A/B basada en ponderación

Prueba un modelo nuevo en versión canary con el 10 % del tráfico de Claude Code antes de aplicarlo a todo el equipo:‍


A continuación, apunta el alias sonnet de Claude Code a este modelo virtual. El 10 % de las solicitudes sonnet de Claude Code irán a GPT-5, disponiendo de métricas completas de coste y calidad en el panel de control del gateway para comparar los resultados.

Paso 3: Controles empresariales aplicados a cada solicitud de Claude Code

Una vez que Claude Code se enruta a través de TrueFoundry, cada solicitud hereda una gobernanza de nivel empresarial, no porque los desarrolladores la configuren, sino porque se aplica directamente en la capa de gateway.

Límites presupuestarios: detén los sobrecostes antes de que se produzcan

La limitación jerárquica de presupuesto de TrueFoundry se activa antes de consumir el token, no después de que llegue la factura mensual. Las reglas se superponen y combinan:

Los ingenieros senior disponen de 50 $/día. Todos los demás tienen por defecto 10 $/día. Y el gasto total de Opus en toda la organización se limita a 1000 $/mes; por lo que, aunque todos los desarrolladores estén dentro de su límite personal, no se podrá superar el presupuesto global asignado a ese modelo.

Límites de tarifa (Rate limiting): protege entornos locales y de control

Los límites de tarifa en el gateway gestionan tres escenarios específicos de Claude Code:

• Pipelines de CI: La ejecución de Claude Code en CI debe tener un límite de tarifa independiente de las sesiones interactivas de los desarrolladores. Un conjunto de pruebas que llama a Claude Code para revisar código no debería agotar la misma cuota que la sesión de programación activa de un desarrollador.
• Modelos de desarrollo frente a producción: Los límites de tarifa vinculados a metadatos te permiten enrutar las solicitudes de environment: dev a un modelo más económico y limitar su tasa de solicitudes sin que afecte a producción.
• Protección de GPU locales: Si ejecutas modelos locales como objetivo principal para Claude Code, limita la tasa del punto de enlace local y realiza una derivación automática (auto-burst) a la API en la nube cuando la capacidad se sature.

Atribución de costes: sabe exactamente quién gasta qué

Cada solicitud de Claude Code procesada por TrueFoundry se atribuye automáticamente al usuario autenticado. El panel de analítica muestra el coste desglosado por desarrollador, equipo, modelo y fecha; filtrable por cualquier etiqueta de metadatos que envíes mediante el encabezado X-TFY-METADATA.

Para los equipos que utilizan la atribución de costes basada en proyectos, etiqueta las solicitudes de Claude Code con metadatos de project_id o feature y cada solicitud se asignará automáticamente al centro de costes correcto:‍


Toda la traza se exporta a través de OpenTelemetry a Grafana, Datadog, Splunk o a tu infraestructura de observabilidad actual.

Paso 4: Desplegar en todo el equipo de ingeniería

Configurar el settings.json de un solo desarrollador es sencillo. Garantizar una configuración de proxy uniforme en cada desarrollador de tu organización requiere una estrategia de despliegue. TrueFoundry admite tres enfoques:

Opción A: Ajustes gestionados mediante MDM (Recomendado para empresas)

Distribuye un archivo managed-settings.json a cada equipo corporativo mediante tu solución MDM (Jamf, Kandji, Mosyle, Intune) y bloquéalo frente a modificaciones a nivel de sistema operativo. Este es el enfoque de ajustes gestionados en el punto de enlace de Claude Code.‍


Rutas a nivel de sistema:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux: /etc/claude-code/managed-settings.json

Esta configuración es resistente a manipulaciones, se aplica inmediatamente al iniciar el sistema sin depender de la red y no requiere ninguna acción por parte del desarrollador. Cada equipo que recibe el perfil MDM utiliza automáticamente el proxy de TrueFoundry.

Opción B: Ajustes gestionados por servidor mediante la consola de administración de Anthropic

Configura los ajustes de forma centralizada desde la consola de administración de Claude (Admin Settings → Claude Code → Managed settings). Los ajustes se entregan desde los servidores de Anthropic cuando los desarrolladores se autentican con las credenciales de su organización, sin necesidad de desplegar archivos.

Este enfoque no requiere infraestructura MDM y funciona en dispositivos personales (BYOD). Los ajustes se entregan en el momento de la autenticación y son más difíciles de anular por parte de los usuarios.

Opción C: settings.json a nivel de proyecto en el control de versiones

Guarda un archivo .claude/settings.json en la raíz de cada repositorio. Cualquier desarrollador que clone el repositorio y ejecute Claude Code en ese directorio utilizará automáticamente la configuración del proyecto, incluida la URL del gateway de TrueFoundry y la configuración del modelo.‍


Esta es la opción con menos fricción para equipos con estructuras de repositorios estandarizadas. Los nuevos desarrolladores heredan la configuración del proxy en cuanto clonan el repositorio.

Paso 5: Extensión de VS Code y Claude Agent SDK

Extensión de VS Code

La extensión de VS Code para Claude Code funciona sin problemas con TrueFoundry una vez que hayas configurado la CLI. La extensión no es autónoma: requiere que la CLI de Claude Code esté instalada y configurada previamente.‍


La extensión utiliza automáticamente la configuración de tu CLI (URL base, claves de API, alias de modelos). No se requiere una configuración independiente.

Nota sobre macOS/Linux: Las aplicaciones con interfaz gráfica (GUI) no heredan las variables de entorno de la terminal por defecto. Inicia siempre VS Code desde una terminal en la que Claude Code esté configurado para garantizar que la extensión lea ANTHROPIC_BASE_URL.

Claude Agent SDK

El Claude Agent SDK (el sucesor del Claude Code SDK) funciona con tu .claude/settings.json existente a través de TrueFoundry. Especifica setting_sources=["project"] para cargar tu configuración de gateway mediante código:

Todas las configuraciones de TrueFoundry (Anthropic Direct, AWS Bedrock, Google Vertex AI) funcionan de forma idéntica con el Agent SDK.

Proxy de Claude Code casero frente a TrueFoundry AI Gateway