Configuración de la puerta de enlace de aplicaciones Claude

Referencia para cada opción de gateway.yaml: listener y TLS, OIDC, sesión, almacén Postgres, upstream de Bedrock, Claude Platform en AWS, Agent Platform de Google Cloud y Microsoft Foundry, enrutamiento de modelos, políticas administradas y telemetría.

Una implementación de la puerta de enlace de aplicaciones Claude se configura mediante un archivo YAML, convencionalmente gateway.yaml. El archivo define todo lo que hace la puerta de enlace: dónde escucha, cómo inician sesión los desarrolladores, dónde va la inferencia y qué políticas y telemetría se aplican. Esta página es la referencia para cada opción en ese archivo.

Para escribir el primero, comience desde el inicio rápido, que construye una configuración mínima funcional y la ejecuta. Una vez que tenga una configuración con la que esté satisfecho, la guía de implementación cubre la containerización y el alojamiento en Kubernetes, Cloud Run o su propia plataforma.

La puerta de enlace lee el archivo una vez, al iniciar, con claude gateway --config /path/to/gateway.yaml. Cada opción se valida contra un esquema al arrancar, por lo que una configuración mal formada falla al iniciar con un error a nivel de campo en lugar de en el primer uso.

El ejemplo completo al final de esta página ejercita cada sección.

Estructura del archivo

Cinco secciones son requeridas. Todas las demás secciones son opcionales, y una sección omitida toma sus valores predeterminados. Las claves desconocidas fallan al arrancar, por lo que un error tipográfico aparece como un error nombrado en lugar de una configuración silenciosamente ignorada.

Secciones requeridas:

listen: dirección de enlace, URL pública, terminación TLS
oidc: su proveedor de identidad (IdP), incluido emisor, cliente, mapeo de reclamaciones y quién puede iniciar sesión
session: los tokens portadores que emite la puerta de enlace, con secreto y duración
store: PostgreSQL, para concesiones de dispositivos y contadores de límite de velocidad
upstreams: dónde va la inferencia, ya sea Anthropic, Amazon Bedrock, Claude Platform en AWS, Agent Platform de Google Cloud o Microsoft Foundry

Secciones opcionales:

admin: autenticación de API de administración y retención de límites de gasto
enforcement: comportamiento de límite de gasto de fallo abierto o fallo cerrado
pricing: tasas contratadas y un multiplicador de descuento para el medidor de gasto y para las cifras de costo que ven los desarrolladores
models y auto_include_builtin_models: lista de modelos curada por administrador e IDs por upstream
managed: políticas de configuración administradas por grupo de IdP
telemetry: reenvío OTLP a su pila de observabilidad
access_control, limits, timeouts, rate_limits: permitir/denegar IP, límites de tamaño de solicitud, tiempo hasta el primer byte del upstream y límites de inicio de sesión por IP
load_test_mode: prueba de carga de la puerta de enlace sin llamar a un proveedor de modelos

Expansión de secretos

No escriba secretos como client_secret, jwt_secret o postgres_url directamente en gateway.yaml. Haga referencia a ellos con uno de los formularios a continuación, y la puerta de enlace resuelve el valor al arrancar desde una variable de entorno o un archivo:

Formulario	Se resuelve a	Usar para
`${VAR}`	La variable de entorno `VAR`. El arranque falla si no está definida.	Variables de entorno de contenedor, AWS Secrets Manager mediante inyección de env
`${file:/path}`	Contenido del archivo en esa ruta absoluta, recortado. La referencia debe ser el valor completo del campo: a diferencia de `${VAR}`, no se expande dentro de una cadena más larga, así que para una contraseña de base de datos establezca `store.password` en lugar de incrustarla en `postgres_url`.	Montajes de volumen de secreto de Kubernetes, Vault Agent, SOPS

Secciones requeridas

`listen`

El bloque listen controla dónde sirve la puerta de enlace: la dirección de enlace y el puerto, el origen visible externamente, y la terminación TLS opcional.

Campo	Requerido	Descripción
`host`	No	Dirección de enlace. Por defecto `0.0.0.0`.
`port`	No	Puerto de enlace. Por defecto `8080`.
`public_url`	A menos que `host` sea loopback	El origen `https://` visible externamente, utilizado para construir el `redirect_uri` del IdP y los metadatos de descubrimiento. Requerido siempre que `host` no sea una dirección loopback, ya sea que TLS termine en un proxy como ALB, Ingress o Cloud Run o en la puerta de enlace misma a través de `tls`, porque la puerta de enlace nunca deriva su propio origen de los encabezados `X-Forwarded-*`; son falsificables por el cliente. El arranque falla sin él. `trusted_proxies` a continuación rige solo la resolución de IP del cliente. También es requerido para habilitar telemetría, porque la puerta de enlace construye el punto final OTLP que envía a los clientes a partir de esta URL.
`tls.cert` / `tls.key`	No	Rutas PEM si la puerta de enlace termina TLS por sí misma
`trusted_proxies`	No	CIDRs o IPs de equilibradores de carga frente a la puerta de enlace. Cuando se establece, la puerta de enlace confía en `X-Forwarded-For` solo desde estos pares y registra la IP del cliente real para limitación de velocidad por IP y auditoría. Equivalente a `set_real_ip_from` de nginx. Las entradas `X-Forwarded-For` escritas como `ipv4:port` o `[ipv6]:port`, como hacen algunos equilibradores de carga, se leen con el puerto eliminado. Una dirección IPv6 con un puerto añadido y sin corchetes puede leerse como una dirección diferente o no leerse en absoluto, así que desactive la opción de puerto en cualquier proxy que escriba esa forma.

`oidc`

El bloque oidc conecta la puerta de enlace a su proveedor de identidad y decide quién puede iniciar sesión. Nombra el emisor y el cliente OAuth, asigna las reclamaciones que llevan correo electrónico y grupos, y restringe el inicio de sesión por dominio de correo electrónico o grupo.

OpenID Connect (OIDC) es el protocolo SSO que la puerta de enlace utiliza con su proveedor de identidad; consulte Configuración del proveedor de identidad para saber qué registrar en el lado del IdP.

Campo	Requerido	Descripción
`issuer`	Sí	Base de descubrimiento OIDC. Debe servir el descubrimiento en `/.well-known/openid-configuration`. Use HTTPS en producción; la puerta de enlace acepta un emisor `http://`. Un emisor loopback como `http://localhost:8081` es rechazado por la protección SSRF a menos que `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` esté establecido en el entorno de la puerta de enlace.
`client_id` / `client_secret`	Sí	De su registro de cliente OAuth
`allowed_email_domains`	No	Rechace id_tokens cuya reclamación `email` no esté en uno de estos dominios, sin distinción de mayúsculas y minúsculas. Defensa en profundidad contra configuración errónea del IdP multiinquilino. Independientemente de esta configuración, un id_token cuya reclamación `email_verified` es explícitamente `false` siempre se rechaza.
`allowed_groups`	No	Restrinja el inicio de sesión a miembros de estos grupos del IdP, comparados contra `groups_claim`. Un usuario en un dominio de correo electrónico permitido pero en ninguno de estos grupos es rechazado. Requiere que el IdP emita la reclamación de grupos. La coincidencia es una comparación de cadena exacta y sensible a mayúsculas y minúsculas contra los valores en esa reclamación, y la puerta de enlace no expande grupos anidados: para admitir miembros de un subgrupo, enumere el subgrupo aquí o configure el IdP para emitir membresía aplanada.
`groups_claim`	No	Qué reclamación id_token lleva la membresía del grupo. Por defecto `groups`. Microsoft Entra emite roles de aplicación bajo `roles`. Acepta una clave plana o un Puntero JSON RFC 6901 como `/resource_access/gateway/roles` para reclamaciones anidadas.
`google_groups`	No	Busque los grupos del usuario que inició sesión a través de la API del Directorio del SDK de administración de Google Workspace, porque el id_token de Google no lleva reclamación de grupos. Establezca `service_account_json_path` en un archivo de clave de cuenta de servicio con delegación en todo el dominio en el alcance `https://www.googleapis.com/auth/admin.directory.group.readonly`, y `admin_email` en un administrador de Workspace que la cuenta de servicio suplanta; la API del Directorio requiere un asunto administrador real. Las direcciones de correo electrónico del grupo de cada usuario se convierten en su reclamación de grupos, así que `allowed_groups` y `managed.policies.match.groups` coinciden en correos electrónicos de grupo.
`email_claim`	No	Qué reclamación id_token lleva el correo electrónico del usuario. Por defecto `email`. Algunos IdPs, como ADFS y Entra B2C, emiten `upn` o `preferred_username` en su lugar. Acepta una clave plana, un Puntero JSON, o una lista de claves de respaldo donde se utiliza la primera clave presente.
`scopes`	No	Anulación completa de los alcances OIDC que solicita la puerta de enlace. Por defecto `[openid, profile, email, offline_access]`. Establezca cuando su IdP rechace alcances que no reconoce, o requiera un alcance personalizado para emitir grupos o correo electrónico. Debe incluir `openid`. Eliminar `offline_access` desactiva los tokens de actualización, por lo que los desarrolladores vuelven a ejecutar el inicio de sesión del navegador cada `session.ttl_hours`. Consulte Configuración del proveedor de identidad para recetas de alcance por IdP como el flujo de token de actualización de Google.
`scope_on_refresh`	No	También envíe `scope`, con la misma lista que la solicitud de inicio de sesión, cuando la puerta de enlace intercambia un token de actualización. Por defecto `false`: la solicitud de actualización omite `scope`. La mayoría de los IdPs devuelven un id_token en cada actualización y no necesitan esto. Establezca `true` cuando su IdP devuelve un id_token en la actualización solo si se solicita `openid` nuevamente, que Okta documenta para su concesión de actualización. Sin un id_token, cada actualización depende del punto final de userinfo del IdP que acepta el token de acceso actualizado. Si controla el inicio de sesión o las políticas de coincidencia en grupos y el id_token del IdP en tiempo de actualización los omite, también establezca `userinfo_fallback: true` para que la puerta de enlace los complete desde el punto final de userinfo. Un IdP que otorgó menos alcances de los solicitados puede rechazar la actualización con `invalid_scope`, incluso para sesiones existentes si agrega entradas a `scopes` mientras esto está activado. Desestablezca la clave si las actualizaciones comienzan a fallar en `token_endpoint` después de establecerla. Requiere Claude Code v2.1.260 o posterior en el servidor de la puerta de enlace.
`extra_auth_params`	No	Parámetros de consulta adicionales añadidos a la solicitud de autorización del IdP, textualmente. Este es el mecanismo de anulación para comportamiento específico del IdP, como `access_type: offline` para tokens de actualización de Google, `domain_hint` para algunos inquilinos de Entra, o `acr_values` para flujos de escalada. No puede anular los parámetros de protocolo gestionados por la puerta de enlace: `state`, `nonce`, `redirect_uri`, PKCE, `scope`, `response_type`, `response_mode`, y `client_id`.
`userinfo_fallback`	No	Cuando el id_token omite correo electrónico o grupos, búsquelos en `/userinfo`. Necesario para tokens de acceso ligeros de Keycloak, el servidor org de Okta, y tokens mínimos de ADFS. El id_token sigue siendo autoritario; userinfo solo llena vacíos. Por defecto `false`.
`use_pkce`	No	Envíe un desafío PKCE (S256) en la solicitud de autorización. Por defecto `true`. Establezca `false` solo si su IdP rechaza PKCE para este cliente confidencial.
`clock_skew_seconds`	No	Tolere la desviación del reloj al validar reclamaciones de tiempo id_token. Por defecto `0`, que es estricto. Aumente si ve errores "token expirado / aún no válido" justo después del inicio de sesión debido a desviación del reloj del host/IdP.
`token_endpoint_auth_method`	No	Anule el método de autenticación del punto final del token. Acepta `client_secret_basic` o `client_secret_post`. Negociado automáticamente por defecto.
`id_token_signed_response_alg`	No	Algoritmo de firma id_token esperado. Por defecto `RS256`. Establezca para IdPs que firman con ES256, PS256, o EdDSA.
`additional_authorized_parties`	No	Valores `azp` adicionales para aceptar más allá de `client_id`, para flujos de intermediario de Keycloak e intercambio de tokens
`discovery_url`	No	Busque el documento de descubrimiento desde esta URL en lugar de derivarlo de `issuer`, para IdPs detrás de un proxy que reescribe el host del emisor. La ruta debe contener `/.well-known/`.
`use_proxy`	No	Envíe las propias solicitudes del IdP de la puerta de enlace a través del proxy directo en `HTTPS_PROXY` o `HTTP_PROXY`, respetando `NO_PROXY`. `false` mantiene esas solicitudes directas. Requiere v2.1.227 o posterior; consulte Solicitudes del IdP a través de un proxy directo a continuación.
`form_action_origins`	No	Orígenes adicionales para la directiva `Content-Security-Policy: form-action` de la página `/device`. La puerta de enlace ya permite `'self'` y el origen `authorization_endpoint` descubierto, pero Chrome aplica `form-action` contra toda la cadena de redirección. Si su IdP redirige a través de un segundo host, como Azure AD federado a ADFS, Okta de concentrador y radio, o un interceptor SSO corporativo, enumere cada origen por el que la solicitud de autorización puede redirigir.
`ca_cert_pem`	No	El certificado CA codificado en PEM en sí, no una ruta a un archivo. Reemplaza el almacén de confianza del sistema solo para solicitudes del IdP. Para cargar un archivo montado, escriba `${file:/etc/gateway/idp-ca.pem}`. Úselo para Keycloak o Dex detrás de PKI corporativa.

Solicitudes del IdP a través de un proxy directo

Los upstreams de inferencia respetan HTTPS_PROXY e HTTP_PROXY en cada versión. Las propias solicitudes de la puerta de enlace al IdP, descubrimiento, JWKS, token y userinfo, van directas a menos que establezca oidc.use_proxy: true, que requiere v2.1.227 o posterior. Cuando se establece una variable de proxy, use_proxy no se establece, y el emisor no está cubierto por NO_PROXY, la puerta de enlace mantiene esas solicitudes directas y registra un aviso al arranque pidiéndole que elija; use_proxy: false las mantiene directas y silencia el aviso.

Con use_proxy: true, el pod resuelve el nombre de host de cada punto final del IdP por sí mismo y pide al proxy que CONNECT a la dirección IP resuelta, por lo que el proxy debe aceptar CONNECT a la dirección IP de cada host que el documento de descubrimiento nombra, no solo el emisor. Use una URL de proxy http://. ca_cert_pem y la protección SSRF se aplican en la ruta proxificada también.

Solo egreso de proxy cambia ambos: mientras está activo, las solicitudes del IdP siguen el proxy a menos que establezca use_proxy: false, y la puerta de enlace entrega al proxy cada nombre de host del IdP sin resolverlo primero.

Solo egreso de proxy

Establezca CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1 en el entorno de la puerta de enlace, junto a HTTPS_PROXY, cuando el pod alcanza otros hosts solo a través de ese proxy directo y no puede resolver nombres DNS públicos por sí mismo, o cuando el proxy rechaza CONNECT a una dirección IP. Requiere v2.1.277 o posterior. Es una variable de entorno en lugar de una clave gateway.yaml para que nada en el archivo de configuración pueda relajar la verificación de dirección de la puerta de enlace.

export HTTPS_PROXY=http://proxy.corp.example.com:3128
export NO_PROXY=
export no_proxy=
export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1

La puerta de enlace registra una línea network: al arranque mientras el egreso solo de proxy está activo.

Cada fila a continuación es una clase de solicitud saliente en una puerta de enlace con HTTPS_PROXY establecido, por defecto y mientras el egreso solo de proxy está activo.

Solicitud saliente	Por defecto	Egreso solo de proxy activo
Upstreams `provider: anthropic`, intercambio de tokens de Workload Identity Federation, exportaciones `telemetry.forward_to`	Resuelto y verificado localmente, luego `CONNECT` a la dirección IP verificada a través del proxy. Un recopilador de telemetría listado en `NO_PROXY` se alcanza directamente en su lugar	Nombre de host entregado al proxy
Descubrimiento del IdP, JWKS, token y userinfo	Directo a menos que `oidc.use_proxy: true`, luego `CONNECT` a la dirección IP verificada	Nombre de host entregado al proxy, a menos que `oidc.use_proxy: false` mantenga un IdP interno directo
Upstreams de Amazon Bedrock, Claude Platform en AWS, Agent Platform de Google Cloud, y Foundry de Microsoft; búsquedas de grupos de Google	Nombre de host entregado al proxy	Sin cambios

El egreso solo de proxy se mantiene desactivado a menos que el entorno de la puerta de enlace cumpla con las tres condiciones siguientes:

HTTPS_PROXY o HTTP_PROXY está establecido.
NO_PROXY y no_proxy están vacíos. Si su plataforma inyecta cualquiera en pods, establezca ambos en un valor vacío en el contenedor de la puerta de enlace. Listar un recopilador de telemetría en NO_PROXY mantiene el egreso solo de proxy desactivado.
CLAUDE_GATEWAY_ALLOW_LOOPBACK no está activado. Un recopilador o IdP en el propio loopback del pod no se puede combinar con egreso solo de proxy, porque una dirección loopback entregada al proxy sería la del propio host del proxy, así que dé a esos servicios una dirección que el proxy pueda alcanzar en su lugar. Por la misma razón, la puerta de enlace rechaza nombres de estilo localhost directamente mientras el egreso solo de proxy está activo.

Cuando una de esas condiciones no se cumple, la puerta de enlace registra una advertencia al arranque nombrando la variable que lo detuvo y mantiene el comportamiento por defecto.

Una vez que el egreso solo de proxy está activo, permita cada destino en el proxy, incluyendo un recopilador interno y cualquier host configurado por dirección IP. Aún puede mantener un IdP interno directo con oidc.use_proxy: false.

`session`

El bloque session forma los tokens portadores que la puerta de enlace acuña después del inicio de sesión: el secreto que los firma y cuánto tiempo viven.

Campo	Requerido	Descripción
`jwt_secret`	Sí	Al menos 32 bytes de entropía, por ejemplo de `openssl rand -base64 32`. Firma los tokens portadores HS256 de la puerta de enlace. Acepta una cadena única o una matriz para rotación: el índice 0 firma y todas las entradas verifican. Para rotar, anteponga un nuevo secreto, espere `ttl_hours`, luego elimine el antiguo.
`ttl_hours`	No	Vida útil del token portador de la puerta de enlace. Por defecto `1`. El CLI se actualiza silenciosamente antes de la expiración cuando el IdP emite tokens de actualización. Una vida útil más corta desprovisiona más rápido; una más larga hace menos viajes de ida y vuelta del IdP. Si su IdP no puede emitir tokens de actualización porque `offline_access` no está disponible, no hay actualización silenciosa, así que aumente esto a `8` o `12` para evitar enviar desarrolladores de vuelta al inicio de sesión del navegador cada hora.

`store`

El bloque store apunta la puerta de enlace a su base de datos PostgreSQL, que contiene concesiones de dispositivos y contadores de límite de velocidad.

Campo	Requerido	Descripción
`postgres_url`	Sí	URL `postgres://` o `postgresql://`. Requerido: el encuentro de concesión de dispositivos, donde la devolución del navegador escribe y el CLI de sondeo lee, necesita estado entre réplicas. La puerta de enlace ejecuta sus propias migraciones de esquema al arranque y en la actualización, por lo que el rol necesita derechos para crear y alterar tablas en el esquema de destino. Consulte Actualizaciones y Postgres.
`username`	No	Anula el usuario en `postgres_url`
`password`	No	Credencial de base de datos. Establézcala aquí en lugar de en `postgres_url` para que la credencial se mantenga fuera de la URL. Acepta cualquier carácter y tiene precedencia sobre las credenciales de URL.
`max_connections`	No	Tamaño del grupo de conexiones de Postgres por réplica. Por defecto `5`, que es conservador y amigable con bases de datos compartidas. Con límites de gasto habilitados, la ruta activa realiza algunas operaciones por solicitud de inferencia, así que auméntelo para una base de datos dedicada bajo carga, y mantenga réplicas × esto por debajo de `max_connections` de la base de datos.
`connect_timeout_seconds`	No	Segundos que la puerta de enlace espera cuando abre una conexión de Postgres. Un número entero de `1` a `60`, por defecto `5`. Auméntelo si los intentos de conexión agotan el tiempo de espera cuando comienza una nueva instancia de puerta de enlace. Requiere Claude Code v2.1.274 o posterior en el servidor de la puerta de enlace. Las versiones anteriores se niegan a iniciar cuando se establece la clave.
`readiness_grace_seconds`	No	Cuántos segundos `/readyz` sigue reportando listo después de que Postgres deja de responder. Un número entero de `0` a `3600`, por defecto `0`. Consulte Comportamiento de interrupción para saber cómo elegir un valor. Requiere Claude Code v2.1.282 o posterior en el servidor de la puerta de enlace. Las versiones anteriores se niegan a iniciar cuando se establece la clave.

Para desarrollo local, apunte postgres_url a un contenedor de Postgres desechable, por ejemplo docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres.

`upstreams`

upstreams es una lista ordenada. La puerta de enlace reenvía la inferencia al primer upstream que resuelve el modelo solicitado.

En 5xx, 429, 401, 403, 404, o tiempo de espera agotado, la puerta de enlace conmuta por error al siguiente upstream; otros 4xx no, porque esos errores son atribuibles a la solicitud en lugar del upstream. Un 401 o 403 significa que la credencial que la puerta de enlace utilizó contra ese upstream falló. Un 404 significa que ese upstream no sirve el modelo solicitado, por lo que un upstream posterior en la lista aún puede hacerlo.

Si establece forward_user_identity: true en un upstream, un 429 que devuelve a una solicitud que llevaba el correo electrónico del desarrollador no conmuta por error. Consulte cómo una denegación de límite por usuario llega al desarrollador.

La conmutación por error en 404 requiere la puerta de enlace v2.1.198 o posterior. Las versiones anteriores devolvieron el primer 404 al cliente incluso cuando un upstream posterior en la lista sirvió el modelo.

Múltiples upstreams del mismo proveedor deben establecer un name: distinto.

Los clientes de Amazon Bedrock, Claude Platform en AWS, Agent Platform de Google Cloud, y Foundry de Microsoft se construyen una vez al inicio, y sus SDKs actualizan credenciales internamente, por lo que rotar credenciales en la nube no requiere un reinicio. Las claves API estáticas de Anthropic y los portadores se leen al inicio; consulte API de Anthropic.

Mensajes de error de upstream

La puerta de enlace devuelve la respuesta de error de un upstream, o su propio 502, dependiendo de cómo respondieron los upstreams:

Un upstream devolvió un estado en el que la puerta de enlace no conmuta por error: esa respuesta del upstream. La puerta de enlace no intenta más upstreams.
Cada upstream que la puerta de enlace intentó falló de una manera en la que conmuta por error: el último 429. Cuando ninguno devolvió un 429, la puerta de enlace prefiere, en orden, el último 401 o 403, el último 404, y el último 501. Cuando ninguno devolvió ninguno de esos, el propio 502 de la puerta de enlace, all upstreams failed (N attempted), donde N cuenta cada entrada en upstreams, incluyendo entradas que la puerta de enlace omitió porque no sirven el modelo solicitado.

Cuando la puerta de enlace devuelve la respuesta de un upstream, mantiene el código de estado del upstream. Si mantiene el mensaje del upstream depende del proveedor. El cuerpo de error de un upstream de API de Anthropic llega al desarrollador sin cambios.

Los upstreams de Amazon Bedrock, Claude Platform en AWS, Agent Platform de Google Cloud, y Foundry de Microsoft pueden nombrar sus IDs de cuenta, ARNs de rol, e IDs de proyecto en su texto de error. La puerta de enlace registra ese texto completo en el registro operacional. Lo que el desarrollador ve de esos upstreams depende del rechazo:

400 o 413 en el sobre de error estándar de Anthropic: el mensaje del upstream, como prompt is too long. Claude Platform en AWS, Agent Platform, y Foundry de Microsoft devuelven este sobre para rechazos de API de modelo.
400 o 413 en la forma propia del proveedor: un token capability_rejected:. Cuando la puerta de enlace no puede clasificar el rechazo, upstream rejected the request en un 400 o request too large for this upstream en un 413.
Cualquier otro estado: copia genérica por estado, como upstream rate limit exceeded en un 429.

Por ejemplo, la puerta de enlace reemplaza Input is too long for requested model. de Amazon Bedrock con capability_rejected: prompt_too_long. Claude Code compacta automáticamente en ese token, como lo hace en prompt is too long.

Mantener el mensaje 400 o 413 de un upstream en la nube, o reemplazarlo con un token capability_rejected:, requiere la puerta de enlace v2.1.233 o posterior.

API de Anthropic

El upstream mínimo de Anthropic es una clave API de la Consola de Claude:

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}
    # O un portador OAuth (p. ej. un token intercambiado por Workload-Identity-Federation):
    #   oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
    # base_url: https://api.anthropic.com   # por defecto; anule para un proxy directo

Las dos formas de credencial difieren en el encabezado que envían:

api_key: envía x-api-key. Rótela en la Consola de Claude y actualice la variable de entorno.
oauth_token: envía Authorization: Bearer. Use la forma de portador cuando su organización emite tokens de corta duración en lugar de claves API de larga duración. El portador se lee una vez al inicio, así que actualice remontando el secreto e reiniciando.

En lugar de una clave estática o portador, puede usar Workload Identity Federation. Cree una regla de federación siguiendo la guía de Workload Identity Federation, luego monte su JWT de OIDC de carga de trabajo como un archivo, como un token de cuenta de servicio proyectado de Kubernetes o un id-token de plataforma de CI. La puerta de enlace intercambia el JWT por un portador de corta duración y lo actualiza automáticamente. El archivo de token se relee en cada intercambio, por lo que los tokens proyectados rotados se recogen sin un reinicio.

upstreams:
  - provider: anthropic
    auth:
      federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
      organization_id: ${ANTHROPIC_ORGANIZATION_ID}
      identity_token_file: /var/run/secrets/anthropic/id-token
      # workspace_id: wrkspc_...       # requerido si la regla cubre >1 espacio de trabajo
      # service_account_id: svac_...   # verificación de destino esperado opcional

Encabezados de identidad por usuario para un proxy que ejecuta

Puede apuntar el base_url de un upstream provider: anthropic a un proxy que ejecuta en lugar de a la API de Anthropic. Para decirle a ese proxy qué desarrollador envió cada solicitud, establezca forward_user_identity: true en ese upstream. El proxy puede entonces atribuir gasto por desarrollador. Requiere una puerta de enlace que ejecute Claude Code v2.1.233 o posterior.

Por ejemplo, para un proxy en upstream-gateway.internal.example.com:

upstreams:
  - provider: anthropic
    base_url: https://upstream-gateway.internal.example.com
    auth:
      api_key: ${PROXY_KEY}
    forward_user_identity: true        # por defecto false

La puerta de enlace añade estos encabezados a cada solicitud que reenvía a ese upstream.

Encabezado	Valor
`x-litellm-end-user-id`	El correo electrónico del desarrollador, cuando el IdP proporcionó uno.
`x-claude-gateway-user-id`	El asunto del IdP del desarrollador, de la reclamación `sub` del token.
`x-claude-gateway-user-email`	El correo electrónico del desarrollador, cuando el IdP proporcionó uno.

Cuando el token del IdP no lleva correo electrónico, la puerta de enlace envía solo x-claude-gateway-user-id y omite los dos encabezados de correo electrónico. Si su IdP pone el correo electrónico en una reclamación diferente, establezca oidc.email_claim en esa reclamación.

Cuando su proxy responde 429 a una solicitud que llevaba el correo electrónico del desarrollador, la puerta de enlace devuelve esa respuesta al desarrollador tal como está en lugar de conmutar por error al siguiente upstream, por lo que el presupuesto por usuario o límite de velocidad de su proxy se mantiene. Las otras respuestas del proxy siguen las reglas de conmutación por error ordinarias. Si el token del IdP de un desarrollador no lleva correo electrónico, la puerta de enlace reenvía sus solicitudes sin los encabezados de correo electrónico, por lo que un 429 a una de esas solicitudes cuenta como capacidad de upstream y conmuta por error. Antes de v2.1.267 en el servidor de la puerta de enlace, cada 429 conmutaba por error.

Establezca forward_user_identity solo en un upstream cuyo base_url sea un proxy que opera. La puerta de enlace envía correos electrónicos de desarrollador a cualquier servidor que ese base_url nombre. Si el base_url es la API de Anthropic, que es el por defecto, la puerta de enlace se niega a iniciar.

Amazon Bedrock

Para la implementación de Amazon Bedrock del lado del cliente que la puerta de enlace reemplaza o fronts, consulte Claude Code en Amazon Bedrock. El upstream del lado de la puerta de enlace:

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # preferido: cadena de credencial por defecto de AWS
    # O credenciales explícitas:
    # auth:
    #   aws_access_key_id: ${AWS_AKID}
    #   aws_secret_access_key: ${AWS_SK}
    #   aws_session_token: ${AWS_ST}
    # O un token portador de API de Bedrock:
    # auth:
    #   aws_bearer_token: ${AWS_BEARER_TOKEN}
    # Anule el punto final de bedrock-runtime para implementaciones FIPS o de punto final de VPC:
    # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

Un bloque auth vacío usa la cadena de credencial por defecto del SDK de AWS: variables de entorno, ~/.aws/credentials, rol de tarea de ECS, metadatos de instancia de EC2, o IRSA en EKS. En producción, dé al pod de la puerta de enlace un rol de IAM en lugar de incrustar claves estáticas en una imagen de contenedor.

Las credenciales explícitas deben ser completas: la puerta de enlace falla al arranque cuando aws_access_key_id y aws_secret_access_key no se establecen juntos, o cuando aws_session_token se establece sin ellos. Antes de v2.1.207, un bloque auth: parcial pasó la validación.

Configuración	Cómo
Permisos de IAM	Otorgue al principal de la puerta de enlace `bedrock:InvokeModel` y `bedrock:InvokeModelWithResponseStream` en los ARNs de perfil de inferencia y los ARNs de modelo de fundación subyacentes. Para el catálogo integrado en regiones de EE.UU.: `arn:aws:bedrock:<region>:<account>:inference-profile/us.anthropic.` y `arn:aws:bedrock:::foundation-model/anthropic.*`. También otorgue `bedrock:CountTokens` en los ARNs de modelo de fundación. La puerta de enlace lo usa, sin cargo, para contar los tokens de entrada de una solicitud que el cliente abandonó, por lo que límites de gasto se mantienen precisos. Sin él, la puerta de enlace vuelve a una solicitud de Bedrock de un token para ese conteo.
Acceso a modelo	Amazon Bedrock habilita el acceso a modelo por defecto en regiones comerciales. La puerta de enlace de nivel de cuenta restante es la de Anthropic: si nadie en su cuenta de AWS la ha enviado, abra la consola de Amazon Bedrock, seleccione un modelo de Anthropic del catálogo de modelos, y complete el formulario. Consulte Enviar detalles de caso de uso para el formulario de AWS Organizations y los permisos que el remitente necesita.
EKS (IRSA)	Cree un rol de IAM con la política anterior y una política de confianza para el proveedor de OIDC de su clúster limitado a la cuenta de servicio de la puerta de enlace. Anote la cuenta de servicio con `eks.amazonaws.com/role-arn: arn:aws:iam::<acct>:role/claude-gateway`. `auth: {}` la recoge.
ECS / EC2	Adjunte el rol de IAM a la definición de tarea o perfil de instancia. `auth: {}` la recoge.
En cualquier otro lugar	Pase credenciales a través de las variables de entorno `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, y `AWS_SESSION_TOKEN`, o establézcalas explícitamente en `auth:` con expansión `${VAR}`
Región	`region:` es la región del punto final de API. Los perfiles de inferencia entre regiones se enrutan a través de la geografía (EE.UU., UE, APAC) independientemente de cuál elija. Para regiones no estadounidenses o ARNs de rendimiento aprovisionado, agregue un bloque `models:` con los IDs correctos por upstream.

Aplicar una protección de Amazon Bedrock

Para aplicar una protección de Amazon Bedrock a cada solicitud de inferencia que la puerta de enlace envía a través de un upstream de Bedrock, agregue un bloque guardrail a ese upstream. Requiere Claude Code v2.1.281 o posterior en el servidor de la puerta de enlace.

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123                    # ID de protección o ARN completo
      version: "1"                     # un número de versión publicada, o DRAFT
 # mantenga las comillas: un 1 desnudo falla al arranque

También otorgue bedrock:ApplyGuardrail en la protección al principal que firma las solicitudes de este upstream: el principal de AWS de la puerta de enlace, o con assume_role el rol nombrado en role_arn.

Establezca guardrail en cada upstream bedrock o en ninguno. La puerta de enlace se niega a iniciar en una mezcla, porque conmutación por error podría enviar una solicitud a un upstream de Bedrock que no tiene protección.

La protección cubre solo upstreams de Bedrock. Si enumera otro proveedor en upstreams, la puerta de enlace envía solicitudes a ese proveedor sin la protección.

Cuando una solicitud /v1/messages cuyo cuerpo lleva un campo amazon-bedrock-*, como amazon-bedrock-guardrailConfig, llega a un upstream de Bedrock que tiene guardrail establecido, la puerta de enlace responde 400 en lugar de reenviarlo.

Bedrock en otra cuenta de AWS

Establezca assume_role en un upstream de Bedrock y la puerta de enlace usa su propia identidad de AWS solo para llamar a sts:AssumeRole en un rol que nombre, que puede estar en una cuenta de AWS diferente de la puerta de enlace. Cada solicitud de Bedrock de ese upstream se firma con las credenciales de una hora que STS devuelve, por lo que ninguna clave de acceso de larga duración cruza cuentas.

Requiere una puerta de enlace que ejecute Claude Code v2.1.281 o posterior. Una puerta de enlace anterior se niega a iniciar cuando encuentra la clave.

upstreams:
  - name: bedrock-isolated
    provider: bedrock
    region: us-east-1
    auth: {}                           # el rol propio de la puerta de enlace: solo llama a STS
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
      # external_id: ${BEDROCK_ROLE_EXTERNAL_ID}   # cuando la política de confianza del rol lo requiere

El bloque assume_role toma tres claves:

Clave	Significado
`role_arn`	El rol de IAM que la puerta de enlace asume, como un ARN `arn:aws:iam::` o `arn:aws-us-gov:iam::`. Dé los permisos de Bedrock que este upstream necesita, `bedrock:CountTokens` incluido, más `bedrock:ApplyGuardrail` cuando el upstream establece `guardrail`.
`external_id`	Opcional. Enviado como el ID externo en cada llamada `sts:AssumeRole`. Establézcalo cuando la política de confianza del rol lo requiera, y cítelo si son todos dígitos.
`session_name`	Opcional. `email` o `sub` da a cada desarrollador su propia sesión: consulte Atribución de costo de AWS por desarrollador. Sin establecer, cada solicitud usa una sesión nombrada `claude-apps-gateway`.

La política de confianza del rol nombra el principal propio de la puerta de enlace, como su IRSA o rol de tarea de ECS. Ese principal necesita sts:AssumeRole en el rol y ningún permiso de Bedrock por sí mismo. Elimine la Condition si no establece external_id.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::111111111111:role/claude-gateway" },
    "Action": "sts:AssumeRole",
    "Condition": { "StringEquals": { "sts:ExternalId": "your-external-id" } }
  }]
}

Si STS rechaza o es inaccesible, la puerta de enlace no envía la solicitud con las credenciales propias del upstream. Registra el error de STS con qué verificar, luego intenta el siguiente upstream que enumeró. Mensajes de error de upstream cubre lo que el cliente recibe cuando ningún upstream tiene éxito. Un upstream posterior sin assume_role serviría la solicitud con sus propias credenciales, así que enumere uno solo si eso es lo que desea.
La puerta de enlace llama al punto final de STS regional sts.<region>.amazonaws.com, que su red debe alcanzar. Para el punto final de FIPS, establezca AWS_USE_FIPS_ENDPOINT=true en el entorno de la puerta de enlace en lugar de use_fips_endpoint en un archivo de configuración de AWS.
assume_role se aplica solo a provider: bedrock y necesita credenciales de origen de SigV4: la puerta de enlace se niega a iniciar cuando se establece junto a aws_bearer_token.
Cada desarrollador que la puerta de enlace admite puede usar este upstream; managed rige qué desarrolladores pueden usar qué modelos. Para mantener un modelo servido a través del rol de también ser servido desde otra cuenta, dé un ID personalizado cuyo mapa upstream_model tiene solo el name de este upstream. Para tal ID, la puerta de enlace omite cada otro upstream, por lo que ni la solicitud ni el conteo de tokens para una solicitud abortada pueden conmutar por error a otra cuenta. Los nombres de modelo integrados aún se intentan en cada upstream en orden, este incluido, y una solicitud que lo alcanza se firma con el mismo rol, así que enumere este upstream último a menos que su cuenta también deba servirlos.

Este ejemplo da a un modelo un ID personalizado que solo el upstream aislado sirve:

models:
  - id: claude-opus-restricted          # un ID personalizado, no un nombre de modelo integrado
    upstream_model:
      bedrock-isolated: us.anthropic.claude-opus-4-8   # el único upstream que lo sirve

Atribución de costo de AWS por desarrollador

Por defecto, la puerta de enlace firma cada solicitud de Bedrock con una credencial, por lo que AWS ve todas las solicitudes de los desarrolladores bajo un único principal de IAM. Agregue session_name: email a assume_role y la puerta de enlace llama a sts:AssumeRole una vez por desarrollador por hora, con el nombre de sesión establecido en el correo electrónico de ese desarrollador, y firma sus solicitudes con las credenciales devueltas, por lo que las solicitudes de cada desarrollador llegan a AWS bajo su propia sesión de rol asumido. El rol puede estar en la cuenta propia de la puerta de enlace.

Requiere una puerta de enlace que ejecute Claude Code v2.1.281 o posterior. Atribución de costo en AWS cubre el rol de IAM y dónde la facturación de AWS muestra las sesiones.

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # el rol propio de la puerta de enlace: solo llama a STS
    assume_role:
      role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
      session_name: email              # o sub

session_name selecciona qué reclamación verificada se convierte en el RoleSessionName de AWS: email o sub. La puerta de enlace escribe cualquier carácter que no sea letras ASCII, dígitos, y _+,.@- como =XX hex por byte UTF-8, y acorta un resultado más largo que 64 caracteres a un prefijo más un hash, por lo que el nombre de sesión de cada desarrollador se mantiene válido y único. Una solicitud de un desarrollador cuyo token carece de la reclamación no se envía a través de este upstream, y el registro del operador dice cambiar a sub o establecer oidc.email_claim.

Un desarrollador activo cuesta una llamada de STS por hora por réplica de puerta de enlace, y las solicitudes de primer tiempo concurrentes comparten una llamada.

La puerta de enlace también hace una llamada de su propio en este rol: el conteo de tokens para una solicitud que el cliente abandonó, por lo que límites de gasto se mantienen precisos. Ese conteo y su solicitud de respaldo de un token se firman por la sesión compartida claude-apps-gateway, por lo que AWS atribuye el respaldo a claude-apps-gateway en lugar de al desarrollador.

Para atribución estricta por desarrollador, establezca assume_role con session_name en cada upstream de Bedrock que enumere. Un upstream sin él firma las solicitudes que sirve con sus propias credenciales.

Claude Platform en AWS

Claude Platform en AWS sirve la API de Anthropic de primera parte en infraestructura de AWS en aws-external-anthropic.<region>.api.aws. Usa IDs de modelo de primera parte, honra encabezados anthropic-beta tal como se envían, y sirve count_tokens, por lo que ninguna de la traducción específica de Bedrock se aplica. El proveedor anthropicAws requiere Claude Code v2.1.198 o posterior; las versiones anteriores de la puerta de enlace lo rechazan al arranque.

Para la implementación del lado del cliente de la misma plataforma, consulte Claude Code en Claude Platform en AWS. El upstream del lado de la puerta de enlace:

upstreams:
  - provider: anthropicAws
    region: us-east-1
    workspace_id: wrkspc_...
    auth:
      api_key: ${ANTHROPIC_AWS_API_KEY}   # enviado como x-api-key
    # O SigV4 a través de la cadena de credencial por defecto de AWS:
    # auth: {}
    # O credenciales de SigV4 explícitas:
    # auth:
    #   aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    #   aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    # Anule el punto final derivado:
    # base_url: https://aws-external-anthropic.us-east-1.api.aws

La plataforma se ejecuta en una cuenta de AWS separada de Amazon Bedrock y firma solicitudes de SigV4 para su propio nombre de servicio, aws-external-anthropic, por lo que un rol de IAM limitado a Bedrock no lo autoriza. Una clave API en auth.api_key tiene precedencia cuando las credenciales de SigV4 también se establecen. Un bloque auth vacío usa la cadena de credencial por defecto del SDK de AWS, la misma cadena que el upstream Amazon Bedrock usa.

Campo	Requerido	Descripción
`region`	Sí	Región de AWS, letras minúsculas, dígitos, y guiones. La puerta de enlace deriva el punto final de él como `https://aws-external-anthropic.<region>.api.aws`.
`workspace_id`	Sí	Enviado como un encabezado en cada solicitud; la plataforma lo requiere
`auth.api_key`	No	Clave API para la plataforma, enviada como `x-api-key`. No es un token portador: los dos modos de autenticación son una clave API o SigV4.
`auth.aws_access_key_id` / `auth.aws_secret_access_key`	No	Credenciales de SigV4 explícitas. Establecer una sin la otra falla al arranque. `auth.aws_session_token` se acepta junto a ellas.
`base_url`	No	Anule el punto final derivado

Porque la plataforma resuelve IDs de modelo de primera parte, el catálogo integrado se enruta a ella sin un bloque models:. Cuando cura una lista models:, clave la entrada anthropicAws: con el ID de primera parte.

Agent Platform de Google Cloud

Para la configuración equivalente del lado del cliente, consulte Claude Code en Google Cloud. El upstream del lado de la puerta de enlace:

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    auth: {}                           # preferido: Credenciales por defecto de aplicación
    # O un archivo de clave de cuenta de servicio:
    # auth: { service_account_json: /secrets/sa.json }
    # Anule el punto final de aiplatform para Conexión de servicio privada:
    # base_url: https://us-east5-aiplatform.p.googleapis.com

Un bloque auth vacío usa Credenciales por defecto de aplicación: GOOGLE_APPLICATION_CREDENTIALS, metadatos de GCE, o Workload Identity de GKE. Los archivos de clave JSON de cuenta de servicio se admiten pero se desaconsejan; use Workload Identity o adjunte una cuenta de servicio a la instancia de GCE o Cloud Run.

Establezca region: global para usar el punto final global para Agent Platform de Google Cloud en lugar de uno regional. Google entonces enruta cada solicitud a una región disponible, por lo que no rastrea disponibilidad de modelo por región. Establecer una región específica fija cada solicitud a ella.

Configuración	Cómo
Permisos de IAM	Otorgue a la cuenta de servicio de la puerta de enlace `roles/aiplatform.user` en el proyecto, o un rol personalizado con `aiplatform.endpoints.predict`. Habilite la API de Agent Platform de Google Cloud (`aiplatform.googleapis.com`).
Acceso a modelo	En Model Garden, habilite los modelos de Claude para su proyecto. Se publican en regiones específicas; verifique la tarjeta del modelo para regiones admitidas.
GKE (Workload Identity)	Vincule una cuenta de servicio de GCP a la cuenta de servicio de Kubernetes de la puerta de enlace y anote la KSA con `iam.gke.io/gcp-service-account: claude-gateway@<proj>.iam.gserviceaccount.com`. `auth: {}` la recoge.
Cloud Run / GCE	Establezca la cuenta de servicio del servicio en una con `roles/aiplatform.user`. `auth: {}` la recoge.
En cualquier otro lugar	`auth: { service_account_json: /secrets/sa.json }`, la ruta a un archivo de clave JSON montado como secreto. El campo toma una ruta de archivo, no el contenido de la clave, por lo que no hay expansión `${file:…}` involucrada.

Microsoft Foundry

Para la implementación de Microsoft Foundry del lado del cliente, consulte Claude Code en Microsoft Foundry. El upstream del lado de la puerta de enlace:

upstreams:
  - provider: foundry
    resource: example-foundry              # https://example-foundry.services.ai.azure.com
    auth: { use_azure_ad: true }        # preferido: DefaultAzureCredential / Identidad administrada
    # O una clave API:
    # auth:
    #   api_key: ${FOUNDRY_API_KEY}

use_azure_ad: true resuelve a través de DefaultAzureCredential: Identidad administrada en AKS, ACI, o App Service; la CLI de Azure; o credenciales de entorno. Las claves API funcionan pero son de todo el proyecto y no se rotan automáticamente. El punto final de Microsoft Foundry se deriva de resource:; establezca el base_url opcional para anularlo para nubes soberanas como Azure Government.

Configuración	Cómo
RBAC	Otorgue a la identidad de la puerta de enlace `Azure AI User` o `Cognitive Services User` en el recurso de Microsoft Foundry
Implementaciones	Microsoft Foundry usa nombres de implementación elegidos por administrador, no IDs de modelo canónicos. Agregue un bloque `models:` asignando cada ID canónico a su nombre de implementación.
AKS (workload identity)	Federe una Identidad administrada asignada por el usuario con el emisor de OIDC del clúster y vincúlela a la cuenta de servicio de la puerta de enlace. `use_azure_ad: true` la recoge a través de `WorkloadIdentityCredential`.
ACI / App Service	Habilite identidad administrada asignada por el sistema o por el usuario en el recurso. `use_azure_ad: true` la recoge.
En cualquier otro lugar	`auth: { api_key: "${FOUNDRY_API_KEY}" }`. Cite `${…}` dentro de `{ }`.

Encabezados estáticos en solicitudes de upstream

Para agregar encabezados fijos a las solicitudes que la puerta de enlace envía a un upstream, establezca headers: en ese upstream. Úselo cuando un proxy que ejecuta frente al proveedor enruta o atribuye tráfico por un encabezado.

headers: requiere Claude Code v2.1.277 o posterior en el servidor de la puerta de enlace. Una puerta de enlace anterior se niega a iniciar cuando encuentra la clave. Actualice cada réplica antes de agregar la clave, y elimine la clave antes de revertir a una versión anterior.

Los encabezados van al servidor que base_url nombra, o al punto final propio del proveedor cuando base_url no se establece. El proveedor también los recibe a menos que su proxy los elimine.

Este ejemplo alcanza un upstream provider: vertex a través de un proxy en upstream-proxy.internal.example.com. Establece el encabezado x-source que el proxy lee, y envía un token de la variable de entorno PROXY_TOKEN como x-proxy-token:

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    base_url: https://upstream-proxy.internal.example.com
    auth: {}
    headers:
      x-source: claude-apps-gateway
      x-proxy-token: ${PROXY_TOKEN}

Los valores son texto ASCII imprimible sin espacio en ninguno de los extremos. Cite un número, true, o false para que YAML lo lea como texto.

Para mantener un secreto fuera del archivo de configuración, use expansión de secreto para cargar el valor de una variable de entorno con ${VAR} o de un archivo con ${file:/path}. Un ${VAR} que se resuelve a un valor vacío detiene el inicio de la puerta de enlace.

headers: funciona en cada proveedor, y cada upstream envía solo el suyo.

No cada solicitud que la puerta de enlace envía a un upstream los lleva:

Solicitud que la puerta de enlace envía a este upstream	Lleva `headers:`
`/v1/messages`, streaming o no, y `/v1/messages/count_tokens`	Sí
Una solicitud que conmutó por error desde otro upstream	Sí, solo `headers:` de este upstream
Llamada `CountTokens` de Amazon Bedrock para una solicitud que el cliente abandonó	No
El intercambio de tokens de Workload Identity Federation	No

En un upstream de Amazon Bedrock o Claude Platform en AWS que firma solicitudes con AWS SigV4, estos encabezados son parte de la firma, por lo que su proxy debe pasarlos sin cambios.

Si usa un nombre que la puerta de enlace reserva, se niega a iniciar, y el error de inicio nombra el encabezado. Los nombres reservados incluyen:

authorization y x-api-key
host, content-type, y user-agent
Cualquier nombre que comience con anthropic-, x-goog-, x-amz-, o x-amzn-

Múltiples upstreams

El mismo proveedor puede aparecer más de una vez con un name: distinto. Esto cubre diferentes regiones, diferentes cuentas a través de diferentes cadenas de credenciales, rendimiento aprovisionado versus bajo demanda, y conmutación por error entre proveedores.

La puerta de enlace intenta upstreams en orden. 5xx, 429, 401, 403, 404, tiempos de espera agotados, y punto final faltante (501) conmutan por error; otros 4xx no.

429 es capacidad por upstream, por lo que el agotamiento de rendimiento aprovisionado (PT) conmuta por error a bajo demanda. Si establece forward_user_identity: true en un upstream, un 429 a una solicitud que llevaba el correo electrónico del desarrollador es una denegación por usuario en su lugar y no conmuta por error.

Cada solicitud comienza en el primer upstream. Una solicitud alcanza un upstream posterior solo cuando cada upstream delante de él ha fallado o no sirve el modelo solicitado.

La puerta de enlace no mantiene registro de upstreams fallidos, por lo que mientras un upstream está inactivo, cada solicitud que lo alcanza aún lo intenta y espera a que falle antes de pasar al siguiente.

Para un upstream de API de Anthropic, timeouts.upstream_ttfb_ms limita la espera en un upstream inactivo. Esa configuración no se aplica a los otros proveedores, donde la puerta de enlace espera hasta una hora a que un upstream comience a responder.

404 es disponibilidad de modelo por upstream, por lo que un upstream que no ha habilitado un modelo no bloquea un upstream posterior que lo sirve. Un upstream que no puede resolver el modelo solicitado se omite sin un viaje de ida y vuelta de red.

Este ejemplo enruta una asignación de rendimiento aprovisionado de Amazon Bedrock primero, desborda a bajo demanda y una segunda cuenta, y vuelve a la API de Anthropic último:

upstreams:
  # Primario: rendimiento aprovisionado en su región de inicio.
  - name: bedrock-pt
    provider: bedrock
    region: us-east-1
    auth: {}
  # Desbordamiento: bajo demanda entre regiones.
  - name: bedrock-od
    provider: bedrock
    region: us-west-2
    auth: {}
  # Cuenta diferente: una asignación de Bedrock separada a través de claves estáticas.
  - name: bedrock-acct2
    provider: bedrock
    region: us-east-1
    auth:
      aws_access_key_id: ${ACCT2_AKID}
      aws_secret_access_key: ${ACCT2_SK}
  # Último recurso: API de Anthropic directo.
  - name: anthropic-fallback
    provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

# Los IDs de modelo por upstream se clave en el `name:` del upstream.
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
      bedrock-od: us.anthropic.claude-opus-4-8
      bedrock-acct2: us.anthropic.claude-opus-4-8
      anthropic-fallback: claude-opus-4-8

Palanca	Cómo
Diferentes regiones	Un upstream de Amazon Bedrock por región, cada uno con su propio `region:`. Con `auto_include_builtin_models: true` los perfiles de inferencia entre regiones se enrutan automáticamente; para implementaciones fijas por región use un bloque `models:`.
Diferentes cuentas	Un upstream de Amazon Bedrock por cuenta. La cadena por defecto (`auth: {}`) usa la identidad del pod; para una segunda cuenta, agregue `assume_role` para alcanzarla con credenciales de corta duración, o establezca credenciales explícitas o un token portador en `auth:`.
Rendimiento aprovisionado	Asigne el modelo al ARN de rendimiento aprovisionado en `models:` para el `name` de ese upstream. Otros upstreams mantienen el ID bajo demanda, por lo que la capacidad de PT se agota antes de conmutar por error.
Puntos finales de VPC / FIPS	Establezca `base_url:` en el upstream a su URL de punto final de VPC o FIPS
Enrutamiento limitado a modelo	Solo un `id` de modelo personalizado, uno que no sea un nombre de modelo Claude integrado, omite los upstreams ausentes de su mapa `upstream_model:`. La puerta de enlace intenta modelos integrados en cada upstream en orden y usa el ID por defecto del proveedor donde el mapa no tiene entrada, por lo que para modelos integrados el mapa cambia qué ID un upstream recibe en lugar de si se intenta; un upstream que rechaza el ID sigue las mismas reglas de conmutación por error que cualquier otro error de upstream.

La conmutación por error entre proveedores en la nube, o a la API de Anthropic directo, cambia qué acuerdo, geografía, y otros términos rigen la solicitud.

El CLI aplica la misma puerta de características a puertas de enlace independientemente de qué upstream sirve una solicitud dada, por lo que la conmutación por error no envía un campo de cuerpo que un upstream rechazaría.

Secciones opcionales

`admin`

Opcional. Habilita /v1/organizations/spend_limits, que replica la Admin API pública de Anthropic, y la aplicación de límites de gasto por desarrollador en /v1/messages. Consulta Límites de gasto para saber cómo se establecen y aplican los límites; esta sección cubre las claves de gateway.yaml que activan la función y la ajustan.

admin:
  # Claves de API estáticas con nombre para los endpoints de administración, enviadas como x-api-key.
  # El id aparece en el registro de auditoría como admin-key:<id> para que cada clave sea
  # atribuible. Array para rotación: agrega la clave nueva, actualiza los clientes,
  # elimina la antigua.
  write_keys:
    - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
    - { id: ci,        key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
  read_keys:
    - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
  # Grupos de IdP con acceso completo de administrador mediante el JWT normal del gateway (sin clave de API).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits

Campo	Requerido	Descripción
`write_keys`	No	Array de `{id, key}`. Una `x-api-key` que coincida con una de estas puede listar, establecer y eliminar límites de gasto. Los valores de clave deben tener al menos 32 caracteres; los `id` deben ser únicos entre `read_keys` y `write_keys`.
`read_keys`	No	Array de `{id, key}`. De solo lectura: todos los endpoints `GET`, incluido listar límites, obtener uno por ID y leer `/effective` y `/audit`.
`admin_groups`	No	Nombres de grupos de IdP. Un JWT del gateway cuya reclamación `groups` incluya uno de estos tiene acceso completo de administrador, de lectura y escritura, y se audita como `oidc:<sub>`. Úsalo para administradores humanos; usa claves de API para máquinas. Una entrada vacía en esta lista detiene el gateway al arrancar. Consulta Valores de matcher que detienen el gateway al arrancar.
`blocked_message`	No	Se añade textualmente al `429 billing_error` que ve un desarrollador bloqueado. Escribe la instrucción completa, como una URL o un canal de Slack. Cuando no está establecido, el gateway envía solo el mensaje predeterminado. Consulta Cómo funciona la aplicación.
`audit_retention_days`	No	Predeterminado `365`. Las filas `admin_audit` más antiguas se eliminan.
`spend_retention_months`	No	Predeterminado `13`. Las filas del contador `spend` más antiguas que esto se eliminan. El valor predeterminado conserva un año completo más el mes parcial actual para informes interanuales.
`identity_retention_days`	No	Predeterminado `90`. TTL desde la última vez que se vio para las filas `principal_emails`, que contienen el correo electrónico, el nombre para mostrar y los grupos de cada desarrollador (PII). Es deliberadamente más corto que la retención de gastos para que una identidad desaprovisionada caduque mientras sus contadores de gasto anónimos permanecen.
`group_limit_mode`	No	`min` (predeterminado) o `max`. Cuando un desarrollador está en varios grupos con límites, `min` aplica el más restrictivo y `max` el menos restrictivo. Lo usan tanto la aplicación como `/effective`.

`enforcement`

El bloque enforcement controla cómo se comportan las comprobaciones de límites de gasto cuando el almacén no está disponible.

Campo	Requerido	Descripción
`fail_closed_on_error`	No	Predeterminado `false`. La aplicación de límites de gasto falla en abierto ante una interrupción de Postgres, por lo que la inferencia sigue disponible. Establece `true` para fallar en cerrado: los desarrolladores que superan el límite quedan bloqueados, pero también todos los demás si el almacén es inaccesible. Requiere un bloque `admin:`: la aplicación de límites de gasto solo se ejecuta cuando `admin` está configurado, y el gateway se niega a iniciar si estableces esto en `true` sin uno.

`pricing`

El bloque pricing le indica al medidor de gastos qué cobrar en lugar del precio de lista en USD, para que los límites y /effective reflejen tus tarifas contratadas. Los montos siguen en USD y siguen siendo una estimación, no una factura. Dos requisitos previos:

Claude Code v2.1.227 o posterior en el servidor del gateway. Las versiones anteriores rechazan la clave desconocida al arrancar.
Un bloque admin: o, en v2.1.268 o posterior, un bloque managed: con al menos una política. El gateway se niega a iniciar con pricing establecido y sin ninguno de los dos bloques, porque nada lo leería.

pricing:
  multiplier: 0.85
  overrides:
    - upstream: bedrock-eu
      model: claude-sonnet-4-6
      input: 3.30
      output: 16.50
      cache_read: 0.33
      cache_write: 4.125

Campo	Requerido	Descripción
`multiplier`	No	Predeterminado `1`. El medidor multiplica cada cantidad medida por este valor, ya sea con precio de lista o sobrescrita, por lo que `0.85` factura el 85% del precio. Debe ser mayor que 0 y como máximo 10, y un valor superior a 1 es un recargo.
`overrides`	No	Filas de `{upstream, model, input, output, cache_read, cache_write}` en USD por millón de tokens. Las cuatro tarifas son obligatorias. Cada una debe ser mayor que 0 y como máximo 10000.

Cómo el medidor hace coincidir una fila de sobrescritura:

Una fila reemplaza el precio de lista para las solicitudes que upstream, un upstreams[].name, atiende para model. Esto incluye la tarifa más alta del modo rápido, por lo que las solicitudes en modo rápido y estándar se miden con las mismas cuatro tarifas.
Un ID integrado como claude-sonnet-4-6, que se hace coincidir como models[].id, cubre todas las formas con fecha, las formas regionales de Amazon Bedrock o las formas de Agent Platform de Google Cloud que el medidor cotiza como ese modelo. Cualquier otra cadena, como un alias o un ARN de perfil de inferencia, coincide con el ID que envió el cliente o con la cadena enviada al upstream, sin distinguir mayúsculas de minúsculas.
Cuando las filas se superponen, el medidor elige la fila más específica en lugar de la primera: una fila cuyo model es la cadena de modelo exacta enviada al upstream, luego una fila que coincide con el ID exacto que envió el cliente y luego una fila que nombra el modelo integrado.
Un nombre de upstream desconocido hace fallar el arranque, y también dos filas para un mismo upstream que nombran el mismo modelo, incluidas dos formas de escribir un mismo modelo integrado. El gateway advierte al arrancar sobre una fila que ningún modelo solicitable puede usar.
Las solicitudes de búsqueda web se mantienen en el precio de lista de $0.01; el multiplicador sigue aplicándose a ellas.

Para tarifas por región, asigna a cada región su propio upstream con nombre y una fila por upstream.

Aplicar un recargo a los precios

Con v2.1.271 o posterior en el servidor del gateway, puedes establecer multiplier por encima de 1, hasta 10, para medir más de lo que cobra el proveedor, por ejemplo una tarifa interna de refacturación. Este ejemplo mide cada solicitud al 120% del precio:

pricing:
  multiplier: 1.2

Con un bloque admin:, el recargo también se aplica a los límites de gasto. El medidor cuenta el 120% del precio, por lo que los desarrolladores alcanzan sus límites antes. El gateway registra una advertencia al arrancar que lo indica.

El multiplicador no cambia lo que cobra el proveedor upstream por las solicitudes.

Si el gateway también envía las tarifas a los clientes con sesión iniciada, los desarrolladores necesitan Claude Code v2.1.271 o posterior para ver el recargo. Los clientes anteriores ignoran un multiplier superior a 1 y muestran los costos sin él.

Un servidor del gateway anterior a v2.1.271 se niega a iniciar si estableces un multiplier superior a 1.

Enviar las tarifas a los clientes con sesión iniciada

Con v2.1.268 o posterior en el servidor del gateway, el gateway también coloca las tarifas de pricing en las políticas managed que sirve, como el ajuste administrado modelPricing. Los desarrolladores que coinciden con una política ven entonces las tarifas de pricing del primer upstream que atiende cada ID de modelo en /usage, la línea de estado y OpenTelemetry. Un desarrollador que no coincide con ninguna política no recibe configuración administrada, por lo que sus cifras se mantienen en el precio de lista. Los clientes aplican el ajuste en Claude Code v2.1.242 o posterior.

Lo que agrega el gateway: a menos que el bloque cli de una política ya establezca modelPricing, el gateway agrega el multiplier y, para cada ID de modelo que un cliente puede solicitar, la fila de sobrescritura del primer upstream que atiende ese ID. Una tarifa que solo cobra un upstream de conmutación por error se queda en el gateway.
Excluir una política: establece modelPricing en {} en el bloque cli de esa política, y sus desarrolladores se mantienen en el precio de lista.
Conservar las tarifas propias de una política: una política cuyo bloque cli establece modelPricing con su propio multiplier u overrides conserva ese modelPricing completo, y el gateway no le agrega tarifas propias.

`models`

El bloque models es una lista de modelos opcional seleccionada por el administrador, servida en /v1/models y usada para traducir los ID de modelo por upstream. Es obligatoria para regiones de Amazon Bedrock fuera de EE. UU., ARN de rendimiento aprovisionado de Amazon Bedrock y nombres de despliegue de Microsoft Foundry.

auto_include_builtin_models: true   # false: exponer solo la lista de abajo
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    # description: texto opcional que se muestra en los clientes que lo muestran
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8   # o un ARN de perfil de inferencia
      foundry: your-opus-deployment-name

Cada clave bajo upstream_model debe coincidir con el name de un upstream configurado, que de forma predeterminada es el nombre del proveedor. Una clave que no coincide con ningún upstream hace fallar el arranque, así que omite las líneas de los proveedores que no uses.

`managed`

El bloque managed define políticas de acceso basadas en roles según grupos de IdP o dominio de correo electrónico. Las políticas se evalúan en orden; se selecciona la primera coincidencia y luego se fusiona sobre la base de captura general match: {}. Se sirven por usuario en GET /managed/settings con almacenamiento en caché ETag/304.

managed:
  policies:
    # Grupos específicos primero.
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    # Captura general predeterminada al final: coincide con todos los que se autenticaron.
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

Una captura general match: {}, que por convención se coloca al final, se trata como una capa base. Todas las demás políticas heredan de la captura general cualquier clave que no establezcan, por lo que las entradas por rol solo necesitan enumerar lo que difiere del valor predeterminado de la organización. Las reglas de fusión dependen del tipo de clave:

Listas de permitidos: availableModels y permissions.allow. La lista de una política específica reemplaza por completo la de la base.
Listas de denegación y arrays de hooks: permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces y cada array de tipo de evento de hooks. Estas toman la unión de la base y la política, por lo que una sobrescritura por rol no puede eliminar accidentalmente una denegación o un hook de auditoría de toda la organización.
Claves de tipo registro: env, modelOverrides y skillOverrides. Estas se fusionan superficialmente, por lo que un bloque env por rol sobrescribe las claves que establece y hereda el resto de la base.

availableModels también se aplica del lado del servidor en /v1/messages, por lo que un modelo denegado devuelve 400 independientemente de lo que envíe el cliente.

El gateway valida el propio valor de model antes de retransmitir una solicitud, por lo que un valor mal formado nunca llega a un upstream. Rechaza la solicitud con un 400 en dos casos:

Cuando el valor falta o está vacío, el gateway rechaza la solicitud con el mensaje model is required. Esa comprobación requiere un gateway que ejecute Claude Code v2.1.228 o posterior.
Cuando el valor está presente pero no es una cadena, el gateway rechaza la solicitud con el mensaje model must be a string. Requiere un gateway que ejecute Claude Code v2.1.221 o posterior.

Matcher	Comportamiento
`match: {}`	Coincide con todos los usuarios autenticados. Empieza con uno de estos y agrega más adelante políticas limitadas a grupos por encima de él.
`match: { groups: [a, b] }`	Coincide si la reclamación `groups` del JWT contiene alguno de los grupos enumerados. Distingue mayúsculas de minúsculas: los grupos deben coincidir con la capitalización exacta del IdP.
`match: { email_domain: example.com }`	Coincide con la parte posterior a la última `@` en la reclamación `email` del JWT, sin distinguir mayúsculas de minúsculas. Acepta un dominio por política.
`match: { groups: [a], email_domain: example.com }`	Ambas condiciones deben coincidir

Un usuario autenticado que no coincide con ninguna política obtiene los valores predeterminados del gateway, es decir, todos los modelos del catálogo y ninguna configuración administrada. Agrega una captura general match: {} al final si quieres una política predeterminada garantizada.

Note

El gateway no mantiene un directorio de usuarios propio. Autoriza cada solicitud a partir del token de IdP del usuario, leyendo la pertenencia a grupos de la reclamación groups del token y evaluando las políticas con ella. No hay una lista de usuarios que enumerar ni cuentas que crear previamente y, por lo tanto, no hay endpoint SCIM, porque no hay nada en lo que SCIM pueda sincronizar.

Gestiona el ciclo de vida de usuarios y grupos en la fuente de verdad, que es el aprovisionamiento SCIM nativo de tu IdP o una plataforma dedicada de gobernanza de identidades. La pertenencia y el desaprovisionamiento gestionados allí llegan al gateway automáticamente a través del token. Si quieres aprovisionamiento SCIM de las propias cuentas de Claude, esa es una capacidad de Claude for Enterprise.

Se aplican dos tiempos de propagación:

Contenido de las políticas: editar una política y volver a desplegar llega a los clientes conectados en su siguiente consulta de la configuración administrada, en menos de una hora, salvo los cambios que solo se aplican en el siguiente inicio
Pertenencia a grupos: cambiar la pertenencia a grupos de un usuario cambia qué política coincide con él. Esto surte efecto en la siguiente nueva emisión de la sesión, es decir, en la siguiente actualización silenciosa, con un límite de session.ttl_hours.

Valores de matcher que detienen el gateway al arrancar

Al arrancar, el gateway comprueba el bloque match de cada política y la lista admin_groups. Cualquiera de estos valores detiene el gateway con un error que nombra el campo:

Una lista groups vacía
Una entrada vacía en groups o en admin_groups
Un email_domain vacío
Un email_domain que contiene @, espacios en blanco o una coma. El gateway recorta el valor y elimina una @ inicial antes de esta comprobación. Escribe un solo dominio sin más, como example.com.

Antes de v2.1.232, el gateway arrancaba con estos valores. Cada valor tenía este efecto:

Un email_domain vacío: el gateway omitía la comprobación de dominio, por lo que una política con un email_domain vacío y sin lista groups coincidía con todos los usuarios autenticados
Una lista groups vacía: la política no coincidía con nadie
Un email_domain que contenía @, espacios en blanco o una coma: la política no coincidía con nadie
Una entrada vacía en groups o en admin_groups: la entrada coincidía con un usuario solo cuando la reclamación groups del IdP de ese usuario también contenía una entrada vacía. En admin_groups, esa coincidencia otorgaba acceso de administrador. Si tu lista admin_groups nunca contuvo una entrada vacía, nadie obtuvo acceso de administrador de esta manera.

Qué va en `cli`

Cada valor de cli es un documento managed-settings.json completo de Claude Code, el mismo esquema que desplegarías mediante MDM o /etc/claude-code/managed-settings.json, expresado aquí como YAML. El CLI aplica el documento entregado en el nivel administrado, por encima de la configuración de usuario y de proyecto, en lugar de la configuración administrada por el servidor. Por lo tanto, ignora los ajustes restringidos a fuentes de políticas a nivel del sistema operativo, como policyHelper y wslInheritsWindowsSettings.

El gateway valida cada documento con el esquema de configuración del CLI al arrancar, por lo que una clave de nivel superior no reconocida hace fallar el arranque con un error que nombra cada clave problemática. Las partes deliberadamente abiertas del esquema siguen aceptando valores arbitrarios, porque los clientes más nuevos pueden reconocer entradas que el esquema del gateway no reconoce. Estas claves abiertas incluyen env, pluginConfigs y las claves anidadas bajo permissions.

Como la validación usa el esquema incluido con la versión instalada del gateway, poner en la configuración administrada una clave de configuración de nivel superior introducida por una versión más reciente de Claude Code requiere actualizar primero el gateway. Haz una prueba rápida de una política nueva en un cliente antes de desplegarla.

La referencia completa de claves está en Configuración de Claude Code. Las claves que los operadores usan primero:

managed:
  policies:
    - match: {}
      cli:
        # Acceso a modelos (también aplicado del lado del servidor en /v1/messages)
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

        # Política de permisos
        permissions:
          deny:
            - "WebFetch"
            - "Read(./.env)"
            - "Read(./secrets/**)"
          disableBypassPermissionsMode: disable   # bloquea --dangerously-skip-permissions
        allowManagedPermissionRulesOnly: true     # ignora las reglas de permisos de usuario/proyecto

        # Entorno enviado al proceso del CLI. DISABLE_UPDATES bloquea
        # las actualizaciones en segundo plano y manuales; DISABLE_AUTOUPDATER detiene solo
        # las actualizaciones en segundo plano.
        env:
          DISABLE_UPDATES: "1"                    # fija las versiones mediante tu propia distribución

        # Hooks de toda la organización. Los comandos de hook se ejecutan en las máquinas de los desarrolladores, no en el
        # gateway, por lo que la ruta debe existir en cada sistema operativo cliente de la política.
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }

Clave	Aplicada por	Efecto
`availableModels`	Gateway + CLI	Lista de modelos permitidos. También se comprueba en `/v1/messages`, por lo que un cliente modificado no puede eludirla.
`permissions.allow` / `.deny`	CLI	Reglas de herramientas y comandos. Consulta Permisos.
`permissions.disableBypassPermissionsMode`	CLI	Establécelo en `disable` para bloquear `bypassPermissions`, el modo que omite las solicitudes de permiso, y el flag `--dangerously-skip-permissions`
`allowManagedPermissionRulesOnly`	CLI	Cuando es `true`, la configuración administrada pasa a ser la única fuente de configuración de reglas de permisos. La entrada `allowManagedPermissionRulesOnly` enumera todas las fuentes que Claude Code ignora entonces.
`env`	CLI	Variables de entorno combinadas en el proceso del CLI. Úsalas para telemetría, actualización automática y sobrescrituras de nombres de modelos.
`hooks`	CLI	Hooks de toda la organización
`managedMcpServers`	CLI	Servidores MCP remotos proporcionados a cada desarrollador que coincide junto con los servidores que agregan ellos mismos, solo `http` y `sse`. Consulta Servidores MCP en una política. Requiere Claude Code v2.1.259 o posterior en el servidor del gateway y en los clientes. Los clientes anteriores ignoran la clave.

Como estos ajustes llegan a través de la red, el CLI muestra a cada desarrollador un diálogo de aprobación de seguridad antes de aplicar los ajustes que se enumeran a continuación:

hooks
variables de env que requieren la aprobación del desarrollador, como las variables de proxy y de URL base
ajustes de ejecución de shell como apiKeyHelper y statusLine
los ajustes de binarios del sandbox sandbox.bwrapPath, sandbox.socatPath y sandbox.ripgrep
Ajustes del sandbox que interceptan tráfico, inyectan credenciales o debilitan el aislamiento, como sandbox.network.tlsTerminate y los ajustes de puerto del proxy. Diálogos de aprobación de seguridad los enumera todos.

Memoria de aprobación explica cuánto dura una aprobación y cuándo vuelve a aparecer el diálogo.

Claude Code aplica algunas variables de env entregadas sin mostrar al desarrollador el diálogo de aprobación, como los ajustes de selección de modelo y los límites numéricos. Otras variables entregadas pueden requerir la aprobación del desarrollador antes de surtir efecto; un valor no vacío de proxy, URL base u OTEL_EXPORTER_OTLP_ENDPOINT siempre la requiere. Cuando una variable entregada necesita aprobación, el diálogo la nombra.

Variables de entorno y el diálogo de aprobación tiene los detalles, incluidos cuatro interruptores de privacidad cuyo valor entregado decide si necesitan aprobación. Antes de v2.1.218, Claude Code aplicaba menos variables sin preguntar al desarrollador, por lo que más variables entregadas activaban el diálogo.

La configuración de telemetría del gateway envía OTEL_EXPORTER_OTLP_ENDPOINT, por lo que establecer telemetry.forward_to activa el diálogo en cada cliente interactivo. El diálogo protege la máquina del desarrollador frente a un gateway comprometido u hostil, no a la organización frente al desarrollador.

Una ejecución no interactiva, como claude -p o una sesión del Agent SDK, no puede mostrar el diálogo. Aplica los ajustes enviados solo para esa ejecución y no los registra como aprobados, por lo que la siguiente sesión interactiva del desarrollador sigue mostrando el diálogo. Antes de v2.1.207, una ejecución no interactiva guardaba los ajustes como aprobados y ninguna sesión interactiva posterior mostraba el diálogo para ellos.

Si un desarrollador rechaza, Claude Code cierra esa sesión en lugar de aplicar la política. Por lo tanto, cuando envías un hook nuevo, o cualquier variable de entorno que active el diálogo, a una política amplia, cada desarrollador que coincide ve el diálogo en sus sesiones interactivas. Una sesión interactiva en ejecución lo muestra en la siguiente consulta horaria y, de lo contrario, aparece en el siguiente inicio interactivo del desarrollador.

La clave cli se llamaba settings en versiones anteriores. Esa forma sigue aceptándose como alias, pero los despliegues nuevos deben usar cli.

Ventana de contexto en sesiones de terminal

Las sesiones de terminal iniciadas mediante /login usan la ventana de contexto de 1M para Opus 4.7 y posteriores, Sonnet 5 y posteriores, y los modelos Fable. El ID del modelo no necesita el sufijo [1m], y las sesiones se compactan en torno a 967K tokens. Antes de Claude Code v2.1.287 en la máquina del desarrollador, Claude Code trataba los modelos Opus y Fable como si tuvieran una ventana de 200K, a menos que el ID del modelo terminara en [1m].

Para que las sesiones de terminal se compacten en el límite de 200K, establece la ventana de compactación automática en el env de la política:

managed:
  policies:
    - match: {}
      cli:
        env:
          CLAUDE_CODE_AUTO_COMPACT_WINDOW: "200000"

Claude Code aplica esta variable sin mostrar al desarrollador el diálogo de aprobación. La variable se aplica a todos los modelos, incluidos los ID de modelo que terminan en [1m].

Para desactivar el contexto de 1M, establece CLAUDE_CODE_DISABLE_1M_CONTEXT: "1" en el mismo bloque env. Claude Code trata entonces todos los modelos como si tuvieran una ventana de 200K. En las sesiones interactivas, cada desarrollador aprueba esta variable en el diálogo de aprobación antes de que surta efecto.

Servidores MCP en una política

Para proporcionar servidores MCP a los clientes de Claude Code que coinciden con una política, establece managedMcpServers en el bloque cli de esa política. Necesitas Claude Code v2.1.259 o posterior en el servidor del gateway y en los clientes.

El gateway comprueba cada entrada al arrancar con las mismas reglas que Claude Code aplica en el cliente y, si una entrada no supera una comprobación, el gateway se niega a iniciar y nombra la entrada.

Si escribes una referencia ${VAR} en gateway.yaml, el gateway la resuelve desde su entorno al arrancar mediante la expansión de secretos antes de ejecutar las comprobaciones de entradas, por lo que cada cliente que coincide recibe el valor literal y puede leerlo. La orientación sobre encabezados para servidores proporcionados se aplica al valor expandido.

El gateway rechaza la forma mcpServers de .mcp.json en un bloque cli, y su error de arranque indica managedMcpServers como la clave que debes usar. Antes de v2.1.259, el gateway rechazaba cualquier definición de servidor MCP en un bloque cli.

Superposición de Claude Desktop

Si tu organización también despliega Claude Desktop, el mismo gateway atiende a ambos clientes. Apunta bootstrapUrl, en la configuración administrada de Claude Desktop, a <listen.public_url>/user/bootstrap. Claude Desktop deriva el emisor de OAuth de esa URL, ejecuta el mismo inicio de sesión con código de dispositivo contra este gateway y obtiene su configuración de la respuesta.

El gateway deriva gran parte de la respuesta del bloque cli de la política coincidente y de la configuración de nivel superior del gateway:

La lista de modelos, de availableModels. Contexto extendido en Claude Desktop explica la opción de contexto de 1M de cada modelo
Las herramientas deshabilitadas, de las entradas de permissions.deny que son solo un nombre de herramienta. Si estableces disabledBuiltinTools en el bloque desktop de la política, el gateway sirve la unión de tu valor y la lista derivada, por lo que puedes deshabilitar más herramientas de esta manera, pero no puedes volver a habilitar una que deshabilitaste mediante permissions.deny
La lista de permitidos de salida, de sandbox.network.allowedDomains. Si estableces coworkEgressAllowedHosts en el bloque desktop de la política, el gateway usa ese valor en lugar de la lista derivada
Un endpoint OTLP que apunta al propio gateway y los atributos de identidad del usuario con sesión iniciada. El gateway retransmite las exportaciones que recibe en ese endpoint a tus destinos forward_to. Incluye el endpoint y los atributos cuando estableces tanto telemetry.forward_to como listen.public_url.

Claude Desktop exporta cada señal con una sola codificación: http/protobuf, o http/json cuando estableces OTEL_EXPORTER_OTLP_PROTOCOL o una de sus variantes por señal en http/json en el env de la política. Antes de Claude Code v2.1.261 en el servidor del gateway, la respuesta establecía http/json en cualquier caso, por lo que un recopilador que solo acepta protobuf rechazaba las exportaciones de Claude Desktop

Para establecer disabledBuiltinTools, coworkEgressAllowedHosts o el ajuste managedMcpServers propio de Claude Desktop en el bloque desktop de una política, necesitas Claude Code v2.1.232 o posterior en el servidor del gateway. El managedMcpServers de Claude Desktop toma un valor de array en lugar de un objeto.

El gateway omite de la respuesta de bootstrap las claves sin equivalente en Claude Desktop, como hooks y las reglas de permisos con alcance como Bash(npm *).

Agrega el bloque opcional desktop junto a cli para establecer directamente la configuración de Claude Desktop. Escribe los ajustes de la referencia de configuración administrada de Claude Desktop como nombres de clave planos. Omite las claves que Claude Desktop lee solo de MDM o de archivos locales, como bootstrapUrl; el gateway las rechaza al arrancar. Antes de v2.1.232, el gateway aceptaba una lista fija de 11 claves de activación de funciones, como chatTabEnabled y disableAutoUpdates, y rechazaba todas las demás claves al arrancar. Antes de v2.1.227, el gateway también rechazaba chatTabEnabled y chatAdvancedFileAnalysisEnabled al arrancar.

managed:
  policies:
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
      desktop:
        isLocalDevMcpEnabled: false
        disableAutoUpdates: true
        banner: { text: "Contractor build: internal use only" }

Todas las claves son opcionales; Claude Desktop aplica su propio valor predeterminado para cualquier clave que omitas. El gateway valida cada bloque desktop al arrancar con el mismo esquema de configuración que usa Claude Desktop, por lo que un error aparece al iniciar el gateway como un mensaje que nombra la clave, en lugar de llegar a cada escritorio conectado. El gateway falla al arrancar cuando un bloque contiene:

Una clave desconocida
Una clave reconocida cuyo valor Claude Desktop rechazaría o descartaría silenciosamente, como un valor vacío o una subclave mal escrita dentro de una entrada anidada. Antes de v2.1.260, el gateway descartaba silenciosamente un campo mal escrito dentro de un objeto anidado de una entrada managedMcpServers u orgPluginSettings en lugar de fallar al arrancar.
Una clave que el propio gateway calcula: la conexión de inferencia, la lista de modelos y la retransmisión OTLP. Configúralas mediante upstreams, models y el forward_to de la sección telemetry.
Un alias heredado de una clave actual. En el error de arranque, el gateway nombra la clave canónica que debes escribir.

Si usas un valor o una forma de entrada obsoletos, como una entrada managedMcpServers sin transport, el gateway arranca y registra una advertencia que nombra el reemplazo.

El gateway valida un bloque desktop con el esquema incluido en su versión instalada, igual que hace con el bloque cli. Para entregar un ajuste introducido por una versión más reciente de Claude Desktop, actualiza primero el gateway. Por ejemplo, userPluginMarketplacesEnabled y userPluginUploadsEnabled necesitan Claude Code v2.1.260 o posterior en el servidor del gateway y Claude Desktop 1.37937.0 o posterior en las máquinas de los miembros.

blockReadsOutsideWorkingDirectories, disableBypassPermissionsMode, configRecheckIntervalMinutes y sshClientPath necesitan Claude Code v2.1.281 o posterior en el servidor del gateway. Lo mismo ocurre con el valor required de microsoftAuthBroker y el campo continuousAccessEvaluation de una entrada managedMcpServers de Microsoft 365. Las versiones de Claude Desktop anteriores al valor required lo leen como disabled, así que establece required solo después de que el Claude Desktop de todos los miembros lo admita. La referencia de configuración administrada de Claude Desktop indica la versión que lee por primera vez cada clave.

Si estableces orgPluginSettings en el bloque desktop de una política, el gateway lo sirve en la forma de array que leen Claude Desktop 1.15200.0 y posteriores. Los escritorios más antiguos ignoran el array y no aplican ninguna política de herramientas de plugins, así que actualiza a los miembros a 1.15200.0 o posterior antes de depender de ello.

El gateway completa las claves que el bloque desktop de una política no establece a partir del bloque desktop de la captura general match: {}, de la misma manera que completa el bloque cli de una política a partir de la base. Si estableces disabledBuiltinTools o builtinToolPolicy tanto en la base como en una política de rol, el gateway conserva la restricción de la base:

disabledBuiltinTools: el gateway usa la unión de la lista de la base y la lista de la política
builtinToolPolicy: si estableces una herramienta en un valor distinto de allow en la base, el gateway conserva ese valor aunque establezcas allow para la misma herramienta en una política de rol

Para cualquier otra clave, si la estableces en la política de rol, el gateway usa el valor de la política de rol. El gateway reemplaza completo un array o un objeto anidado como banner, por lo que si estableces banner.text en una política de rol, el gateway descarta el banner.backgroundColor de la base.

Si no despliegas Claude Desktop, deja desktop completamente fuera de tus políticas; el gateway devuelve entonces 404 desde /user/bootstrap para todos los usuarios.

Contexto extendido en Claude Desktop

Si sirves Claude Desktop desde el gateway, su selector de modelos ofrece una opción de contexto de 1M para cada modelo de la lista que puede ejecutarse con una ventana de contexto de 1M. Estos incluyen Claude Opus 4.6 y posteriores, Claude Sonnet 4.6 y posteriores, y los modelos Fable. La opción es la variante [1m] del modelo, que se describe en Contexto extendido. Necesitas Claude Code v2.1.284 o posterior en el servidor del gateway.

Una entrada de models no recibe la opción de 1M cuando:

Un upstream que puede atender la entrada la asigna a un modelo sin compatibilidad con 1M, incluido un upstream al que el gateway solo llega en la conmutación por error
Ni su id ni ninguno de sus valores de upstream_model nombra un modelo Claude, como un alias personalizado enrutado a un ARN de perfil de inferencia de aplicación

Para cambiar lo que ofrece el selector, usa una de estas opciones:

Iniciar a los usuarios en la opción de 1M: establece modelPrefer1mContext: true en el bloque desktop de la política. Los usuarios que aún no han elegido un modelo empiezan en la opción de 1M cuando el primer modelo de la lista la tiene. Los usuarios que ya eligieron un modelo conservan su elección.
Ofrecer la opción manualmente: haz esto si tu servidor del gateway ejecuta una versión anterior a v2.1.284, o si una entrada no nombra ningún modelo Claude. Incluye el modelo dos veces en models, una con su ID simple y otra con [1m] añadido, ambas con el mismo mapa upstream_model. Claude Desktop muestra el par como un solo modelo con una opción de 1M. El gateway sirve una entrada [1m] sin comprobarla, así que agrégala solo para un modelo que tus upstreams atienden con 1M.

Este ejemplo ofrece la opción manualmente para un alias personalizado enrutado a un perfil de inferencia de aplicación e inicia en ella a los usuarios nuevos:

models:
  - id: corp-sonnet
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod
  - id: corp-sonnet[1m]
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod

managed:
  policies:
    - match: {}
      desktop:
        modelPrefer1mContext: true

Quitar la opción de 1M

Para quitar la opción del selector, establece CLAUDE_CODE_DISABLE_1M_CONTEXT: "1" en el bloque env bajo la clave cli de la política. Si además incluiste una entrada cuyo id termina en [1m], el gateway la sigue sirviendo, así que elimina también esa entrada.

La variable también llega a las sesiones de terminal de los desarrolladores que coinciden con la política. Para saber qué cambia allí, consulta Contexto extendido.

Precedencia con otras fuentes administradas

Si un dispositivo también tiene una política entregada por MDM o un managed-settings.json local, la configuración entregada por el gateway tiene la máxima prioridad. Precedencia dentro del nivel administrado, en la página de configuración administrada, indica cuándo se aplican las fuentes locales e incluye las claves que Claude Code lee de todas las fuentes de administración independientemente de la fuente que haya seleccionado, como las claves de bloqueo del sandbox, forceRemoteSettingsRefresh y la combinación de env por variable. Un policyHelper configurado en un perfil MDM o en el archivo de configuración administrada se ejecuta solo cuando el gateway no entrega ninguna configuración; la entrada indica qué reemplaza su salida.

Los hosts que integran Claude Code, como Claude Desktop, pueden suministrar políticas mediante la opción managedSettings del SDK. Configuración principal de hosts de integración indica cuándo la aplica Claude Code, y Restringir la configuración principal enumera qué ajustes en sentido de permiso siguen aplicándose sin los bloqueos allowManaged*Only.

Las políticas del gateway se aplican a cada invocación de Claude Code en la máquina, incluidas las ejecuciones no interactivas claude -p y las sesiones generadas por el Agent SDK. Si el gateway es inaccesible al inicio, las sesiones con sesión iniciada terminan con un error en lugar de ejecutarse sin su política.

`telemetry`

El CLI envía métricas, registros y, cuando están habilitadas, trazas al gateway, que las retransmite textualmente a cada destino configurado. Las exportaciones usan OpenTelemetry Protocol (OTLP) sobre HTTP. Para omitir la retransmisión y que las sesiones exporten directamente a tu recopilador, nombra el recopilador en una política. Consulta Supervisión del uso para conocer las métricas y eventos que emite el CLI.

En las sesiones iniciadas mediante /login, el CLI marca cada exportación con la identidad del usuario autenticado, leída del JWT emitido por el gateway: los atributos user.id, user.email y user.groups. Por lo tanto, la atribución de costos y uso por desarrollador funciona sin ninguna configuración del lado del desarrollador.

Las sesiones de Claude Desktop y Cowork iniciadas mediante el gateway marcan su telemetría con user.email y user.groups junto a enduser.id, por lo que puedes cubrir el uso de terminal, Desktop y Cowork con una sola consulta sobre user.email o user.groups. user.groups es la lista de grupos del IdP separada por comas.

La telemetría de Desktop y Cowork también incluye enduser.sub, la reclamación sub que tu proveedor de identidad emite para el usuario, que no cambia cuando cambia el correo electrónico de un usuario. Las sesiones de terminal marcan el mismo valor bajo user.id, por lo que una consulta que compara enduser.sub con el user.id de terminal cubre conjuntamente el uso de terminal, Desktop y Cowork de un usuario. En las exportaciones de Desktop y Cowork, user.id es un identificador anónimo, no el sujeto.

Como todos los datos de OpenTelemetry de Claude Code, estos atributos van solo a los destinos que configura tu organización, nunca a Anthropic.

Si la lista de grupos de un usuario supera los 255 caracteres una vez codificada en porcentaje, o un nombre de grupo contiene una coma o un signo igual, el gateway omite user.groups de la telemetría de Desktop y Cowork de ese usuario en lugar de truncarla. Las sesiones de terminal de ese usuario siguen incluyendo la lista completa.

El gateway omite enduser.sub cuando el sujeto supera los 255 caracteres una vez codificado en porcentaje, o contiene un espacio, un carácter fuera del ASCII imprimible o uno de , ; = \ " %. La telemetría de Desktop y Cowork de ese usuario conserva sus demás atributos.

Necesitas Claude Code v2.1.265 o posterior en el servidor del gateway para user.email y user.groups en la telemetría de Desktop y Cowork, y Claude Desktop 1.24012 o posterior en la máquina de cada desarrollador para user.groups.

Necesitas Claude Code v2.1.274 o posterior en el servidor del gateway para enduser.sub.

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      # Activación por señal. Predeterminado: solo métricas.
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

Cada URL de forward_to debe usar https://, con una excepción para un recopilador en la interfaz de loopback del propio gateway:

http://localhost:<port> supera la validación de la configuración, pero la protección contra SSRF bloquea todas las exportaciones con ECONNREFUSED_SSRF a menos que establezcas CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 en el entorno del gateway
http://127.0.0.1:<port> o http://[::1]:<port> hace fallar el arranque a menos que esa variable esté establecida

Para un recopilador dentro del clúster, exponlo por HTTPS en su propia dirección interna, o ejecútalo como sidecar con la variable establecida.

Cuando HTTPS_PROXY está establecido, el gateway envía las exportaciones a través de ese proxy.

Para llegar directamente a un recopilador interno, agrégalo a NO_PROXY por nombre de host o mediante un dominio con un punto inicial como .internal.example.com, lo que requiere Claude Code v2.1.277 o posterior en el servidor del gateway. Asegúrate de que el gateway pueda llegar al recopilador sin el proxy. Una entrada sin punto inicial coincide solo con ese nombre exacto, no con los nombres que dependen de él. Los rangos CIDR no coinciden.

Con la salida solo a través del proxy activada, permite el recopilador en el proxy, ya que cualquier entrada de NO_PROXY mantiene desactivada la salida solo a través del proxy.

La telemetría está desactivada en el CLI de forma predeterminada. Cuando estableces tanto telemetry.forward_to como listen.public_url, el gateway la activa para los clientes con sesión iniciada enviando seis variables de entorno a través de /managed/settings:

CLAUDE_CODE_ENABLE_TELEMETRY=1
OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER y OTEL_TRACES_EXPORTER, cada una establecida en otlp si al menos un destino forward_to habilita esa señal y en none en caso contrario
OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

Cuando agregas tus propias etiquetas, el gateway también envía OTEL_RESOURCE_ATTRIBUTES.

Antes de Claude Code v2.1.265 en el servidor del gateway, el gateway enviaba los tres selectores de exportador como otlp, incluso para señales que ningún destino había activado.

El endpoint enviado se construye a partir de la URL pública, por lo que las métricas y los registros no necesitan configuración de OTEL por parte de los desarrolladores ni de las políticas.

Los desarrolladores con sesión iniciada mediante /login no pueden redirigir las exportaciones con su propia configuración de OTEL:

Variables establecidas localmente: Claude Code aplica las variables enviadas en el nivel administrado, por lo que cada una sobrescribe el valor que un desarrollador establece localmente para ella.
Endpoints configurados localmente: con la exportación OTLP/HTTP habilitada, el CLI ignora cualquier endpoint configurado localmente, independientemente de que el gateway haya enviado o no las variables de telemetría. Sus exportaciones van al gateway a menos que una política nombre tu recopilador como endpoint.

Sin un destino forward_to para una señal, el gateway la acepta y la descarta. Si los desarrolladores ya exportan la telemetría de Claude Code a uno de tus recopiladores, agrégalo como destino forward_to, con registros o trazas habilitados si los exportan, para que siga recibiendo sus datos después de que inicien sesión. Para omitir la retransmisión, nombra el recopilador en una política.

Las trazas también requieren CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 en cada cliente. Establécela en el bloque env de una política administrada, ya que el gateway no la envía. Los desarrolladores la aprueban en el mismo diálogo de aprobación de seguridad que ya activa el endpoint enviado.

Establécela en 1 solo en las políticas cuyos grupos quieras trazar. Una política que no la establece hereda el valor de tu política de captura general match: {} si esa política establece uno, según las reglas de fusión. Para evitar que los clientes de un grupo envíen trazas incluso cuando un desarrollador establece la variable localmente, establécela en 0 en la política de ese grupo.

Se retransmiten tanto la codificación OTLP protobuf como la JSON, y cualquier backend compatible con OpenTelemetry funciona como destino.

Agrega tus propias etiquetas

Para poner etiquetas fijas como service.namespace o deployment.environment.name en la telemetría de las sesiones iniciadas mediante el gateway, establece telemetry.resource_attributes. Cada etiqueta es un atributo de recurso de OpenTelemetry, y todos los destinos reciben las mismas etiquetas.

Las sesiones reciben las etiquetas solo cuando también estableces telemetry.forward_to y listen.public_url. Este ejemplo agrega dos etiquetas:

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
  resource_attributes:
    service.namespace: claude
    deployment.environment.name: prod

El gateway se niega a iniciar cuando una etiqueta incumple una de estas reglas, y el error de inicio nombra la etiqueta:

Los nombres usan solo letras, dígitos, ., _ y -
Los nombres no están reservados. Sin distinguir mayúsculas de minúsculas, los nombres reservados son todos los que empiezan por user., enduser. o identity., además de service.name, service.version, claude.deployment_mode, host.arch, os.type, os.version y wsl.version
Los valores son ASCII imprimible no vacío, sin espacios y sin ninguno de , ; = \ " %
Los valores tienen como máximo 255 caracteres según el recuento del gateway tras la codificación en porcentaje, por lo que /, : y @ cuentan como tres cada uno
Los valores son texto, así que pon entre comillas un número, true o false

Necesitas Claude Code v2.1.281 o posterior en el servidor del gateway para establecer telemetry.resource_attributes. Un gateway anterior se niega a iniciar cuando encuentra la clave. Actualiza todas las réplicas antes de agregar la clave, y elimina la clave antes de volver a una versión anterior.

Las sesiones de terminal iniciadas mediante /login reciben las etiquetas como OTEL_RESOURCE_ATTRIBUTES, enviada junto con las demás variables de telemetría. Si estableces OTEL_RESOURCE_ATTRIBUTES en el bloque env de una política, las sesiones de terminal que coinciden con esa política reciben ese valor en lugar de las etiquetas. Claude Desktop recibe las etiquetas del gateway junto con user.email y los demás atributos de identidad.

Claude Code también copia cada etiqueta en cada punto de datos de métrica, para que puedas filtrar las métricas por ella en un backend que no indexa atributos de recurso. Para desactivar esa copia, consulta Control de cardinalidad de métricas.

Exportar directamente a tu recopilador

Para que las sesiones iniciadas mediante /login envíen la telemetría directamente a tu recopilador en lugar de a través de la retransmisión, establece OTEL_EXPORTER_OTLP_ENDPOINT en la URL base https:// del recopilador en el bloque env de una política administrada. Claude Code añade /v1/metrics, /v1/logs o /v1/traces a la URL que estableces, como https://otel-collector.example.com:4318, y exporta allí cada señal mediante OTLP/HTTP. Requiere Claude Code v2.1.265 o posterior en la máquina de cada desarrollador. Los clientes anteriores exportan a través de la retransmisión.

Para autenticarte en el recopilador, establece OTEL_EXPORTER_OTLP_HEADERS en el mismo bloque env. Las sesiones nunca envían el token de sesión del gateway del desarrollador a un recopilador nombrado de esta manera.

Cuando agregas o cambias este endpoint en una política, Claude Code pide a cada desarrollador que lo apruebe en el diálogo de aprobación de seguridad antes de aplicarlo en una sesión interactiva.

Claude Code comprueba el endpoint antes de exportar una señal directamente, y mantiene esa señal en la retransmisión cuando falla una comprobación. Las comprobaciones incluyen:

El endpoint proviene del propio gateway. Si estableces la misma variable en un perfil MDM o en un managed-settings.json local, las exportaciones se mantienen en la retransmisión.
La URL usa https://, o http:// hacia una dirección de loopback
La URL se resuelve en una ruta que termina en /v1/<signal>, sin consulta ni fragmento. Claude Code construye esa ruta a partir de la variable genérica. Usa una variable por señal como OTEL_EXPORTER_OTLP_METRICS_ENDPOINT tal como está escrita, así que incluye allí la ruta completa.
La URL no es el propio host del gateway. Un endpoint dirigido al gateway mantiene la ruta de retransmisión y su token de sesión.
Ni tú ni el desarrollador han configurado otelHeadersHelper en ninguna fuente de configuración. Con un helper configurado, todas las señales se mantienen en la retransmisión.

El endpoint que nombras solo cambia adónde van las exportaciones. Sigues eligiendo qué señales se exportan con los selectores OTEL_*_EXPORTER.

El endpoint por sí solo no activa la exportación, así que establece también las variables que sí lo hacen, a menos que el gateway ya las envíe:

Si el gateway ya envía las variables de telemetría, estas cubren la habilitación, los selectores y el protocolo, y tu endpoint explícito sobrescribe el valor <public_url> enviado. Establece tú mismo un selector OTEL_*_EXPORTER en otlp solo para una señal que ningún destino forward_to habilita.
Si no las envía, establece también CLAUDE_CODE_ENABLE_TELEMETRY=1, los selectores OTEL_*_EXPORTER y OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.

Cuando el desarrollador cierra sesión, o inicia sesión en otro gateway, las exportaciones al recopilador se detienen y Claude Code descarta cada lote pendiente en lugar de enviarlo.

Cuando un destino falla

El gateway no almacena en búfer, no reintenta ni guarda la telemetría, por lo que descarta una exportación que no llega a un destino en lugar de entregarla tarde. Cada destino tiene éxito o falla por separado, y el cliente que exporta recibe una respuesta de éxito en cualquier caso, por lo que una entrega fallida solo aparece en el registro del gateway.

Tras cinco entregas fallidas consecutivas a un destino, el gateway pausa el reenvío a ese destino en intervalos de 30 segundos, registrando cada pausa, hasta que una entrega tiene éxito. Cualquier respuesta de error, tiempo de espera agotado o error de conexión cuenta como entrega fallida, excepto 400, 413, 415, 422 y 431, que indican que el recopilador rechazó el payload de esa exportación por estar mal formado o ser demasiado grande.

Un payload rechazado no incrementa ni reinicia el contador de fallos: el gateway sigue reenviando al destino y registra una advertencia que nombra el destino y el estado, en el primer rechazo del destino y cada cien rechazos posteriores.

Ajuste HTTP

Cuatro bloques opcionales de nivel superior, access_control, limits, timeouts y rate_limits, ajustan la superficie HTTP. Los valores predeterminados sirven para la mayoría de los despliegues.

Bloque	Clave	Predeterminado	Descripción
`access_control`	`allow_cidrs` / `deny_cidrs`	vacío	Permiso o denegación de IP entrante según la dirección del cliente, después de la resolución de `trusted_proxies`. `deny_cidrs` se comprueba primero; un cliente que coincide con ella se rechaza aunque `allow_cidrs` también coincida. Si `allow_cidrs` no está vacía, el gateway deniega de forma predeterminada. `/healthz` y `/readyz` están exentos de `allow_cidrs`. Cuando un proxy de confianza envía una entrada `X-Forwarded-For` que no es una dirección IP, el cliente real es desconocido y el gateway registra una vez una advertencia que indica qué revisar. Si alguna de las listas se aplica a la solicitud, la rechaza con `403` y el motivo de auditoría `xff_unparseable`. Si ninguna se aplica, atiende la solicitud y usa la propia dirección del proxy como IP del cliente para los rate limits por IP y la auditoría.
`limits`	`max_request_bytes`	32 MiB	Tamaño máximo del cuerpo de la solicitud entrante; las solicitudes demasiado grandes reciben `413` antes de que el cuerpo se almacene en búfer. Auméntalo para solicitudes con archivos o imágenes grandes.
`limits`	`max_request_header_bytes`	sin establecer	Cuando se establece, los encabezados demasiado grandes devuelven `431`
`limits`	`max_url_length`	sin establecer	Cuando se establece, una URL demasiado larga devuelve `414`
`timeouts`	`upstream_ttfb_ms`	120000	Espera máxima para los encabezados de respuesta del upstream (tiempo hasta el primer byte). Después, el cuerpo de la respuesta se transmite sin límite de tiempo total. Se aplica a la ruta directa al upstream de Anthropic; en todos los demás proveedores, el gateway espera hasta una hora a que empiece la respuesta.
`rate_limits`	`device_authorization.max` / `.window_seconds`	30 / 600	Rate limit por IP en el endpoint no autenticado de autorización de dispositivo. Auméntalo para una organización grande detrás de una IP de salida compartida o NAT. Despliegues a gran escala muestra cómo dimensionarlo. Estos límites se aplican solo al flujo de inicio de sesión con concesión de dispositivo, no a la inferencia de `/v1/messages`. Consulta Resistencia a la fuerza bruta del código de usuario.
`rate_limits`	`device_verify.max` / `.window_seconds`	10 / 600	Rate limit por IP en los envíos de `user_code` en `/device`. Es lo que impide que alguien adivine el código de otro desarrollador. Despliegues a gran escala muestra cuánto aumentarlo.

Si dejas vacías ambas listas de access_control, que es el valor predeterminado, el gateway atiende cualquier dirección de cliente, por lo que solo tu red restringe quién puede llegar a él. Eso importa porque un gateway puede enviar configuración administrada que ejecuta comandos en las máquinas de los desarrolladores.

Mientras allow_cidrs está vacía, el gateway advierte en dos lugares, sin cambiar cómo responde a ninguna solicitud:

Al arrancar: una advertencia en el registro operativo recomienda permitir solo los rangos privados 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, 127.0.0.0/8, ::1/128 y fc00::/7, además de cualquier otro rango interno desde el que se conecten tus desarrolladores. Si vinculas el gateway a una dirección de loopback y no estableces trusted_proxies ni public_url, como en el desarrollo local, la advertencia no aparece.
En tiempo de ejecución: la primera vez que llega una solicitud desde una dirección fuera de esos rangos privados, el gateway registra una advertencia y emite un evento de auditoría access.public_client que incluye la IP del cliente. Ambos se producen una vez por proceso. Las direcciones de enlace local, 169.254.0.0/16 y fe80::/10, no cuentan como públicas. El gateway responde a /healthz y /readyz antes de que se ejecute esta comprobación, por lo que los sondeos de estado desde rangos públicos no la activan.

Ambas señales usan la dirección del cliente tal como la resuelve el gateway. Si un balanceador de carga, un reenvío de puertos o un túnel retransmite el tráfico y no figura en listen.trusted_proxies, el gateway ve la dirección del intermediario, que suele ser privada, por lo que ni la advertencia en tiempo de ejecución ni una lista de permitidos privada detectan el tráfico retransmitido a través de él.

Detrás de un front end así, establece primero listen.trusted_proxies para que el gateway vea las direcciones reales de los clientes, y mantén el gateway y todo lo que está delante de él inaccesibles desde internet pública en cualquier caso.

`load_test_mode`

El bloque load_test_mode te permite hacer pruebas de carga de un gateway sin llamar a un proveedor de modelos. Mientras está activado, el gateway construye y firma cada solicitud al proveedor como de costumbre, la descarta en lugar de enviarla y transmite una respuesta predefinida por su ruta de respuesta normal. La respuesta es texto de relleno que empieza con una oración que indica que es predefinida.

Requiere Claude Code v2.1.282 o posterior en el servidor del gateway. Un gateway anterior se niega a iniciar cuando encuentra la clave. Actualiza todas las réplicas antes de agregar el bloque, y elimina el bloque antes de volver a una versión anterior.

El siguiente ejemplo activa el modo con los valores predeterminados, una respuesta de aproximadamente 750 tokens de texto transmitida durante unos 10 segundos:

load_test_mode:
  enabled: true
  reply_tokens: 750     # aproximadamente cuántos tokens de texto contiene cada respuesta predefinida
  reply_seconds: 9.5    # cuánto tarda una respuesta transmitida

Campo	Requerido	Descripción
`enabled`	Sí	`true` activa el modo. `false` conserva tus valores en el archivo con el modo desactivado. El gateway se niega a iniciar si el bloque está presente sin este campo.
`reply_tokens`	No	Predeterminado `750`. Aproximadamente cuántos tokens de texto contiene cada respuesta predefinida, un número entero de 1 a 100000.
`reply_seconds`	No	Predeterminado `9.5`. Cuánto tarda una respuesta transmitida, de 0 a 600. `0` envía toda la respuesta de una vez. La respuesta a una solicitud sin streaming siempre llega de una vez.

Una prueba de carga en este modo cubre el gateway, tu Postgres y todo lo que está delante del gateway. No cubre los límites, la velocidad ni la ruta de red del proveedor.

No se envía ninguna solicitud de modelo al proveedor, por lo que el uso de CPU por solicitud de una réplica es una estimación y resulta menor que en producción, donde además se cifra el tráfico hacia el proveedor. Confirma el número de réplicas con un piloto pequeño contra el proveedor real. Antes de v2.1.283, la estimación resulta mucho menor.

Mientras el modo está activado, una solicitud puede incluir un encabezado x-load-test-user con un número entero de hasta siete dígitos. El gateway cuenta cada número como un desarrollador distinto, con el correo electrónico y los grupos del desarrollador cuyo token acompañó la solicitud.

Asigna al despliegue de pruebas de carga su propia base de datos vacía, porque el gateway se niega a iniciar con el modo activado contra una base de datos en la que algún desarrollador ya haya gastado algo.

Ejemplo completo

Esta configuración de referencia completa ejercita cada sección central; los bloques de ajuste HTTP mantienen sus valores predeterminados. Cópiela, elimine lo que no necesite y complete sus valores. La configuración en el Inicio rápido es una versión mínima de esta.

# Ejecutar con:
#   claude gateway --config gateway.yaml
#
# La verbosidad del registro operativo se controla mediante la variable de entorno
# CLAUDE_GATEWAY_LOG_LEVEL (debug | info | warn | error; predeterminado info). debug
# también registra los nombres de reclamaciones en cada id_token, para diagnóstico de groups_claim.
# No afecta los eventos de auditoría, que siempre se emiten.

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  # Omita el bloque tls cuando se ejecute detrás de una entrada que termina TLS.
  # tls:
  #   cert: /certs/gateway.crt
  #   key: /certs/gateway.key
  # trusted_proxies:
  #   - 10.0.0.0/8

oidc:
  issuer: https://example.okta.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains:
    - example.com
  # Requerido cuando el emisor es el servidor de la organización Okta, cuyos id_tokens
  # pueden omitir correo electrónico y grupos; la puerta de enlace los completa desde /userinfo.
  userinfo_fallback: true
  # allowed_groups: [claude-code-users]
  # Okta emite grupos solo cuando se solicita el alcance `groups` y el
  # filtro de reclamación de grupos de la aplicación los permite. La política de contratistas a continuación
  # coincide con grupos, por lo que el alcance se solicita aquí.
  scopes: [openid, profile, email, offline_access, groups]
  # extra_auth_params: { access_type: offline, prompt: consent }  # Google
  # groups_claim: groups          # Roles de aplicación de Entra: use `roles`
  # email_claim: email

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}   # openssl rand -base64 32
  # ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}
  # max_connections: 5
  # connect_timeout_seconds: 5
  # readiness_grace_seconds: 300   # mantener pasando la verificación de disponibilidad durante una conmutación por error de base de datos

# Habilita /v1/organizations/spend_limits (refleja la API de administrador de Anthropic)
# y cumplimiento de gasto por desarrollador en /v1/messages. Omita para deshabilitar.
# Los límites en sí se establecen a través de la API de administrador, no aquí.
# admin:
#   write_keys:
#     - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
#   read_keys:
#     - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
#   admin_groups: [platform-finops]
#   blocked_message: request an increase at https://go.example.com/claude-limits
#   # audit_retention_days: 365
#   # spend_retention_months: 13
#   # identity_retention_days: 90
#   # group_limit_mode: min

# enforcement:
#   fail_closed_on_error: false

# Prueba de carga de esta implementación sin llamar a un proveedor de modelo. Nunca en una
# puerta de enlace que usen desarrolladores: cada solicitud obtiene una respuesta enlatada.
# load_test_mode:
#   enabled: true
#   # reply_tokens: 750
#   # reply_seconds: 9.5

# Medir a tasas contratadas en lugar del precio de lista en USD. Requiere admin: o una
# política managed:. Con managed:, las mismas tasas también van a clientes que han iniciado sesión.
# Las tasas a continuación son marcadores de posición, no precios de contrato reales.
# pricing:
#   multiplier: 0.85
#   overrides:
#     - { upstream: anthropic, model: claude-sonnet-4-6, input: 3.30, output: 16.50, cache_read: 0.33, cache_write: 4.125 }

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

  # - provider: bedrock
  #   region: us-east-1
  #   auth: {}

  # - provider: anthropicAws
  #   region: us-east-1
  #   workspace_id: wrkspc_...
  #   auth:
  #     api_key: ${ANTHROPIC_AWS_API_KEY}

  # - provider: vertex
  #   region: us-east5
  #   project_id: example-prod
  #   auth: {}

  # - provider: foundry
  #   resource: example-foundry
  #   auth: { use_azure_ad: true }

auto_include_builtin_models: true
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      anthropic: claude-opus-4-8
      # bedrock: us.anthropic.claude-opus-4-8
      # anthropicAws: claude-opus-4-8
      # vertex: claude-opus-4-8
      # foundry: <your-opus-deployment-name>
  - id: claude-sonnet-4-6
    label: Claude Sonnet 4.6
    upstream_model:
      anthropic: claude-sonnet-4-6
  - id: claude-haiku-4-5
    label: Claude Haiku 4.5
    upstream_model:
      anthropic: claude-haiku-4-5

managed:
  policies:
    - match: { groups: [contractors] }
      cli:
        availableModels: [claude-haiku-4-5]
        # Restrinja la opción del selector predeterminado a availableModels en lugar de
        # el predeterminado de nivel, para que los contratistas no obtengan un 400 en el predeterminado.
        enforceAvailableModels: true
        # allow aprueba automáticamente estas herramientas; no bloquea el resto.
        # Agregue reglas de negación para restringir herramientas.
        permissions: { allow: [Read, Grep] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        permissions:
          allow: [Read, Grep, Bash, Edit]
          deny: ["WebFetch"]
        env: { HTTP_PROXY: http://proxy.example.com:8080 }

telemetry:
  forward_to:
    - url: https://otel.internal.example.com:4318
      headers:
        Authorization: Bearer ${OTEL_TOKEN}

Configuración administrada del lado del cliente

Todo lo anterior configura el servidor de puerta de enlace. Apuntar máquinas de desarrollador a la puerta de enlace se configura por separado, en cada dispositivo, a través de la configuración administrada de Claude Code. La puerta de enlace no puede empujar las claves de inicio de sesión por sí misma, porque son lo que le dice al cliente dónde está la puerta de enlace.

Para el CLI, establezca estas claves en el managed-settings.json por SO. Las dos claves de inicio de sesión enrutan el /login de cada desarrollador a su puerta de enlace:

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge"
}

parentSettingsBehavior: "merge" mantiene el funcionamiento de la entrega de Claude Desktop de la lista de permitidos de salida a sus sesiones de Claude Code integradas; Entregar política a sesiones de Claude Desktop explica el mecanismo y dónde debe estar la aceptación.

Para evitar que los desarrolladores eludan la puerta de enlace con una variable de proveedor de nube o un ANTHROPIC_BASE_URL propio, agregue "allowedProviders": ["gateway"] al mismo archivo. Claude Code entonces rechaza cada sesión en la máquina que no esté configurada para una puerta de enlace en la nube, y admite una puerta de enlace solo cuando es la que forceLoginGatewayUrl nombra o una cuya URL el bloque env del archivo establece como ANTHROPIC_BASE_URL. claude gateway se niega a ejecutarse en una máquina que establece la lista, así que mantenga la clave fuera del host de la puerta de enlace. Consulte la entrada allowedProviders en la referencia de configuración. Requiere Claude Code v2.1.285 o posterior.

Implemente el archivo managed-settings.json en cada dispositivo, típicamente a través de su plataforma MDM. La ruta del archivo difiere por plataforma. Consulte dónde almacena cada mecanismo la política.

De forma predeterminada, una política de registro en Windows o una plist de preferencias administradas en macOS reemplaza el archivo managed-settings.json en lugar de fusionarse con él, aparte de las claves de excepción y verificaciones entre fuentes anteriores. Las tres claves en este fragmento siguen la regla de fuente de prioridad más alta, por lo que las flotas que entregan política a través de Política de grupo o perfiles de configuración deben poner las tres en ese mecanismo en su lugar.

Para Claude Desktop, establezca la clave bootstrapUrl en la propia configuración administrada de Claude Desktop en <listen.public_url>/user/bootstrap. El flujo de inicio de sesión y la política por grupo coinciden entonces con los del CLI una vez que una política se acepta del lado del servidor con una clave desktop; sin la aceptación, /user/bootstrap devuelve 404. Consulte Superposición de Claude Desktop para la mitad del lado del servidor.

Claude Code honra forceLoginGatewayUrl, gatewayInternalNetworks, y el valor "gateway" de forceLoginMethod solo desde una fuente administrada en la máquina: managed-settings.json, la plist de macOS o el registro HKLM de Windows, o un asistente de política. Establecerlos en el ~/.claude/settings.json propio de un desarrollador no configura el inicio de sesión de la puerta de enlace, y tampoco lo hace establecerlos en la carga útil de la puerta de enlace.

Deje forceLoginMethod y forceLoginOrgUUID fuera de la carga útil. Claude Code aún lee ambas claves de la carga útil para su verificación de credenciales de inicio, por lo que un desarrollador que mantenga una credencial emitida por Anthropic en la máquina obtiene la salida de inicio descrita en La política del administrador requiere un inicio de sesión de puerta de enlace en la nube incluso después de que inicie sesión.

Descripción general de la puerta de enlace de aplicaciones Claude: inicio rápido y conexión de desarrollador
Guía de implementación: configuración de IdP, imagen de contenedor, Kubernetes y Cloud Run, y operaciones
Límites de gasto: límites por desarrollador y la API de administración

claude-apps-gateway-config.md +279 −216

644 `admin`644 `admin`

645</h3>645</h3>

646 646

647Opcional. Habilita `/v1/organizations/spend_limits`, que refleja la API pública de administrador de Anthropic, y la aplicación de gastos por desarrollador en `/v1/messages`. Consulte [Límites de gastos](/docs/es/claude-apps-gateway-spend-limits) para saber cómo se establecen y aplican los límites; esta sección cubre las claves de `gateway.yaml` que activan la función y la ajustan.647Opcional. Habilita `/v1/organizations/spend_limits`, que replica la Admin API pública de Anthropic, y la aplicación de límites de gasto por desarrollador en `/v1/messages`. Consulta [Límites de gasto](/docs/es/claude-apps-gateway-spend-limits) para saber cómo se establecen y aplican los límites; esta sección cubre las claves de `gateway.yaml` que activan la función y la ajustan.

648 648

649```yaml theme={null}649```yaml theme={null}

650admin:650admin:

651 # Claves API estáticas nombradas para los puntos finales de administrador, enviadas como x-api-key.651 # Claves de API estáticas con nombre para los endpoints de administración, enviadas como x-api-key.

652 # El id aparece en el registro de auditoría como admin-key:<id> para que cada clave sea652 # El id aparece en el registro de auditoría como admin-key:<id> para que cada clave sea

653 # atribuible. Array para rotación: agregue la clave nueva, actualice los clientes,653 # atribuible. Array para rotación: agrega la clave nueva, actualiza los clientes,

654 # elimine la antigua.654 # elimina la antigua.

655 write_keys:655 write_keys:

656 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }656 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }

657 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }657 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }

658 read_keys:658 read_keys:

659 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }659 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }

660 # Grupos de IdP con acceso de administrador completo a través del JWT de puerta de enlace normal (sin clave API).660 # Grupos de IdP con acceso completo de administrador mediante el JWT normal del gateway (sin clave de API).

661 admin_groups: [platform-finops]661 admin_groups: [platform-finops]

662 blocked_message: request an increase at https://go.example.com/claude-limits662 blocked_message: request an increase at https://go.example.com/claude-limits

663```663```

664 664

666| - | - | - |666| - | - | - |

667| `write_keys` | No | Array de `{id, key}`. Una `x-api-key` que coincida con una de estas puede listar, establecer y eliminar límites de gastos. Los valores de clave deben tener al menos 32 caracteres; los `id` deben ser únicos en `read_keys` y `write_keys`. |667| `write_keys` | No | Array de `{id, key}`. Una `x-api-key` que coincida con una de estas puede listar, establecer y eliminar límites de gasto. Los valores de clave deben tener al menos 32 caracteres; los `id` deben ser únicos entre `read_keys` y `write_keys`. |

668| `read_keys` | No | Array de `{id, key}`. Solo lectura: todos los puntos finales `GET`, incluida la enumeración de límites, la obtención de uno por ID y la lectura de [`/effective`](/docs/es/claude-apps-gateway-spend-limits#%2Feffective) y [`/audit`](/docs/es/claude-apps-gateway-spend-limits#%2Faudit). |668| `read_keys` | No | Array de `{id, key}`. De solo lectura: todos los endpoints `GET`, incluido listar límites, obtener uno por ID y leer [`/effective`](/docs/es/claude-apps-gateway-spend-limits#%2Feffective) y [`/audit`](/docs/es/claude-apps-gateway-spend-limits#%2Faudit). |

669| `admin_groups` | No | Nombres de grupos de IdP. Un JWT de puerta de enlace cuya reclamación `groups` incluya uno de estos tiene acceso de administrador completo, lectura y escritura, y auditorías como `oidc:<sub>`. Úselo para administradores humanos; use claves API para máquinas. Una entrada vacía en esta lista detiene la puerta de enlace al arrancar. Consulte [Valores de coincidencia que detienen la puerta de enlace al arrancar](#matcher-values-that-stop-the-gateway-at-boot). |669| `admin_groups` | No | Nombres de grupos de IdP. Un JWT del gateway cuya reclamación `groups` incluya uno de estos tiene acceso completo de administrador, de lectura y escritura, y se audita como `oidc:<sub>`. Úsalo para administradores humanos; usa claves de API para máquinas. Una entrada vacía en esta lista detiene el gateway al arrancar. Consulta [Valores de matcher que detienen el gateway al arrancar](#matcher-values-that-stop-the-gateway-at-boot). |

670| `blocked_message` | No | Se añade textualmente al `429 billing_error` que ve un desarrollador bloqueado. Escriba la instrucción completa, como una URL o un canal de Slack. Cuando no está establecido, la puerta de enlace envía solo el mensaje predeterminado. Consulte [Cómo funciona la aplicación](/docs/es/claude-apps-gateway-spend-limits#how-enforcement-works). |670| `blocked_message` | No | Se añade textualmente al `429 billing_error` que ve un desarrollador bloqueado. Escribe la instrucción completa, como una URL o un canal de Slack. Cuando no está establecido, el gateway envía solo el mensaje predeterminado. Consulta [Cómo funciona la aplicación](/docs/es/claude-apps-gateway-spend-limits#how-enforcement-works). |

671| `audit_retention_days` | No | Predeterminado `365`. Las filas `admin_audit` más antiguas se eliminan. |671| `audit_retention_days` | No | Predeterminado `365`. Las filas `admin_audit` más antiguas se eliminan. |

672| `spend_retention_months` | No | Predeterminado `13`. Las filas del contador `spend` más antiguas que esto se eliminan. El valor predeterminado mantiene un año completo más el mes parcial actual para informes año a año. |672| `spend_retention_months` | No | Predeterminado `13`. Las filas del contador `spend` más antiguas que esto se eliminan. El valor predeterminado conserva un año completo más el mes parcial actual para informes interanuales. |

673| `identity_retention_days` | No | Predeterminado `90`. TTL de última visualización para filas `principal_emails`, que contienen el correo electrónico, el nombre para mostrar y los grupos de cada desarrollador (PII). Deliberadamente más corto que la retención de gastos para que una identidad desaprovisionada caduque mientras sus contadores de gastos anónimos permanecen. |673| `identity_retention_days` | No | Predeterminado `90`. TTL desde la última vez que se vio para las filas `principal_emails`, que contienen el correo electrónico, el nombre para mostrar y los grupos de cada desarrollador (PII). Es deliberadamente más corto que la retención de gastos para que una identidad desaprovisionada caduque mientras sus contadores de gasto anónimos permanecen. |

674| `group_limit_mode` | No | `min` (predeterminado) o `max`. Cuando un desarrollador está en varios grupos con límites, `min` aplica el más restrictivo y `max` el menos restrictivo. Utilizado tanto por la aplicación como por `/effective`. |674| `group_limit_mode` | No | `min` (predeterminado) o `max`. Cuando un desarrollador está en varios grupos con límites, `min` aplica el más restrictivo y `max` el menos restrictivo. Lo usan tanto la aplicación como `/effective`. |

675 675

676<h3 id="enforcement">676<h3 id="enforcement">

677 `enforcement`677 `enforcement`

678</h3>678</h3>

679 679

680El bloque `enforcement` controla cómo se comportan las comprobaciones de límites de gastos cuando el almacén no está disponible.680El bloque `enforcement` controla cómo se comportan las comprobaciones de límites de gasto cuando el almacén no está disponible.

681 681

683| - | - | - |683| - | - | - |

684| `fail_closed_on_error` | No | Predeterminado `false`. La aplicación de límites de gastos falla abierta en una interrupción de Postgres, por lo que la inferencia se mantiene activa. Establezca `true` para fallar cerrado: los desarrolladores que superan el límite se bloquean, pero también todos los demás si el almacén es inaccesible. Requiere un bloque [`admin:`](#admin): la aplicación de límites de gastos solo se ejecuta cuando `admin` está configurado, y la puerta de enlace se niega a iniciar si establece esto en `true` sin uno. |684| `fail_closed_on_error` | No | Predeterminado `false`. La aplicación de límites de gasto falla en abierto ante una interrupción de Postgres, por lo que la inferencia sigue disponible. Establece `true` para fallar en cerrado: los desarrolladores que superan el límite quedan bloqueados, pero también todos los demás si el almacén es inaccesible. Requiere un bloque [`admin:`](#admin): la aplicación de límites de gasto solo se ejecuta cuando `admin` está configurado, y el gateway se niega a iniciar si estableces esto en `true` sin uno. |

685 685

686<h3 id="pricing">686<h3 id="pricing">

687 `pricing`687 `pricing`

688</h3>688</h3>

689 689

690El bloque `pricing` le dice al medidor de gastos qué cobrar en lugar del precio de lista en USD, para que los límites y [`/effective`](/docs/es/claude-apps-gateway-spend-limits#%2Feffective) reflejen sus tasas contratadas. Los montos permanecen en USD y siguen siendo una estimación, no una factura. Dos requisitos previos:690El bloque `pricing` le indica al medidor de gastos qué cobrar en lugar del precio de lista en USD, para que los límites y [`/effective`](/docs/es/claude-apps-gateway-spend-limits#%2Feffective) reflejen tus tarifas contratadas. Los montos siguen en USD y siguen siendo una estimación, no una factura. Dos requisitos previos:

691 691

692* Claude Code v2.1.227 o posterior en el servidor de puerta de enlace. Las versiones anteriores rechazan la clave desconocida al arrancar.692* Claude Code v2.1.227 o posterior en el servidor del gateway. Las versiones anteriores rechazan la clave desconocida al arrancar.

693* Un bloque [`admin:`](#admin) o, en v2.1.268 o posterior, un bloque [`managed:`](#managed) con al menos una política. La puerta de enlace se niega a iniciar con `pricing` establecido y ninguno de los dos bloques, porque nada lo leería.693* Un bloque [`admin:`](#admin) o, en v2.1.268 o posterior, un bloque [`managed:`](#managed) con al menos una política. El gateway se niega a iniciar con `pricing` establecido y sin ninguno de los dos bloques, porque nada lo leería.

694 694

695```yaml theme={null}695```yaml theme={null}

696pricing:696pricing:

706 706

708| - | - | - |708| - | - | - |

709| `multiplier` | No | Predeterminado `1`. El medidor multiplica cada cantidad medida por esto, ya sea con precio de lista o anulada, por lo que `0.85` factura el 85% del precio. Debe ser mayor que 0 y como máximo 10, y un valor superior a 1 es un [marcado](#mark-prices-up). |709| `multiplier` | No | Predeterminado `1`. El medidor multiplica cada cantidad medida por este valor, ya sea con precio de lista o sobrescrita, por lo que `0.85` factura el 85% del precio. Debe ser mayor que 0 y como máximo 10, y un valor superior a 1 es un [recargo](#mark-prices-up). |

710| `overrides` | No | Filas de `{upstream, model, input, output, cache_read, cache_write}` en USD por millón de tokens. Las cuatro tasas son obligatorias. Cada una debe ser mayor que 0 y como máximo 10000. |710| `overrides` | No | Filas de `{upstream, model, input, output, cache_read, cache_write}` en USD por millón de tokens. Las cuatro tarifas son obligatorias. Cada una debe ser mayor que 0 y como máximo 10000. |

711 711

712Cómo el medidor coincide con una fila de anulación:712Cómo el medidor hace coincidir una fila de sobrescritura:

713 713

714* Una fila reemplaza el precio de lista para solicitudes que `upstream`, un [`upstreams[].name`](#upstreams), sirve para `model`. Esto incluye la tasa de [modo rápido](/docs/es/fast-mode#understand-the-cost-tradeoff) más alta, por lo que las solicitudes de modo rápido y estándar se miden con las mismas cuatro tasas.714* Una fila reemplaza el precio de lista para las solicitudes que `upstream`, un [`upstreams[].name`](#upstreams), atiende para `model`. Esto incluye la tarifa más alta del [modo rápido](/docs/es/fast-mode#understand-the-cost-tradeoff), por lo que las solicitudes en modo rápido y estándar se miden con las mismas cuatro tarifas.

715* Un ID integrado como `claude-sonnet-4-6`, coincidido como [`models[].id`](#models), cubre todas las formas fechadas, formas regionales de Amazon Bedrock, o formas de la Plataforma de Agentes de Google Cloud que el medidor valora como ese modelo. Cualquier otra cadena, como un alias o un ARN de perfil de inferencia, coincide con el ID que el cliente envió o la cadena enviada ascendente, sin distinción de mayúsculas y minúsculas.715* Un ID integrado como `claude-sonnet-4-6`, que se hace coincidir como [`models[].id`](#models), cubre todas las formas con fecha, las formas regionales de Amazon Bedrock o las formas de Agent Platform de Google Cloud que el medidor cotiza como ese modelo. Cualquier otra cadena, como un alias o un ARN de perfil de inferencia, coincide con el ID que envió el cliente o con la cadena enviada al upstream, sin distinguir mayúsculas de minúsculas.

716* Donde las filas se superponen, el medidor elige la fila más específica en lugar de la primera fila: una fila cuyo `model` es la cadena de modelo exacta enviada ascendente, luego una fila que coincide con el ID exacto que el cliente envió, luego una fila que nombra el modelo integrado.716* Cuando las filas se superponen, el medidor elige la fila más específica en lugar de la primera: una fila cuyo `model` es la cadena de modelo exacta enviada al upstream, luego una fila que coincide con el ID exacto que envió el cliente y luego una fila que nombra el modelo integrado.

717* Un nombre de upstream desconocido falla al arrancar, al igual que dos filas para un upstream que nombran el mismo modelo, incluidas dos ortografías de un modelo integrado. La puerta de enlace advierte al arrancar sobre una fila que ningún modelo solicitable puede usar.717* Un nombre de upstream desconocido hace fallar el arranque, y también dos filas para un mismo upstream que nombran el mismo modelo, incluidas dos formas de escribir un mismo modelo integrado. El gateway advierte al arrancar sobre una fila que ningún modelo solicitable puede usar.

718* Las solicitudes de búsqueda web permanecen en el precio de lista de \$0.01; el multiplicador aún se aplica a ellas.718* Las solicitudes de búsqueda web se mantienen en el precio de lista de \$0.01; el multiplicador sigue aplicándose a ellas.

719 719

720Para tasas por región, asigne a cada región su propio upstream nombrado y una fila por upstream.720Para tarifas por región, asigna a cada región su propio upstream con nombre y una fila por upstream.

721 721

722<h4 id="mark-prices-up">722<h4 id="mark-prices-up">

723 Marcar precios hacia arriba723 Aplicar un recargo a los precios

724</h4>724</h4>

725 725

726Con v2.1.271 o posterior en el servidor de puerta de enlace, puede establecer `multiplier` por encima de 1, hasta 10, para medir más de lo que cobra el proveedor, por ejemplo una tasa de reembolso interno. Este ejemplo mide cada solicitud al 120% del precio:726Con v2.1.271 o posterior en el servidor del gateway, puedes establecer `multiplier` por encima de 1, hasta 10, para medir más de lo que cobra el proveedor, por ejemplo una tarifa interna de refacturación. Este ejemplo mide cada solicitud al 120% del precio:

727 727

728```yaml theme={null}728```yaml theme={null}

729pricing:729pricing:

730 multiplier: 1.2730 multiplier: 1.2

731```731```

732 732

733Con un bloque [`admin:`](#admin), el marcado también se aplica a los límites de gastos. El medidor cuenta el 120% del precio, por lo que los desarrolladores alcanzan sus límites más rápido. La puerta de enlace registra una advertencia al arrancar que lo dice.733Con un bloque [`admin:`](#admin), el recargo también se aplica a los límites de gasto. El medidor cuenta el 120% del precio, por lo que los desarrolladores alcanzan sus límites antes. El gateway registra una advertencia al arrancar que lo indica.

734 734

735El multiplicador no cambia lo que cobra el proveedor ascendente por las solicitudes.735El multiplicador no cambia lo que cobra el proveedor upstream por las solicitudes.

736 736

737Si la puerta de enlace también [envía las tasas a clientes conectados](#send-the-rates-to-signed-in-clients), los desarrolladores necesitan Claude Code v2.1.271 o posterior para ver el marcado. Los clientes anteriores ignoran un `multiplier` superior a 1 y muestran costos sin él.737Si el gateway también [envía las tarifas a los clientes con sesión iniciada](#send-the-rates-to-signed-in-clients), los desarrolladores necesitan Claude Code v2.1.271 o posterior para ver el recargo. Los clientes anteriores ignoran un `multiplier` superior a 1 y muestran los costos sin él.

738 738

739Un servidor de puerta de enlace anterior a v2.1.271 se niega a iniciar si establece un `multiplier` superior a 1.739Un servidor del gateway anterior a v2.1.271 se niega a iniciar si estableces un `multiplier` superior a 1.

740 740

741<h4 id="send-the-rates-to-signed-in-clients">741<h4 id="send-the-rates-to-signed-in-clients">

742 Enviar las tasas a clientes conectados742 Enviar las tarifas a los clientes con sesión iniciada

743</h4>743</h4>

744 744

745Con v2.1.268 o posterior en el servidor de puerta de enlace, la puerta de enlace también coloca las tasas de `pricing` en las políticas [`managed`](#managed) que sirve, como la configuración administrada [`modelPricing`](/docs/es/settings-reference#modelpricing). Los desarrolladores coincididos por una política ven las tasas de `pricing` para el primer upstream que sirve cada ID de modelo en `/usage`, la línea de estado y OpenTelemetry. Un desarrollador que no coincide con ninguna política no recibe configuración administrada, por lo que sus cifras permanecen en el precio de lista. Los clientes aplican la configuración en Claude Code v2.1.242 o posterior.745Con v2.1.268 o posterior en el servidor del gateway, el gateway también coloca las tarifas de `pricing` en las políticas [`managed`](#managed) que sirve, como el ajuste administrado [`modelPricing`](/docs/es/settings-reference#modelpricing). Los desarrolladores que coinciden con una política ven entonces las tarifas de `pricing` del primer upstream que atiende cada ID de modelo en `/usage`, la línea de estado y OpenTelemetry. Un desarrollador que no coincide con ninguna política no recibe configuración administrada, por lo que sus cifras se mantienen en el precio de lista. Los clientes aplican el ajuste en Claude Code v2.1.242 o posterior.

746 746

747* Lo que agrega la puerta de enlace: a menos que el bloque `cli` de una política ya establezca `modelPricing`, la puerta de enlace agrega el `multiplier` y, para cada ID de modelo que un cliente pueda solicitar, la fila de anulación del primer upstream que sirve ese ID. Una tasa que solo cobra un upstream de conmutación por error permanece en la puerta de enlace.747* Lo que agrega el gateway: a menos que el bloque `cli` de una política ya establezca `modelPricing`, el gateway agrega el `multiplier` y, para cada ID de modelo que un cliente puede solicitar, la fila de sobrescritura del primer upstream que atiende ese ID. Una tarifa que solo cobra un upstream de conmutación por error se queda en el gateway.

748* Optar una política: establezca `modelPricing` en `{}` en el bloque `cli` de esa política, y sus desarrolladores permanecen en el precio de lista.748* Excluir una política: establece `modelPricing` en `{}` en el bloque `cli` de esa política, y sus desarrolladores se mantienen en el precio de lista.

749* Mantener las tasas propias de una política: una política cuyo bloque `cli` establece `modelPricing` con su propio `multiplier` u `overrides` mantiene ese `modelPricing` completo, y la puerta de enlace no agrega tasas propias a él.749* Conservar las tarifas propias de una política: una política cuyo bloque `cli` establece `modelPricing` con su propio `multiplier` u `overrides` conserva ese `modelPricing` completo, y el gateway no le agrega tarifas propias.

750 750

751<h3 id="models">751<h3 id="models">

752 `models`752 `models`

753</h3>753</h3>

754 754

755El bloque `models` es una lista de modelos opcional curada por administrador, servida en `/v1/models` y utilizada para traducir ID de modelos por upstream. Es obligatorio para regiones de Amazon Bedrock que no sean EE.UU., ARN de rendimiento aprovisionado de Amazon Bedrock y nombres de implementación de Microsoft Foundry.755El bloque `models` es una lista de modelos opcional seleccionada por el administrador, servida en `/v1/models` y usada para traducir los ID de modelo por upstream. Es obligatoria para regiones de Amazon Bedrock fuera de EE. UU., ARN de rendimiento aprovisionado de Amazon Bedrock y nombres de despliegue de Microsoft Foundry.

756 756

757```yaml theme={null}757```yaml theme={null}

758auto_include_builtin_models: true # false: exponer solo la lista a continuación758auto_include_builtin_models: true # false: exponer solo la lista de abajo

759models:759models:

760 - id: claude-opus-4-8760 - id: claude-opus-4-8

761 label: Claude Opus 4.8761 label: Claude Opus 4.8

762 # description: texto opcional mostrado en clientes que lo muestren762 # description: texto opcional que se muestra en los clientes que lo muestran

763 upstream_model:763 upstream_model:

764 anthropic: claude-opus-4-8764 anthropic: claude-opus-4-8

765 bedrock: us.anthropic.claude-opus-4-8 # o un ARN de perfil de inferencia765 bedrock: us.anthropic.claude-opus-4-8 # o un ARN de perfil de inferencia

766 foundry: your-opus-deployment-name766 foundry: your-opus-deployment-name

767```767```

768 768

769Cada clave bajo `upstream_model` debe coincidir con el `name` de un upstream configurado, que por defecto es el nombre del proveedor. Una clave que no coincida con ningún upstream falla al arrancar, así que omita las líneas para proveedores que no use.769Cada clave bajo `upstream_model` debe coincidir con el `name` de un upstream configurado, que de forma predeterminada es el nombre del proveedor. Una clave que no coincide con ningún upstream hace fallar el arranque, así que omite las líneas de los proveedores que no uses.

770 770

771<h3 id="managed">771<h3 id="managed">

772 `managed`772 `managed`

773</h3>773</h3>

774 774

775El bloque `managed` define políticas de acceso basadas en roles con clave en grupos de IdP o dominio de correo electrónico. Las políticas se evalúan en orden; se selecciona la primera coincidencia, luego se fusiona en la base de captura general `match: {}`. Se sirven por usuario en `GET /managed/settings` con almacenamiento en caché ETag/304.775El bloque `managed` define políticas de acceso basadas en roles según grupos de IdP o dominio de correo electrónico. Las políticas se evalúan en orden; se selecciona la primera coincidencia y luego se fusiona sobre la base de captura general `match: {}`. Se sirven por usuario en `GET /managed/settings` con almacenamiento en caché ETag/304.

776 776

777```yaml theme={null}777```yaml theme={null}

778managed:778managed:

782 cli:782 cli:

783 availableModels: [claude-sonnet-4-6]783 availableModels: [claude-sonnet-4-6]

784 permissions: { deny: ["WebFetch", "WebSearch"] }784 permissions: { deny: ["WebFetch", "WebSearch"] }

785 # Captura general predeterminada última: coincide con todos los que se autenticaron.785 # Captura general predeterminada al final: coincide con todos los que se autenticaron.

786 - match: {}786 - match: {}

787 cli:787 cli:

788 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]788 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

789```789```

790 790

791Una captura general `match: {}`, convencionalmente enumerada última, se trata como una capa base. Todas las demás políticas heredan cualquier clave que no establezcan de la captura general, por lo que las entradas por rol solo necesitan enumerar lo que difiere del valor predeterminado de la organización. Las reglas de fusión dependen del tipo de clave:791Una captura general `match: {}`, que por convención se coloca al final, se trata como una capa base. Todas las demás políticas heredan de la captura general cualquier clave que no establezcan, por lo que las entradas por rol solo necesitan enumerar lo que difiere del valor predeterminado de la organización. Las reglas de fusión dependen del tipo de clave:

792 792

793* **Listas de permitidos**: `availableModels` y `permissions.allow`. La lista de una política específica reemplaza completamente la de la base.793* **Listas de permitidos**: `availableModels` y `permissions.allow`. La lista de una política específica reemplaza por completo la de la base.

794* **Listas de denegación y arrays de hooks**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` y cada array de tipo de evento `hooks`. Estos toman la unión de base y política, por lo que un hook de auditoría o denegación de toda la organización no puede ser eliminado accidentalmente por una anulación por rol.794* **Listas de denegación y arrays de hooks**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` y cada array de tipo de evento de `hooks`. Estas toman la unión de la base y la política, por lo que una sobrescritura por rol no puede eliminar accidentalmente una denegación o un hook de auditoría de toda la organización.

795* **Claves de tipo registro**: `env`, `modelOverrides` y `skillOverrides`. Estos se fusionan superficialmente, por lo que un bloque `env` por rol anula las claves que establece y hereda el resto de la base.795* **Claves de tipo registro**: `env`, `modelOverrides` y `skillOverrides`. Estas se fusionan superficialmente, por lo que un bloque `env` por rol sobrescribe las claves que establece y hereda el resto de la base.

796 796

797`availableModels` también se aplica del lado del servidor en `/v1/messages`, por lo que un modelo denegado devuelve `400` independientemente de lo que envíe el cliente.797`availableModels` también se aplica del lado del servidor en `/v1/messages`, por lo que un modelo denegado devuelve `400` independientemente de lo que envíe el cliente.

798 798

799La puerta de enlace valida el valor `model` en sí antes de retransmitir una solicitud, por lo que un valor mal formado nunca llega a un upstream. Rechaza la solicitud con un `400` en dos casos:799El gateway valida el propio valor de `model` antes de retransmitir una solicitud, por lo que un valor mal formado nunca llega a un upstream. Rechaza la solicitud con un `400` en dos casos:

800 800

801* Cuando el valor falta o está vacío, la puerta de enlace rechaza la solicitud con el mensaje `model is required`. Esa comprobación requiere una puerta de enlace que ejecute Claude Code v2.1.228 o posterior.801* Cuando el valor falta o está vacío, el gateway rechaza la solicitud con el mensaje `model is required`. Esa comprobación requiere un gateway que ejecute Claude Code v2.1.228 o posterior.

802* Cuando el valor está presente pero no es una cadena, la puerta de enlace rechaza la solicitud con el mensaje `model must be a string`. Requiere una puerta de enlace que ejecute Claude Code v2.1.221 o posterior.802* Cuando el valor está presente pero no es una cadena, el gateway rechaza la solicitud con el mensaje `model must be a string`. Requiere un gateway que ejecute Claude Code v2.1.221 o posterior.

803 803

804| Coincidencia | Comportamiento |804| Matcher | Comportamiento |

805| - | - |805| - | - |

806| `match: {}` | Coincide con todos los usuarios autenticados. Comience con uno de estos y agregue políticas con alcance de grupo por encima más tarde. |806| `match: {}` | Coincide con todos los usuarios autenticados. Empieza con uno de estos y agrega más adelante políticas limitadas a grupos por encima de él. |

807| `match: { groups: [a, b] }` | Coincide si la reclamación `groups` del JWT contiene alguno de los grupos enumerados. Sensible a mayúsculas y minúsculas: los grupos deben coincidir con la capitalización exacta del IdP. |807| `match: { groups: [a, b] }` | Coincide si la reclamación `groups` del JWT contiene alguno de los grupos enumerados. Distingue mayúsculas de minúsculas: los grupos deben coincidir con la capitalización exacta del IdP. |

808| `match: { email_domain: example.com }` | Coincide con la parte después de la última `@` en la reclamación `email` del JWT, sin distinción de mayúsculas y minúsculas. Acepta un dominio por política. |808| `match: { email_domain: example.com }` | Coincide con la parte posterior a la última `@` en la reclamación `email` del JWT, sin distinguir mayúsculas de minúsculas. Acepta un dominio por política. |

809| `match: { groups: [a], email_domain: example.com }` | Ambas condiciones deben coincidir |809| `match: { groups: [a], email_domain: example.com }` | Ambas condiciones deben coincidir |

810 810

811Un usuario autenticado que no coincida con ninguna política obtiene los valores predeterminados de la puerta de enlace, lo que significa cada modelo en el catálogo y sin configuración administrada. Agregue una captura general `match: {}` última si desea una política predeterminada garantizada.811Un usuario autenticado que no coincide con ninguna política obtiene los valores predeterminados del gateway, es decir, todos los modelos del catálogo y ninguna configuración administrada. Agrega una captura general `match: {}` al final si quieres una política predeterminada garantizada.

812 812

813<Note>813<Note>

814 La puerta de enlace no mantiene su propio directorio de usuarios. Autoriza cada solicitud desde el token de IdP del usuario, leyendo la pertenencia al grupo de la reclamación `groups` del token y evaluando políticas contra ella. No hay un registro para enumerar y no hay cuentas para crear previamente, y por lo tanto no hay punto final SCIM, porque no hay nada para que SCIM sincronice.814 El gateway no mantiene un directorio de usuarios propio. Autoriza cada solicitud a partir del token de IdP del usuario, leyendo la pertenencia a grupos de la reclamación `groups` del token y evaluando las políticas con ella. No hay una lista de usuarios que enumerar ni cuentas que crear previamente y, por lo tanto, no hay endpoint SCIM, porque no hay nada en lo que SCIM pueda sincronizar.

815 815

816 Ejecute la gestión del ciclo de vida de usuarios y grupos en la fuente de verdad, que es el aprovisionamiento SCIM nativo de su IdP o una plataforma dedicada de gobernanza de identidad. La pertenencia y desaprovisionamiento gobernados allí fluyen hacia la puerta de enlace automáticamente a través del token. Si desea el aprovisionamiento SCIM de las propias cuentas de Claude, esa es una capacidad de [Claude para Empresas](/docs/es/admin-setup).816 Gestiona el ciclo de vida de usuarios y grupos en la fuente de verdad, que es el aprovisionamiento SCIM nativo de tu IdP o una plataforma dedicada de gobernanza de identidades. La pertenencia y el desaprovisionamiento gestionados allí llegan al gateway automáticamente a través del token. Si quieres aprovisionamiento SCIM de las propias cuentas de Claude, esa es una capacidad de [Claude for Enterprise](/docs/es/admin-setup).

817 817

818 Se aplican dos relojes de propagación:818 Se aplican dos tiempos de propagación:

819 819

820 * **Contenidos de política**: editar una política y reimplementar llega a clientes conectados en su próxima encuesta de configuración administrada, dentro de una hora, aparte de los [cambios que se aplican solo en el próximo lanzamiento](/docs/es/server-managed-settings#fetch-and-caching-behavior)820 * **Contenido de las políticas**: editar una política y volver a desplegar llega a los clientes conectados en su siguiente consulta de la configuración administrada, en menos de una hora, salvo los [cambios que solo se aplican en el siguiente inicio](/docs/es/server-managed-settings#fetch-and-caching-behavior)

821 * **Pertenencia al grupo**: cambiar la pertenencia al grupo de un usuario cambia qué política los coincide. Esto entra en vigor en el próximo acuñamiento de sesión, lo que significa la próxima actualización silenciosa, limitada por `session.ttl_hours`.821 * **Pertenencia a grupos**: cambiar la pertenencia a grupos de un usuario cambia qué política coincide con él. Esto surte efecto en la siguiente nueva emisión de la sesión, es decir, en la siguiente actualización silenciosa, con un límite de `session.ttl_hours`.

822</Note>822</Note>

823 823

824<h4 id="matcher-values-that-stop-the-gateway-at-boot">824<h4 id="matcher-values-that-stop-the-gateway-at-boot">

825 Valores de coincidencia que detienen la puerta de enlace al arrancar825 Valores de matcher que detienen el gateway al arrancar

826</h4>826</h4>

827 827

828Al arrancar, la puerta de enlace comprueba el bloque `match` de cada política y la lista [`admin_groups`](#admin). Cualquiera de estos valores detiene la puerta de enlace con un error que nombra el campo:828Al arrancar, el gateway comprueba el bloque `match` de cada política y la lista [`admin_groups`](#admin). Cualquiera de estos valores detiene el gateway con un error que nombra el campo:

829 829

830* Una lista `groups` vacía830* Una lista `groups` vacía

831* Una entrada vacía en `groups` o en `admin_groups`831* Una entrada vacía en `groups` o en `admin_groups`

832* Un `email_domain` vacío832* Un `email_domain` vacío

833* Un `email_domain` que contiene `@`, espacios en blanco o una coma. La puerta de enlace recorta el valor y elimina una `@` inicial antes de esta comprobación. Escriba un dominio desnudo, como `example.com`.833* Un `email_domain` que contiene `@`, espacios en blanco o una coma. El gateway recorta el valor y elimina una `@` inicial antes de esta comprobación. Escribe un solo dominio sin más, como `example.com`.

834 834

835Antes de v2.1.232, la puerta de enlace comenzaba con estos valores. Cada valor tenía este efecto:835Antes de v2.1.232, el gateway arrancaba con estos valores. Cada valor tenía este efecto:

836 836

837* Un `email_domain` vacío: la puerta de enlace omitía la comprobación de dominio, por lo que una política con un `email_domain` vacío y sin lista `groups` coincidía con todos los usuarios autenticados837* Un `email_domain` vacío: el gateway omitía la comprobación de dominio, por lo que una política con un `email_domain` vacío y sin lista `groups` coincidía con todos los usuarios autenticados

838* Una lista `groups` vacía: la política no coincidía con nadie838* Una lista `groups` vacía: la política no coincidía con nadie

839* Un `email_domain` que contiene `@`, espacios en blanco o una coma: la política no coincidía con nadie839* Un `email_domain` que contenía `@`, espacios en blanco o una coma: la política no coincidía con nadie

840* Una entrada vacía en `groups` o en `admin_groups`: la entrada coincidía con un usuario solo cuando la reclamación `groups` de IdP de ese usuario también contenía una entrada vacía. En `admin_groups`, esa coincidencia otorgaba acceso de administrador. Si su lista `admin_groups` nunca contenía una entrada vacía, nadie obtenía acceso de administrador de esta manera.840* Una entrada vacía en `groups` o en `admin_groups`: la entrada coincidía con un usuario solo cuando la reclamación `groups` del IdP de ese usuario también contenía una entrada vacía. En `admin_groups`, esa coincidencia otorgaba acceso de administrador. Si tu lista `admin_groups` nunca contuvo una entrada vacía, nadie obtuvo acceso de administrador de esta manera.

841 841

842<h4 id="what-goes-in-cli">842<h4 id="what-goes-in-cli">

843 Qué va en `cli`843 Qué va en `cli`

844</h4>844</h4>

845 845

846Cada valor `cli` es un documento completo de `managed-settings.json` de Claude Code, el mismo esquema que implementaría a través de MDM o `/etc/claude-code/managed-settings.json`, expresado aquí como YAML. El CLI aplica el documento entregado en el nivel administrado, por encima de la configuración de usuario y proyecto, en lugar de la configuración administrada por servidor. Por lo tanto, ignora la configuración [restringida a fuentes de política a nivel de SO](/docs/es/server-managed-settings#current-limitations), como `policyHelper` y `wslInheritsWindowsSettings`.846Cada valor de `cli` es un documento `managed-settings.json` completo de Claude Code, el mismo esquema que desplegarías mediante MDM o `/etc/claude-code/managed-settings.json`, expresado aquí como YAML. El CLI aplica el documento entregado en el nivel administrado, por encima de la configuración de usuario y de proyecto, en lugar de la configuración administrada por el servidor. Por lo tanto, ignora los ajustes [restringidos a fuentes de políticas a nivel del sistema operativo](/docs/es/server-managed-settings#current-limitations), como `policyHelper` y `wslInheritsWindowsSettings`.

847 847

848La puerta de enlace valida cada documento contra el esquema de configuración del CLI al arrancar, por lo que una clave de nivel superior no reconocida falla al arrancar con un error que nombra cada clave ofensiva. Las partes deliberadamente abiertas del esquema aún aceptan valores arbitrarios, porque clientes más nuevos pueden reconocer entradas que el esquema de la puerta de enlace no. Estas claves abiertas incluyen `env`, `pluginConfigs` y claves anidadas bajo `permissions`.848El gateway valida cada documento con el esquema de configuración del CLI al arrancar, por lo que una clave de nivel superior no reconocida hace fallar el arranque con un error que nombra cada clave problemática. Las partes deliberadamente abiertas del esquema siguen aceptando valores arbitrarios, porque los clientes más nuevos pueden reconocer entradas que el esquema del gateway no reconoce. Estas claves abiertas incluyen `env`, `pluginConfigs` y las claves anidadas bajo `permissions`.

849 849

850Debido a que la validación utiliza el esquema incluido con la versión instalada de la puerta de enlace, poner una clave de configuración de nivel superior introducida por una versión más nueva de Claude Code en la configuración administrada requiere actualizar primero la puerta de enlace. Pruebe una nueva política en un cliente antes de implementarla.850Como la validación usa el esquema incluido con la versión instalada del gateway, poner en la configuración administrada una clave de configuración de nivel superior introducida por una versión más reciente de Claude Code requiere actualizar primero el gateway. Haz una prueba rápida de una política nueva en un cliente antes de desplegarla.

851 851

852La referencia de clave completa está en [Configuración de Claude Code](/docs/es/settings-reference#all-settings). Las claves que los operadores buscan primero:852La referencia completa de claves está en [Configuración de Claude Code](/docs/es/settings-reference#all-settings). Las claves que los operadores usan primero:

853 853

854```yaml theme={null}854```yaml theme={null}

855managed:855managed:

866 - "Read(./.env)"866 - "Read(./.env)"

867 - "Read(./secrets/**)"867 - "Read(./secrets/**)"

868 disableBypassPermissionsMode: disable # bloquea --dangerously-skip-permissions868 disableBypassPermissionsMode: disable # bloquea --dangerously-skip-permissions

869 allowManagedPermissionRulesOnly: true # ignora reglas de permisos de usuario/proyecto869 allowManagedPermissionRulesOnly: true # ignora las reglas de permisos de usuario/proyecto

870 870

871 # Entorno insertado en el proceso CLI. DISABLE_UPDATES bloquea871 # Entorno enviado al proceso del CLI. DISABLE_UPDATES bloquea

872 # actualizaciones de fondo y manuales; DISABLE_AUTOUPDATER detiene solo872 # las actualizaciones en segundo plano y manuales; DISABLE_AUTOUPDATER detiene solo

873 # actualizaciones de fondo.873 # las actualizaciones en segundo plano.

874 env:874 env:

875 DISABLE_UPDATES: "1" # fijar versiones a través de su propia distribución875 DISABLE_UPDATES: "1" # fija las versiones mediante tu propia distribución

876 876

877 # Hooks de toda la organización. Los comandos de hook se ejecutan en máquinas de desarrollador, no en la877 # Hooks de toda la organización. Los comandos de hook se ejecutan en las máquinas de los desarrolladores, no en el

878 # puerta de enlace, por lo que la ruta debe existir en cada SO cliente en la política.878 # gateway, por lo que la ruta debe existir en cada sistema operativo cliente de la política.

879 hooks:879 hooks:

880 PostToolUse:880 PostToolUse:

881 - matcher: "Edit|Write"881 - matcher: "Edit|Write"

885 885

887| - | - | - |887| - | - | - |

889| `permissions.allow` / `.deny` | CLI | Reglas de herramientas y comandos. Consulte [Permisos](/docs/es/permissions). |889| `permissions.allow` / `.deny` | CLI | Reglas de herramientas y comandos. Consulta [Permisos](/docs/es/permissions). |

890| `permissions.disableBypassPermissionsMode` | CLI | Establezca en `disable` para bloquear [`bypassPermissions`](/docs/es/permission-modes#skip-all-checks-with-bypasspermissions-mode), el modo que omite indicadores de permisos, y la bandera `--dangerously-skip-permissions` |890| `permissions.disableBypassPermissionsMode` | CLI | Establécelo en `disable` para bloquear [`bypassPermissions`](/docs/es/permission-modes#skip-all-checks-with-bypasspermissions-mode), el modo que omite las solicitudes de permiso, y el flag `--dangerously-skip-permissions` |

891| `allowManagedPermissionRulesOnly` | CLI | Cuando es `true`, la configuración administrada se convierte en la única fuente de configuración de reglas de permisos. La entrada [`allowManagedPermissionRulesOnly`](/docs/es/settings-reference#allowmanagedpermissionrulesonly) enumera todas las fuentes que Claude Code luego ignora. |891| `allowManagedPermissionRulesOnly` | CLI | Cuando es `true`, la configuración administrada pasa a ser la única fuente de configuración de reglas de permisos. La entrada [`allowManagedPermissionRulesOnly`](/docs/es/settings-reference#allowmanagedpermissionrulesonly) enumera todas las fuentes que Claude Code ignora entonces. |

892| `env` | CLI | Variables de entorno fusionadas en el proceso CLI. Úselo para telemetría, actualización automática y anulaciones de nombres de modelos. |892| `env` | CLI | Variables de entorno combinadas en el proceso del CLI. Úsalas para telemetría, actualización automática y sobrescrituras de nombres de modelos. |

893| `hooks` | CLI | Hooks de toda la organización [hooks](/docs/es/hooks) |893| `hooks` | CLI | [Hooks](/docs/es/hooks) de toda la organización |

894| `managedMcpServers` | CLI | Servidores MCP remotos [proporcionados a cada desarrollador coincidente](/docs/es/managed-mcp#provide-servers-through-managed-settings) junto con los servidores que agregan ellos mismos, solo `http` y `sse`. Consulte [Servidores MCP en una política](#mcp-servers-in-a-policy). Requiere Claude Code v2.1.259 o posterior en el servidor de puerta de enlace y en clientes. Los clientes anteriores ignoran la clave. |894| `managedMcpServers` | CLI | Servidores MCP remotos [proporcionados a cada desarrollador que coincide](/docs/es/managed-mcp#provide-servers-through-managed-settings) junto con los servidores que agregan ellos mismos, solo `http` y `sse`. Consulta [Servidores MCP en una política](#mcp-servers-in-a-policy). Requiere Claude Code v2.1.259 o posterior en el servidor del gateway y en los clientes. Los clientes anteriores ignoran la clave. |

895 895

896Debido a que estas configuraciones llegan a través de la red, el CLI muestra a cada desarrollador un diálogo de aprobación de seguridad antes de aplicar la configuración enumerada a continuación:896Como estos ajustes llegan a través de la red, el CLI muestra a cada desarrollador un diálogo de aprobación de seguridad antes de aplicar los ajustes que se enumeran a continuación:

897 897

898* `hooks`898* `hooks`

899* Variables `env` que requieren la aprobación del desarrollador, como variables de proxy y URL base899* variables de `env` que requieren la aprobación del desarrollador, como las variables de proxy y de URL base

900* configuración de ejecución de shell como `apiKeyHelper` y `statusLine`900* ajustes de ejecución de shell como `apiKeyHelper` y `statusLine`

901* la configuración de binario de sandbox `sandbox.bwrapPath`, `sandbox.socatPath` y `sandbox.ripgrep`901* los ajustes de binarios del sandbox `sandbox.bwrapPath`, `sandbox.socatPath` y `sandbox.ripgrep`

902* Configuración de Sandbox que intercepta tráfico, inyecta credenciales o debilita el aislamiento, como `sandbox.network.tlsTerminate` y la configuración del puerto proxy. [Diálogos de aprobación de seguridad](/docs/es/server-managed-settings#security-approval-dialogs) los enumera todos.902* Ajustes del sandbox que interceptan tráfico, inyectan credenciales o debilitan el aislamiento, como `sandbox.network.tlsTerminate` y los ajustes de puerto del proxy. [Diálogos de aprobación de seguridad](/docs/es/server-managed-settings#security-approval-dialogs) los enumera todos.

903 903

904[Memoria de aprobación](/docs/es/server-managed-settings#approval-memory) cubre cuánto tiempo dura una aprobación y cuándo aparece el diálogo nuevamente.904[Memoria de aprobación](/docs/es/server-managed-settings#approval-memory) explica cuánto dura una aprobación y cuándo vuelve a aparecer el diálogo.

905 905

906Claude Code aplica algunas variables `env` entregadas sin mostrar al desarrollador el diálogo de aprobación de seguridad, como configuración de selección de modelos y límites numéricos. Otras variables entregadas pueden requerir la aprobación del desarrollador antes de que surtan efecto; un valor de proxy, URL base u `OTEL_EXPORTER_OTLP_ENDPOINT` no vacío siempre lo hace. Cuando una variable entregada necesita aprobación, el diálogo la nombra.906Claude Code aplica algunas variables de `env` entregadas sin mostrar al desarrollador el diálogo de aprobación, como los ajustes de selección de modelo y los límites numéricos. Otras variables entregadas pueden requerir la aprobación del desarrollador antes de surtir efecto; un valor no vacío de proxy, URL base u `OTEL_EXPORTER_OTLP_ENDPOINT` siempre la requiere. Cuando una variable entregada necesita aprobación, el diálogo la nombra.

907 907

908[Variables de entorno y el diálogo de aprobación](/docs/es/server-managed-settings#environment-variables-and-the-approval-dialog) tiene los detalles, incluidos cuatro conmutadores de privacidad cuyo valor entregado decide si necesitan aprobación. Antes de v2.1.218, Claude Code aplicaba menos variables sin preguntar al desarrollador, por lo que más variables entregadas activaban el diálogo.908[Variables de entorno y el diálogo de aprobación](/docs/es/server-managed-settings#environment-variables-and-the-approval-dialog) tiene los detalles, incluidos cuatro interruptores de privacidad cuyo valor entregado decide si necesitan aprobación. Antes de v2.1.218, Claude Code aplicaba menos variables sin preguntar al desarrollador, por lo que más variables entregadas activaban el diálogo.

909 909

910La configuración de [telemetría](#telemetry) de la puerta de enlace inserta `OTEL_EXPORTER_OTLP_ENDPOINT`, por lo que establecer `telemetry.forward_to` activa el diálogo en cada cliente interactivo. El diálogo protege la máquina del desarrollador de una puerta de enlace comprometida u hostil, no la organización del desarrollador.910La configuración de [telemetría](#telemetry) del gateway envía `OTEL_EXPORTER_OTLP_ENDPOINT`, por lo que establecer `telemetry.forward_to` activa el diálogo en cada cliente interactivo. El diálogo protege la máquina del desarrollador frente a un gateway comprometido u hostil, no a la organización frente al desarrollador.

911 911

912Una [ejecución no interactiva](/docs/es/server-managed-settings#security-approval-dialogs), como `claude -p` o una sesión de Agent SDK, no puede mostrar el diálogo. Aplica la configuración insertada para esa ejecución solo y no la registra como aprobada, por lo que la próxima sesión interactiva del desarrollador aún muestra el diálogo para ellas. Antes de v2.1.207, una ejecución no interactiva guardaba la configuración como aprobada y ninguna sesión interactiva posterior mostraba el diálogo para ellas.912Una [ejecución no interactiva](/docs/es/server-managed-settings#security-approval-dialogs), como `claude -p` o una sesión del Agent SDK, no puede mostrar el diálogo. Aplica los ajustes enviados solo para esa ejecución y no los registra como aprobados, por lo que la siguiente sesión interactiva del desarrollador sigue mostrando el diálogo. Antes de v2.1.207, una ejecución no interactiva guardaba los ajustes como aprobados y ninguna sesión interactiva posterior mostraba el diálogo para ellos.

913 913

914Si un desarrollador rechaza, Claude Code sale de esa sesión en lugar de aplicar la política. Cuando inserta un nuevo hook, o cualquier variable env que active el diálogo, en una política amplia, cada desarrollador coincidente ve el diálogo en sus sesiones interactivas. Una sesión interactiva en ejecución lo muestra en la próxima encuesta cada hora, y de lo contrario aparece en el próximo inicio interactivo del desarrollador.914Si un desarrollador rechaza, Claude Code cierra esa sesión en lugar de aplicar la política. Por lo tanto, cuando envías un hook nuevo, o cualquier variable de entorno que active el diálogo, a una política amplia, cada desarrollador que coincide ve el diálogo en sus sesiones interactivas. Una sesión interactiva en ejecución lo muestra en la siguiente consulta horaria y, de lo contrario, aparece en el siguiente inicio interactivo del desarrollador.

915 915

916La clave `cli` se llamaba `settings` en versiones anteriores. Esa ortografía aún se acepta como alias, pero las nuevas implementaciones deben usar `cli`.916La clave `cli` se llamaba `settings` en versiones anteriores. Esa forma sigue aceptándose como alias, pero los despliegues nuevos deben usar `cli`.

917

918<h4 id="context-window-in-terminal-sessions">

919 Ventana de contexto en sesiones de terminal

920</h4>

921

922Las sesiones de terminal iniciadas mediante `/login` usan la ventana de contexto de 1M para Opus 4.7 y posteriores, Sonnet 5 y posteriores, y los modelos Fable. El ID del modelo no necesita el sufijo `[1m]`, y las sesiones se compactan en torno a 967K tokens. Antes de Claude Code v2.1.287 en la máquina del desarrollador, Claude Code trataba los modelos Opus y Fable como si tuvieran una ventana de 200K, a menos que el ID del modelo terminara en `[1m]`.

923

924Para que las sesiones de terminal se compacten en el límite de 200K, establece la [ventana de compactación automática](/docs/es/model-config#set-the-auto-compact-window) en el `env` de la política:

925

926```yaml theme={null}

927managed:

928 policies:

929 - match: {}

930 cli:

931 env:

932 CLAUDE_CODE_AUTO_COMPACT_WINDOW: "200000"

933```

934

935Claude Code aplica esta variable sin mostrar al desarrollador el diálogo de aprobación. La variable se aplica a todos los modelos, incluidos los ID de modelo que terminan en `[1m]`.

936

937Para desactivar el contexto de 1M, establece [`CLAUDE_CODE_DISABLE_1M_CONTEXT: "1"`](/docs/es/model-config#extended-context) en el mismo bloque `env`. Claude Code trata entonces todos los modelos como si tuvieran una ventana de 200K. En las sesiones interactivas, cada desarrollador aprueba esta variable en el [diálogo de aprobación](#what-goes-in-cli) antes de que surta efecto.

917 938

918<h4 id="mcp-servers-in-a-policy">939<h4 id="mcp-servers-in-a-policy">

919 Servidores MCP en una política940 Servidores MCP en una política

920</h4>941</h4>

921 942

922Para proporcionar servidores MCP a los clientes de Claude Code que coincida una política, establezca [`managedMcpServers`](/docs/es/managed-mcp#provide-servers-through-managed-settings) en el bloque `cli` de esa política. Necesita Claude Code v2.1.259 o posterior en el servidor de puerta de enlace y en clientes.943Para proporcionar servidores MCP a los clientes de Claude Code que coinciden con una política, establece [`managedMcpServers`](/docs/es/managed-mcp#provide-servers-through-managed-settings) en el bloque `cli` de esa política. Necesitas Claude Code v2.1.259 o posterior en el servidor del gateway y en los clientes.

923 944

924La puerta de enlace comprueba cada entrada al arrancar con [las mismas reglas que Claude Code aplica en el cliente](/docs/es/managed-mcp#what-an-entry-can-contain), y si una entrada falla una comprobación, la puerta de enlace se niega a iniciar y nombra la entrada.945El gateway comprueba cada entrada al arrancar con [las mismas reglas que Claude Code aplica en el cliente](/docs/es/managed-mcp#what-an-entry-can-contain) y, si una entrada no supera una comprobación, el gateway se niega a iniciar y nombra la entrada.

925 946

926Si escribe una referencia `${VAR}` en `gateway.yaml`, la puerta de enlace la resuelve desde su entorno al arrancar a través de [expansión de secretos](#secret-expansion) antes de ejecutar las comprobaciones de entrada, por lo que cada cliente coincidente recibe el valor literal y puede leerlo. La [orientación de encabezado para servidores proporcionados](/docs/es/managed-mcp#provide-servers-through-managed-settings) se aplica al valor expandido.947Si escribes una referencia `${VAR}` en `gateway.yaml`, el gateway la resuelve desde su entorno al arrancar mediante la [expansión de secretos](#secret-expansion) antes de ejecutar las comprobaciones de entradas, por lo que cada cliente que coincide recibe el valor literal y puede leerlo. La [orientación sobre encabezados para servidores proporcionados](/docs/es/managed-mcp#provide-servers-through-managed-settings) se aplica al valor expandido.

927 948

928La puerta de enlace rechaza la ortografía `.mcp.json` `mcpServers` en un bloque `cli`, y su error de arranque nombra `managedMcpServers` como la clave a usar. Antes de v2.1.259, la puerta de enlace rechazaba cualquier definición de servidor MCP en un bloque `cli`.949El gateway rechaza la forma `mcpServers` de `.mcp.json` en un bloque `cli`, y su error de arranque indica `managedMcpServers` como la clave que debes usar. Antes de v2.1.259, el gateway rechazaba cualquier definición de servidor MCP en un bloque `cli`.

929 950

930<h4 id="claude-desktop-overlay">951<h4 id="claude-desktop-overlay">

931 Superposición de Claude Desktop952 Superposición de Claude Desktop

932</h4>953</h4>

933 954

934Si su organización también implementa [Claude Desktop](/docs/es/desktop), la misma puerta de enlace sirve a ambos clientes. Apunte `bootstrapUrl`, en la [configuración administrada](https://claude.com/docs/third-party/claude-desktop/configuration) de Claude Desktop, a `<listen.public_url>/user/bootstrap`. Claude Desktop deriva el emisor de OAuth de esa URL, ejecuta el mismo inicio de sesión de código de dispositivo contra esta puerta de enlace y obtiene su configuración de la respuesta.955Si tu organización también despliega [Claude Desktop](/docs/es/desktop), el mismo gateway atiende a ambos clientes. Apunta `bootstrapUrl`, en la [configuración administrada](https://claude.com/docs/third-party/claude-desktop/configuration) de Claude Desktop, a `<listen.public_url>/user/bootstrap`. Claude Desktop deriva el emisor de OAuth de esa URL, ejecuta el mismo inicio de sesión con código de dispositivo contra este gateway y obtiene su configuración de la respuesta.

935 956

936<Note>957<Note>

937 Requiere Claude Code v2.1.203 o posterior en el servidor de puerta de enlace, y una opción explícita: `/user/bootstrap` devuelve 404 a menos que la política que coincida con el usuario lleve una clave `desktop`. Un `desktop: {}` vacío opta una política, y una clave `desktop` en la capa base `match: {}` opta en cada política que la hereda. El registro de auditoría registra cada solicitud como `desktop_bootstrap.serve` o `desktop_bootstrap.denied`.958 Requiere Claude Code v2.1.203 o posterior en el servidor del gateway y una activación explícita: `/user/bootstrap` devuelve 404 a menos que la política que coincide con el usuario tenga una clave `desktop`. Un `desktop: {}` vacío activa una política, y una clave `desktop` en la capa base `match: {}` activa todas las políticas que la heredan. El registro de auditoría registra cada solicitud como `desktop_bootstrap.serve` o `desktop_bootstrap.denied`.

938</Note>959</Note>

939 960

940La puerta de enlace deriva gran parte de la respuesta del bloque `cli` de la política coincidente y de la configuración de puerta de enlace de nivel superior:961El gateway deriva gran parte de la respuesta del bloque `cli` de la política coincidente y de la configuración de nivel superior del gateway:

941 962

942* La lista de modelos, de `availableModels`963* La lista de modelos, de `availableModels`. [Contexto extendido en Claude Desktop](#extended-context-in-claude-desktop) explica la opción de contexto de 1M de cada modelo

943* Herramientas deshabilitadas, de entradas `permissions.deny` de nombre de herramienta desnuda. Si establece `disabledBuiltinTools` en el bloque `desktop` de la política, la puerta de enlace sirve la unión de su valor y la lista derivada, por lo que puede deshabilitar más herramientas de esta manera pero no puede volver a habilitar una que deshabilitó a través de `permissions.deny`964* Las herramientas deshabilitadas, de las entradas de `permissions.deny` que son solo un nombre de herramienta. Si estableces `disabledBuiltinTools` en el bloque `desktop` de la política, el gateway sirve la unión de tu valor y la lista derivada, por lo que puedes deshabilitar más herramientas de esta manera, pero no puedes volver a habilitar una que deshabilitaste mediante `permissions.deny`

944* La lista de permitidos de salida, de `sandbox.network.allowedDomains`. Si establece `coworkEgressAllowedHosts` en el bloque `desktop` de la política, la puerta de enlace usa ese valor en lugar de la lista derivada965* La lista de permitidos de salida, de `sandbox.network.allowedDomains`. Si estableces `coworkEgressAllowedHosts` en el bloque `desktop` de la política, el gateway usa ese valor en lugar de la lista derivada

945* Un punto final OTLP que apunta a la puerta de enlace en sí, y los atributos de identidad del usuario conectado. La puerta de enlace retransmite las exportaciones que recibe en ese punto final a sus destinos `forward_to`. Incluye el punto final y los atributos cuando establece tanto [`telemetry.forward_to`](#telemetry) como `listen.public_url`.966* Un endpoint OTLP que apunta al propio gateway y los atributos de identidad del usuario con sesión iniciada. El gateway retransmite las exportaciones que recibe en ese endpoint a tus destinos `forward_to`. Incluye el endpoint y los atributos cuando estableces tanto [`telemetry.forward_to`](#telemetry) como `listen.public_url`.

946 967

947 Claude Desktop exporta cada señal con una codificación: `http/protobuf`, o `http/json` cuando establece `OTEL_EXPORTER_OTLP_PROTOCOL` o una de sus variantes por señal en `http/json` en el `env` de la política. Antes de Claude Code v2.1.261 en el servidor de puerta de enlace, la respuesta establecía `http/json` independientemente, por lo que un recopilador que acepta solo protobuf rechazaba las exportaciones de Claude Desktop968 Claude Desktop exporta cada señal con una sola codificación: `http/protobuf`, o `http/json` cuando estableces `OTEL_EXPORTER_OTLP_PROTOCOL` o una de sus variantes por señal en `http/json` en el `env` de la política. Antes de Claude Code v2.1.261 en el servidor del gateway, la respuesta establecía `http/json` en cualquier caso, por lo que un recopilador que solo acepta protobuf rechazaba las exportaciones de Claude Desktop

948 969

949Para establecer `disabledBuiltinTools`, `coworkEgressAllowedHosts` o la configuración `managedMcpServers` propia de Claude Desktop en el bloque `desktop` de una política, necesita Claude Code v2.1.232 o posterior en el servidor de puerta de enlace. El `managedMcpServers` de Claude Desktop toma un valor de array en lugar de un objeto.970Para establecer `disabledBuiltinTools`, `coworkEgressAllowedHosts` o el ajuste `managedMcpServers` propio de Claude Desktop en el bloque `desktop` de una política, necesitas Claude Code v2.1.232 o posterior en el servidor del gateway. El `managedMcpServers` de Claude Desktop toma un valor de array en lugar de un objeto.

950 971

951La puerta de enlace omite claves sin equivalente de Claude Desktop, como `hooks` y reglas de permisos con alcance como `Bash(npm *)`, de la respuesta de arranque.972El gateway omite de la respuesta de bootstrap las claves sin equivalente en Claude Desktop, como `hooks` y las reglas de permisos con alcance como `Bash(npm *)`.

952 973

953Agregue el bloque `desktop` opcional junto a `cli` para establecer la configuración de Claude Desktop directamente. Escriba la configuración de la [referencia de configuración administrada](https://claude.com/docs/third-party/claude-desktop/configuration) de Claude Desktop como nombres de clave planos. Deje fuera las claves que Claude Desktop lee solo de MDM o archivos locales, como `bootstrapUrl`; la puerta de enlace las rechaza al arrancar. Antes de v2.1.232, la puerta de enlace aceptaba una lista fija de 11 claves de puerta de características, como `chatTabEnabled` y `disableAutoUpdates`, y rechazaba todas las demás claves al arrancar. Antes de v2.1.227, la puerta de enlace también rechazaba `chatTabEnabled` y `chatAdvancedFileAnalysisEnabled` al arrancar.974Agrega el bloque opcional `desktop` junto a `cli` para establecer directamente la configuración de Claude Desktop. Escribe los ajustes de la [referencia de configuración administrada](https://claude.com/docs/third-party/claude-desktop/configuration) de Claude Desktop como nombres de clave planos. Omite las claves que Claude Desktop lee solo de MDM o de archivos locales, como `bootstrapUrl`; el gateway las rechaza al arrancar. Antes de v2.1.232, el gateway aceptaba una lista fija de 11 claves de activación de funciones, como `chatTabEnabled` y `disableAutoUpdates`, y rechazaba todas las demás claves al arrancar. Antes de v2.1.227, el gateway también rechazaba `chatTabEnabled` y `chatAdvancedFileAnalysisEnabled` al arrancar.

954 975

955```yaml theme={null}976```yaml theme={null}

956managed:977managed:

964 banner: { text: "Contractor build: internal use only" }985 banner: { text: "Contractor build: internal use only" }

965```986```

966 987

967Cada clave es opcional; Claude Desktop aplica su propio valor predeterminado para cualquier clave que omita. La puerta de enlace valida cada bloque `desktop` al arrancar contra el esquema de configuración que Claude Desktop usa, por lo que un error aparece al inicio de la puerta de enlace como un error que nombra la clave en lugar de llegar a cada escritorio conectado. La puerta de enlace falla al arrancar cuando un bloque contiene:988Todas las claves son opcionales; Claude Desktop aplica su propio valor predeterminado para cualquier clave que omitas. El gateway valida cada bloque `desktop` al arrancar con el mismo esquema de configuración que usa Claude Desktop, por lo que un error aparece al iniciar el gateway como un mensaje que nombra la clave, en lugar de llegar a cada escritorio conectado. El gateway falla al arrancar cuando un bloque contiene:

968 989

969* Una clave desconocida990* Una clave desconocida

970* Una clave reconocida cuyo valor Claude Desktop rechazaría o dejaría caer silenciosamente, como un valor vacío o una subclave mal escrita dentro de una entrada anidada. Antes de v2.1.260, la puerta de enlace dejaba caer silenciosamente un campo mal escrito dentro de un objeto anidado de una entrada `managedMcpServers` u `orgPluginSettings` en lugar de fallar al arrancar.991* Una clave reconocida cuyo valor Claude Desktop rechazaría o descartaría silenciosamente, como un valor vacío o una subclave mal escrita dentro de una entrada anidada. Antes de v2.1.260, el gateway descartaba silenciosamente un campo mal escrito dentro de un objeto anidado de una entrada `managedMcpServers` u `orgPluginSettings` en lugar de fallar al arrancar.

971* Una clave que la puerta de enlace calcula en sí: la conexión de inferencia, la lista de modelos y el relé OTLP. Configure esos a través de [`upstreams`](#upstreams), [`models`](#models) y la sección [`telemetry`](#telemetry) de `forward_to`.992* Una clave que el propio gateway calcula: la conexión de inferencia, la lista de modelos y la retransmisión OTLP. Configúralas mediante [`upstreams`](#upstreams), [`models`](#models) y el `forward_to` de la sección [`telemetry`](#telemetry).

972* Un alias heredado de una clave actual. En el error de arranque, la puerta de enlace nombra la clave canónica a escribir.993* Un alias heredado de una clave actual. En el error de arranque, el gateway nombra la clave canónica que debes escribir.

994

995Si usas un valor o una forma de entrada obsoletos, como una entrada `managedMcpServers` sin `transport`, el gateway arranca y registra una advertencia que nombra el reemplazo.

973 996

974Si usa un valor o forma de entrada obsoleta, como una entrada `managedMcpServers` sin `transport`, la puerta de enlace se inicia y registra una advertencia que nombra el reemplazo.997El gateway valida un bloque `desktop` con el esquema incluido en su versión instalada, igual que hace con el bloque `cli`. Para entregar un ajuste introducido por una versión más reciente de Claude Desktop, actualiza primero el gateway. Por ejemplo, `userPluginMarketplacesEnabled` y `userPluginUploadsEnabled` necesitan Claude Code v2.1.260 o posterior en el servidor del gateway y Claude Desktop 1.37937.0 o posterior en las máquinas de los miembros.

975 998

976La puerta de enlace valida un bloque `desktop` contra el esquema incluido con su versión instalada, como lo hace con el bloque `cli`. Para entregar una configuración introducida por una versión más nueva de Claude Desktop, actualice primero la puerta de enlace. Por ejemplo, `userPluginMarketplacesEnabled` y `userPluginUploadsEnabled` necesitan Claude Code v2.1.260 o posterior en el servidor de puerta de enlace y Claude Desktop 1.37937.0 o posterior en las máquinas de los miembros.999`blockReadsOutsideWorkingDirectories`, `disableBypassPermissionsMode`, `configRecheckIntervalMinutes` y `sshClientPath` necesitan Claude Code v2.1.281 o posterior en el servidor del gateway. Lo mismo ocurre con el valor `required` de `microsoftAuthBroker` y el campo `continuousAccessEvaluation` de una entrada `managedMcpServers` de Microsoft 365. Las versiones de Claude Desktop anteriores al valor `required` lo leen como `disabled`, así que establece `required` solo después de que el Claude Desktop de todos los miembros lo admita. La [referencia de configuración administrada](https://claude.com/docs/third-party/claude-desktop/configuration) de Claude Desktop indica la versión que lee por primera vez cada clave.

977 1000

978`blockReadsOutsideWorkingDirectories`, `disableBypassPermissionsMode`, `configRecheckIntervalMinutes` y `sshClientPath` necesitan Claude Code v2.1.281 o posterior en el servidor de puerta de enlace. También lo hace el valor `required` de `microsoftAuthBroker` y el campo `continuousAccessEvaluation` de una entrada `managedMcpServers` de Microsoft 365. Los lanzamientos de Claude Desktop que preceden al valor `required` lo leen como `disabled`, así que establezca `required` solo después de que cada miembro de Claude Desktop lo admita. La [referencia de configuración administrada](https://claude.com/docs/third-party/claude-desktop/configuration) de Claude Desktop enumera el lanzamiento que primero lee cada clave.1001Si estableces `orgPluginSettings` en el bloque `desktop` de una política, el gateway lo sirve en la forma de array que leen Claude Desktop 1.15200.0 y posteriores. Los escritorios más antiguos ignoran el array y no aplican ninguna política de herramientas de plugins, así que actualiza a los miembros a 1.15200.0 o posterior antes de depender de ello.

979 1002

980Si establece `orgPluginSettings` en el bloque `desktop` de una política, la puerta de enlace lo sirve en la forma de array que Claude Desktop 1.15200.0 y posterior leen. Los escritorios más antiguos ignoran el array y no aplican ninguna política de herramientas de complemento, así que actualice los miembros a 1.15200.0 o posterior antes de confiar en ello.1003El gateway completa las claves que el bloque `desktop` de una política no establece a partir del bloque `desktop` de la captura general `match: {}`, de la misma manera que completa el bloque `cli` de una política a partir de la base. Si estableces `disabledBuiltinTools` o `builtinToolPolicy` tanto en la base como en una política de rol, el gateway conserva la restricción de la base:

981 1004

982La puerta de enlace rellena las claves que el bloque `desktop` de una política no establece desde el bloque `desktop` de la captura general `match: {}`, de la misma manera que rellena el bloque `cli` de una política desde la base. Si establece `disabledBuiltinTools` o `builtinToolPolicy` en la base y una política de rol, la puerta de enlace mantiene la restricción de la base:1005* `disabledBuiltinTools`: el gateway usa la unión de la lista de la base y la lista de la política

1006* `builtinToolPolicy`: si estableces una herramienta en un valor distinto de `allow` en la base, el gateway conserva ese valor aunque establezcas `allow` para la misma herramienta en una política de rol

1007

1008Para cualquier otra clave, si la estableces en la política de rol, el gateway usa el valor de la política de rol. El gateway reemplaza completo un array o un objeto anidado como `banner`, por lo que si estableces `banner.text` en una política de rol, el gateway descarta el `banner.backgroundColor` de la base.

1009

1010Si no despliegas Claude Desktop, deja `desktop` completamente fuera de tus políticas; el gateway devuelve entonces 404 desde `/user/bootstrap` para todos los usuarios.

1011

1012<h4 id="extended-context-in-claude-desktop">

1013 Contexto extendido en Claude Desktop

1014</h4>

983 1015

984* `disabledBuiltinTools`: la puerta de enlace usa la unión de la lista de la base y la lista de la política1016Si sirves [Claude Desktop](#claude-desktop-overlay) desde el gateway, su selector de modelos ofrece una opción de contexto de 1M para cada modelo de la lista que puede ejecutarse con una ventana de contexto de 1M. Estos incluyen Claude Opus 4.6 y posteriores, Claude Sonnet 4.6 y posteriores, y los modelos Fable. La opción es la variante `[1m]` del modelo, que se describe en [Contexto extendido](/docs/es/model-config#extended-context). Necesitas Claude Code v2.1.284 o posterior en el servidor del gateway.

985* `builtinToolPolicy`: si establece una herramienta en un valor distinto de `allow` en la base, la puerta de enlace mantiene ese valor incluso si establece `allow` para la misma herramienta en una política de rol1017

1018Una entrada de [`models`](#models) no recibe la opción de 1M cuando:

1019

1020* Un upstream que puede atender la entrada la asigna a un modelo sin compatibilidad con 1M, incluido un upstream al que el gateway solo llega en la conmutación por error

1021* Ni su `id` ni ninguno de sus valores de `upstream_model` nombra un modelo Claude, como un alias personalizado enrutado a un ARN de perfil de inferencia de aplicación

1022

1023Para cambiar lo que ofrece el selector, usa una de estas opciones:

1024

1025* **Iniciar a los usuarios en la opción de 1M**: establece `modelPrefer1mContext: true` en el bloque `desktop` de la política. Los usuarios que aún no han elegido un modelo empiezan en la opción de 1M cuando el primer modelo de la lista la tiene. Los usuarios que ya eligieron un modelo conservan su elección.

1026* **Ofrecer la opción manualmente**: haz esto si tu servidor del gateway ejecuta una versión anterior a v2.1.284, o si una entrada no nombra ningún modelo Claude. Incluye el modelo dos veces en `models`, una con su ID simple y otra con `[1m]` añadido, ambas con el mismo mapa `upstream_model`. Claude Desktop muestra el par como un solo modelo con una opción de 1M. El gateway sirve una entrada `[1m]` sin comprobarla, así que agrégala solo para un modelo que tus upstreams atienden con 1M.

1027

1028Este ejemplo ofrece la opción manualmente para un alias personalizado enrutado a un perfil de inferencia de aplicación e inicia en ella a los usuarios nuevos:

1029

1030```yaml theme={null}

1031models:

1032 - id: corp-sonnet

1033 upstream_model:

1034 bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod

1035 - id: corp-sonnet[1m]

1036 upstream_model:

1037 bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod

1038

1039managed:

1040 policies:

1041 - match: {}

1042 desktop:

1043 modelPrefer1mContext: true

1044```

1045

1046<h5 id="remove-the-1m-option">

1047 Quitar la opción de 1M

1048</h5>

986 1049

987Para todas las demás claves, si las establece en la política de rol, la puerta de enlace usa el valor de la política de rol. La puerta de enlace reemplaza un array o un objeto anidado como `banner` completo, por lo que si establece `banner.text` en una política de rol, la puerta de enlace descarta el `banner.backgroundColor` de la base.1050Para quitar la opción del selector, establece `CLAUDE_CODE_DISABLE_1M_CONTEXT: "1"` en el bloque `env` bajo la clave `cli` de la política. Si además incluiste una entrada cuyo `id` termina en `[1m]`, el gateway la sigue sirviendo, así que elimina también esa entrada.

988 1051

989Si no implementa Claude Desktop, deje `desktop` completamente fuera de sus políticas; la puerta de enlace luego devuelve 404 desde `/user/bootstrap` para cada usuario.1052La variable también llega a las sesiones de terminal de los desarrolladores que coinciden con la política. Para saber qué cambia allí, consulta [Contexto extendido](/docs/es/model-config#extended-context).

990 1053

991<h4 id="precedence-with-other-managed-sources">1054<h4 id="precedence-with-other-managed-sources">

992 Precedencia con otras fuentes administradas1055 Precedencia con otras fuentes administradas

993</h4>1056</h4>

994 1057

995Si un dispositivo también tiene una política entregada por MDM o un `managed-settings.json` local, la configuración entregada por puerta de enlace ocupa el primer lugar. [Precedencia dentro del nivel administrado](/docs/es/managed-settings#precedence-within-the-managed-tier) en la página de configuración administrada dice cuándo se aplican las fuentes locales, y tiene las [claves que Claude Code lee de todas las fuentes de administrador](/docs/es/managed-settings#keys-read-from-every-admin-source) independientemente de cuál fuente seleccione, como las claves de bloqueo de sandbox, `forceRemoteSettingsRefresh` y el `env` por variable fusionado. Un [`policyHelper`](/docs/es/settings-reference#policyhelper) configurado en un perfil MDM o el archivo de configuración administrada se ejecuta solo cuando la puerta de enlace no entrega configuración; la entrada dice qué reemplaza su salida.1058Si un dispositivo también tiene una política entregada por MDM o un `managed-settings.json` local, la configuración entregada por el gateway tiene la máxima prioridad. [Precedencia dentro del nivel administrado](/docs/es/managed-settings#precedence-within-the-managed-tier), en la página de configuración administrada, indica cuándo se aplican las fuentes locales e incluye las [claves que Claude Code lee de todas las fuentes de administración](/docs/es/managed-settings#keys-read-from-every-admin-source) independientemente de la fuente que haya seleccionado, como las claves de bloqueo del sandbox, `forceRemoteSettingsRefresh` y la combinación de `env` por variable. Un [`policyHelper`](/docs/es/settings-reference#policyhelper) configurado en un perfil MDM o en el archivo de configuración administrada se ejecuta solo cuando el gateway no entrega ninguna configuración; la entrada indica qué reemplaza su salida.

996 1059

997Los hosts de incrustación como [Claude Desktop](/docs/es/desktop) pueden suministrar política a través de la opción `managedSettings` del SDK. [Configuración de padres de hosts de incrustación](/docs/es/managed-settings#parent-settings-from-embedding-hosts) dice cuándo Claude Code la aplica, y [Restringir configuración de padres](/docs/es/claude-apps-gateway#restrict-parent-settings) enumera qué configuración de dirección de permitidos aún se aplica sin los bloqueos `allowManaged*Only`.1060Los hosts que integran Claude Code, como [Claude Desktop](/docs/es/desktop), pueden suministrar políticas mediante la opción `managedSettings` del SDK. [Configuración principal de hosts de integración](/docs/es/managed-settings#parent-settings-from-embedding-hosts) indica cuándo la aplica Claude Code, y [Restringir la configuración principal](/docs/es/claude-apps-gateway#restrict-parent-settings) enumera qué ajustes en sentido de permiso siguen aplicándose sin los bloqueos `allowManaged*Only`.

998 1061

999Las políticas de puerta de enlace se aplican a cada invocación de Claude Code en la máquina, incluidas ejecuciones no interactivas `claude -p` y sesiones generadas por el Agent SDK. Si la puerta de enlace es inaccesible al inicio, las sesiones conectadas salen con un error en lugar de ejecutarse sin su política.1062Las políticas del gateway se aplican a cada invocación de Claude Code en la máquina, incluidas las ejecuciones no interactivas `claude -p` y las sesiones generadas por el Agent SDK. Si el gateway es inaccesible al inicio, las sesiones con sesión iniciada terminan con un error en lugar de ejecutarse sin su política.

1000 1063

1001<h3 id="telemetry">1064<h3 id="telemetry">

1002 `telemetry`1065 `telemetry`

1003</h3>1066</h3>

1004 1067

1005El CLI envía métricas, registros y, cuando está habilitado, trazas a la puerta de enlace, que las retransmite textualmente a cada destino configurado. Las exportaciones utilizan OpenTelemetry Protocol (OTLP) sobre HTTP. Para omitir el relé y hacer que las sesiones exporten directamente a su recopilador, [nombre el recopilador en una política](#export-directly-to-your-collector). Consulte [Monitoreo de uso](/docs/es/monitoring-usage) para las métricas y eventos que emite el CLI.1068El CLI envía métricas, registros y, cuando están habilitadas, trazas al gateway, que las retransmite textualmente a cada destino configurado. Las exportaciones usan OpenTelemetry Protocol (OTLP) sobre HTTP. Para omitir la retransmisión y que las sesiones exporten directamente a tu recopilador, [nombra el recopilador en una política](#export-directly-to-your-collector). Consulta [Supervisión del uso](/docs/es/monitoring-usage) para conocer las métricas y eventos que emite el CLI.

1006 1069

1007En sesiones conectadas a través de `/login`, el CLI marca cada exportación con la identidad del usuario autenticado, leída del JWT emitido por la puerta de enlace: los atributos `user.id`, `user.email` y `user.groups`. La atribución de costo y uso por desarrollador funciona sin configuración del lado del desarrollador.1070En las sesiones iniciadas mediante `/login`, el CLI marca cada exportación con la identidad del usuario autenticado, leída del JWT emitido por el gateway: los atributos `user.id`, `user.email` y `user.groups`. Por lo tanto, la atribución de costos y uso por desarrollador funciona sin ninguna configuración del lado del desarrollador.

1008 1071

1009Las sesiones de [Claude Desktop](#claude-desktop-overlay) y Cowork conectadas a través de la puerta de enlace marcan su telemetría con `user.email` y `user.groups` junto a `enduser.id`, por lo que puede cubrir el uso de terminal, Desktop y Cowork con una consulta en `user.email` o `user.groups`. `user.groups` es la lista de grupos de IdP separada por comas.1072Las sesiones de [Claude Desktop](#claude-desktop-overlay) y Cowork iniciadas mediante el gateway marcan su telemetría con `user.email` y `user.groups` junto a `enduser.id`, por lo que puedes cubrir el uso de terminal, Desktop y Cowork con una sola consulta sobre `user.email` o `user.groups`. `user.groups` es la lista de grupos del IdP separada por comas.

1010 1073

1011La telemetría de Desktop y Cowork también lleva `enduser.sub`, la reclamación `sub` que su proveedor de identidad emite para el usuario, que permanece igual cuando cambia el correo electrónico de un usuario. Las sesiones de terminal marcan el mismo valor bajo `user.id`, por lo que una consulta que coincida `enduser.sub` contra `user.id` de terminal cubre el uso de terminal, Desktop y Cowork de un usuario junto. En las exportaciones de Desktop y Cowork, `user.id` es un identificador anónimo, no el sujeto.1074La telemetría de Desktop y Cowork también incluye `enduser.sub`, la reclamación `sub` que tu proveedor de identidad emite para el usuario, que no cambia cuando cambia el correo electrónico de un usuario. Las sesiones de terminal marcan el mismo valor bajo `user.id`, por lo que una consulta que compara `enduser.sub` con el `user.id` de terminal cubre conjuntamente el uso de terminal, Desktop y Cowork de un usuario. En las exportaciones de Desktop y Cowork, `user.id` es un identificador anónimo, no el sujeto.

1012 1075

1013Como todos los datos de OpenTelemetry de Claude Code, estos atributos van solo a destinos que su organización configura, nunca a Anthropic.1076Como todos los datos de OpenTelemetry de Claude Code, estos atributos van solo a los destinos que configura tu organización, nunca a Anthropic.

1014 1077

1015Si la lista de grupos de un usuario es más larga que 255 caracteres una vez codificada en porcentaje, o un nombre de grupo contiene una coma o un signo igual, la puerta de enlace deja `user.groups` fuera de la telemetría de Desktop y Cowork de ese usuario en lugar de truncarla. Las sesiones de terminal de ese usuario aún llevan la lista completa.1078Si la lista de grupos de un usuario supera los 255 caracteres una vez codificada en porcentaje, o un nombre de grupo contiene una coma o un signo igual, el gateway omite `user.groups` de la telemetría de Desktop y Cowork de ese usuario en lugar de truncarla. Las sesiones de terminal de ese usuario siguen incluyendo la lista completa.

1016 1079

1017La puerta de enlace deja `enduser.sub` fuera cuando el sujeto es más largo que 255 caracteres una vez codificado en porcentaje, o contiene un espacio, un carácter fuera de ASCII imprimible, o uno de `,` `;` `=` `\` `"` `%`. La telemetría de Desktop y Cowork de ese usuario mantiene sus otros atributos.1080El gateway omite `enduser.sub` cuando el sujeto supera los 255 caracteres una vez codificado en porcentaje, o contiene un espacio, un carácter fuera del ASCII imprimible o uno de `,` `;` `=` `\` `"` `%`. La telemetría de Desktop y Cowork de ese usuario conserva sus demás atributos.

1018 1081

1019Necesita Claude Code v2.1.265 o posterior en el servidor de puerta de enlace para `user.email` y `user.groups` en telemetría de Desktop y Cowork, y Claude Desktop 1.24012 o posterior en la máquina de cada desarrollador para `user.groups`.1082Necesitas Claude Code v2.1.265 o posterior en el servidor del gateway para `user.email` y `user.groups` en la telemetría de Desktop y Cowork, y Claude Desktop 1.24012 o posterior en la máquina de cada desarrollador para `user.groups`.

1020 1083

1021Necesita Claude Code v2.1.274 o posterior en el servidor de puerta de enlace para `enduser.sub`.1084Necesitas Claude Code v2.1.274 o posterior en el servidor del gateway para `enduser.sub`.

1022 1085

1023```yaml theme={null}1086```yaml theme={null}

1024telemetry:1087telemetry:

1026 - url: https://otel-collector.internal.example.com1089 - url: https://otel-collector.internal.example.com

1027 headers:1090 headers:

1028 Authorization: ${OTLP_TOKEN}1091 Authorization: ${OTLP_TOKEN}

1029 # Opción de participación por señal. Predeterminado: solo métricas.1092 # Activación por señal. Predeterminado: solo métricas.

1030 metrics: true1093 metrics: true

1031 logs: false1094 logs: false

1032 traces: false1095 traces: false

1036```1099```

1037 1100

1038<Warning>1101<Warning>

1039 Cada destino opta en `metrics`, `logs` y `traces` independientemente, y el valor predeterminado es solo métricas. Las señales difieren en sensibilidad:1102 Cada destino activa `metrics`, `logs` y `traces` de forma independiente, y el valor predeterminado es solo métricas. Las señales difieren en sensibilidad:

1040 1103

1041 * **Métricas**: contadores agregados como conteos de tokens, conteos de solicitudes y latencia1104 * **Métricas**: contadores agregados como recuentos de tokens, recuentos de solicitudes y latencia

1042 * **Registros y trazas**: pueden llevar comandos Bash completos, entradas de herramientas y rutas de archivos, cubriendo cualquier cosa que Claude Code haga en la máquina de un desarrollador1105 * **Registros y trazas**: pueden incluir comandos Bash completos, entradas de herramientas y rutas de archivos, y abarcan todo lo que Claude Code hace en la máquina de un desarrollador

1043 1106

1044 Habilite registros y trazas solo en destinos con los controles de acceso y la política de retención que esos datos justifican.1107 Habilita registros y trazas solo en destinos con los controles de acceso y la política de retención que esos datos requieren.

1045</Warning>1108</Warning>

1046 1109

1047Cada URL `forward_to` debe usar `https://`, con una excepción para un recopilador en la interfaz de bucle de retorno de la puerta de enlace:1110Cada URL de `forward_to` debe usar `https://`, con una excepción para un recopilador en la interfaz de loopback del propio gateway:

1048 1111

1049* `http://localhost:<port>` pasa la validación de configuración, pero la [protección SSRF](/docs/es/claude-apps-gateway-deploy#threat-model-summary) bloquea cada exportación con `ECONNREFUSED_SSRF` a menos que establezca `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` en el entorno de la puerta de enlace1112* `http://localhost:<port>` supera la validación de la configuración, pero la [protección contra SSRF](/docs/es/claude-apps-gateway-deploy#threat-model-summary) bloquea todas las exportaciones con `ECONNREFUSED_SSRF` a menos que establezcas `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` en el entorno del gateway

1050* `http://127.0.0.1:<port>` o `http://[::1]:<port>` falla al arrancar a menos que esa variable esté establecida1113* `http://127.0.0.1:<port>` o `http://[::1]:<port>` hace fallar el arranque a menos que esa variable esté establecida

1051 1114

1052Para un recopilador en clúster, expóngalo sobre HTTPS en su propia dirección interna, o ejecútelo como un sidecar con la variable establecida.1115Para un recopilador dentro del clúster, exponlo por HTTPS en su propia dirección interna, o ejecútalo como sidecar con la variable establecida.

1053 1116

1054Cuando se establece `HTTPS_PROXY`, la puerta de enlace envía exportaciones a través de ese proxy.1117Cuando `HTTPS_PROXY` está establecido, el gateway envía las exportaciones a través de ese proxy.

1055 1118

1056Para llegar a un recopilador interno directamente, agréguelo a `NO_PROXY` por nombre de host o por un dominio con un punto inicial como `.internal.example.com`, que requiere Claude Code v2.1.277 o posterior en el servidor de puerta de enlace. Asegúrese de que la puerta de enlace pueda llegar al recopilador sin el proxy. Una entrada sin un punto inicial coincide solo con ese nombre exacto, no con nombres bajo él. Los rangos CIDR no coinciden.1119Para llegar directamente a un recopilador interno, agrégalo a `NO_PROXY` por nombre de host o mediante un dominio con un punto inicial como `.internal.example.com`, lo que requiere Claude Code v2.1.277 o posterior en el servidor del gateway. Asegúrate de que el gateway pueda llegar al recopilador sin el proxy. Una entrada sin punto inicial coincide solo con ese nombre exacto, no con los nombres que dependen de él. Los rangos CIDR no coinciden.

1057 1120

1058Con [salida solo proxy](#proxy-only-egress) activada, permita el recopilador en el proxy en su lugar, ya que cualquier entrada `NO_PROXY` mantiene la salida solo proxy desactivada.1121Con la [salida solo a través del proxy](#proxy-only-egress) activada, permite el recopilador en el proxy, ya que cualquier entrada de `NO_PROXY` mantiene desactivada la salida solo a través del proxy.

1059 1122

1060La telemetría está desactivada en el CLI de forma predeterminada. Cuando establece tanto `telemetry.forward_to` como `listen.public_url`, la puerta de enlace la activa para clientes conectados insertando seis variables de entorno a través de `/managed/settings`:1123La telemetría está desactivada en el CLI de forma predeterminada. Cuando estableces tanto `telemetry.forward_to` como `listen.public_url`, el gateway la activa para los clientes con sesión iniciada enviando seis variables de entorno a través de `/managed/settings`:

1061 1124

1062* `CLAUDE_CODE_ENABLE_TELEMETRY=1`1125* `CLAUDE_CODE_ENABLE_TELEMETRY=1`

1063* `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` y `OTEL_TRACES_EXPORTER`, cada uno establecido en `otlp` si al menos un destino `forward_to` habilita esa señal y en `none` de lo contrario1126* `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` y `OTEL_TRACES_EXPORTER`, cada una establecida en `otlp` si al menos un destino `forward_to` habilita esa señal y en `none` en caso contrario

1064* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`1127* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`

1065* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`1128* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`

1066 1129

1067Cuando [agrega sus propias etiquetas](#add-your-own-labels), la puerta de enlace también inserta `OTEL_RESOURCE_ATTRIBUTES`.1130Cuando [agregas tus propias etiquetas](#add-your-own-labels), el gateway también envía `OTEL_RESOURCE_ATTRIBUTES`.

1068 1131

1069Antes de Claude Code v2.1.265 en el servidor de puerta de enlace, la puerta de enlace insertaba los tres selectores de exportador como `otlp`, incluido para señales que ningún destino optó.1132Antes de Claude Code v2.1.265 en el servidor del gateway, el gateway enviaba los tres selectores de exportador como `otlp`, incluso para señales que ningún destino había activado.

1070 1133

1071El punto final insertado se construye a partir de la URL pública, por lo que las métricas y registros no necesitan configuración OTEL de desarrolladores o políticas.1134El endpoint enviado se construye a partir de la URL pública, por lo que las métricas y los registros no necesitan configuración de OTEL por parte de los desarrolladores ni de las políticas.

1072 1135

1073Los desarrolladores conectados a través de `/login` no pueden redirigir exportaciones con su propia configuración OTEL:1136Los desarrolladores con sesión iniciada mediante `/login` no pueden redirigir las exportaciones con su propia configuración de OTEL:

1074 1137

1075* **Variables establecidas localmente**: Claude Code aplica las variables insertadas en el nivel administrado, por lo que cada una anula el valor que un desarrollador establece localmente.1138* **Variables establecidas localmente**: Claude Code aplica las variables enviadas en el nivel administrado, por lo que cada una sobrescribe el valor que un desarrollador establece localmente para ella.

1076* **Puntos finales configurados localmente**: con exportación OTLP/HTTP habilitada, el CLI ignora cualquier punto final configurado localmente, independientemente de si la puerta de enlace insertó las variables de telemetría. Sus exportaciones van a la puerta de enlace a menos que una política [nombre su recopilador como punto final](#export-directly-to-your-collector).1139* **Endpoints configurados localmente**: con la exportación OTLP/HTTP habilitada, el CLI ignora cualquier endpoint configurado localmente, independientemente de que el gateway haya enviado o no las variables de telemetría. Sus exportaciones van al gateway a menos que una política [nombre tu recopilador como endpoint](#export-directly-to-your-collector).

1077 1140

1078Sin un destino `forward_to` para una señal, la puerta de enlace la acepta y la descarta. Si los desarrolladores ya exportan telemetría de Claude Code a uno de sus recopiladores, agréguelo como destino `forward_to`, con registros o trazas habilitadas si exportan esos, para que continúe recibiendo sus datos después de que se conecten. Para omitir el relé en su lugar, [nombre el recopilador en una política](#export-directly-to-your-collector).1141Sin un destino `forward_to` para una señal, el gateway la acepta y la descarta. Si los desarrolladores ya exportan la telemetría de Claude Code a uno de tus recopiladores, agrégalo como destino `forward_to`, con registros o trazas habilitados si los exportan, para que siga recibiendo sus datos después de que inicien sesión. Para omitir la retransmisión, [nombra el recopilador en una política](#export-directly-to-your-collector).

1079 1142

1080[Trazas](/docs/es/monitoring-usage#traces-beta) también requieren `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` en cada cliente. Establézcalo en un bloque `env` de política administrada, ya que la puerta de enlace no lo inserta. Los desarrolladores lo aprueban en el mismo [diálogo de aprobación de seguridad](#managed) que el punto final insertado ya activa.1143Las [trazas](/docs/es/monitoring-usage#traces-beta) también requieren `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` en cada cliente. Establécela en el bloque `env` de una política administrada, ya que el gateway no la envía. Los desarrolladores la aprueban en el mismo [diálogo de aprobación de seguridad](#managed) que ya activa el endpoint enviado.

1081 1144

1082Establézcalo en `1` solo en las políticas cuyos grupos desea rastrear. Una política que no lo establece hereda el valor de su política de captura general `match: {}` si esa política establece uno, según las [reglas de fusión](#managed). Para evitar que los clientes de un grupo envíen trazas incluso cuando un desarrollador establece la variable localmente, establézcala en `0` en la política de ese grupo.1145Establécela en `1` solo en las políticas cuyos grupos quieras trazar. Una política que no la establece hereda el valor de tu política de captura general `match: {}` si esa política establece uno, según las [reglas de fusión](#managed). Para evitar que los clientes de un grupo envíen trazas incluso cuando un desarrollador establece la variable localmente, establécela en `0` en la política de ese grupo.

1083 1146

1084Tanto las codificaciones OTLP de protobuf como JSON se retransmiten, y cualquier backend compatible con OpenTelemetry funciona como destino.1147Se retransmiten tanto la codificación OTLP protobuf como la JSON, y cualquier backend compatible con OpenTelemetry funciona como destino.

1085 1148

1086<h4 id="add-your-own-labels">1149<h4 id="add-your-own-labels">

1087 Agregue sus propias etiquetas1150 Agrega tus propias etiquetas

1088</h4>1151</h4>

1089 1152

1090Para poner etiquetas fijas como `service.namespace` o `deployment.environment.name` en la telemetría de sesiones conectadas a través de la puerta de enlace, establezca `telemetry.resource_attributes`. Cada etiqueta es un atributo de recurso de OpenTelemetry, y cada destino recibe las mismas etiquetas.1153Para poner etiquetas fijas como `service.namespace` o `deployment.environment.name` en la telemetría de las sesiones iniciadas mediante el gateway, establece `telemetry.resource_attributes`. Cada etiqueta es un atributo de recurso de OpenTelemetry, y todos los destinos reciben las mismas etiquetas.

1091 1154

1092Las sesiones obtienen las etiquetas solo cuando también establece `telemetry.forward_to` y `listen.public_url`. Este ejemplo agrega dos etiquetas:1155Las sesiones reciben las etiquetas solo cuando también estableces `telemetry.forward_to` y `listen.public_url`. Este ejemplo agrega dos etiquetas:

1093 1156

1094```yaml theme={null}1157```yaml theme={null}

1095telemetry:1158telemetry:

1100 deployment.environment.name: prod1163 deployment.environment.name: prod

1101```1164```

1102 1165

1103La puerta de enlace se niega a iniciar cuando una etiqueta rompe una de estas reglas, y el error de inicio nombra la etiqueta:1166El gateway se niega a iniciar cuando una etiqueta incumple una de estas reglas, y el error de inicio nombra la etiqueta:

1104 1167

1105* Los nombres usan solo letras, dígitos, `.`, `_` y `-`1168* Los nombres usan solo letras, dígitos, `.`, `_` y `-`

1106* Los nombres no están reservados. Comparados en cualquier caso de letra, los nombres reservados son todo lo que comienza con `user.`, `enduser.` o `identity.`, más `service.name`, `service.version`, `claude.deployment_mode`, `host.arch`, `os.type`, `os.version` y `wsl.version`1169* Los nombres no están reservados. Sin distinguir mayúsculas de minúsculas, los nombres reservados son todos los que empiezan por `user.`, `enduser.` o `identity.`, además de `service.name`, `service.version`, `claude.deployment_mode`, `host.arch`, `os.type`, `os.version` y `wsl.version`

1107* Los valores son ASCII imprimible no vacío sin espacio y ninguno de `, ; = \ " %`1170* Los valores son ASCII imprimible no vacío, sin espacios y sin ninguno de `, ; = \ " %`

1108* Los valores tienen como máximo 255 caracteres según los cuenta la puerta de enlace después de la codificación en porcentaje, por lo que `/`, `:` y `@` cada uno cuentan como tres1171* Los valores tienen como máximo 255 caracteres según el recuento del gateway tras la codificación en porcentaje, por lo que `/`, `:` y `@` cuentan como tres cada uno

1109* Los valores son texto, así que cite un número, `true` o `false`1172* Los valores son texto, así que pon entre comillas un número, `true` o `false`

1110 1173

1111Necesita Claude Code v2.1.281 o posterior en el servidor de puerta de enlace para establecer `telemetry.resource_attributes`. Una puerta de enlace anterior se niega a iniciar cuando encuentra la clave. Actualice cada réplica antes de agregar la clave, y elimine la clave antes de revertir a una versión anterior.1174Necesitas Claude Code v2.1.281 o posterior en el servidor del gateway para establecer `telemetry.resource_attributes`. Un gateway anterior se niega a iniciar cuando encuentra la clave. Actualiza todas las réplicas antes de agregar la clave, y elimina la clave antes de volver a una versión anterior.

1112 1175

1113Las sesiones de terminal conectadas a través de `/login` reciben las etiquetas como `OTEL_RESOURCE_ATTRIBUTES`, insertadas con las otras [variables de telemetría](#telemetry). Si establece `OTEL_RESOURCE_ATTRIBUTES` en un bloque `env` de política, las sesiones de terminal que esa política coincida obtienen ese valor en lugar de las etiquetas. Claude Desktop recibe las etiquetas de la puerta de enlace junto a `user.email` y los otros atributos de identidad.1176Las sesiones de terminal iniciadas mediante `/login` reciben las etiquetas como `OTEL_RESOURCE_ATTRIBUTES`, enviada junto con las demás [variables de telemetría](#telemetry). Si estableces `OTEL_RESOURCE_ATTRIBUTES` en el bloque `env` de una política, las sesiones de terminal que coinciden con esa política reciben ese valor en lugar de las etiquetas. Claude Desktop recibe las etiquetas del gateway junto con `user.email` y los demás atributos de identidad.

1114 1177

1115Claude Code también copia cada etiqueta en cada punto de datos de métrica, por lo que puede filtrar métricas por ella en un backend que no indexe atributos de recurso. Para desactivar esa copia, consulte [Control de cardinalidad de métricas](/docs/es/monitoring-usage#metrics-cardinality-control).1178Claude Code también copia cada etiqueta en cada punto de datos de métrica, para que puedas filtrar las métricas por ella en un backend que no indexa atributos de recurso. Para desactivar esa copia, consulta [Control de cardinalidad de métricas](/docs/es/monitoring-usage#metrics-cardinality-control).

1116 1179

1117<h4 id="export-directly-to-your-collector">1180<h4 id="export-directly-to-your-collector">

1118 Exportar directamente a su recopilador1181 Exportar directamente a tu recopilador

1119</h4>1182</h4>

1120 1183

1121Para hacer que las sesiones conectadas a través de `/login` envíen telemetría directamente a su recopilador en lugar de a través del relé, establezca `OTEL_EXPORTER_OTLP_ENDPOINT` en la URL base `https://` del recopilador en el bloque `env` de una [política administrada](#managed). Claude Code añade `/v1/metrics`, `/v1/logs` o `/v1/traces` a la URL que establece, como `https://otel-collector.example.com:4318`, y exporta cada señal allí sobre OTLP/HTTP. Requiere Claude Code v2.1.265 o posterior en la máquina de cada desarrollador. Los clientes anteriores exportan a través del relé.1184Para que las sesiones iniciadas mediante `/login` envíen la telemetría directamente a tu recopilador en lugar de a través de la retransmisión, establece `OTEL_EXPORTER_OTLP_ENDPOINT` en la URL base `https://` del recopilador en el bloque `env` de una [política administrada](#managed). Claude Code añade `/v1/metrics`, `/v1/logs` o `/v1/traces` a la URL que estableces, como `https://otel-collector.example.com:4318`, y exporta allí cada señal mediante OTLP/HTTP. Requiere Claude Code v2.1.265 o posterior en la máquina de cada desarrollador. Los clientes anteriores exportan a través de la retransmisión.

1122 1185

1123Para autenticarse en el recopilador, establezca `OTEL_EXPORTER_OTLP_HEADERS` en el mismo bloque `env`. Las sesiones nunca envían el token de sesión de puerta de enlace del desarrollador a un recopilador nombrado de esta manera.1186Para autenticarte en el recopilador, establece `OTEL_EXPORTER_OTLP_HEADERS` en el mismo bloque `env`. Las sesiones nunca envían el token de sesión del gateway del desarrollador a un recopilador nombrado de esta manera.

1124 1187

1125Cuando agrega o cambia este punto final en una política, Claude Code pide a cada desarrollador que lo apruebe en el [diálogo de aprobación de seguridad](#managed) antes de aplicarlo en una sesión interactiva.1188Cuando agregas o cambias este endpoint en una política, Claude Code pide a cada desarrollador que lo apruebe en el [diálogo de aprobación de seguridad](#managed) antes de aplicarlo en una sesión interactiva.

1126 1189

1127Claude Code comprueba el punto final antes de exportar una señal directamente, y mantiene esa señal en el relé cuando una comprobación falla. Las comprobaciones incluyen:1190Claude Code comprueba el endpoint antes de exportar una señal directamente, y mantiene esa señal en la retransmisión cuando falla una comprobación. Las comprobaciones incluyen:

1128 1191

1129* El punto final proviene de la puerta de enlace en sí. Si establece la misma variable en un perfil MDM o un `managed-settings.json` local, las exportaciones permanecen en el relé.1192* El endpoint proviene del propio gateway. Si estableces la misma variable en un perfil MDM o en un `managed-settings.json` local, las exportaciones se mantienen en la retransmisión.

1130* La URL usa `https://`, o `http://` a una dirección de bucle de retorno1193* La URL usa `https://`, o `http://` hacia una dirección de loopback

1131* La URL se resuelve en una ruta que termina en `/v1/<signal>`, sin consulta o fragmento. Claude Code construye esa ruta en sí desde la variable genérica. Usa una variable por señal como `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` tal como está escrita, así que incluye la ruta completa allí.1194* La URL se resuelve en una ruta que termina en `/v1/<signal>`, sin consulta ni fragmento. Claude Code construye esa ruta a partir de la variable genérica. Usa una variable por señal como `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` tal como está escrita, así que incluye allí la ruta completa.

1132* La URL no es el host de la puerta de enlace. Un punto final dirigido a la puerta de enlace mantiene la ruta de relé y su token de sesión.1195* La URL no es el propio host del gateway. Un endpoint dirigido al gateway mantiene la ruta de retransmisión y su token de sesión.

1133* Ni usted ni el desarrollador han configurado [`otelHeadersHelper`](/docs/es/settings-reference#otelheadershelper) en ninguna fuente de configuración. Con un ayudante configurado, cada señal permanece en el relé.1196* Ni tú ni el desarrollador han configurado [`otelHeadersHelper`](/docs/es/settings-reference#otelheadershelper) en ninguna fuente de configuración. Con un helper configurado, todas las señales se mantienen en la retransmisión.

1134 1197

1135El punto final que nombra cambia solo dónde van las exportaciones. Aún elige qué señales exportan en absoluto con los selectores `OTEL_*_EXPORTER`.1198El endpoint que nombras solo cambia adónde van las exportaciones. Sigues eligiendo qué señales se exportan con los selectores `OTEL_*_EXPORTER`.

1136 1199

1137El punto final solo no activa la exportación, así que también establezca las variables que lo hacen, a menos que la puerta de enlace ya las inserte:1200El endpoint por sí solo no activa la exportación, así que establece también las variables que sí lo hacen, a menos que el gateway ya las envíe:

1138 1201

1139* Si la puerta de enlace ya [inserta las variables de telemetría](#telemetry), cubren habilitación, selectores y protocolo, y su punto final explícito anula el valor `<public_url>` insertado. Establezca un selector `OTEL_*_EXPORTER` en `otlp` usted mismo solo para una señal que ningún destino `forward_to` habilita.1202* Si el gateway ya [envía las variables de telemetría](#telemetry), estas cubren la habilitación, los selectores y el protocolo, y tu endpoint explícito sobrescribe el valor `<public_url>` enviado. Establece tú mismo un selector `OTEL_*_EXPORTER` en `otlp` solo para una señal que ningún destino `forward_to` habilita.

1140* Si no, también establezca `CLAUDE_CODE_ENABLE_TELEMETRY=1`, los selectores `OTEL_*_EXPORTER` y `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`.1203* Si no las envía, establece también `CLAUDE_CODE_ENABLE_TELEMETRY=1`, los selectores `OTEL_*_EXPORTER` y `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`.

1141 1204

1142Cuando el desarrollador se desconecta, o se conecta a una puerta de enlace diferente, las exportaciones al recopilador se detienen y Claude Code descarta cada lote restante en lugar de enviarlo.1205Cuando el desarrollador cierra sesión, o inicia sesión en otro gateway, las exportaciones al recopilador se detienen y Claude Code descarta cada lote pendiente en lugar de enviarlo.

1143 1206

1144<h4 id="when-a-destination-fails">1207<h4 id="when-a-destination-fails">

1145 Cuando un destino falla1208 Cuando un destino falla

1146</h4>1209</h4>

1147 1210

1148La puerta de enlace no almacena en búfer, reintenta ni almacena telemetría, por lo que descarta una exportación que no llega a un destino en lugar de entregarla tarde. Cada destino tiene éxito o falla por su cuenta, y el cliente exportador recibe una respuesta de éxito de cualquier manera, por lo que una entrega fallida aparece solo en el registro de la puerta de enlace.1211El gateway no almacena en búfer, no reintenta ni guarda la telemetría, por lo que descarta una exportación que no llega a un destino en lugar de entregarla tarde. Cada destino tiene éxito o falla por separado, y el cliente que exporta recibe una respuesta de éxito en cualquier caso, por lo que una entrega fallida solo aparece en el registro del gateway.

1149 1212

1150Después de cinco entregas consecutivas fallidas a un destino, la puerta de enlace pausa el reenvío a él en tramos de 30 segundos, registrando cada pausa, hasta que una entrega tiene éxito. Cualquier respuesta de error, tiempo de espera o error de conexión cuenta como una entrega fallida, excepto `400`, `413`, `415`, `422` y `431`, que significan que el recopilador rechazó la carga útil de esa exportación como mal formada o demasiado grande.1213Tras cinco entregas fallidas consecutivas a un destino, el gateway pausa el reenvío a ese destino en intervalos de 30 segundos, registrando cada pausa, hasta que una entrega tiene éxito. Cualquier respuesta de error, tiempo de espera agotado o error de conexión cuenta como entrega fallida, excepto `400`, `413`, `415`, `422` y `431`, que indican que el recopilador rechazó el payload de esa exportación por estar mal formado o ser demasiado grande.

1151 1214

1152Una carga útil rechazada ni avanza ni reinicia el contador de fallos: la puerta de enlace continúa reenviando al destino y registra una advertencia que lo nombra y el estado, en el primer rechazo del destino y cada centésimo después.1215Un payload rechazado no incrementa ni reinicia el contador de fallos: el gateway sigue reenviando al destino y registra una advertencia que nombra el destino y el estado, en el primer rechazo del destino y cada cien rechazos posteriores.

1153 1216

1154<h3 id="http-tuning">1217<h3 id="http-tuning">

1155 Ajuste HTTP1218 Ajuste HTTP

1156</h3>1219</h3>

1157 1220

1158Cuatro bloques opcionales de nivel superior, `access_control`, `limits`, `timeouts` y `rate_limits`, ajustan la superficie HTTP. Los valores predeterminados se adaptan a la mayoría de implementaciones.1221Cuatro bloques opcionales de nivel superior, `access_control`, `limits`, `timeouts` y `rate_limits`, ajustan la superficie HTTP. Los valores predeterminados sirven para la mayoría de los despliegues.

1159 1222

1161| - | - | - | - |1224| - | - | - | - |

1162| `access_control` | `allow_cidrs` / `deny_cidrs` | vacío | Entrada IP permitida/denegada por dirección de cliente, después de la resolución de `trusted_proxies`. `deny_cidrs` se comprueba primero; un cliente que coincida se rechaza incluso si `allow_cidrs` también coincide. Si `allow_cidrs` no está vacío, la puerta de enlace es denegación predeterminada. `/healthz` y `/readyz` están exentos de `allow_cidrs`. Cuando un proxy de confianza envía una entrada `X-Forwarded-For` que no es una dirección IP, el cliente real es desconocido y la puerta de enlace registra una advertencia una vez nombrando qué verificar. Donde se aplica cualquiera de las listas a la solicitud, la rechaza con `403` y razón de auditoría `xff_unparseable`. Donde ninguno lo hace, sirve la solicitud y usa la dirección del proxy como dirección IP del cliente para límites de velocidad por IP y auditoría. |1225| `access_control` | `allow_cidrs` / `deny_cidrs` | vacío | Permiso o denegación de IP entrante según la dirección del cliente, después de la resolución de `trusted_proxies`. `deny_cidrs` se comprueba primero; un cliente que coincide con ella se rechaza aunque `allow_cidrs` también coincida. Si `allow_cidrs` no está vacía, el gateway deniega de forma predeterminada. `/healthz` y `/readyz` están exentos de `allow_cidrs`. Cuando un proxy de confianza envía una entrada `X-Forwarded-For` que no es una dirección IP, el cliente real es desconocido y el gateway registra una vez una advertencia que indica qué revisar. Si alguna de las listas se aplica a la solicitud, la rechaza con `403` y el motivo de auditoría `xff_unparseable`. Si ninguna se aplica, atiende la solicitud y usa la propia dirección del proxy como IP del cliente para los rate limits por IP y la auditoría. |

1163| `limits` | `max_request_bytes` | 32 MiB | Cuerpo de solicitud de entrada máximo; las solicitudes de tamaño excesivo obtienen `413` antes de que el cuerpo se almacene en búfer. Aumente para solicitudes de archivo o imagen grandes. |1226| `limits` | `max_request_bytes` | 32 MiB | Tamaño máximo del cuerpo de la solicitud entrante; las solicitudes demasiado grandes reciben `413` antes de que el cuerpo se almacene en búfer. Auméntalo para solicitudes con archivos o imágenes grandes. |

1166| `timeouts` | `upstream_ttfb_ms` | 120000 | Espera máxima para los encabezados de respuesta ascendentes (tiempo al primer byte). El cuerpo de respuesta luego se transmite sin límite de reloj de pared. Se aplica a la ruta de upstream de Anthropic directo; en todos los demás proveedores, la puerta de enlace espera hasta una hora a que comience la respuesta. |1229| `timeouts` | `upstream_ttfb_ms` | 120000 | Espera máxima para los encabezados de respuesta del upstream (tiempo hasta el primer byte). Después, el cuerpo de la respuesta se transmite sin límite de tiempo total. Se aplica a la ruta directa al upstream de Anthropic; en todos los demás proveedores, el gateway espera hasta una hora a que empiece la respuesta. |

1167| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Límite de velocidad por IP en el punto final de autorización de dispositivo no autenticado. Aumente para una organización grande detrás de una IP de salida compartida o NAT. [Implementaciones grandes](/docs/es/claude-apps-gateway-deploy#large-rollouts) muestra cómo dimensionarlo. Estos límites se aplican solo al flujo de inicio de sesión de concesión de dispositivo, no a la inferencia `/v1/messages`. Consulte [Resistencia de fuerza bruta de código de usuario](/docs/es/claude-apps-gateway-deploy#user-code-brute-force-resistance). |1230| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | Rate limit por IP en el endpoint no autenticado de autorización de dispositivo. Auméntalo para una organización grande detrás de una IP de salida compartida o NAT. [Despliegues a gran escala](/docs/es/claude-apps-gateway-deploy#large-rollouts) muestra cómo dimensionarlo. Estos límites se aplican solo al flujo de inicio de sesión con concesión de dispositivo, no a la inferencia de `/v1/messages`. Consulta [Resistencia a la fuerza bruta del código de usuario](/docs/es/claude-apps-gateway-deploy#user-code-brute-force-resistance). |

1168| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | Límite de velocidad por IP en envíos de `user_code` en `/device`. Es lo que detiene a alguien de adivinar el código de otro desarrollador. [Implementaciones grandes](/docs/es/claude-apps-gateway-deploy#large-rollouts) muestra cuánto levantarlo. |1231| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | Rate limit por IP en los envíos de `user_code` en `/device`. Es lo que impide que alguien adivine el código de otro desarrollador. [Despliegues a gran escala](/docs/es/claude-apps-gateway-deploy#large-rollouts) muestra cuánto aumentarlo. |

1169 1232

1170Si deja ambas listas `access_control` vacías, que es el valor predeterminado, la puerta de enlace sirve cualquier dirección de cliente, por lo que solo su red restringe quién puede alcanzarla. Eso importa porque una puerta de enlace puede insertar [configuración administrada](#managed) que ejecuta comandos en máquinas de desarrollador.1233Si dejas vacías ambas listas de `access_control`, que es el valor predeterminado, el gateway atiende cualquier dirección de cliente, por lo que solo tu red restringe quién puede llegar a él. Eso importa porque un gateway puede enviar [configuración administrada](#managed) que ejecuta comandos en las máquinas de los desarrolladores.

1171 1234

1172Mientras `allow_cidrs` está vacío, la puerta de enlace advierte en dos lugares, sin cambiar cómo responde a ninguna solicitud:1235Mientras `allow_cidrs` está vacía, el gateway advierte en dos lugares, sin cambiar cómo responde a ninguna solicitud:

1173 1236

1174* **Al arrancar**: una advertencia en el registro operativo recomienda permitir solo los rangos privados `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, `127.0.0.0/8`, `::1/128` y `fc00::/7`, más cualquier otro rango interno desde el que se conectan sus desarrolladores. Si vincula la puerta de enlace a una dirección de bucle de retorno y no establece ni `trusted_proxies` ni `public_url`, como en desarrollo local, la advertencia no aparece.1237* **Al arrancar**: una advertencia en el registro operativo recomienda permitir solo los rangos privados `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, `127.0.0.0/8`, `::1/128` y `fc00::/7`, además de cualquier otro rango interno desde el que se conecten tus desarrolladores. Si vinculas el gateway a una dirección de loopback y no estableces `trusted_proxies` ni `public_url`, como en el desarrollo local, la advertencia no aparece.

1175* **En tiempo de ejecución**: la primera vez que una solicitud llega desde una dirección fuera de esos rangos privados, la puerta de enlace registra una advertencia y emite un evento de auditoría [`access.public_client`](/docs/es/claude-apps-gateway-deploy#logs) que lleva la IP del cliente. Ambos se disparan una vez por proceso. Las direcciones de enlace local, `169.254.0.0/16` y `fe80::/10`, no cuentan como públicas. La puerta de enlace responde `/healthz` y `/readyz` antes de que se ejecute esta comprobación, por lo que los sondeos de salud desde rangos públicos no la activan.1238* **En tiempo de ejecución**: la primera vez que llega una solicitud desde una dirección fuera de esos rangos privados, el gateway registra una advertencia y emite un [evento de auditoría `access.public_client`](/docs/es/claude-apps-gateway-deploy#logs) que incluye la IP del cliente. Ambos se producen una vez por proceso. Las direcciones de enlace local, `169.254.0.0/16` y `fe80::/10`, no cuentan como públicas. El gateway responde a `/healthz` y `/readyz` antes de que se ejecute esta comprobación, por lo que los sondeos de estado desde rangos públicos no la activan.

1176 1239

1177Ambas señales usan la dirección del cliente tal como la resuelve la puerta de enlace. Si un equilibrador de carga, reenvío de puerto o túnel retransmite tráfico y no está enumerado en `listen.trusted_proxies`, la puerta de enlace ve la dirección del relé, que generalmente es privada, por lo que ni la advertencia en tiempo de ejecución ni una lista de permitidos privada lo detecta.1240Ambas señales usan la dirección del cliente tal como la resuelve el gateway. Si un balanceador de carga, un reenvío de puertos o un túnel retransmite el tráfico y no figura en `listen.trusted_proxies`, el gateway ve la dirección del intermediario, que suele ser privada, por lo que ni la advertencia en tiempo de ejecución ni una lista de permitidos privada detectan el tráfico retransmitido a través de él.

1178 1241

1179Detrás de tal front-end, establezca primero [`listen.trusted_proxies`](#listen) para que la puerta de enlace vea direcciones de cliente reales, y mantenga la puerta de enlace y todo lo que está frente a ella inaccesible desde la internet pública de cualquier manera.1242Detrás de un front end así, establece primero [`listen.trusted_proxies`](#listen) para que el gateway vea las direcciones reales de los clientes, y mantén el gateway y todo lo que está delante de él inaccesibles desde internet pública en cualquier caso.

1180 1243

1181<h3 id="load_test_mode">1244<h3 id="load_test_mode">

1182 `load_test_mode`1245 `load_test_mode`

1183</h3>1246</h3>

1184 1247

1185El bloque `load_test_mode` le permite hacer pruebas de carga en una puerta de enlace sin llamar a un proveedor de modelos. Mientras está activado, la puerta de enlace construye y firma cada solicitud de proveedor como de costumbre, la descarta en lugar de enviarla, y transmite una respuesta enlatada a través de su ruta de respuesta normal. La respuesta es texto de relleno que comienza con una oración que dice que es enlatada.1248El bloque `load_test_mode` te permite hacer pruebas de carga de un gateway sin llamar a un proveedor de modelos. Mientras está activado, el gateway construye y firma cada solicitud al proveedor como de costumbre, la descarta en lugar de enviarla y transmite una respuesta predefinida por su ruta de respuesta normal. La respuesta es texto de relleno que empieza con una oración que indica que es predefinida.

1186 1249

1187Requiere Claude Code v2.1.282 o posterior en el servidor de puerta de enlace. Una puerta de enlace anterior se niega a iniciar cuando encuentra la clave. Actualice cada réplica antes de agregar el bloque, y elimine el bloque antes de revertir.1250Requiere Claude Code v2.1.282 o posterior en el servidor del gateway. Un gateway anterior se niega a iniciar cuando encuentra la clave. Actualiza todas las réplicas antes de agregar el bloque, y elimina el bloque antes de volver a una versión anterior.

1188 1251

1189El ejemplo a continuación activa el modo con los valores predeterminados, una respuesta de aproximadamente 750 tokens de texto transmitida durante aproximadamente 10 segundos:1252El siguiente ejemplo activa el modo con los valores predeterminados, una respuesta de aproximadamente 750 tokens de texto transmitida durante unos 10 segundos:

1190 1253

1191```yaml theme={null}1254```yaml theme={null}

1192load_test_mode:1255load_test_mode:

1193 enabled: true1256 enabled: true

1194 reply_tokens: 750 # aproximadamente cuántos tokens de texto lleva cada respuesta enlatada1257 reply_tokens: 750 # aproximadamente cuántos tokens de texto contiene cada respuesta predefinida

1195 reply_seconds: 9.5 # cuánto tiempo tarda una respuesta transmitida1258 reply_seconds: 9.5 # cuánto tarda una respuesta transmitida

1196```1259```

1197 1260

1199| - | - | - |1262| - | - | - |

1200| `enabled` | Sí | `true` activa el modo. `false` mantiene sus números en el archivo con el modo desactivado. La puerta de enlace se niega a iniciar si el bloque está presente sin él. |1263| `enabled` | Sí | `true` activa el modo. `false` conserva tus valores en el archivo con el modo desactivado. El gateway se niega a iniciar si el bloque está presente sin este campo. |

1201| `reply_tokens` | No | Predeterminado `750`. Aproximadamente cuántos tokens de texto lleva cada respuesta enlatada, un número entero de 1 a 100000. |1264| `reply_tokens` | No | Predeterminado `750`. Aproximadamente cuántos tokens de texto contiene cada respuesta predefinida, un número entero de 1 a 100000. |

1202| `reply_seconds` | No | Predeterminado `9.5`. Cuánto tiempo tarda una respuesta transmitida, de 0 a 600. `0` envía toda la respuesta a la vez. Una respuesta a una solicitud sin transmisión siempre vuelve a la vez. |1265| `reply_seconds` | No | Predeterminado `9.5`. Cuánto tarda una respuesta transmitida, de 0 a 600. `0` envía toda la respuesta de una vez. La respuesta a una solicitud sin streaming siempre llega de una vez. |

1203 1266

1204Una prueba de carga en este modo cubre la puerta de enlace, su Postgres y todo lo que está frente a la puerta de enlace. No cubre los límites, velocidad o ruta de red del proveedor.1267Una prueba de carga en este modo cubre el gateway, tu Postgres y todo lo que está delante del gateway. No cubre los límites, la velocidad ni la ruta de red del proveedor.

1205 1268

1206No se envía ninguna solicitud de modelo al proveedor, por lo que la CPU de una réplica por solicitud es una estimación y se lee más baja que la producción, que también cifra su tráfico al proveedor. Confirme un recuento de réplica con un pequeño piloto contra el proveedor real. Antes de v2.1.283, la estimación se lee mucho más baja.1269No se envía ninguna solicitud de modelo al proveedor, por lo que el uso de CPU por solicitud de una réplica es una estimación y resulta menor que en producción, donde además se cifra el tráfico hacia el proveedor. Confirma el número de réplicas con un piloto pequeño contra el proveedor real. Antes de v2.1.283, la estimación resulta mucho menor.

1207 1270

1208Mientras el modo está activado, una solicitud puede llevar un encabezado `x-load-test-user` que contenga un número entero de hasta siete dígitos. La puerta de enlace cuenta cada número como un desarrollador separado, con el correo electrónico y los grupos del desarrollador cuyo token vino con la solicitud.1271Mientras el modo está activado, una solicitud puede incluir un encabezado `x-load-test-user` con un número entero de hasta siete dígitos. El gateway cuenta cada número como un desarrollador distinto, con el correo electrónico y los grupos del desarrollador cuyo token acompañó la solicitud.

1209 1272

1210Asigne a la implementación de prueba de carga su propia base de datos vacía, porque la puerta de enlace se niega a iniciar con el modo activado contra una base de datos en la que algún desarrollador ya ha gastado algo.1273Asigna al despliegue de pruebas de carga su propia base de datos vacía, porque el gateway se niega a iniciar con el modo activado contra una base de datos en la que algún desarrollador ya haya gastado algo.

1211 1274

1212<Warning>1275<Warning>

1213 Nunca active esto para una puerta de enlace que los desarrolladores usan. Cada solicitud obtiene la respuesta enlatada y ningún modelo se llama. La puerta de enlace registra una advertencia `load_test_mode is on` al arrancar y marca cada evento de auditoría [`inference`](/docs/es/claude-apps-gateway-deploy#logs) con `load_test: true` mientras el modo está activado.1276 Nunca actives esto en un gateway que usen los desarrolladores. Todas las solicitudes reciben la respuesta predefinida y no se llama a ningún modelo. El gateway registra una advertencia `load_test_mode is on` al arrancar y marca cada [evento de auditoría](/docs/es/claude-apps-gateway-deploy#logs) `inference` con `load_test: true` mientras el modo está activado.

1214</Warning>1277</Warning>

1215 1278

1216<h2 id="complete-example">1279<h2 id="complete-example">

claude-apps-gateway-config.md 2026-10-01 23:59 UTC to 2026-10-02 16:57 UTC

Configuración de la puerta de enlace de aplicaciones Claude

Estructura del archivo

Expansión de secretos

Secciones requeridas

`listen`

`oidc`

Solicitudes del IdP a través de un proxy directo

Solo egreso de proxy

`session`

`store`

`upstreams`

Mensajes de error de upstream

API de Anthropic

Encabezados de identidad por usuario para un proxy que ejecuta

Amazon Bedrock

Aplicar una protección de Amazon Bedrock

Bedrock en otra cuenta de AWS

Atribución de costo de AWS por desarrollador

Claude Platform en AWS

Agent Platform de Google Cloud

Microsoft Foundry

Encabezados estáticos en solicitudes de upstream

Múltiples upstreams

Secciones opcionales

`admin`

`enforcement`

`pricing`

Aplicar un recargo a los precios

Enviar las tarifas a los clientes con sesión iniciada

`models`

`managed`

Valores de matcher que detienen el gateway al arrancar

Qué va en `cli`

Ventana de contexto en sesiones de terminal

Servidores MCP en una política

Superposición de Claude Desktop

Contexto extendido en Claude Desktop

Quitar la opción de 1M

Precedencia con otras fuentes administradas

`telemetry`

Agrega tus propias etiquetas

Exportar directamente a tu recopilador

Cuando un destino falla

Ajuste HTTP

`load_test_mode`

Ejemplo completo

Configuración administrada del lado del cliente

Relacionado