La puerta de enlace de aplicaciones Claude está diseñada para organizaciones que deben —o prefieren— enrutar la inferencia a través de su propio proveedor de nube, por ejemplo para cumplir con los requisitos de residencia de datos. Si no tiene este requisito y desea acceso a otras características como aprovisionamiento SCIM o Claude Code en web y dispositivos móviles, Claude Enterprise puede ser una mejor opción. Consulte la página de disponibilidad de características para una comparación completa de todos los métodos de implementación.
claude, por lo que el mismo ejecutable que ejecuta Claude Code en una computadora portátil ejecuta el servidor de puerta de enlace con claude gateway --config gateway.yaml.
Esta página cubre:
- Por qué Claude apps gateway, qué agrega sobre ejecutar el suyo propio, y cuándo algo más se ajusta mejor
- Un inicio rápido con requisitos previos que lleva una puerta de enlace de cero a un desarrollador que ha iniciado sesión
- Conectar desarrolladores, incluida la configuración de la URL de la puerta de enlace a través de configuraciones administradas
- Disponibilidad y limitaciones que cubre qué características de Claude Code funcionan a través de la puerta de enlace y qué soporta el servidor
Por qué puerta de enlace de aplicaciones Claude
La descripción general de la puerta de enlace cubre qué hace una puerta de enlace y por qué ejecutaría una. La puerta de enlace de aplicaciones Claude es la propia puerta de enlace de Anthropic, integrada en el binarioclaude y probada junto con cada lanzamiento de Claude Code, por lo que reenvía los encabezados y campos de solicitud que Claude Code envía sin que los operadores mantengan una lista de permitidos separada. Una vez implementada, le proporciona:
- Credenciales: la clave API ascendente o la credencial de nube vive solo en su infraestructura. Los desarrolladores se autentican con SSO corporativo y reciben tokens portadores de corta duración, por lo que la desvinculación ocurre en su IdP. Desaprovisione un usuario y su acceso a la puerta de enlace expira dentro de la duración de la sesión, una hora por defecto.
- Control de acceso: sus grupos de IdP se asignan a listas de permitidos de modelos y políticas de configuración administrada. La puerta de enlace aplica el acceso a modelos del lado del servidor, rechazando solicitudes de modelos no otorgados, y selecciona la política de configuración administrada de cada grupo, que la CLI aplica en el nivel de configuración administrada. Diferentes equipos obtienen diferentes modelos, herramientas y permisos, y un desarrollador no puede anular lo que su política bloquea.
- Entrega de configuración: la puerta de enlace entrega la configuración administrada a los clientes conectados por sí misma, reemplazando la configuración administrada por servidor de la consola de administrador de claude.ai.
- Telemetría: cada destino configurado, como Datadog, Splunk o ClickHouse, recibe métricas del Protocolo OpenTelemetry (OTLP) con recuentos de tokens, modelo, identidad del usuario y latencia por defecto, con registros y trazas como activaciones opcionales por destino.
- Enrutamiento ascendente: los clientes hablan la API de Mensajes de Anthropic a la puerta de enlace, y la puerta de enlace traduce para cada ascendente, ya sea Amazon Bedrock, Plataforma Claude en AWS, Plataforma de Agentes de Google Cloud, Microsoft Foundry, o la API de Anthropic, con conmutación por error entre ellos. Puede cambiar regiones, proveedores u orden de conmutación por error sin que los desarrolladores lo noten o reconfiguren.
El plano de datos de la puerta de enlace no envía nada a la infraestructura de Anthropic a menos que la API de Anthropic sea un ascendente configurado. Usted controla dónde van la telemetría, los registros de auditoría, la configuración administrada y la identidad de IdP de sus desarrolladores, y la puerta de enlace no envía ninguno de ellos a Anthropic. Para el tráfico restante que el proceso de CLI puede enviar y cómo cerrarlo, consulte Postura de cumplimiento.
Otras implementaciones de puerta de enlace
Si ya ejecuta una puerta de enlace LLM o puerta de enlace API que cumple con sus necesidades, continúe usándola; Otras puertas de enlace LLM cubre la configuración de Claude Code contra ella. La referencia del protocolo de puerta de enlace documenta el contrato que Claude Code espera de cualquier puerta de enlace: los puntos finales que llama, los encabezados y campos de cuerpo a reenviar, y qué deja de funcionar cuando se eliminan. Una puerta de enlace de aplicaciones Claude en ejecución sirve un superconjunto de ese contrato enGET /protocol, agregando los puntos finales específicos de la puerta de enlace de aplicaciones Claude para inicio de sesión SSO, entrega de configuración administrada y telemetría. Obténgalo con curl https://claude-gateway.internal.example.com/protocol desde cualquier puerta de enlace implementada, como la que produce el inicio rápido a continuación.
Los cambios importantes en el protocolo se anuncian con anticipación, pero no se garantiza compatibilidad hacia atrás indefinida.
Inicio rápido
Este inicio rápido recorre la ruta mínima: registre un cliente OAuth en su IdP, escriba ungateway.yaml, ejecute la puerta de enlace junto con Postgres con Docker Compose, y verifique el inicio de sesión de extremo a extremo. Utiliza un ascendente de Amazon Bedrock; la Plataforma de Claude en AWS, la Plataforma de Agentes de Google Cloud, Microsoft Foundry, y la API de Anthropic son igualmente compatibles intercambiando el bloque upstreams como se muestra en la referencia de configuración. Al final tiene una puerta de enlace a la que un desarrollador puede /login.
Implemente en su red privada. Claude Code solo se conecta a una puerta de enlace cuya dirección es privada. Esta es una protección de seguridad, porque una puerta de enlace confiable puede insertar configuración que ejecute comandos en máquinas de desarrolladores. Coloque la puerta de enlace detrás de un equilibrador de carga interno o VPN y asígnele un nombre de host que se resuelva solo a direcciones IP privadas.Los puntos finales de puerta de enlace pública operados por Anthropic son la excepción:
/login los acepta sobre https://. Estos son un conjunto pequeño y fijo de puertas de enlace que el propio Anthropic opera; no son una opción de implementación que pueda seleccionar o configurar. La lista se compila en Claude Code, por lo que ninguna configuración puede agregar un nombre de host a ella y ninguna puerta de enlace que aloje califica para la exención. Antes de v2.1.206, /login rechazaba esos puntos finales como cualquier otra dirección pública.Requisitos previos
Tenga estos en lugar antes de comenzar:
El servidor de puerta de enlace requiere el binario
claude nativo; descargue una versión fija como se describe en Instalar Claude Code. El servidor utiliza características de tiempo de ejecución que no están disponibles cuando Claude Code se ejecuta bajo Node. Si ve requires the native binary al arrancar, cambie a uno de los métodos de instalación independientes.
Pasos
1
Registre un cliente OAuth en su IdP
Decida primero el nombre de host de la puerta de enlace, porque el URI de redirección debe coincidir con él. Cree una nueva aplicación web OIDC y establezca el URI de redirección en
https://claude-gateway.<your-domain>/oauth/callback, donde el host es el mismo valor que establece como listen.public_url en el paso 3. Anote el client_id y client_secret. Las instrucciones por IdP están en Configuración del proveedor de identidad.2
Aprovisione una base de datos PostgreSQL
Cualquier Postgres 14 o posterior funciona, incluido el nivel administrado más pequeño. La puerta de enlace ejecuta sus propias migraciones de esquema al arrancar, por lo que el usuario de la base de datos necesita permiso
CREATE TABLE. Si su política de seguridad prohíbe DDL de roles de aplicación, pre-cree el esquema en su lugar; consulte store.3
Escriba gateway.yaml
Los secretos se leen a través de la expansión Esta configuración es suficiente para un bucle de inicio de sesión funcional con el catálogo de modelos predeterminado de Bedrock. Una vez que se ejecute, agregue RBAC por grupo y configuración administrada a través de
${ENV_VAR} para que el archivo en sí pueda vivir en control de versiones. Use un nombre de host public_url que se resuelva a una IP privada en su red, porque /login rechaza direcciones públicas. La configuración mínima tiene cinco secciones, y todos los demás campos tienen un valor predeterminado:gateway.yaml
managed.policies, distribución de telemetría a través de telemetry, y conmutación por error de múltiples ascendentes, ARNs de rendimiento aprovisionado, o regiones no estadounidenses a través de models.El ascendente de Bedrock necesita un principal de AWS con
bedrock:InvokeModel y bedrock:InvokeModelWithResponseStream en los ARNs inference-profile/us.anthropic.* y los ARNs foundation-model/anthropic.* subyacentes, y acceso a modelos habilitado en la consola de Bedrock para los modelos Claude que desea. Suministre la credencial con IRSA en EKS, un rol de tarea de ECS, o un perfil de instancia de EC2 en lugar de claves estáticas. La referencia upstreams tiene los detalles completos de IAM, la matriz de credenciales entre nubes, y los bloques auth para los otros proveedores.4
Ejecútelo
Construya una imagen de contenedor alrededor del binario La puerta de enlace es un único binario de Linux que lee la configuración, ejecuta el descubrimiento OIDC contra su IdP, aplica sus migraciones de esquema de Postgres, construye clientes ascendentes, e inicia la escucha. El arranque es de cierre fallido para la configuración, la conexión de Postgres con un tiempo de espera de 5 segundos, el descubrimiento OIDC, y la construcción del cliente ascendente. Si alguno de esos es inaccesible o está mal configurado, la puerta de enlace sale con un error en lugar de servir tráfico en un estado degradado.Un arranque exitoso no valida la ruta de inferencia, porque las credenciales de instancia de Bedrock y Agent Platform se resuelven en la primera solicitud, no al arrancar.Observe stderr para la secuencia de arranque. Las líneas de registro utilizan el formato Si el arranque sale antes de la línea
claude que cumpla con los requisitos de imagen, luego ejecútela junto con Postgres:docker-compose.yaml
[gateway] <timestamp> <level> <message>, los eventos de auditoría son JSON de una sola línea con un campo evt, y un banner de inicio, omitido a continuación, se imprime entre las líneas de migración y escucha. Debería ver, en orden:claude gateway listening on, la última línea de stderr nombra el problema:- un Postgres inaccesible
- un rol de Postgres sin permiso DDL
- un documento de descubrimiento OIDC inaccesible o inválido
- una violación del esquema de configuración con la ruta del campo ofensivo
claude gateway --config gateway.yaml. Establezca public_url en el origen de la entrada y vincule listen a una dirección de loopback o interna del clúster.5
Verifique la superficie de autenticación
Tres verificaciones confirman que la puerta de enlace puede autenticar a un usuario real antes de entregársela a un desarrollador.Los ejemplos utilizan la URL pública de la puerta de enlace; para la configuración local de Compose sin una entrada, sustituya La respuesta incluye campos adicionales, como Tercero, pruebe la rama del navegador abriendo
http://localhost:8080 en las dos primeras verificaciones. La tercera verificación abre verification_uri_complete, que se construye a partir de public_url, por lo que para Compose local establezca public_url: http://localhost:8080 en gateway.yaml, y agregue http://localhost:8080/oauth/callback como un segundo URI de redirección en el cliente OAuth del paso 1, porque la puerta de enlace construye el redirect_uri de IdP a partir de public_url. El enlace de verificación luego se abre en su navegador local.En Windows PowerShell, ejecute curl.exe; el curl simple es un alias para Invoke-WebRequest y rechaza estas banderas.Primero, obtenga el documento de descubrimiento, que confirma que la puerta de enlace está activa, la configuración es válida, y todas las verificaciones de arranque pasaron:response_types_supported y scopes_supported.Segundo, solicite una autorización de dispositivo, que confirma que el flujo de inicio de sesión del dispositivo funciona y Postgres es accesible y escribible:verification_uri_complete en un navegador y confirmando el código. Debería ser redirigido a la página de inicio de sesión de su IdP, y después de iniciar sesión, aterrizar de nuevo en la puerta de enlace con una confirmación de inicio de sesión.Use la primera verificación fallida para localizar el problema:- Primera verificación falla: el arranque no se completó; verifique stderr
- Segunda verificación falla: Postgres no es accesible desde la puerta de enlace o el rol no puede escribir; verifique la cadena de conexión y los permisos
- Tercera verificación no llega al IdP: verifique que el URI de redirección de IdP coincida exactamente con
https://<gateway>/oauth/callback - Tercera verificación llega al IdP pero rebota con un error: lea el registro de auditoría de la puerta de enlace, que registra cada rechazo de autenticación con la razón, como
email domain not allowed
6
Inicie sesión de un desarrollador
Este último paso ocurre en una máquina de desarrollador, no en el servidor. Establezca
forceLoginMethod en "gateway" y forceLoginGatewayUrl en la public_url de su puerta de enlace en el archivo de configuración administrada de esa máquina, luego ejecute /login, presione Intro en la pantalla Cloud gateway, y complete el inicio de sesión del navegador. Establezca la URL de la puerta de enlace a continuación cubre la distribución de ambas claves a escala.Conectar desarrolladores
Los desarrolladores se conectan desde sus propias computadoras portátiles con un inicio de sesión de navegador, usando su cuenta de trabajo corporativa. No necesitan una cuenta de claude.ai, una clave API, o una suscripción, porque las solicitudes al modelo van a través de la puerta de enlace usando la credencial ascendente de la organización. La conexión es impulsada por la configuración administrada del lado del cliente que inserta a través de MDM, por lo que no hay configuración manual en el lado del desarrollador; esta sección cubre lo que configura el administrador. La CLI toma la huella digital del certificado TLS de hoja de la puerta de enlace en la primera conexión y la fija por nombre de host. Publique la huella digital SHA-256 esperada junto con la URL de la puerta de enlace para que los desarrolladores tengan algo con lo que comparar. Obtenga la huella digital del archivo de certificado conopenssl x509 -noout -fingerprint -sha256 -in cert.pem; el indicador /login muestra los primeros 16 caracteres del resumen como hexadecimal minúscula sin separadores.
Cuando el certificado rota, cada desarrollador ve el indicador de confianza nuevamente, por lo que trate las rotaciones como un evento planificado y republique la huella digital.
Una vez conectado, el selector de modelos muestra los modelos en la lista de permitidos availableModels del desarrollador, la configuración administrada se aplica al inicio y se actualiza cada hora, y la telemetría se enruta a su recopilador. Las sesiones se actualizan silenciosamente antes de la expiración de ttl_hours, y una actualización fallida después del desaprovisionamiento de IdP solicita un nuevo inicio de sesión.
Establecer la URL de la puerta de enlace
Establezca ambas claves en el archivo de configuración administrada por sistema operativo que implementa a través de MDM o directamente en el disco, y/login abre directamente en la pantalla Cloud gateway con la URL rellenada:
forceLoginGatewayUrl se ignora en los archivos de configuración propios de un desarrollador. forceLoginMethod solo, sin una URL, deja al desarrollador en un mensaje “Contacte a su administrador de TI”. Ambas claves pertenecen al archivo que inserta en máquinas, no en el bloque managed.policies[].cli de la puerta de enlace, que solo llega a clientes que ya están conectados.
Canalizaciones de CI y máquinas remotas
No hay flujo de token de servicio para canalizaciones desatendidas. El inicio de sesión de la puerta de enlace siempre ejecuta el flujo de dispositivo del navegador, por lo que un trabajo de CI sin un desarrollador para aprobar el inicio de sesión no puede autenticarse; configure esos contra su proveedor directamente. Una vez que un desarrollador ha iniciado sesión, cada invocación de Claude Code en esa máquina usa la sesión de la puerta de enlace, incluidas las ejecuciones no interactivas declaude -p y sesiones iniciadas por el SDK del Agente, y la política de la puerta de enlace se aplica a todas ellas.
El flujo de dispositivo separa la CLI de sondeo de la aprobación del navegador, por lo que una caja de desarrollo remota sin pantalla aún funciona: el desarrollador ejecuta /login sobre SSH en la máquina remota y abre el enlace de verificación en el navegador en su computadora portátil.
Qué se aplica en los desarrolladores
Estas garantías se aplican a cada sesión de puerta de enlace conectada.- Acceso a modelos: las solicitudes de modelos que la política no otorga devuelven 400, y el selector
/modelse filtra a la lista de permitidosavailableModelsde la política. EstablezcaenforceAvailableModels: trueen la política para que la opción Predeterminado se resuelva a un modelo dentro deavailableModelsen lugar de al predeterminado integrado de Claude Code; sin él, Predeterminado permanece seleccionable y se rechaza en el tiempo de solicitud si ese modelo no se otorga. - Destino de telemetría: cuando se configura reenvío de telemetría, el punto final de exportación OTLP se fija a la puerta de enlace, y la configuración insertada por la puerta de enlace anula las variables
OTEL_*configuradas localmente. - Credenciales: el token de la puerta de enlace es la única credencial de la sesión.
ANTHROPIC_AUTH_TOKEN,ANTHROPIC_API_KEY,apiKeyHelper, y cualquier inicio de sesión anterior de claude.ai se ignoran mientras se conecta, por lo que los desarrolladores no necesitan cerrar sesión de claude.ai primero. - Configuración administrada: las claves bloqueadas no se pueden anular localmente. La CLI aplica la política al inicio y en cada sondeo cada hora.
- Inicio: las sesiones conectadas salen al inicio con un error después de aproximadamente 10 segundos cuando la puerta de enlace es inaccesible, en lugar de iniciarse sin su configuración.
- Desaprovisionamiento: una sesión cuyo usuario está deshabilitado en el IdP expira dentro de
ttl_hourscuando la siguiente actualización falla.
Qué puede ver la organización
La telemetría de uso lleva la identidad del desarrollador, recuentos de tokens, modelo y latencia al recopilador de la organización. La puerta de enlace no registra ni almacena contenido de indicación o finalización. Si se recopila telemetría más rica como registros y trazas, que puede incluir comandos y rutas de archivo, es la opción por destino de la organización.Disponibilidad y limitaciones
La tabla cubre qué características de Claude Code funcionan cuando los desarrolladores se conectan a través de la puerta de enlace, y qué soporta el servidor de puerta de enlace en sí. Donde algo no es compatible, la columna Notas proporciona la alternativa. La puerta de enlace entrega los valoresanthropic-beta que la CLI envía a cada ascendente, por lo que los operadores no mantienen una lista de permitidos de beta. Para Amazon Bedrock, que ignora el encabezado, la puerta de enlace mueve los valores al campo anthropic_beta del cuerpo de la solicitud; los otros ascendentes reciben el encabezado como se envía.
El conjunto de beta de sesión de puerta de enlace de la CLI omite betas solo de primera parte y la beta de ttl de caché extendido, por lo que esas filas a continuación muestran como no disponibles.
Próximos pasos
El inicio rápido lo deja con una configuración mínima ejecutándose bajo Docker Compose. Para llevarlo más lejos:- Expanda
gateway.yamlmás allá de la configuración mínima, por ejemplo para agregar RBAC por grupo, conmutación por error de múltiples ascendentes, o destinos de telemetría. La referencia de configuración cubre cada opción. - Pase de Compose a una implementación de producción en Kubernetes o Cloud Run, configure su IdP correctamente, y revise el modelo de seguridad. La guía de implementación y operaciones cubre la configuración por IdP, los requisitos de imagen de contenedor, sondeos de salud y solución de problemas.
- Coloque límites de gasto en desarrolladores individuales o grupos para que una carga de trabajo descontrolada no pueda consumir todo su compromiso. Límites de gasto cubre la API de administrador y cómo funciona la aplicación.
- Para un ejemplo completo trabajado en Google Cloud, con Cloud Run, Cloud SQL y Secret Manager, consulte Implementar en Google Cloud.