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

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:

Secciones requeridas

`listen`

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

`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 cliente OAuth, mapea 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 de IdP.

Solicitudes de IdP a través de un proxy directo

Los upstreams de inferencia honran 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 arrancar pidiéndole que elija; use_proxy: false las mantiene directas y silencia el aviso.

Con use_proxy: true, la vaina resuelve el nombre de host de cada punto final de IdP por sí misma 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.

`session`

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

`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.

Para desarrollo local, apunte postgres_url a un contenedor 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, 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 propia de la puerta de enlace falló contra ese upstream. Un 404 significa que ese upstream no sirve el modelo solicitado, por lo que un upstream posterior en la lista aún puede.

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 gateway 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 Bedrock, Claude Platform en AWS, Agent Platform de Google Cloud y Microsoft Foundry se construyen una vez al iniciar, y sus SDK 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 iniciar; 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 Microsoft Foundry pueden nombrar sus IDs de cuenta, ARN 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 Microsoft Foundry 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 gateway v2.1.233 o posterior.

API de Anthropic

El upstream mínimo de Anthropic es una clave API de la Consola 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   # predeterminado; 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ótelo en la Consola Claude y actualice la variable env.
• oauth_token: envía Authorization: Bearer. Use la forma de portador cuando su organización emita tokens de corta duración en lugar de claves API de larga duración. El portador se lee una vez al iniciar, 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 el JWT de OIDC de su 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

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

Cuando el token de 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 de 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 usted 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 predeterminado, la puerta de enlace se niega a iniciar.

Amazon Bedrock

Para la implementación de Bedrock del lado del cliente que la puerta de enlace reemplaza o enfrenta, 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 credenciales predeterminada 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 utiliza la cadena de credenciales predeterminada del SDK de AWS: variables env, ~/.aws/credentials, rol de tarea de ECS, metadatos de instancia de EC2 o IRSA en EKS. En producción, otorgue a la vaina 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 arrancar 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.

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. Utiliza 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 gateway lo rechazan al arrancar.

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 credenciales predeterminada de AWS:
    # auth: {}
    # O credenciales 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 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 prioridad cuando también se establecen credenciales SigV4. Un bloque auth vacío utiliza la cadena de credenciales predeterminada del SDK de AWS, la misma cadena que usa el upstream Amazon Bedrock.

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

Plataforma de agentes 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 predeterminadas 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 Private Service Connect:
    # base_url: https://us-east5-aiplatform.p.googleapis.com

Un bloque auth vacío utiliza Credenciales predeterminadas de aplicación: GOOGLE_APPLICATION_CREDENTIALS, metadatos de GCE o Workload Identity de GKE. Los archivos de clave JSON de cuenta de servicio son compatibles pero desaconsejados; 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 de Agent Platform en lugar de uno regional. Google luego enruta cada solicitud a una región disponible, por lo que no rastrea la disponibilidad de modelos por región. Establecer una región específica fija cada solicitud a ella.

Microsoft Foundry

Para la implementación de 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 / Managed Identity
    # O una clave API:
    # auth:
    #   api_key: ${FOUNDRY_API_KEY}

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

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 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.

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 red.

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

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 credenciales de rol asumido.
  - 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

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 el mismo control de características a puertas de enlace independientemente de cuál upstream sirva 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 refleja la API de administración pública de Anthropic, y cumplimiento de gasto por desarrollador en /v1/messages. Consulte Límites de gasto para saber cómo se establecen y aplican los límites; esta sección cubre las claves gateway.yaml que activan la función y la ajustan.

admin:
  # Claves API estáticas nombradas para los puntos finales 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. Matriz para rotación: agregue la nueva clave, despliegue clientes,
  # elimine 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 otorgados acceso de administrador completo a través del JWT de puerta de enlace normal (sin clave API).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits

`enforcement`

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

`pricing`

El bloque pricing le dice al medidor de gasto qué cobrar en lugar del precio de lista en USD, por lo que los límites y /effective reflejan sus tasas contratadas. Los montos permanecen en USD y siguen siendo una estimación, no una factura. Dos requisitos previos:

• Claude Code v2.1.227 o posterior en el servidor de puerta de enlace. 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. La puerta de enlace se niega a iniciar con pricing establecido y ninguno de estos 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

Cómo el medidor coincide con una fila de anulación:

• Una fila reemplaza el precio de lista para solicitudes que upstream, un upstreams[].name, sirve para model. Eso incluye la tasa de modo rápido más alta, por lo que las solicitudes de modo rápido y estándar se miden con las mismas cuatro tasas.
• Un ID integrado como claude-sonnet-4-6, coincidido como models[].id, cubre cada forma fechada, forma regional de Amazon Bedrock, o forma de Plataforma de Agentes de Google Cloud que el medidor precifica 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 la cadena enviada upstream, sin distinción de mayúsculas y minúsculas.
• 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 upstream, luego una fila que coincide con el ID exacto que envió el cliente, luego una fila que nombra el modelo integrado.
• 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.
• Las solicitudes de búsqueda web permanecen en el precio de lista de $0.01; el multiplicador aún se aplica a ellas.

Para tasas por región, proporcione a cada región su propio upstream nombrado y una fila por upstream.

Marcar precios hacia arriba

Con 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:

pricing:
  multiplier: 1.2

Con un bloque admin:, el marcado 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 más rápido. La puerta de enlace registra una advertencia al arrancar que lo dice.

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

Si la puerta de enlace también envía las tasas a clientes firmados, 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.

Un servidor de puerta de enlace anterior a v2.1.271 se niega a iniciar si establece un multiplier superior a 1.

Enviar las tasas a clientes firmados

Con 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 que sirve, como la configuración administrada modelPricing. Los desarrolladores coincidentes por una política ven entonces 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 coincida con ninguna política no recibe configuración administrada, por lo que sus cifras permanecen en precio de lista. Los clientes aplican la configuración en Claude Code v2.1.242 o posterior.

• 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 puede solicitar, la fila de anulación del primer upstream que sirve ese ID. Una tasa que solo un upstream de conmutación por error cobra permanece en la puerta de enlace.
• Optar una política: establezca modelPricing en {} en el bloque cli de esa política, y sus desarrolladores permanecen en precio de lista.
• 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.

`models`

El bloque models es una lista de modelos curada por administrador opcional, servida en /v1/models y utilizada para traducir IDs de modelo por upstream. Es necesario para regiones de Bedrock no estadounidenses, ARN de rendimiento aprovisionado de Bedrock y nombres de implementación de Foundry.

auto_include_builtin_models: true   # false: exponga solo la lista a continuación
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    # description: texto opcional mostrado en clientes que lo muestren
    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 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 usa.

`managed`

El bloque managed define políticas de acceso basadas en roles 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 match: {} descrita a continuación. Se sirven por usuario en GET /managed/settings con almacenamiento en caché de ETag/304.

managed:
  policies:
    # Grupos específicos primero.
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    # Captura 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 match: {}, convencionalmente listada al final, se trata como una capa base. Cada otra política hereda cualquier clave que no establezca de la captura, por lo que las entradas por rol solo necesitan listar lo que difiere del 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 completamente la de la base.
• Listas de denegación y matrices de hooks: permissions.deny, permissions.ask, disabledMcpjsonServers, deniedMcpServers, blockedMarketplaces y cada matriz de tipo de evento hooks. Estos toman la unión de base y política, por lo que un gancho de denegación o auditoría en toda la organización no puede ser accidentalmente eliminado por una anulación por rol.
• 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.

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.

La 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:

• Cuando el valor falta o está vacío, la puerta de enlace rechaza la solicitud con el mensaje model is required. Esa verificación requiere una puerta de enlace que ejecute Claude Code v2.1.228 o posterior.
• 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.

Un 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 match: {} al final si desea una política predeterminada garantizada.

Valores de coincidencia que detienen la puerta de enlace al arrancar

Al arrancar, la puerta de enlace verifica el bloque match de cada política y la lista admin_groups. Cualquiera de estos valores detiene la puerta de enlace 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. La puerta de enlace recorta el valor y elimina un @ inicial antes de esta verificación. Escriba un dominio desnudo, como example.com.

Antes de v2.1.232, la puerta de enlace se iniciaba con estos valores. Cada valor tenía este efecto:

• Un email_domain vacío: la puerta de enlace omitía la verificación de dominio, por lo que una política con un email_domain vacío y sin lista groups coincidía con cada usuario autenticado
• Una lista groups vacía: la política no coincidía con nadie
• Un email_domain que contiene @, 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 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.

Qué va en `cli`

Cada 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, como policyHelper y wslInheritsWindowsSettings.

La 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 son env, pluginConfigs y claves anidadas bajo permissions.

Debido 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 ampliamente.

La referencia de clave completa está en Configuración de Claude Code. Las claves que los operadores alcanzan 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 reglas de permisos de usuario/proyecto

        # Entorno empujado al proceso CLI. DISABLE_UPDATES bloquea
        # actualizaciones de fondo y manuales; DISABLE_AUTOUPDATER detiene solo
        # actualizaciones de fondo.
        env:
          DISABLE_UPDATES: "1"                    # versiones de pin a través de su propia distribución

        # Hooks en toda la organización. Los comandos de gancho se ejecutan en máquinas de desarrollador, no en la
        # puerta de enlace, por lo que la ruta debe existir en cada SO de cliente en la política.
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }

Debido 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 listada a continuación:

• hooks
• Variables env que requieren la aprobación del desarrollador, como variables de proxy y URL base
• configuración de ejecución de shell como apiKeyHelper y statusLine
• la configuración de binarios de sandbox sandbox.bwrapPath, sandbox.socatPath y sandbox.ripgrep
• 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 los enumera todos.

Memoria de aprobación cubre cuánto tiempo dura una aprobación y cuándo aparece el diálogo nuevamente.

Claude 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.

Variables de entorno y el diálogo de aprobación tiene los detalles, incluidos cuatro alteradores 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 desencadenaban el diálogo.

La configuración de telemetría de la puerta de enlace empuja OTEL_EXPORTER_OTLP_ENDPOINT, por lo que establecer telemetry.forward_to desencadena 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.

Una ejecución no interactiva con la bandera -p no puede mostrar el diálogo. Aplica la configuración empujada solo para esa ejecución y no la registra como aprobada, por lo que la siguiente sesión interactiva del desarrollador aún muestra el diálogo. 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.

Si un desarrollador rechaza, Claude Code sale de esa sesión en lugar de aplicar la política. Cuando empuja un nuevo gancho, o cualquier variable env que desencadene el diálogo, a una política amplia, Claude Code por lo tanto muestra el diálogo a cada desarrollador coincidente. Muestra el diálogo en una sesión en ejecución en la próxima encuesta por hora, y de lo contrario en el próximo inicio del desarrollador.

La clave cli se nombró settings en versiones anteriores. Ese deletreo aún se acepta como alias, pero las nuevas implementaciones deben usar cli.

Servidores MCP en una política

Para proporcionar servidores MCP a los clientes de Claude Code que coincida una política, establezca managedMcpServers 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.

La puerta de enlace verifica cada entrada al arrancar con las mismas reglas que Claude Code aplica en el cliente, y si una entrada falla una verificación, la puerta de enlace se niega a iniciar y nombra la entrada.

Si 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 antes de ejecutar las verificaciones de entrada, por lo que cada cliente coincidente recibe el valor literal y puede leerlo. La orientación de encabezado para servidores proporcionados se aplica al valor expandido.

La 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.

Superposición de Claude Desktop

Si su organización también implementa Claude Desktop, la misma puerta de enlace sirve a ambos clientes. Apunte 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 de código de dispositivo contra esta puerta de enlace, y obtiene su configuración de la respuesta.

La 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:

• La lista de modelos, de availableModels

• Herramientas deshabilitadas, de entradas permissions.deny de nombre de herramienta desnudo. 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

• 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 derivada

• Un punto final OTLP que apunta a la puerta de enlace en sí, y los atributos de identidad del usuario firmado. 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 como listen.public_url.

  Claude Desktop exporta cada señal con una codificación: http/protobuf, o http/json cuando establece OTEL_EXPORTER_OTLP_PROTOCOL o uno de sus variantes por señal en http/json en el bloque 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 Desktop

Para 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. managedMcpServers de Claude Desktop toma un valor de matriz en lugar de un objeto.

La puerta de enlace omite claves sin equivalente de Claude Desktop, como hooks y reglas de permisos limitadas como Bash(npm *), de la respuesta de bootstrap.

Agregue 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 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.

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

Cada clave es opcional; Claude Desktop aplica su propio 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 en sí 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:

• Una clave desconocida
• Una clave reconocida cuyo valor Claude Desktop rechazaría o silenciosamente descartaría, como un valor vacío o una subclave mal escrita dentro de una entrada anidada. Antes de v2.1.260, la puerta de enlace silenciosamente descartaba un campo mal escrito dentro de un objeto anidado de una entrada managedMcpServers u orgPluginSettings en lugar de fallar al arrancar.
• 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, models y la sección telemetry de forward_to.
• Un alias heredado de una clave actual. En el error de arranque, la puerta de enlace nombra la clave canónica a escribir.

Si usa un valor o forma de entrada deprecada, como una entrada managedMcpServers sin transport, la puerta de enlace se inicia y registra una advertencia que nombra el reemplazo.

La 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.

Si establece orgPluginSettings en el bloque desktop de una política, la puerta de enlace lo sirve en la forma de matriz que Claude Desktop 1.15200.0 y posterior lee. Los escritorios más antiguos ignoran la matriz y no aplican ninguna política de herramientas de complementos, por lo que actualice a los miembros a 1.15200.0 o posterior antes de confiar en ello.

La puerta de enlace rellena las claves que el bloque desktop de una política no establece desde el bloque desktop de la captura 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:

• disabledBuiltinTools: la puerta de enlace usa la unión de la lista de la base y la lista de la política
• 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 rol

Para todas las demás claves, si la 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 una matriz 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.

Si 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.

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 puerta de enlace tiene rango primero. Precedencia dentro del nivel administrado 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 cada fuente de administrador independientemente de cuál fuente seleccione, como las claves de bloqueo de sandbox, forceRemoteSettingsRefresh y la fusión env por variable. Un 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.

Los hosts de incrustación como Claude Desktop pueden suministrar política a través de la opción managedSettings del SDK. Configuración de padres de hosts de incrustación dice cuándo Claude Code la aplica, y Restringir configuración de padres enumera qué configuración de dirección de permitir aún se aplica sin los bloqueos allowManaged*Only.

Las 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 SDK del agente. Si la puerta de enlace es inaccesible al iniciar, las sesiones firmadas salen con un error en lugar de ejecutarse sin su política.

`telemetry`

El 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 Protocolo OpenTelemetry (OTLP) sobre HTTP. Para omitir el relé y hacer que las sesiones exporten directamente a su recopilador, nombre el recopilador en una política. Consulte Monitoreo de uso para las métricas y eventos que emite el CLI.

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.

Claude Desktop y las sesiones de Cowork firmadas 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.

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

Si 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 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.

Necesita 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.

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      # Opt-in 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 forward_to debe usar https://, con una excepción para un recopilador en la interfaz de bucle de retorno de la puerta de enlace:

• http://localhost:<port> pasa la validación de configuración, pero la protección SSRF bloquea cada exportación con ECONNREFUSED_SSRF a menos que establezca CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 en el entorno de la puerta de enlace
• http://127.0.0.1:<port> o http://[::1]:<port> falla al arrancar a menos que esa variable esté establecida

Para 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.

La 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 empujando 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 uno establecido en otlp si al menos un destino forward_to habilita esa señal y en none de lo contrario
• OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
• OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

Antes de Claude Code v2.1.265 en el servidor de puerta de enlace, la puerta de enlace empujaba los tres selectores de exportador como otlp, incluido para señales que ningún destino optó.

El punto final empujado 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.

Los desarrolladores firmados a través de /login no pueden redirigir exportaciones con su propia configuración OTEL:

• Variables establecidas localmente: Claude Code aplica las variables empujadas en el nivel administrado, por lo que cada una anula el valor que un desarrollador establece para ella localmente.
• Puntos finales configurados localmente: con la exportación OTLP/HTTP habilitada, el CLI ignora cualquier punto final configurado localmente, independientemente de si la puerta de enlace empujó las variables de telemetría. Sus exportaciones van a la puerta de enlace a menos que una política nombre su recopilador como el punto final.

Sin un destino forward_to para una señal, la puerta de enlace acepta y 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 firmen. Para omitir el relé en su lugar, nombre el recopilador en una política.

Las trazas además requieren CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 en cada cliente. Establézcalo en el bloque env de una política administrada, ya que la puerta de enlace no lo empuja. Los desarrolladores lo aprueban en el mismo diálogo de aprobación de seguridad que el punto final empujado ya desencadena.

Establé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 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ézcala en 0 en la política de ese grupo.

Tanto las codificaciones OTLP de protobuf como JSON se retransmiten, y cualquier backend compatible con OpenTelemetry funciona como destino.

Exportar directamente a su recopilador

Para hacer que las sesiones firmadas 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. Claude Code agrega /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é.

Para 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.

Cuando 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 antes de aplicarlo en una sesión interactiva.

Claude Code verifica el punto final antes de exportar una señal directamente, y mantiene esa señal en el relé cuando una verificación falla. Las verificaciones incluyen:

• 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é.
• La URL usa https://, o http:// a una dirección de bucle de retorno
• La URL se resuelve a 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 como se escribe, así que incluya la ruta completa allí.
• La URL no es el host de la puerta de enlace en sí. Un punto final dirigido a la puerta de enlace mantiene la ruta de relé y su token de sesión.
• Ni usted ni el desarrollador han configurado otelHeadersHelper en ninguna fuente de configuración. Con un ayudante configurado, cada señal permanece en el relé.

El 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.

El 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 empuje:

• Si la puerta de enlace ya empuja las variables de telemetría, cubren habilitación, selectores y protocolo, y su punto final explícito anula el valor <public_url> empujado. Establezca un selector OTEL_*_EXPORTER en otlp usted mismo solo para una señal que ningún destino forward_to habilita.
• Si no, también establezca CLAUDE_CODE_ENABLE_TELEMETRY=1, los selectores OTEL_*_EXPORTER y OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.

Cuando el desarrollador cierra sesión, o firma en una puerta de enlace diferente, las exportaciones al recopilador se detienen y Claude Code descarta cada lote restante en lugar de enviarlo.

Cuando un destino falla

La puerta de enlace no almacena en búfer, reintenta o 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.

Despué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 de esa exportación como mal formada o demasiado grande.

Una carga 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.

Ajuste de HTTP

Cuatro 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.

Si deja ambas listas access_control vacías, que es el 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 empujar configuración administrada que ejecuta comandos en máquinas de desarrollador.

Mientras allow_cidrs esté vacío, la puerta de enlace advierte en dos lugares, sin cambiar cómo responde a ninguna solicitud:

• Al arrancar: una advertencia en el registro operacional 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.
• En tiempo de ejecución: la primera vez que llega una solicitud 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 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 verificación, por lo que los sondeos de salud desde rangos públicos no la desencadenan.

Ambas 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á listado 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.

Detrás de tal front end, establezca listen.trusted_proxies primero 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 Internet público independientemente.

Ejemplo completo

Esta configuración de referencia completa ejercita cada sección principal; los bloques ajuste de 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 reclamación en cada id_token, para diagnóstico de groups_claim.
# No afecta 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 termine 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 org de 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 en 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

# Habilita /v1/organizations/spend_limits (refleja la API de administración de Anthropic)
# y cumplimiento de gasto por desarrollador en /v1/messages. Omita para desactivar.
# Los límites en sí se establecen a través de la API de administración, 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

# Medir a tasas contratadas en lugar del precio de lista USD. Requiere admin: o una
# política managed:. Con managed:, las mismas tasas también van a clientes con sesión iniciada.
# 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 denegació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.

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. Un desarrollador que los establezca en su propio ~/.claude/settings.json no tiene efecto, y tampoco lo hace establecerlos en la carga útil de la puerta de enlace.

Relacionado

• 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