Puerta de enlace de aplicaciones Claude para Amazon Bedrock, Claude Platform en AWS, Google Cloud y Microsoft Foundry
Ejecute Claude Code a través de Amazon Bedrock, Claude Platform en AWS, Google Cloud o Microsoft Foundry detrás de una puerta de enlace autohospedada con inicio de sesión SSO, acceso a modelos por grupo y telemetría OTLP.
[!NOTE]
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 Code usa un solo inicio de sesión a la vez: un inicio de sesión en el gateway reemplaza un inicio de sesión de Claude for Teams o Enterprise. Las sesiones del gateway no obtienen la configuración administrada por el servidor que estableces en la consola de administración de claude.ai, así que entrégala desde el bloque
manageddel gateway. DejaforceLoginMethodyforceLoginOrgUUIDfuera de ese bloque, o algunas sesiones con inicio de sesión se cerrarán al arrancar. Consulta Disponibilidad y limitaciones para ver lo que pierden las sesiones del gateway.
Claude apps gateway es un servicio autohospedado que se sitúa entre los clientes de Claude Code de sus desarrolladores y su proveedor de modelos. Los desarrolladores inician sesión con su proveedor de identidad corporativo (IdP) en lugar de mantener claves API o credenciales de nube. La puerta de enlace mantiene la credencial ascendente, aplica el acceso a modelos y configuraciones administradas por grupo de IdP, y retransmite la telemetría de uso a su propia pila de observabilidad.
Se incluye en el binario 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
Las páginas complementarias profundizan más. La referencia de configuración cubre todas las opciones en el archivo YAML que escribe el inicio rápido, y la guía de implementación cubre la configuración por IdP, la implementación en Kubernetes y Cloud Run, y las operaciones.
Por qué puerta de enlace de aplicaciones Claude
La descripción general del gateway cubre qué hace un gateway y por qué ejecutarías uno. Claude apps gateway es el gateway propio de Anthropic, integrado en el binario claude y probado junto con cada lanzamiento de Claude Code, por lo que reenvía los valores de anthropic-beta y los campos de solicitud que Claude Code envía sin que los operadores mantengan una lista de permitidos separada. Una vez desplegado, te 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: tus grupos de IdP se asignan a listas de modelos permitidos, políticas de configuración administrada y ascendentes. El gateway 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 sobrescribir 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 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.
[!NOTE]
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.
Para ver qué características de Claude Code funcionan a través de la puerta de enlace y qué soporta el servidor en sí, consulte Disponibilidad y limitaciones a continuación. Para decisiones como costo, derivación, ejecutar múltiples puertas de enlace y plataformas sin servidor, consulte la guía de implementación.
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 guía de compatibilidad de protocolo de puerta de enlace documenta qué espera Claude Code 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 también sirve su propia referencia de protocolo en GET /protocol, que describe los puntos finales que expone a clientes de Claude Code: inicio de sesión SSO, inferencia, entrega de configuración administrada, descubrimiento de modelos 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.
[!NOTE]
Un token de inicio de sesión del gateway identifica al desarrollador que aprobó el inicio de sesión, no al programa que lo usa. Claude Code inicia sesión sin un ID de cliente ni un secreto propios, por lo que un gateway no tiene forma de verificar qué programa está iniciando sesión. Cualquier cliente puede establecer
User-Agenty otros campos de la solicitud, así que úsalos para enrutamiento o métricas, no como prueba de que una solicitud proviene de Claude Code.
Inicio rápido
Este inicio rápido recorre el camino mínimo: registrar un cliente OAuth en tu IdP, escribir un gateway.yaml, ejecutar el gateway junto a Postgres con Docker Compose y verificar el inicio de sesión de principio a fin. Usa un upstream de Amazon Bedrock; Claude Platform on AWS, Google Cloud's Agent Platform, Microsoft Foundry y la API de Anthropic son igualmente compatibles si cambias el bloque upstreams como se muestra en la referencia de configuración. Al final tendrás un gateway en el que un desarrollador puede hacer /login.
[!NOTE]
Despliega en tu red privada. Claude Code solo se conecta a un gateway cuya dirección sea privada. Esto es una medida de seguridad, porque un gateway de confianza puede enviar configuración que ejecuta comandos en las máquinas de los desarrolladores. Coloca el gateway detrás de un balanceador de carga interno o una VPN y asígnale un hostname que resuelva solo a IP privadas. Si tu red interna está numerada con espacio IPv4 público que pertenece a tu organización, consulta Permitir un gateway en espacio de direcciones públicas que te pertenece.
Requisitos previos
Ten esto listo antes de empezar:
| Necesitas | Detalles |
|---|---|
| Claude Code v2.1.195 o posterior | El subcomando claude gateway y el flujo de inicio de sesión del gateway se incluyen en v2.1.195. Las compilaciones públicas anteriores no los incluyen. Tanto la máquina que ejecuta el servidor del gateway como la máquina de cada desarrollador deben tener v2.1.195 o posterior; ejecuta claude update para obtener la versión más reciente. El upstream de Claude Platform on AWS requiere Claude Code v2.1.198 o posterior en el servidor del gateway. |
| Proveedor de identidad OpenID Connect (OIDC) | Okta, Microsoft Entra ID, Google Workspace, Keycloak o Dex, o cualquier otro IdP compatible con OIDC, como PingFederate. El gateway ejecuta el descubrimiento OIDC estándar y el flujo de código de autorización contra él. SAML y LDAP no son compatibles. |
| PostgreSQL 11 o posterior | Respalda el flujo de inicio de sesión de dispositivo y los contadores de rate limit. Funciona un servicio administrado de PostgreSQL, incluido el nivel más pequeño; consulta qué bases de datos son compatibles. Con límites de gasto, también almacena tablas duraderas de gasto, auditoría e identidad que deben respaldarse. Se recomienda TLS mediante ?sslmode=require. PostgreSQL 11, 12 y 13 requieren Claude Code v2.1.290 o posterior en el servidor del gateway. El proyecto PostgreSQL ya no mantiene esas versiones, así que usa una más reciente cuando puedas. |
| Upstream de modelos | Credenciales de Amazon Bedrock, credenciales de Claude Platform on AWS, credenciales de Google Cloud, un recurso de Microsoft Foundry o una clave de API de Anthropic. Se admiten varios upstreams con conmutación por error. |
| HTTPS | El gateway debe ser accesible mediante https:// desde las laptops de los desarrolladores y desde cualquier navegador que se use para iniciar sesión; el gateway sirve la página de verificación de dispositivo en el mismo listener. Proporciona un certificado TLS mediante listen.tls o ejecútalo detrás de un ingress que termine TLS, y en ambos casos establece listen.public_url en el origen externo. En /login, Claude Code acepta un origen http:// simple solo cuando el host del gateway es loopback: localhost, 127.0.0.1 o ::1. |
| Dirección de red privada | En /login, Claude Code requiere que el hostname o la dirección IP del gateway resuelva solo a direcciones privadas: RFC 1918, link-local, CGNAT 100.64.0.0/10, IPv6 ULA fc00::/7 o loopback. Para un gateway que alojas tú, se rechaza cualquier dirección pública fuera de un bloque que declares; consulta el modelo de amenazas en la guía de despliegue. Si las máquinas de los desarrolladores enrutan HTTPS a través de un proxy corporativo, el inicio de sesión también requiere que el host del proxy resuelva a direcciones privadas; si no es así, agrega el host del gateway a NO_PROXY para que la CLI se conecte directamente. Si tu red interna está numerada con espacio IPv4 público que pertenece a tu organización, declara esos bloques para que /login acepte un gateway ahí. |
| Entorno de ejecución Linux | El servidor del gateway solo se ejecuta en el binario nativo de Linux. macOS funciona para desarrollo local. Windows no es compatible como plataforma de servidor. |
Pasos
1. Registra un cliente OAuth en tu IdP
Decide primero el hostname del gateway, porque el URI de redirección debe coincidir con él. Crea una nueva aplicación web OIDC y establece el URI de redirección en https://claude-gateway.<your-domain>/oauth/callback, donde el host es el mismo valor que estableces como listen.public_url en el paso 3. Anota el client_id y el client_secret. Las instrucciones para cada IdP están en Configuración del proveedor de identidad.
2. Aprovisiona una base de datos PostgreSQL
Usa PostgreSQL 11 o posterior. El nivel administrado más pequeño es suficiente. El gateway ejecuta sus propias migraciones de esquema al arrancar, así que el rol de la base de datos necesita permisos para crear y modificar tablas; consulta store.
3. Escribe gateway.yaml
Los secretos se leen mediante la expansión ${ENV_VAR} para que el archivo en sí pueda estar en control de versiones. Usa un hostname de public_url que resuelva a una IP privada en tu 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:
listen:
host: 0.0.0.0
port: 8080
# Required unless host is a loopback address. Used for the IdP
# redirect_uri and the discovery document.
public_url: https://claude-gateway.internal.example.com
oidc:
issuer: https://login.example.com # must serve /.well-known/openid-configuration
client_id: 0oa1example2
client_secret: ${OIDC_CLIENT_SECRET}
allowed_email_domains: [example.com] # reject id_tokens outside your org
userinfo_fallback: true # for IdPs whose id_token omits email/groups; harmless otherwise
session:
jwt_secret: ${GATEWAY_JWT_SECRET} # openssl rand -base64 32
ttl_hours: 1 # also bounds revocation latency on IdP deprovision
store:
postgres_url: ${GATEWAY_POSTGRES_URL} # add ?sslmode=require for managed Postgres
upstreams:
- provider: bedrock
region: us-east-1
auth: {} # empty: AWS default credential chain
# (IRSA, EC2/ECS task role, env vars, ~/.aws)
# Models are translated per upstream automatically. The built-in catalog
# maps claude-opus-4-8 to us.anthropic.claude-opus-4-8 and so on for every
# Bedrock-supported Claude model. Set false and add a `models:` list to
# expose only specific models.
auto_include_builtin_models: true
Esta configuración es suficiente para un ciclo de inicio de sesión funcional con el catálogo de modelos predeterminado de Amazon Bedrock. Una vez que esté en ejecución, agrega RBAC por grupo y configuración administrada mediante managed.policies, distribución de telemetría mediante telemetry, y conmutación por error entre varios upstreams, ARN de rendimiento aprovisionado o regiones fuera de EE. UU. mediante models.
[!NOTE]
El upstream de Amazon Bedrock necesita un principal de AWS con
bedrock:InvokeModelybedrock:InvokeModelWithResponseStreamtanto en los ARNinference-profile/us.anthropic.*como en los ARN subyacentesfoundation-model/anthropic.*. También necesita que se haya enviado el formulario único de caso de uso de Anthropic para la cuenta desde el catálogo de modelos de la consola de Bedrock.Proporciona 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 de
upstreamstiene todos los detalles de IAM, la matriz de credenciales entre nubes y los bloquesauthpara los demás proveedores.
4. Ejecútalo
Crea una imagen de contenedor alrededor del binario claude que cumpla los requisitos de la imagen y luego ejecútala junto a Postgres. El archivo de Compose hace referencia a la imagen como registry.example.com/claude-gateway:2.1.198; sustitúyela por tu propio registro y etiqueta de imagen:
services:
gateway:
image: registry.example.com/claude-gateway:2.1.198
ports: ["8080:8080"]
volumes: ["./gateway.yaml:/etc/claude/gateway.yaml:ro"]
environment:
OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}
GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway
# AWS credentials: in production, omit these and use an instance
# role. For local Compose testing, pass through your own:
AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}
AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}
depends_on:
postgres:
condition: service_healthy
postgres:
image: postgres:16-alpine
environment: { POSTGRES_USER: gw, POSTGRES_PASSWORD: pw, POSTGRES_DB: gateway }
healthcheck:
test: ["CMD-SHELL", "pg_isready -U gw"]
interval: 5s
volumes: ["pgdata:/var/lib/postgresql/data"]
volumes: { pgdata: }
El gateway es un único binario de Linux que lee la configuración, se conecta a Postgres y aplica sus migraciones de esquema, ejecuta el descubrimiento OIDC contra tu IdP, crea los clientes de upstream y empieza a escuchar.
El arranque falla de forma cerrada para la configuración, la conexión a Postgres, el descubrimiento OIDC y la creación de clientes de upstream. Si alguno de ellos es inaccesible o está mal configurado, el gateway termina 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 Amazon Bedrock y Google Cloud's Agent Platform se resuelven en la primera solicitud, no al arrancar.
Observa stderr para ver la secuencia de arranque. De forma predeterminada, las líneas de registro usan el formato [gateway] <timestamp> <level> <message>, y un banner de inicio, omitido abajo, se imprime entre las líneas de migración y de escucha. Los eventos de auditoría son JSON de una sola línea con un campo evt. Una base de datos nueva imprime una línea migration N applied por cada migración de esquema; una base de datos ya migrada no imprime ninguna. Deberías ver, en orden:
{"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}
[gateway] 2026-06-10T17:03:21.395Z info waiting for migration lock (another replica may be migrating; check pg_locks for key 6775156 if this persists)
[gateway] 2026-06-10T17:03:21.408Z info migration 1 applied
…
[gateway] 2026-06-10T17:03:21.431Z info migration 6 applied
[gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080
El gateway también registra una advertencia de que access_control.allow_cidrs está vacío. Eso es esperado aquí, porque nada limita a qué direcciones de cliente sirve el gateway hasta que establezcas una lista de permitidos. La referencia de access_control tiene los rangos recomendados.
Si el arranque termina antes de la línea claude gateway listening on, la última línea de stderr indica el problema:
- un Postgres inaccesible
- un rol de Postgres sin permiso de DDL
- un documento de descubrimiento OIDC inaccesible o no válido
- una violación del esquema de configuración con la ruta del campo problemático
Corrígelo y reinicia.
Si ya tienes un ingress que termina TLS, omite Compose y ejecuta el binario directamente con claude gateway --config gateway.yaml. Establece public_url en el origen del ingress y vincula listen a una dirección loopback o interna del clúster.
5. Verifica la superficie de autenticación
Tres comprobaciones confirman que el gateway puede autenticar a un usuario real antes de compartirlo con un desarrollador.
Los ejemplos usan la URL pública del gateway; para la configuración local de Compose sin ingress, sustitúyela por http://localhost:8080 en las dos primeras comprobaciones. La tercera comprobación abre verification_uri_complete, que se construye a partir de public_url, así que para Compose local establece public_url: http://localhost:8080 en gateway.yaml y agrega http://localhost:8080/oauth/callback como segundo URI de redirección en el cliente OAuth del paso 1, porque el gateway construye el redirect_uri del IdP a partir de public_url. El enlace de verificación se abre entonces en tu navegador local.
En Windows PowerShell, ejecuta curl.exe; curl a secas es un alias de Invoke-WebRequest y rechaza estos flags.
Primero, obtén el documento de descubrimiento, lo que confirma que el gateway está activo, que la configuración es válida y que se superaron todas las comprobaciones de arranque:
curl -s https://claude-gateway.internal.example.com/.well-known/oauth-authorization-server | jq
{
"issuer": "https://claude-gateway.internal.example.com",
"device_authorization_endpoint": "…/oauth/device_authorization",
"token_endpoint": "…/oauth/token",
"grant_types_supported": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]
}
La respuesta incluye campos adicionales, como response_types_supported y scopes_supported.
Segundo, solicita una autorización de dispositivo, lo que confirma que el flujo de inicio de sesión de dispositivo funciona y que Postgres es accesible y permite escritura:
curl -s -X POST https://claude-gateway.internal.example.com/oauth/device_authorization | jq
{
"device_code": "…",
"user_code": "WDJB-MJHT",
"verification_uri": "https://claude-gateway.internal.example.com/device",
"verification_uri_complete": "https://claude-gateway.internal.example.com/device?user_code=WDJB-MJHT",
"expires_in": 600,
"interval": 5
}
Tercero, prueba el tramo del navegador abriendo verification_uri_complete en un navegador y confirmando el código. Deberías ser redirigido a la página de inicio de sesión de tu IdP y, después de iniciar sesión, volver al gateway con una confirmación de sesión iniciada.
Usa la primera comprobación que falle para localizar el problema:
- Falla la primera comprobación: el arranque no se completó; revisa stderr
- Falla la segunda comprobación: Postgres no es accesible desde el gateway o el rol no puede escribir; revisa la cadena de conexión y los permisos
- La tercera comprobación no llega al IdP: verifica que el URI de redirección del IdP coincida exactamente con
https://<gateway>/oauth/callback - La tercera comprobación llega al IdP pero regresa con un error: lee el registro de auditoría del gateway, que registra cada rechazo de autenticación con el motivo, como
email domain not allowed
6. Inicia la sesión de un desarrollador
Este último paso ocurre en la máquina de un desarrollador, no en el servidor. Establece forceLoginMethod en "gateway", forceLoginGatewayUrl en el public_url de tu gateway y parentSettingsBehavior en "merge" en el archivo de configuración administrada de esa máquina; luego ejecuta /login, presiona Enter en la pantalla Cloud gateway y completa el inicio de sesión en el navegador. Establecer la URL del gateway, más abajo, describe las tres claves y cómo distribuirlas a la máquina de cada desarrollador.
Conectar desarrolladores
Los desarrolladores se conectan desde sus propias laptops con un único inicio de sesión en el navegador, usando su cuenta de trabajo corporativa. No necesitan una cuenta de claude.ai, una clave de API ni una suscripción, porque las solicitudes al modelo pasan por el gateway usando la credencial ascendente de la organización. La conexión se controla mediante la configuración administrada del lado del cliente que distribuyes a través de MDM, y esta sección cubre lo que configura el administrador.
La CLI toma la huella digital del certificado TLS hoja del gateway en la primera conexión y la fija por nombre de host. Vuelve a verificar esa fijación durante el inicio de sesión, en las actualizaciones silenciosas de la sesión y en las obtenciones de configuración administrada, mientras que las solicitudes de inferencia usan la validación TLS estándar sin la fijación. Las solicitudes enrutadas a través de un proxy HTTPS omiten la verificación de la fijación, así que agrega el host del gateway a NO_PROXY para mantenerlas directas.
Publica la huella digital SHA-256 esperada junto con la URL del gateway para que los desarrolladores tengan algo con qué compararla. El prompt de /login muestra los primeros 16 caracteres de la huella digital en hexadecimal en minúsculas, sin dos puntos. Para imprimir la huella digital completa en ese formato a partir del archivo del certificado, ejecuta:
openssl x509 -noout -fingerprint -sha256 -in cert.pem | cut -d= -f2 | tr -d : | tr 'A-F' 'a-f'
Cuando el certificado rota, todos los desarrolladores vuelven a ver el prompt de confianza, así que trata las rotaciones como un evento planificado y vuelve a publicar la huella digital. Si la política de tu gateway incluye ajustes que requieren aprobación, el desarrollador también vuelve a ver ese diálogo de aprobación después de aceptar el nuevo certificado, porque Claude Code vincula la memoria de aprobación al certificado fijado.
Un gateway puede devolver el campo opcional email en su respuesta de token para indicar la cuenta que usó un inicio de sesión. Cuando lo hace, el desarrollador confirma la cuenta antes de que Claude Code guarde la credencial. Después de un inicio de sesión confirmado, /status muestra la cuenta.
La confirmación requiere Claude Code v2.1.275 o posterior en la máquina del desarrollador; un cliente con una versión anterior ignora el campo. El servidor de gateway incluido en el binario claude no devuelve el campo, por lo que sus inicios de sesión se completan sin la confirmación.
Una vez que el desarrollador inicia sesión, el selector de modelos muestra los modelos de su lista de permitidos availableModels. La configuración administrada se aplica al inicio y se actualiza cada hora, y la telemetría se enruta a tu recopilador.
Las sesiones se actualizan silenciosamente antes de que venza ttl_hours. Cuando una actualización falla después del desaprovisionamiento en el IdP, Claude Code le pide al desarrollador que vuelva a iniciar sesión.
Establecer la URL del gateway
Tres claves van en el archivo de configuración administrada de cada sistema operativo que implementas a través de MDM o directamente en el disco. Para una máquina sin configuración administrada, consulta en su lugar Establecer la URL del gateway en la configuración de usuario. forceLoginMethod y forceLoginGatewayUrl abren /login directamente en la pantalla Cloud gateway con la URL ya completada, y parentSettingsBehavior: "merge" permite que Claude Desktop entregue la lista de permitidos de salida del gateway a las sesiones de Claude Code que inicia, como se explica en Entregar la política a las sesiones de Claude Desktop:
{
"forceLoginMethod": "gateway",
"forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
"parentSettingsBehavior": "merge"
}
El desarrollador presiona Enter para conectarse. El prompt de huella digital TLS de la primera conexión sigue apareciendo. Una vez que el archivo está en una máquina, un desarrollador que no ha completado el inicio de sesión en el gateway ve uno de los mensajes descritos en Administrator policy requires a Cloud gateway sign-in. Los desarrolladores que seleccionan un proveedor de nube mediante una variable de entorno como CLAUDE_CODE_USE_BEDROCK no necesitan el inicio de sesión en el gateway.
El selector de inicio de sesión no tiene una opción de gateway, y en la configuración administrada forceLoginMethod por sí solo, sin una URL, deja al desarrollador ante un mensaje "Contact your IT administrator". Las claves de inicio de sesión van en el archivo que distribuyes a las máquinas, no en el bloque managed.policies[].cli del gateway, que solo llega a los clientes que ya están conectados.
Establecer la URL del gateway en la configuración de usuario
En las máquinas sin configuración administrada, pide a cada desarrollador que agregue forceLoginMethod y forceLoginGatewayUrl a su propio archivo de configuración de usuario, ~/.claude/settings.json. Esto requiere Claude Code v2.1.295 o posterior en la máquina del desarrollador. Este ejemplo indica un gateway en claude-gateway.internal.example.com:
{
"forceLoginMethod": "gateway",
"forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"
}
Cuando el desarrollador ejecuta /login en el prompt de Claude Code, la pantalla Cloud gateway se abre con esa dirección y presiona Enter para conectarse. El prompt de huella digital TLS de la primera conexión sigue apareciendo. Estos límites se aplican a las claves establecidas de esta forma:
- Solo configuración de usuario: Claude Code lee las dos claves de
~/.claude/settings.json, no de.claude/settings.jsonni de.claude/settings.local.jsonde un proyecto. - La configuración administrada las desactiva: una vez que la configuración de un administrador llega a la máquina mediante un archivo de configuración administrada, un plist de macOS o una política HKLM de Windows, o un policy helper, Claude Code ignora un gateway indicado en la configuración de usuario.
Permitir un gateway en un espacio de direcciones público de tu propiedad
Algunas organizaciones numeran su red interna a partir de un bloque IPv4 público de su propiedad, como el espacio de direcciones propio de un operador o un /8 heredado, por lo que su gateway no tiene una dirección privada. Enumera esos bloques en el ajuste de configuración administrada gatewayInternalNetworks. Entonces /login acepta un gateway dentro de un bloque enumerado cuando la máquina del desarrollador se conecta a él desde una dirección dentro del mismo bloque. Esto requiere Claude Code v2.1.268 o posterior en la máquina del desarrollador; las versiones anteriores ignoran la clave y aplican la regla de direcciones privadas.
[!WARNING]
gatewayInternalNetworkses para redes internas que resultan estar numeradas a partir de un espacio de direcciones público. No hace que sea seguro exponer un gateway a internet: un gateway de confianza puede distribuir ajustes que ejecutan comandos en las máquinas de los desarrolladores.Mantén el gateway inaccesible desde fuera de tu red con las reglas de tu firewall o balanceador de carga. Establece el
access_control.allow_cidrsdel gateway en los mismos bloques que declaras aquí, para que el propio gateway rechace clientes desde cualquier otro lugar. Detrás de un balanceador de carga o ingress, establece tambiénlisten.trusted_proxiesen ese front end, porque de lo contrario el gateway comparaallow_cidrscon la dirección del propio front end en lugar de la del desarrollador.
Agrega la clave a la misma fuente de configuración administrada que las claves de inicio de sesión: el archivo de configuración administrada, el perfil de MDM o la política del registro. Claude Code la ignora en la configuración de usuario, de proyecto y administrada por el servidor.
Este ejemplo declara un bloque. Reemplaza 203.0.113.0/24 por tu propio bloque. Es un rango de documentación, y Claude Code los rechaza.
{
"gatewayInternalNetworks": ["203.0.113.0/24"]
}
Claude Code valida la lista en /login antes de contactar a cualquier gateway:
- Cada entrada es un bloque IPv4 escrito como su primera dirección y un prefijo de
/8a/32. - La lista contiene como máximo cuatro bloques, y no hay dos que se superpongan.
- Ningún bloque se superpone con el espacio de direcciones privadas:
10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.0/8,169.254.0.0/16y100.64.0.0/10./loginya acepta un gateway ahí sin esta clave. - Ningún bloque se superpone con espacio que nunca es la red de una organización:
198.18.0.0/15y192.0.0.0/24, que los clientes de VPN y NAT64 usan como direcciones locales; los rangos de documentación192.0.2.0/24,198.51.100.0/24y203.0.113.0/24; y los rangos reservados0.0.0.0/8,192.88.99.0/24y el de multidifusión224.0.0.0/4. Puedes declarar bloques dentro de240.0.0.0/4, que algunas redes grandes usan como espacio interno de unidifusión.
Los bloques de managed-settings.json y sus archivos drop-in managed-settings.d/ se combinan en una sola lista, y estos límites se aplican a la lista combinada. Para reducir un bloque, reemplaza su entrada en lugar de agregar una segunda que se superponga en un drop-in; /login rechaza la superposición.
Si una entrada incumple una regla, o el valor no es una lista de cadenas, Claude Code rechaza todo nuevo inicio de sesión en un gateway en esa máquina e indica el problema en el mensaje. El inicio de sesión en un gateway con una dirección privada también falla, y los inicios de sesión existentes siguen funcionando. Prueba el valor en una máquina antes de implementarlo. Claude Code también incluye un valor con un tipo incorrecto entre la configuración administrada no válida que informa.
Con una lista válida, /login aplica tres verificaciones a un gateway cuya dirección está dentro de un bloque enumerado:
- Todas las direcciones a las que resuelve el nombre de host del gateway están dentro de ese mismo bloque. Claude Code rechaza un nombre que también tiene registros fuera de él, incluidas direcciones privadas e IPv6.
- La máquina del desarrollador se conecta desde dentro del mismo bloque. Claude Code rechaza una máquina detrás de NAT, dentro de un contenedor o de WSL2, o en una VPN cuyo grupo de direcciones está fuera del bloque, e indica la dirección desde la que se conectó la máquina.
- La conexión es directa. Si
HTTPS_PROXYse aplica al host del gateway,/loginla rechaza e indica la entrada deNO_PROXYque debes agregar.
Cuando las tres se cumplen, el prompt de confianza agrega una línea que indica la dirección de la máquina, la dirección del gateway y el bloque declarado que contiene ambas.
La clave no cambia nada para otros gateways: el inicio de sesión en uno con una dirección privada funciona como antes, y el inicio de sesión en uno con una dirección pública fuera de todos los bloques enumerados se rechaza como antes.
Un bloque declarado restringe quién puede iniciar sesión, pero no prueba dónde está una máquina, así que declara solo espacio de direcciones que controla tu organización. Un bloque compartido con otros inquilinos, como el rango público de un proveedor de nube, permite que cualquiera dentro de él pase la misma verificación.
Entregar la política a las sesiones de Claude Desktop
Claude Desktop ejecuta sus pestañas sobre sesiones integradas de Claude Code y envía sus solicitudes al modelo a través del gateway. Pasa la política a cada una de esas sesiones, construida a partir de la configuración que el gateway le sirve en /user/bootstrap. Esa configuración contiene la lista de modelos permitidos, las herramientas deshabilitadas y la lista de destinos de salida permitidos derivadas del bloque cli o code de la política coincidente, además de la superposición desktop.
Las demás claves del bloque, como los hooks, env y las reglas de permisos con alcance como Bash(npm *), llegan a los clientes que inician sesión a través de /login. En code, también llegan a la sesión de la pestaña Code cuando se cumplen las condiciones para la pestaña Code. No llegan a las sesiones de Cowork ni de Chat. Claude Desktop lee la URL del gateway de su propia configuración administrada e inicia sesión con su propio flujo, independiente de las claves forceLoginMethod y forceLoginGatewayUrl de Establecer la URL del gateway.
Los ajustes que pasa un proceso que inicia Claude Code son la configuración del proceso padre. Claude Code ignora la configuración del proceso padre en cualquier máquina que tenga una fuente administrada implementada por un administrador, a menos que la fuente que entrega la política establezca parentSettingsBehavior: "merge".
Qué máquinas necesitan la activación
Las máquinas que solo ejecutan Claude Desktop la necesitan. Claude Desktop aplica por sí mismo la lista de modelos y la lista de herramientas deshabilitadas a las sesiones integradas, pero la lista de permitidos de salida solo les llega como configuración del proceso padre, en forma de reglas de dominio de WebFetch y reglas de red del sandbox. Sin la activación, esas sesiones se ejecutan sin la restricción de salida, y nada te lo advierte. El gateway sigue rechazando las solicitudes de inferencia para modelos que la política no concede.
Una lista de marketplaces de plugins permitidos también llega a las sesiones integradas solo como configuración del proceso padre. Cuando desactivas los marketplaces de plugins agregados por el usuario en la configuración administrada de Claude Desktop, Claude Desktop 2.16120.0 o posterior oculta los marketplaces que tu organización no aprovisionó y rechaza instalaciones desde ellos. Para evitar que las sesiones integradas carguen plugins ya instalados desde esos marketplaces, les envía una lista strictKnownMarketplaces como configuración del proceso padre. Sin la activación, Claude Code ignora esa lista, y esos plugins se siguen cargando.
Las máquinas en las que los desarrolladores inician sesión a través de /login no la necesitan; cada sesión de Claude Code obtiene su política del gateway.
Las flotas cuyo policyHelper proporciona la configuración administrada no pueden usarla: Claude Code nunca combina la configuración del proceso padre en esas flotas, porque lee la configuración administrada únicamente de la salida del helper.
Configurar la activación
Implementa el fragmento de configuración administrada de Establecer la URL del gateway, replícalo en cualquier fuente del lado del cliente que tenga prioridad sobre el archivo y luego verifica.
1. Implementa la activación en el archivo de configuración administrada
El fragmento anterior ya incluye parentSettingsBehavior: "merge", así que el archivo que distribuyes a las máquinas lo contiene.
2. Replica el fragmento en cualquier fuente que tenga prioridad sobre el archivo
Claude Code lee parentSettingsBehavior solo de la fuente seleccionada. Agregar cualquier clave de política a una fuente puede convertirla en la seleccionada, así que en una fuente del lado del cliente replica el fragmento completo en lugar de solo parentSettingsBehavior. Configuración administrada del lado del cliente cubre las flotas que entregan la política a través de Group Policy o de perfiles de configuración. Un plist de preferencias administradas en macOS o una política HKLM en Windows tiene prioridad sobre el archivo managed-settings.json, y la configuración administrada remota del propio gateway tiene prioridad sobre ambos, así que en las máquinas que inician sesión en el gateway establece también parentSettingsBehavior en el bloque cli o code de la política del gateway.
3. Verifica qué fuente está seleccionada
En una máquina que solo ejecuta Claude Desktop, llama a resolveSettings() del Agent SDK y lee policyOrigin en la entrada managed de su lista sources. El valor indica la fuente del lado del cliente seleccionada, plist, hklm o file, que es la fuente que debe contener el fragmento.
Las sesiones de Cowork y Chat no obtienen la política del gateway, por lo que el bloque del gateway no es la fuente seleccionada para ellas.
Una sesión de la pestaña Code sí la obtiene cuando los ajustes de la política están en code y se cumplen las condiciones para la pestaña Code. En ese caso, los ajustes code del gateway son la fuente seleccionada para esa sesión.
Restringir la configuración del proceso padre
Una vez que implementas parentSettingsBehavior: "merge", cualquier proceso host que inicie Claude Code puede proporcionar configuración del proceso padre; no solo Claude Desktop, sino también una aplicación del Agent SDK o una extensión de IDE.
Claude Code filtra la configuración del proceso padre con una lista de permitidos de claves restrictivas, pero algunas claves permitidas pueden conceder acceso en lugar de restringirlo. A menos que establezcas los bloqueos allowManaged*Only, las reglas de permisos de tipo allow y las listas de permitidos del sandbox que proporciona el host siguen aplicándose. Las reglas deny y ask de tu política siguen vigentes en cualquier caso; se evalúan antes que cualquier regla allow.
Claude Code reenvía las entradas de sandbox.credentials proporcionadas por el proceso padre en forma reducida:
- Entradas
deny: se reenvían solo con supathonamey el modo. - Entradas de archivo con
mode: mask: se reenvían solo como centinela, como una máscara de archivo completo cuyoinjectHostses la lista vacía, de modo que el proxy nunca sustituye el valor real en una entrada proporcionada por el proceso padre en ninguna plataforma. También se descartan todos los campos de enmascaramiento estructurado, de modo que un patrón de extracción proporcionado por el proceso padre no puede desplazar una máscara más estricta que otra fuente establece para la misma ruta. - Entradas
envVarsconmode: mask: no se reenvían.denyes la única restricción que el canal del proceso padre puede expresar mediante entradasenvVars. awsPairsysigv4: se reenvían solo como restricciones. Desigv4solo se conservan los valoresdeny, y un proceso padre que define cualquier bloquesigv4fija las tres formas de solicitud,streaming,presignedysigv4a, endeny. Un par deawsPairsnunca se reenvía en una forma que pueda volver a firmar; un par que nombra una de las variables convencionales de AWS se reemplaza por una entrada inerte que mantiene suprimido el emparejamiento automático deAWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEYyAWS_SESSION_TOKEN.
Implementar los bloqueos
Para que la configuración del proceso padre sea lo más restrictiva posible según lo que admite el filtro, agrega los cinco bloqueos allowManaged*Only, y las listas de permitidos que controlan, a las mismas fuentes que la activación de merge:
{
"forceLoginMethod": "gateway",
"forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
"parentSettingsBehavior": "merge",
"allowManagedPermissionRulesOnly": true,
"allowManagedMcpServersOnly": true,
"allowManagedHooksOnly": true,
"allowedMcpServers": [{ "serverUrl": "https://mcp.internal.example.com/*" }],
"sandbox": {
"network": {
"allowManagedDomainsOnly": true,
"allowedDomains": ["github.com", "*.npmjs.org"]
},
"filesystem": {
"allowManagedReadPathsOnly": true,
"denyRead": ["~/"],
"allowRead": ["~/projects"]
}
}
}
Una política del sistema operativo, como una política de registro HKLM o un plist de preferencias administradas, tiene prioridad sobre este archivo, así que en ese caso entrega el fragmento completo a través de ella en lugar del archivo. La configuración administrada remota del gateway tiene prioridad sobre las fuentes de política del sistema operativo y de archivo, pero solo llega a los clientes conectados. Replica los bloqueos, las listas de permitidos y la activación de merge en el bloque cli o code de la política y mantén este archivo implementado, porque las máquinas que nunca se conectan obtienen su política únicamente del archivo.
Comportamiento de los bloqueos entre fuentes
Establecer un bloqueo no restringe los demás; cada clave está documentada en la referencia de configuración.
Desde una fuente de administrador por debajo de la ganadora, los dos bloqueos del sandbox siguen aplicándose, y allowManagedPermissionRulesOnly sigue bloqueando las reglas allow y los additionalDirectories proporcionados por el proceso padre. En Claude Code v2.1.273 o posterior, el bloqueo de servidores MCP también se aplica desde una fuente por debajo de la ganadora, y mientras está activado, la lista administrada allowedMcpServers proviene de la fuente de administrador de mayor prioridad que establece una.
El bloqueo de hooks y el efecto de allowManagedPermissionRulesOnly sobre las reglas propias del desarrollador requieren, de forma predeterminada, la fuente ganadora; con la activación de merge de managedSourcesBehavior descrita en cómo combina Claude Code las fuentes administradas, Claude Code aplica para cada bloqueo el valor más estricto que establezca cualquier fuente. En las flotas con policyHelper, Claude Code lee los bloqueos únicamente de la salida del helper.
Cada bloqueo hace que Claude Code ignore las entradas propias del desarrollador para ese ajuste, así que incluye las listas de permitidos de tu organización junto a los bloqueos:
- Dominios de red: bloquear con una lista de dominios administrados vacía bloquea todo el tráfico saliente del sandbox.
- Servidores MCP: bloquear sin
allowedMcpServersen ninguna fuente de administrador ni en la configuración proporcionada por el proceso padre carga todos los servidores quedeniedMcpServersno bloquea. - Rutas de lectura: las entradas
allowReadsolo vuelven a permitir rutas dentro de las regiones dedenyRead, así que combínalas con undenyReadadministrado.
Ajustes que los bloqueos no cubren
Estos ajustes proporcionados por el proceso padre pasan el filtro incluso con los cinco bloqueos establecidos:
forceLoginOrgUUID: Claude Code respeta un valor proporcionado por el proceso padre cuando la configuración administrada que aplica no establece un UUID de organización. El inicio de sesión en el gateway no verifica esta clave. Un UUID de organización en la configuración administrada que aplica Claude Code bloquea el valor del proceso padre y es el UUID de organización que Claude Code aplica. Si tu flota fija una organización de Anthropic, consulta Qué fuente administrada proporciona las claves de inicio de sesión para saber dónde establecerforceLoginOrgUUID.allowedMcpServers: Claude Code respeta una lista de permitidos proporcionada por el proceso padre cuando no hay ninguna lista de administrador vigente.allowManagedMcpServersOnlyno la bloquea, porque el bloqueo aplica la lista que resulte ganadora como valor administrado, incluida una proporcionada por el proceso padre cuando ninguna fuente de administrador proporciona una lista. Una lista en la fuente de administrador de mayor prioridad bloquea la del proceso padre y es la que Claude Code aplica, así que estableceallowedMcpServersahí, junto al bloqueo. Antes de v2.1.223, un valor para cualquiera de las dos claves en cualquier fuente de administrador bloqueaba el del proceso padre.availableModels: Claude Code respeta una lista de modelos proporcionada por el proceso padre cuando la fuente administrada ganadora no establece una. Si tu flota restringe los modelos, estableceavailableModelsen la fuente ganadora.allowedProviders: Claude Code respeta una lista de proveedores de API permitidos proporcionada por el proceso padre cuando la fuente administrada ganadora no establece una. Si tu flota restringe qué proveedores de API pueden usar los desarrolladores, estableceallowedProvidersen la fuente ganadora. Requiere Claude Code v2.1.285 o posterior.strictKnownMarketplaces: Claude Code respeta una lista de marketplaces de plugins permitidos proporcionada por el proceso padre cuando la fuente administrada ganadora no establece una. Claude Desktop 2.16120.0 o posterior envía una cuando su configuración administrada desactiva los marketplaces de plugins agregados por el usuario. Si tu flota restringe los marketplaces, establecestrictKnownMarketplacesen la fuente ganadora. Requiere Claude Code v2.1.282 o posterior.blockedMarketplaces: una lista de marketplaces bloqueados proporcionada por el proceso padre pasa el filtro y se suma a cualquier lista de bloqueados que establezca una fuente administrada, ya que una lista de bloqueados solo puede restringir más. Requiere Claude Code v2.1.282 o posterior.strictPluginOnlyCustomization: esta clave pasa el filtro independientemente de cualquier bloqueo, y hace que Claude Code ignore la personalización propia del desarrollador, incluidos los hooks de protección. Ningún bloqueo la bloquea.
Si estableces managedSourcesBehavior en "merge", consulta qué valor de fuente se aplica para cada tipo de clave.
Cómo surten efecto las claves de hooks y skills en la configuración del proceso padre
Las claves que tu aplicación pasa en la opción managedSettings del Agent SDK son configuración del proceso padre. En una máquina en la que un administrador implementa configuración administrada, Claude Code ignora la configuración del proceso padre a menos que el administrador permita que un host integrador agregue políticas.
Si pasas disableAllHooks: true en managedSettings:
- Se detienen: los hooks de usuario, de proyecto y locales, además de los hooks declarados en el frontmatter de un agente o en la opción
settingsdel SDK. - Siguen ejecutándose: los callbacks de hooks del SDK de tu aplicación y los hooks de un administrador definidos en la configuración administrada. Tu aplicación no puede desactivar los hooks del administrador.
| Lo que pasas | Lo que sucede |
|---|---|
hooks, o allowedHttpHookUrls o httpHookAllowedEnvVars con entradas |
Claude Code ignora la clave. Usa en su lugar la opción settings del SDK. |
allowedHttpHookUrls: [] |
Surte efecto a menos que el administrador defina hooks o habilite un plugin. No se ejecuta ningún hook HTTP, excepto para las URL que enumere otra fuente de configuración. |
httpHookAllowedEnvVars: [] |
Surte efecto a menos que el administrador defina hooks o habilite un plugin. Los encabezados de los hooks HTTP solo pueden incluir las variables de entorno que enumere otra fuente de configuración. |
disableSkillShellExecution: true |
Surte efecto. |
Pasar estas claves en managedSettings requiere Claude Code v2.1.309 o posterior, o el Agent SDK de TypeScript v0.3.309 o posterior.
Conectar Claude Desktop
Claude Desktop se conecta al mismo gateway mediante una clave de MDM diferente: establece bootstrapUrl en la configuración administrada de Claude Desktop en <listen.public_url>/user/bootstrap, y activa la política del usuario con una clave desktop. Superposición de Claude Desktop cubre ambas partes. Requiere Claude Code v2.1.203 o posterior en el servidor del gateway. Una vez conectado, Claude Desktop envía las solicitudes al modelo de todas las pestañas activadas a través del gateway.
Claude Desktop inicia la sesión del desarrollador a través del proveedor de identidad del gateway con el mismo paso de SSO en el navegador y luego obtiene su configuración del gateway en lugar de Anthropic. El acceso a los modelos y la política siguen las mismas reglas por grupo que la CLI. Un desarrollador que usa tanto la CLI como Claude Desktop inicia sesión en cada uno por separado; la sesión del gateway no se comparte entre ellos.
Pipelines de CI y máquinas remotas
No existe un flujo de token de servicio para pipelines desatendidos. El inicio de sesión en el gateway siempre ejecuta el flujo de dispositivo del navegador, por lo que un trabajo de CI sin un desarrollador que apruebe el inicio de sesión no puede autenticarse; configura esos trabajos directamente con tu proveedor. Implementa forceLoginMethod y forceLoginGatewayUrl en las máquinas de los desarrolladores y no los incluyas en los runners de CI. En una máquina cuya configuración administrada los establece, una sesión que se autentica con ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN o apiKeyHelper termina al arrancar.
Una vez que un desarrollador inicia sesión, cada sesión de Claude Code en esa máquina usa la sesión del gateway, incluidas las ejecuciones no interactivas de claude -p y las sesiones iniciadas por el Agent SDK. Claude Code aplica la política del gateway a cada una de ellas.
El flujo de dispositivo separa la CLI que consulta del navegador que aprueba, así que una máquina de desarrollo remota sin pantalla también funciona: el desarrollador ejecuta /login por SSH en la máquina remota y abre el enlace de verificación en el navegador de su laptop.
Qué se aplica a los desarrolladores
Estas garantías se aplican a todas las sesiones iniciadas a través de /login. Las sesiones integradas que inicia Claude Desktop reciben su política como se describe en Entregar la política a las sesiones de Claude Desktop, y el punto sobre telemetría indica adónde van sus exportaciones.
- Acceso a modelos: las solicitudes de modelos que la política no concede devuelven 400, y el selector de
/modelse filtra según la lista de permitidosavailableModelsde la política. Esto incluye el modelo con el que se inicia una sesión antes de que el desarrollador elija uno; consulta Iniciar sesiones con un modelo que la política permite. - Destino de la telemetría: en las sesiones iniciadas a través de
/login, la CLI envía sus exportaciones OTLP/HTTP al gateway en lugar de a unOTEL_EXPORTER_OTLP_ENDPOINTestablecido localmente, a menos que una política indique tu recopilador como endpoint. El gateway reenvía las exportaciones que recibe a los destinos detelemetry.forward_to.- En las sesiones integradas que inicia Claude Desktop, la CLI envía sus exportaciones al
OTEL_EXPORTER_OTLP_ENDPOINTconfigurado. La CLI adjunta el token de sesión del gateway a esas exportaciones solo cuando ese endpoint apunta al propio gateway. - Si no hay un destino configurado para una señal, el gateway la acepta y la descarta.
- Si ya recopilas la telemetría de Claude Code directamente, agrega tu recopilador como destino de
forward_to, o indícalo en una política para omitir el reenvío.
- En las sesiones integradas que inicia Claude Desktop, la CLI envía sus exportaciones al
- Credenciales: el token del gateway es la única credencial de la sesión. Los perfiles de Anthropic y cualquier inicio de sesión anterior en claude.ai se ignoran mientras la sesión está iniciada, así que los desarrolladores no necesitan cerrar primero la sesión de claude.ai. Para una credencial configurada de
ANTHROPIC_API_KEY,ANTHROPIC_AUTH_TOKENoapiKeyHelper, o una clave de API guardada por un inicio de sesión anterior en Claude Console, consulta Administrator policy requires a Cloud gateway sign-in. - Configuración administrada: las claves bloqueadas no se pueden anular localmente. La CLI aplica la política al inicio y aplica los cambios en cada consulta horaria, salvo los cambios que solo se aplican en el siguiente inicio.
- Inicio con el gateway inaccesible: las sesiones iniciadas terminan al arrancar con un error después de unos 10 segundos en lugar de iniciarse sin su configuración.
- Inicio después de que el gateway finaliza la sesión: consulta Aplicar un inicio con cierre ante fallos para ver qué inicios se abren sin sesión en el gateway y cuáles terminan cuando el gateway responde con un
401. - Desaprovisionamiento: una sesión cuyo usuario está deshabilitado en el IdP vence dentro de
ttl_hourscuando falla la siguiente actualización. - Cierre de sesión:
/logoutelimina la credencial del gateway de la máquina del desarrollador.- Cuando el documento de descubrimiento del gateway anuncia un
revocation_endpointen el mismo esquema, host y puerto que la URL del gateway,/logouttambién envía los tokens almacenados a ese endpoint para que el gateway pueda finalizar la sesión de su lado. La solicitud se hace con el mejor esfuerzo, así que el cierre de sesión se completa en la máquina del desarrollador tanto si el endpoint responde como si no. La revocación requiere Claude Code v2.1.275 o posterior en la máquina del desarrollador. - El servidor de gateway incluido en el binario
claudeno anuncia ninguno, así que un cierre de sesión en él finaliza la sesión solo en la máquina del desarrollador. Para forzar el cierre de las sesiones del lado del servidor, consulta Rotación del secreto JWT.
- Cuando el documento de descubrimiento del gateway anuncia un
Qué puede ver la organización
La telemetría de uso lleva al recopilador de la organización la identidad del desarrollador, los recuentos de tokens, el modelo y la latencia. El gateway no registra ni almacena el contenido de los prompts ni de las respuestas. Si se recopila telemetría más detallada, como registros y trazas, que puede incluir comandos y rutas de archivos, es una elecció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 del gateway, y qué soporta el servidor del gateway en sí. Donde algo no es compatible, la columna Notas proporciona la alternativa.
El gateway entrega los valores anthropic-beta que la CLI envía a cada ascendente, por lo que los operadores no mantienen una lista de permitidos de betas. Para Amazon Bedrock, que ignora el encabezado, el gateway mueve los valores al campo anthropic_beta del cuerpo de la solicitud; los otros ascendentes reciben el encabezado tal como se envía.
| Característica | Estado | Notas |
|---|---|---|
| Reenvío de inferencia (Amazon Bedrock, Claude Platform en AWS, Agent Platform de Google Cloud, Microsoft Foundry, Anthropic) | Disponible | Con traducción de modelos por ascendente y conmutación por error. El ascendente de Amazon Bedrock utiliza el endpoint bedrock-runtime y la cadena de credenciales predeterminada de AWS. El ascendente Amazon Bedrock Mantle requiere Claude Code v2.1.283 o posterior en el servidor del gateway, y el ascendente Claude Platform en AWS requiere v2.1.198 o posterior. |
| Ventana de contexto de 1M tokens | Disponible | Los modelos Fable, Sonnet 5 y posteriores, y Opus 4.7 y posteriores se ejecutan con la ventana de 1M de forma predeterminada; consulta Contexto extendido. El valor predeterminado de 1M para los modelos Fable y Opus requiere Claude Code v2.1.287 o posterior en la máquina del desarrollador |
| Acceso a modelos y configuración administrada por grupo de IdP | Disponible | El acceso a modelos se aplica del lado del servidor; la configuración administrada se entrega por grupo de IdP y la CLI la aplica en el nivel de configuración administrada |
| Claude Desktop | Disponible con participación opcional | Haz que una política participe con una clave desktop. Requiere Claude Code v2.1.203 o posterior en el servidor del gateway. |
| Distribución de telemetría (OTLP/HTTP) | Disponible | Marcada con la identidad en cada exportación; codificaciones protobuf y JSON |
| Proveedores de identidad OIDC | Disponible | Cualquier IdP compatible con OIDC; el gateway ejecuta el descubrimiento OIDC estándar y el flujo de código de autorización. Consulta Configuración del proveedor de identidad para la configuración por IdP |
| Límites de gasto por usuario y por grupo | Disponible | Consulta Límites de gasto |
| Búsqueda web del lado del servidor | No disponible | La CLI no puede ver a qué proveedor ascendente enruta el gateway, por lo que no puede verificar la compatibilidad con la búsqueda web y deshabilita WebSearch en las sesiones del gateway |
| Remote Control | No disponible | La CLI muestra un error que nombra el gateway |
/design-sync y /design-login |
No disponible | Ambos necesitan claude.ai, que la CLI no contacta en las sesiones del gateway, por lo que ninguno de los dos comandos aparece allí |
Características que necesitan obtener flags de características, como /import y claude import |
No disponible | La CLI omite la obtención de flags en las sesiones del gateway. Características que necesitan obtener flags de características enumera lo que eso desactiva |
| Caché de prompts estándar | Disponible | El gateway reenvía los puntos de interrupción cache_control a cada ascendente. Dónde vive la caché cubre qué bloques marca la CLI, incluido el contexto del sistema que añade a mitad de la conversación |
| TTL de caché de 1 hora | Disponible con participación opcional | La CLI usa el TTL de 5 minutos en las sesiones del gateway de forma predeterminada. Para solicitar el TTL de 1 hora, establécelo en una política. Establécelo solo si tus ascendentes ofrecen el TTL de 1 hora para todos los modelos que sirve el gateway, porque la solicitud falla si un ascendente rechaza el TTL |
| Modo automático | Disponible | Sigue las reglas de proveedores de terceros: solo los modelos elegibles en proveedores de terceros pueden usarlo. Antes de v2.1.207, el modo automático en las sesiones del gateway requería establecer CLAUDE_CODE_ENABLE_AUTO_MODE=1, que se podía entregar a través del bloque env de la política administrada |
| Optimizaciones exclusivas de primera parte, como el alcance de caché global y las herramientas eficientes en tokens | No disponible | La CLI no las habilita en las sesiones del gateway; consulta la nota sobre el encabezado beta anterior |
| OTLP/gRPC | No compatible | Solo OTLP sobre HTTP |
| SAML, LDAP y otra autenticación no OIDC | No compatible | Solo OIDC. Coloca un puente OIDC delante si es necesario |
| Multiinquilino (múltiples emisores OIDC) | No compatible | Un emisor por gateway. Ejecuta instancias separadas |
| Servidor Windows | No compatible | Despliega en Linux. macOS solo para desarrollo local |
| Gráfico Helm | No disponible | El gateway se ejecuta como un Deployment estándar sin estado; consulta la guía de despliegue |
| Interfaz de administración | Solo límites de gasto | En Claude Desktop 4.23118.0 o posterior conectado al gateway, los miembros de admin.admin_groups pueden administrar los límites de gasto. El resto de la configuración es el archivo YAML; vuelve a desplegar para cambiarla |
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 AWS, con ECS Fargate o EKS, Amazon RDS y Secrets Manager, consulte Implementar en AWS.
- Para un ejemplo completo trabajado en Google Cloud, con Cloud Run, Cloud SQL y Secret Manager, consulte Implementar en Google Cloud.