58 `listen`58 `listen`
59</h3>59</h3>
60 60
61El 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.61El 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.
62 62
63| Campo | Requerido | Descripción |63| Campo | Requerido | Descripción |
64| - | - | - |64| - | - | - |
65| `host` | No | Dirección de enlace. Predeterminado `0.0.0.0`. |65| `host` | No | Dirección de enlace. Por defecto `0.0.0.0`. |
66| `port` | No | Puerto de enlace. Predeterminado `8080`. |66| `port` | No | Puerto de enlace. Por defecto `8080`. |
67| `public_url` | A menos que `host` sea loopback | El origen `https://` visible externamente, utilizado para construir el `redirect_uri` de IdP y 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 encabezados `X-Forwarded-*`; son suplantables 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 necesario para habilitar [telemetría](#telemetry), porque la puerta de enlace construye el punto final OTLP que envía a los clientes desde esta URL. |67| `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](#telemetry), porque la puerta de enlace construye el punto final OTLP que envía a los clientes a partir de esta URL. |
68| `tls.cert` / `tls.key` | No | Rutas PEM si la puerta de enlace termina TLS por sí misma |68| `tls.cert` / `tls.key` | No | Rutas PEM si la puerta de enlace termina TLS por sí misma |
69| `trusted_proxies` | No | CIDR 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 límites de velocidad por IP y auditoría. Equivalente a nginx `set_real_ip_from`. Las entradas `X-Forwarded-For` escritas como `ipv4:port` o `[ipv6]:port`, como algunos equilibradores de carga hacen, se leen con el puerto descartado. 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. |69| `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. |
70 70
71<h3 id="oidc">71<h3 id="oidc">
72 `oidc`72 `oidc`
73</h3>73</h3>
74 74
75El 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.75El 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.
76 76
77OpenID Connect (OIDC) es el protocolo SSO que la puerta de enlace utiliza con su proveedor de identidad; consulte [Configuración del proveedor de identidad](/docs/es/claude-apps-gateway-deploy#identity-provider-setup) para saber qué registrar en el lado de IdP.77OpenID Connect (OIDC) es el protocolo SSO que la puerta de enlace utiliza con su proveedor de identidad; consulte [Configuración del proveedor de identidad](/docs/es/claude-apps-gateway-deploy#identity-provider-setup) para saber qué registrar en el lado del IdP.
78 78
79| Campo | Requerido | Descripción |79| Campo | Requerido | Descripción |
80| - | - | - |80| - | - | - |
81| `issuer` | Sí | Base de descubrimiento OIDC. Debe servir descubrimiento en `/.well-known/openid-configuration`. Use HTTPS en producción; la puerta de enlace acepta un emisor `http://`. Un emisor de bucle local como `http://localhost:8081` es rechazado por la [protección SSRF](/docs/es/claude-apps-gateway-deploy#threat-model-summary) a menos que `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` esté establecido en el entorno de la puerta de enlace. |81| `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](/docs/es/claude-apps-gateway-deploy#threat-model-summary) a menos que `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` esté establecido en el entorno de la puerta de enlace. |
82| `client_id` / `client_secret` | Sí | De su registro de cliente OAuth |82| `client_id` / `client_secret` | Sí | De su registro de cliente OAuth |
83| `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 de IdP multiinquilino. Independientemente de esta configuración, un id\_token cuya reclamación `email_verified` es explícitamente `false` siempre se rechaza. |83| `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. |
84| `allowed_groups` | No | Restrinja el inicio de sesión a miembros de estos grupos de 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 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 IdP para emitir membresía aplanada. |84| `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. |
85| `groups_claim` | No | Qué reclamación de id\_token lleva la membresía del grupo. Predeterminado `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. |85| `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. |
86| `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, por lo que `allowed_groups` y `managed.policies.match.groups` coinciden en correos electrónicos de grupo. |86| `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. |
87| `email_claim` | No | Qué reclamación de id\_token lleva el correo electrónico del usuario. Predeterminado `email`. Algunos IdP, 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. |87| `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. |
88| `scopes` | No | Anulación completa de los alcances OIDC que solicita la puerta de enlace. Predeterminado `[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`. Soltar `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](/docs/es/claude-apps-gateway-deploy#identity-provider-setup) para recetas de alcance por IdP como el flujo de token de actualización de Google. |88| `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](/docs/es/claude-apps-gateway-deploy#identity-provider-setup) para recetas de alcance por IdP como el flujo de token de actualización de Google. |
89| `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. Predeterminado `false`: la solicitud de actualización omite `scope`. La mayoría de IdP 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 userinfo de IdP que acepte el token de acceso actualizado. Si controla el inicio de sesión o coincide con políticas en grupos y el id\_token de su 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 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. |89| `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. |
90| `extra_auth_params` | No | Parámetros de consulta adicionales añadidos a la solicitud de autorización de IdP, textualmente. Este es el mecanismo de anulación para comportamiento específico de 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 administrados por la puerta de enlace: `state`, `nonce`, `redirect_uri`, PKCE, `scope`, `response_type`, `response_mode` y `client_id`. |90| `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`. |
91| `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. Predeterminado `false`. |91| `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`. |
92| `use_pkce` | No | Envíe un desafío PKCE (S256) en la solicitud de autorización. Predeterminado `true`. Establezca `false` solo si su IdP rechaza PKCE para este cliente confidencial. |92| `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. |
93| `clock_skew_seconds` | No | Tolere la desviación del reloj al validar reclamaciones de tiempo de id\_token. Predeterminado `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 de host/IdP. |93| `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. |
94| `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 de forma predeterminada. |94| `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. |
95| `id_token_signed_response_alg` | No | Algoritmo de firma de id\_token esperado. Predeterminado `RS256`. Establezca para IdP que firman con ES256, PS256 o EdDSA. |95| `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. |
96| `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 |96| `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 |
97| `discovery_url` | No | Busque el documento de descubrimiento desde esta URL en lugar de derivarlo de `issuer`, para IdP detrás de un proxy que reescribe el host del emisor. La ruta debe contener `/.well-known/`. |97| `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/`. |
98| `use_proxy` | No | Envíe las propias solicitudes de IdP de la puerta de enlace a través del proxy directo en `HTTPS_PROXY` o `HTTP_PROXY`, honrando `NO_PROXY`. `false` mantiene esas solicitudes directas. Requiere v2.1.227 o posterior; consulte [Solicitudes de IdP a través de un proxy directo](#idp-requests-through-a-forward-proxy) a continuación. |98| `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](#idp-requests-through-a-forward-proxy) a continuación. |
99| `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. |99| `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. |
100| `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 de IdP. Para cargar un archivo montado, escriba `${file:/etc/gateway/idp-ca.pem}`. Úselo para Keycloak o Dex detrás de PKI corporativa. |100| `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. |
101 101
102<h4 id="idp-requests-through-a-forward-proxy">102<h4 id="idp-requests-through-a-forward-proxy">
103 Solicitudes de IdP a través de un proxy directo103 Solicitudes del IdP a través de un proxy directo
104</h4>104</h4>
105 105
106Los 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.106Los 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.
107 107
108Con `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](/docs/es/claude-apps-gateway-deploy#threat-model-summary) se aplican en la ruta proxificada también.108Con `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](/docs/es/claude-apps-gateway-deploy#threat-model-summary) se aplican en la ruta proxificada también.
109 109
110[Egreso solo de proxy](#proxy-only-egress) cambia ambos: mientras está activo, las solicitudes de IdP siguen el proxy a menos que establezca `use_proxy: false`, y la puerta de enlace entrega al proxy cada nombre de host de IdP sin resolverlo primero.110[Solo egreso de proxy](#proxy-only-egress) 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.
111 111
112<h4 id="proxy-only-egress">112<h4 id="proxy-only-egress">
113 Egreso solo de proxy113 Solo egreso de proxy
114</h4>114</h4>
115 115
116Establezca `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1` en el entorno de la puerta de enlace, junto a `HTTPS_PROXY`, cuando la vaina alcanza otros hosts solo a través de ese proxy directo y no puede resolver nombres DNS públicos por sí misma, 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.116Establezca `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.
117 117
118```bash theme={null}118```bash theme={null}
119export HTTPS_PROXY=http://proxy.corp.example.com:3128119export HTTPS_PROXY=http://proxy.corp.example.com:3128
122export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1122export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1
123```123```
124 124
125La puerta de enlace registra una línea `network:` al arrancar mientras el egreso solo de proxy está activo.125La puerta de enlace registra una línea `network:` al arranque mientras el egreso solo de proxy está activo.
126 126
127Cada fila a continuación es una clase de solicitud saliente en una puerta de enlace con `HTTPS_PROXY` establecido, de forma predeterminada y mientras el egreso solo de proxy está activo.127Cada 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.
128 128
129| Solicitud saliente | Predeterminado | Egreso solo de proxy activo |129| Solicitud saliente | Por defecto | Egreso solo de proxy activo |
130| - | - | - |130| - | - | - |
131| 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 |131| 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 |
132| Descubrimiento de IdP, JWKS, token y userinfo | Directo a menos que [`oidc.use_proxy: true`](#idp-requests-through-a-forward-proxy), 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 |132| Descubrimiento del IdP, JWKS, token y userinfo | Directo a menos que [`oidc.use_proxy: true`](#idp-requests-through-a-forward-proxy), 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 |
133| Upstreams de Amazon Bedrock, Claude Platform en AWS, Agent Platform de Google Cloud y Microsoft Foundry; búsquedas de grupos de Google | Nombre de host entregado al proxy | Sin cambios |133| 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 |
134 134
135El egreso solo de proxy se mantiene desactivado a menos que el entorno de la puerta de enlace cumpla con las tres condiciones siguientes:135El egreso solo de proxy se mantiene desactivado a menos que el entorno de la puerta de enlace cumpla con las tres condiciones siguientes:
136 136
137* `HTTPS_PROXY` o `HTTP_PROXY` está establecido.137* `HTTPS_PROXY` o `HTTP_PROXY` está establecido.
138* `NO_PROXY` y `no_proxy` están vacíos. Si su plataforma inyecta cualquiera en vainas, 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.138* `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.
139* `CLAUDE_GATEWAY_ALLOW_LOOPBACK` no está activado. Un recopilador o IdP en el propio loopback de la vaina 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.139* `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.
140 140
141Cuando una de esas condiciones no se cumple, la puerta de enlace registra una advertencia al arrancar nombrando la variable que lo detuvo y mantiene el comportamiento predeterminado.141Cuando 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.
142 142
143Una 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`](#idp-requests-through-a-forward-proxy).143Una 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`](#idp-requests-through-a-forward-proxy).
144 144
150 `session`150 `session`
151</h3>151</h3>
152 152
153El 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.153El 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.
154 154
155| Campo | Requerido | Descripción |155| Campo | Requerido | Descripción |
156| - | - | - |156| - | - | - |
157| `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 suelte el antiguo. |157| `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. |
158| `ttl_hours` | No | Duración del token portador de la puerta de enlace. Predeterminado `1`. El CLI se actualiza silenciosamente antes de la expiración cuando IdP emite tokens de actualización. Una duración más corta desactiva más rápido; una más larga hace menos viajes de 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. |158| `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. |
159 159
160<h3 id="store">160<h3 id="store">
161 `store`161 `store`
165 165
166| Campo | Requerido | Descripción |166| Campo | Requerido | Descripción |
167| - | - | - |167| - | - | - |
168| `postgres_url` | Sí | URL `postgres://` o `postgresql://`. Requerido: el encuentro de concesión de dispositivo, 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 arrancar y al actualizar, por lo que el rol necesita derechos para crear y alterar tablas en el esquema de destino. Consulte [Actualizaciones](/docs/es/claude-apps-gateway-deploy#upgrades) y [Postgres](/docs/es/claude-apps-gateway-deploy#postgres). |168| `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](/docs/es/claude-apps-gateway-deploy#upgrades) y [Postgres](/docs/es/claude-apps-gateway-deploy#postgres). |
169| `username` | No | Anula el usuario en `postgres_url` |169| `username` | No | Anula el usuario en `postgres_url` |
170| `password` | No | Credencial de base de datos. Establézcalo aquí en lugar de en `postgres_url` para que la credencial se mantenga fuera de la URL. Acepta cualquier carácter y tiene prioridad sobre las credenciales de URL. |170| `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. |
171| `max_connections` | No | Tamaño del grupo de conexiones de Postgres por réplica. Predeterminado `5`, que es conservador y amigable con bases de datos compartidas. Con [límites de gasto](#admin) habilitados, la ruta activa realiza algunas operaciones por solicitud de inferencia, así que aumente para una base de datos dedicada bajo carga, y mantenga réplicas × esto por debajo de `max_connections` de la base de datos. |171| `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](#admin) 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. |
172| `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`, predeterminado `5`. Aumente 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. |172| `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. |
173| `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`, predeterminado `0`. Consulte [Comportamiento de interrupción](/docs/es/claude-apps-gateway-deploy#outage-behavior) 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. |173| `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](/docs/es/claude-apps-gateway-deploy#outage-behavior) 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. |
174 174
175Para 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`.175Para 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`.
176 176
177<h3 id="upstreams">177<h3 id="upstreams">
178 `upstreams`178 `upstreams`
180 180
181`upstreams` es una lista ordenada. La puerta de enlace reenvía la inferencia al primer upstream que resuelve el modelo solicitado.181`upstreams` es una lista ordenada. La puerta de enlace reenvía la inferencia al primer upstream que resuelve el modelo solicitado.
182 182
183En `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.183En `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.
184 184
185Si 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](#per-user-identity-headers-for-a-proxy-you-run).185Si 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](#per-user-identity-headers-for-a-proxy-you-run).
186 186
187La 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.187La 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.
188 188
189Múltiples upstreams del mismo proveedor deben establecer un `name:` distinto.189Múltiples upstreams del mismo proveedor deben establecer un `name:` distinto.
190 190
191Los 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](#anthropic-api).191Los 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](#anthropic-api).
192 192
193<h4 id="upstream-error-messages">193<h4 id="upstream-error-messages">
194 Mensajes de error de upstream194 Mensajes de error de upstream
201 201
202Cuando 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.202Cuando 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.
203 203
204Los 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](/docs/es/claude-apps-gateway-deploy#logs). Lo que el desarrollador ve de esos upstreams depende del rechazo:204Los 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](/docs/es/claude-apps-gateway-deploy#logs). Lo que el desarrollador ve de esos upstreams depende del rechazo:
205 205
206* `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.206* `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.
207* `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`.207* `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`.
208* Cualquier otro estado: copia genérica por estado, como `upstream rate limit exceeded` en un `429`.208* Cualquier otro estado: copia genérica por estado, como `upstream rate limit exceeded` en un `429`.
209 209
210Por 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](/docs/es/errors#prompt-is-too-long) en ese token, como lo hace en `prompt is too long`.210Por 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](/docs/es/errors#prompt-is-too-long) en ese token, como lo hace en `prompt is too long`.
211 211
212Mantener 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.212Mantener 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.
213 213
214<h4 id="anthropic-api">214<h4 id="anthropic-api">
215 API de Anthropic215 API de Anthropic
216</h4>216</h4>
217 217
218El upstream mínimo de Anthropic es una clave API de la [Consola Claude](https://platform.claude.com):218El upstream mínimo de Anthropic es una clave API de la [Consola de Claude](https://platform.claude.com):
219 219
220```yaml theme={null}220```yaml theme={null}
221upstreams:221upstreams:
222 - provider: anthropic222 - provider: anthropic
223 auth:223 auth:
224 api_key: ${ANTHROPIC_API_KEY}224 api_key: ${ANTHROPIC_API_KEY}
225 # O un portador OAuth (p. ej., un token intercambiado por Workload-Identity-Federation):225 # O un portador OAuth (p. ej. un token intercambiado por Workload-Identity-Federation):
226 # oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}226 # oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
227 # base_url: https://api.anthropic.com # predeterminado; anule para un proxy directo227 # base_url: https://api.anthropic.com # por defecto; anule para un proxy directo
228```228```
229 229
230Las dos formas de credencial difieren en el encabezado que envían:230Las dos formas de credencial difieren en el encabezado que envían:
231 231
232* **`api_key`**: envía `x-api-key`. Rótelo en la Consola Claude y actualice la variable env.232* **`api_key`**: envía `x-api-key`. Rótela en la Consola de Claude y actualice la variable de entorno.
233* **`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.233* **`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.
234 234
235En 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](https://platform.claude.com/docs/en/manage-claude/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.235En 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](https://platform.claude.com/docs/en/manage-claude/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.
236 236
237```yaml theme={null}237```yaml theme={null}
238upstreams:238upstreams:
248<a id="per-user-identity-headers-for-a-proxy-you-run" />248<a id="per-user-identity-headers-for-a-proxy-you-run" />
249 249
250<h5 id="per-user-identity-headers-for-a-proxy-you-run">250<h5 id="per-user-identity-headers-for-a-proxy-you-run">
251 Encabezados de identidad por usuario para un proxy que usted ejecuta251 Encabezados de identidad por usuario para un proxy que ejecuta
252</h5>252</h5>
253 253
254Puede apuntar el `base_url` de un upstream `provider: anthropic` a un proxy que usted 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 ejecutando Claude Code v2.1.233 o posterior.254Puede 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.
255 255
256Por ejemplo, para un proxy en `upstream-gateway.internal.example.com`:256Por ejemplo, para un proxy en `upstream-gateway.internal.example.com`:
257 257
261 base_url: https://upstream-gateway.internal.example.com261 base_url: https://upstream-gateway.internal.example.com
262 auth:262 auth:
263 api_key: ${PROXY_KEY}263 api_key: ${PROXY_KEY}
264 forward_user_identity: true # predeterminado false264 forward_user_identity: true # por defecto false
265```265```
266 266
267La puerta de enlace añade estos encabezados a cada solicitud que reenvía a ese upstream.267La puerta de enlace añade estos encabezados a cada solicitud que reenvía a ese upstream.
268 268
269| Encabezado | Valor |269| Encabezado | Valor |
270| - | - |270| - | - |
271| `x-litellm-end-user-id` | El correo electrónico del desarrollador, cuando IdP lo proporcionó. |271| `x-litellm-end-user-id` | El correo electrónico del desarrollador, cuando el IdP proporcionó uno. |
272| `x-claude-gateway-user-id` | El asunto de IdP del desarrollador, de la reclamación `sub` del token. |272| `x-claude-gateway-user-id` | El asunto del IdP del desarrollador, de la reclamación `sub` del token. |
273| `x-claude-gateway-user-email` | El correo electrónico del desarrollador, cuando IdP lo proporcionó. |273| `x-claude-gateway-user-email` | El correo electrónico del desarrollador, cuando el IdP proporcionó uno. |
274 274
275Cuando 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`](#oidc) en esa reclamación.275Cuando 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`](#oidc) en esa reclamación.
276 276
277Cuando 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](#upstreams) 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.277Cuando 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](#upstreams) 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.
278 278
279Establezca `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.279Establezca `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.
280 280
281<h4 id="amazon-bedrock">281<h4 id="amazon-bedrock">
282 Amazon Bedrock282 Amazon Bedrock
283</h4>283</h4>
284 284
285Para la implementación de Bedrock del lado del cliente que la puerta de enlace reemplaza o enfrenta, consulte [Claude Code en Amazon Bedrock](/docs/es/amazon-bedrock). El upstream del lado de la puerta de enlace:285Para la implementación de Amazon Bedrock del lado del cliente que la puerta de enlace reemplaza o fronts, consulte [Claude Code en Amazon Bedrock](/docs/es/amazon-bedrock). El upstream del lado de la puerta de enlace:
286 286
287```yaml theme={null}287```yaml theme={null}
288upstreams:288upstreams:
289 - provider: bedrock289 - provider: bedrock
290 region: us-east-1290 region: us-east-1
291 auth: {} # preferido: cadena de credenciales predeterminada de AWS291 auth: {} # preferido: cadena de credencial por defecto de AWS
292 # O credenciales explícitas:292 # O credenciales explícitas:
293 # auth:293 # auth:
294 # aws_access_key_id: ${AWS_AKID}294 # aws_access_key_id: ${AWS_AKID}
301 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com301 # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com
302```302```
303 303
304Un 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.304Un 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.
305 305
306Las 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.306Las 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.
307 307
308| Configuración | Cómo |308| Configuración | Cómo |
309| - | - |309| - | - |
310| Permisos de IAM | Otorgue al principal de la puerta de enlace `bedrock:InvokeModel` y `bedrock:InvokeModelWithResponseStream` tanto en los ARN de perfil de inferencia como en los ARN 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 ARN de modelo de fundación. La puerta de enlace lo utiliza, sin cargo, para contar los tokens de entrada de una solicitud que el cliente abandonó, por lo que [límites de gasto](#admin) se mantienen precisos. Sin él, la puerta de enlace vuelve a una solicitud de Bedrock de un token para ese conteo. |310| 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](#admin) se mantienen precisos. Sin él, la puerta de enlace vuelve a una solicitud de Bedrock de un token para ese conteo. |
311| Acceso a modelos | Amazon Bedrock habilita el acceso a modelos de forma predeterminada 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](/docs/es/amazon-bedrock#1-submit-use-case-details) para el formulario de AWS Organizations y los permisos que el remitente necesita. |311| 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](/docs/es/amazon-bedrock#1-submit-use-case-details) para el formulario de AWS Organizations y los permisos que el remitente necesita. |
312| EKS (IRSA) | Cree un rol de IAM con la política anterior y una política de confianza para el proveedor 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. |312| 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. |
313| ECS / EC2 | Adjunte el rol de IAM a la definición de tarea o perfil de instancia. `auth: {}` la recoge. |313| ECS / EC2 | Adjunte el rol de IAM a la definición de tarea o perfil de instancia. `auth: {}` la recoge. |
314| En cualquier otro lugar | Pase credenciales a través de las variables env `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` y `AWS_SESSION_TOKEN`, o establézcalas explícitamente en `auth:` con expansión `${VAR}` |314| 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}` |
315| Región | `region:` es la región del punto final de API. Los perfiles de inferencia entre regiones enrutan a través de la geografía (EE.UU., UE, APAC) independientemente de cuál elija. Para regiones no estadounidenses o ARN de rendimiento aprovisionado, agregue un bloque [`models:`](#models) con los IDs correctos por upstream. |315| 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:`](#models) con los IDs correctos por upstream. |
316
317<h5 id="apply-an-amazon-bedrock-guardrail">
318 Aplicar una protección de Amazon Bedrock
319</h5>
320
321Para 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.
322
323```yaml theme={null}
324upstreams:
325 - provider: bedrock
326 region: us-east-1
327 auth: {}
328 guardrail:
329 id: gr-abc123 # ID de protección o ARN completo
330 version: "1" # un número de versión publicada, o DRAFT
331 # mantenga las comillas: un 1 desnudo falla al arranque
332```
333
334<Warning>
335 La puerta de enlace no admite etiquetas de entrada de protección. No añade etiquetas de contenido de protección a los avisos, por lo que un filtro de protección que Amazon Bedrock aplica solo a entrada etiquetada no se ejecuta en el tráfico a través de la puerta de enlace. Para qué filtros dependen de etiquetas de entrada, consulte [etiquetas de entrada](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-tagging.html) en la documentación de Amazon Bedrock.
336</Warning>
337
338Tambié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`](#bedrock-in-another-aws-account) el rol nombrado en `role_arn`.
339
340Establezca `guardrail` en cada upstream `bedrock` o en ninguno. La puerta de enlace se niega a iniciar en una mezcla, porque [conmutación por error](#multiple-upstreams) podría enviar una solicitud a un upstream de Bedrock que no tiene protección.
341
342La 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.
343
344Cuando 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.
345
346<a id="bedrock-in-another-aws-account" />
347
348<h5 id="bedrock-in-another-aws-account">
349 Bedrock en otra cuenta de AWS
350</h5>
351
352Establezca `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.
353
354Requiere 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.
355
356```yaml theme={null}
357upstreams:
358 - name: bedrock-isolated
359 provider: bedrock
360 region: us-east-1
361 auth: {} # el rol propio de la puerta de enlace: solo llama a STS
362 assume_role:
363 role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
364 # external_id: ${BEDROCK_ROLE_EXTERNAL_ID} # cuando la política de confianza del rol lo requiere
365```
366
367El bloque `assume_role` toma tres claves:
368
369| Clave | Significado |
370| - | - |
371| `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](#amazon-bedrock) que este upstream necesita, `bedrock:CountTokens` incluido, más `bedrock:ApplyGuardrail` cuando el upstream establece `guardrail`. |
372| `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. |
373| `session_name` | Opcional. `email` o `sub` da a cada desarrollador su propia sesión: consulte [Atribución de costo de AWS por desarrollador](#per-developer-aws-cost-attribution). Sin establecer, cada solicitud usa una sesión nombrada `claude-apps-gateway`. |
374
375La 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`.
376
377```json theme={null}
378{
379 "Version": "2012-10-17",
380 "Statement": [{
381 "Effect": "Allow",
382 "Principal": { "AWS": "arn:aws:iam::111111111111:role/claude-gateway" },
383 "Action": "sts:AssumeRole",
384 "Condition": { "StringEquals": { "sts:ExternalId": "your-external-id" } }
385 }]
386}
387```
388
389* 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](#upstream-error-messages) 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.
390* 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.
391* `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`.
392* Cada desarrollador que la puerta de enlace admite puede usar este upstream; [`managed`](#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.
393
394Este ejemplo da a un modelo un ID personalizado que solo el upstream aislado sirve:
395
396```yaml theme={null}
397models:
398 - id: claude-opus-restricted # un ID personalizado, no un nombre de modelo integrado
399 upstream_model:
400 bedrock-isolated: us.anthropic.claude-opus-4-8 # el único upstream que lo sirve
401```
402
403<a id="per-developer-aws-cost-attribution" />
404
405<h5 id="per-developer-aws-cost-attribution">
406 Atribución de costo de AWS por desarrollador
407</h5>
408
409Por 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`](#bedrock-in-another-aws-account) 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.
410
411Requiere una puerta de enlace que ejecute Claude Code v2.1.281 o posterior. [Atribución de costo en AWS](/docs/es/claude-apps-gateway-on-aws#cost-attribution) cubre el rol de IAM y dónde la facturación de AWS muestra las sesiones.
412
413```yaml theme={null}
414upstreams:
415 - provider: bedrock
416 region: us-east-1
417 auth: {} # el rol propio de la puerta de enlace: solo llama a STS
418 assume_role:
419 role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
420 session_name: email # o sub
421```
422
423`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`](#oidc).
424
425Un 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.
426
427La 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](/docs/es/claude-apps-gateway-spend-limits) se mantienen precisos. Ese conteo y su [solicitud de respaldo de un token](#amazon-bedrock) 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.
428
429Para 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.
316 430
317<h4 id="claude-platform-on-aws">431<h4 id="claude-platform-on-aws">
318 Claude Platform en AWS432 Claude Platform en AWS
319</h4>433</h4>
320 434
321Claude 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.435Claude 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.
322 436
323Para la implementación del lado del cliente de la misma plataforma, consulte [Claude Code en Claude Platform en AWS](/docs/es/claude-platform-on-aws). El upstream del lado de la puerta de enlace:437Para la implementación del lado del cliente de la misma plataforma, consulte [Claude Code en Claude Platform en AWS](/docs/es/claude-platform-on-aws). El upstream del lado de la puerta de enlace:
324 438
329 workspace_id: wrkspc_...443 workspace_id: wrkspc_...
330 auth:444 auth:
331 api_key: ${ANTHROPIC_AWS_API_KEY} # enviado como x-api-key445 api_key: ${ANTHROPIC_AWS_API_KEY} # enviado como x-api-key
332 # O SigV4 a través de la cadena de credenciales predeterminada de AWS:446 # O SigV4 a través de la cadena de credencial por defecto de AWS:
333 # auth: {}447 # auth: {}
334 # O credenciales SigV4 explícitas:448 # O credenciales de SigV4 explícitas:
335 # auth:449 # auth:
336 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}450 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}
337 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}451 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
339 # base_url: https://aws-external-anthropic.us-east-1.api.aws453 # base_url: https://aws-external-anthropic.us-east-1.api.aws
340```454```
341 455
342La 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](#amazon-bedrock).456La 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](#amazon-bedrock) usa.
343 457
344| Campo | Requerido | Descripción |458| Campo | Requerido | Descripción |
345| - | - | - |459| - | - | - |
346| `region` | Sí | Región de AWS, letras minúsculas, dígitos e guiones. La puerta de enlace deriva el punto final de él como `https://aws-external-anthropic.<region>.api.aws`. |460| `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`. |
347| `workspace_id` | Sí | Enviado como encabezado en cada solicitud; la plataforma lo requiere |461| `workspace_id` | Sí | Enviado como un encabezado en cada solicitud; la plataforma lo requiere |
348| `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. |462| `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. |
349| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | No | Credenciales SigV4 explícitas. Establecer uno sin el otro falla al arrancar. `auth.aws_session_token` se acepta junto a ellos. |463| `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. |
350| `base_url` | No | Anule el punto final derivado |464| `base_url` | No | Anule el punto final derivado |
351 465
352Debido a que la plataforma resuelve IDs de modelo de primera parte, el catálogo integrado enruta a ella sin un bloque [`models:`](#models). Cuando cura una lista `models:`, clave la entrada `anthropicAws:` con el ID de primera parte.466Porque la plataforma resuelve IDs de modelo de primera parte, el catálogo integrado se enruta a ella sin un bloque [`models:`](#models). Cuando cura una lista `models:`, clave la entrada `anthropicAws:` con el ID de primera parte.
353 467
354<h4 id="google-cloud-agent-platform">468<h4 id="google-cloud-agent-platform">
355 Plataforma de agentes de Google Cloud469 Agent Platform de Google Cloud
356</h4>470</h4>
357 471
358Para la configuración equivalente del lado del cliente, consulte [Claude Code en Google Cloud](/docs/es/google-vertex-ai). El upstream del lado de la puerta de enlace:472Para la configuración equivalente del lado del cliente, consulte [Claude Code en Google Cloud](/docs/es/google-vertex-ai). El upstream del lado de la puerta de enlace:
362 - provider: vertex476 - provider: vertex
363 region: us-east5477 region: us-east5
364 project_id: example-prod478 project_id: example-prod
365 auth: {} # preferido: Credenciales predeterminadas de aplicación479 auth: {} # preferido: Credenciales por defecto de aplicación
366 # O un archivo de clave de cuenta de servicio:480 # O un archivo de clave de cuenta de servicio:
367 # auth: { service_account_json: /secrets/sa.json }481 # auth: { service_account_json: /secrets/sa.json }
368 # Anule el punto final de aiplatform para Private Service Connect:482 # Anule el punto final de aiplatform para Conexión de servicio privada:
369 # base_url: https://us-east5-aiplatform.p.googleapis.com483 # base_url: https://us-east5-aiplatform.p.googleapis.com
370```484```
371 485
372Un 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.486Un 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.
373 487
374Establezca `region: global` para usar el [punto final global de Agent Platform](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations) 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.488Establezca `region: global` para usar el [punto final global para Agent Platform de Google Cloud](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations) 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.
375 489
376| Configuración | Cómo |490| Configuración | Cómo |
377| - | - |491| - | - |
378| 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 (`aiplatform.googleapis.com`). |492| 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`). |
379| Acceso a modelos | En Model Garden, habilite los modelos Claude para su proyecto. Se publican en regiones específicas; consulte la tarjeta del modelo para regiones compatibles. |493| 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. |
380| 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. |494| 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. |
381| Cloud Run / GCE | Establezca la cuenta de servicio del servicio en una con `roles/aiplatform.user`. `auth: {}` la recoge. |495| Cloud Run / GCE | Establezca la cuenta de servicio del servicio en una con `roles/aiplatform.user`. `auth: {}` la recoge. |
382| 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. |496| 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. |
385 Microsoft Foundry499 Microsoft Foundry
386</h4>500</h4>
387 501
388Para la implementación de Foundry del lado del cliente, consulte [Claude Code en Microsoft Foundry](/docs/es/microsoft-foundry). El upstream del lado de la puerta de enlace:502Para la implementación de Microsoft Foundry del lado del cliente, consulte [Claude Code en Microsoft Foundry](/docs/es/microsoft-foundry). El upstream del lado de la puerta de enlace:
389 503
390```yaml theme={null}504```yaml theme={null}
391upstreams:505upstreams:
392 - provider: foundry506 - provider: foundry
393 resource: example-foundry # https://example-foundry.services.ai.azure.com507 resource: example-foundry # https://example-foundry.services.ai.azure.com
394 auth: { use_azure_ad: true } # preferido: DefaultAzureCredential / Managed Identity508 auth: { use_azure_ad: true } # preferido: DefaultAzureCredential / Identidad administrada
395 # O una clave API:509 # O una clave API:
396 # auth:510 # auth:
397 # api_key: ${FOUNDRY_API_KEY}511 # api_key: ${FOUNDRY_API_KEY}
398```512```
399 513
400`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.514`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.
401 515
402| Configuración | Cómo |516| Configuración | Cómo |
403| - | - |517| - | - |
404| RBAC | Otorgue a la identidad de la puerta de enlace `Azure AI User` o `Cognitive Services User` en el recurso de Foundry |518| RBAC | Otorgue a la identidad de la puerta de enlace `Azure AI User` o `Cognitive Services User` en el recurso de Microsoft Foundry |
405| Implementaciones | Foundry utiliza nombres de implementación elegidos por administrador, no IDs de modelo canónicos. Agregue un bloque [`models:`](#models) que asigne cada ID canónico a su nombre de implementación. |519| Implementaciones | Microsoft Foundry usa nombres de implementación elegidos por administrador, no IDs de modelo canónicos. Agregue un bloque [`models:`](#models) asignando cada ID canónico a su nombre de implementación. |
406| AKS (workload identity) | Federe una Managed Identity asignada por el usuario con el emisor 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`. |520| 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`. |
407| ACI / App Service | Habilite la identidad administrada asignada por el sistema o por el usuario en el recurso. `use_azure_ad: true` la recoge. |521| ACI / App Service | Habilite identidad administrada asignada por el sistema o por el usuario en el recurso. `use_azure_ad: true` la recoge. |
408| En cualquier otro lugar | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. Entrecomille `${…}` dentro de `{ }`. |522| En cualquier otro lugar | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. Cite `${…}` dentro de `{ }`. |
409 523
410<h4 id="static-headers-on-upstream-requests">524<h4 id="static-headers-on-upstream-requests">
411 Encabezados estáticos en solicitudes de upstream525 Encabezados estáticos en solicitudes de upstream
431 x-proxy-token: ${PROXY_TOKEN}545 x-proxy-token: ${PROXY_TOKEN}
432```546```
433 547
434Los valores son texto ASCII imprimible sin espacio en ninguno de los extremos. Entrecomille un número, `true`, o `false` para que YAML lo lea como texto.548Los 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.
435 549
436Para mantener un secreto fuera del archivo de configuración, use [expansión de secretos](#secret-expansion) 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 la puerta de enlace de iniciar.550Para mantener un secreto fuera del archivo de configuración, use [expansión de secreto](#secret-expansion) 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.
437 551
438`headers:` funciona en cada proveedor, y cada upstream envía solo el suyo.552`headers:` funciona en cada proveedor, y cada upstream envía solo el suyo.
439 553
448 562
449En 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.563En 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.
450 564
451Si utiliza un nombre que la puerta de enlace reserva, se niega a iniciar, y el error de inicio nombra el encabezado. Los nombres reservados incluyen:565Si 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:
452 566
453* `authorization` y `x-api-key`567* `authorization` y `x-api-key`
454* `host`, `content-type` y `user-agent`568* `host`, `content-type`, y `user-agent`
455* Cualquier nombre que comience con `anthropic-`, `x-goog-`, `x-amz-` o `x-amzn-`569* Cualquier nombre que comience con `anthropic-`, `x-goog-`, `x-amz-`, o `x-amzn-`
456 570
457<h4 id="multiple-upstreams">571<h4 id="multiple-upstreams">
458 Múltiples upstreams572 Múltiples upstreams
460 574
461El 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.575El 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.
462 576
463La 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.577La 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.
464 578
465`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`](#per-user-identity-headers-for-a-proxy-you-run) 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.579`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`](#per-user-identity-headers-for-a-proxy-you-run) 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.
466 580
467Cada solicitud comienza en el primer upstream. Una solicitud alcanza un upstream posterior solo cuando cada upstream anterior a él ha fallado o no sirve el modelo solicitado.581Cada 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.
468 582
469La 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.583La 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.
470 584
471Para un upstream de API de Anthropic, [`timeouts.upstream_ttfb_ms`](#http-tuning) 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.585Para un upstream de API de Anthropic, [`timeouts.upstream_ttfb_ms`](#http-tuning) 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.
472 586
473`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.587`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.
474 588
475Este 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:589Este 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:
476 590
477```yaml theme={null}591```yaml theme={null}
478upstreams:592upstreams:
486 provider: bedrock600 provider: bedrock
487 region: us-west-2601 region: us-west-2
488 auth: {}602 auth: {}
489 # Cuenta diferente: una asignación de Bedrock separada a través de credenciales de rol asumido.603 # Cuenta diferente: una asignación de Bedrock separada a través de claves estáticas.
490 - name: bedrock-acct2604 - name: bedrock-acct2
491 provider: bedrock605 provider: bedrock
492 region: us-east-1606 region: us-east-1
512 626
513| Palanca | Cómo |627| Palanca | Cómo |
514| - | - |628| - | - |
515| Diferentes regiones | Un upstream de Bedrock por región, cada uno con su propio `region:`. Con [`auto_include_builtin_models: true`](#models) los perfiles de inferencia entre regiones enrutan automáticamente; para implementaciones fijas de región use un bloque `models:`. |629| Diferentes regiones | Un upstream de Amazon Bedrock por región, cada uno con su propio `region:`. Con [`auto_include_builtin_models: true`](#models) los perfiles de inferencia entre regiones se enrutan automáticamente; para implementaciones fijas por región use un bloque `models:`. |
516| Diferentes cuentas | Un upstream de Bedrock por cuenta, cada uno con sus propias credenciales en `auth:`. La cadena predeterminada (`auth: {}`) utiliza la identidad de la vaina; para una segunda cuenta, establezca credenciales explícitas o un token portador. |630| 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`](#bedrock-in-another-aws-account) para alcanzarla con credenciales de corta duración, o establezca credenciales explícitas o un token portador en `auth:`. |
517| Rendimiento aprovisionado | Asigne el modelo al ARN de rendimiento aprovisionado en `models:` para el nombre de ese upstream. Otros upstreams mantienen el ID bajo demanda, por lo que la capacidad de PT se agota antes de conmutar por error. |631| 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. |
518| Puntos finales de VPC / FIPS | Establezca `base_url:` en el upstream a su URL de punto final de VPC o FIPS |632| Puntos finales de VPC / FIPS | Establezca `base_url:` en el upstream a su URL de punto final de VPC o FIPS |
519| Enrutamiento limitado a modelo | Solo un modelo `id` personalizado, uno que no sea un 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 utiliza el ID predeterminado del proveedor donde el mapa no tiene entrada, por lo que para modelos integrados el mapa cambia qué ID recibe un upstream en lugar de si se intenta; un upstream que rechaza el ID sigue las mismas [reglas de conmutación por error](#upstreams) que cualquier otro error de upstream. |633| 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](#upstreams) que cualquier otro error de upstream. |
520 634
521La 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.635La 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.
522 636
523El 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.637El 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.
524 638
525<h2 id="optional-sections">639<h2 id="optional-sections">
526 Secciones opcionales640 Secciones opcionales
530 `admin`644 `admin`
531</h3>645</h3>
532 646
533Opcional. Habilita `/v1/organizations/spend_limits`, que refleja la API pública de administración 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 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.
534 648
535```yaml theme={null}649```yaml theme={null}
536admin:650admin:
537 # Claves API estáticas nombradas para los puntos finales de administración, enviadas como x-api-key.651 # Claves API estáticas nombradas para los puntos finales de administrador, enviadas como x-api-key.
538 # 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
539 # atribuible. Array para rotación: agregue la nueva clave, actualice los clientes,653 # atribuible. Array para rotación: agregue la clave nueva, actualice los clientes,
540 # elimine la antigua.654 # elimine la antigua.
541 write_keys:655 write_keys:
542 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }656 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
543 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }657 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
544 read_keys:658 read_keys:
545 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }659 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
546 # Grupos de IdP con acceso administrativo completo a través del JWT de gateway normal (sin clave API).660 # Grupos de IdP con acceso de administrador completo a través del JWT de puerta de enlace normal (sin clave API).
547 admin_groups: [platform-finops]661 admin_groups: [platform-finops]
548 blocked_message: request an increase at https://go.example.com/claude-limits662 blocked_message: request an increase at https://go.example.com/claude-limits
549```663```
551| Campo | Requerido | Descripción |665| Campo | Requerido | Descripción |
552| - | - | - |666| - | - | - |
553| `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 gastos. Los valores de clave deben tener al menos 32 caracteres; los `id` deben ser únicos en `read_keys` y `write_keys`. |
554| `read_keys` | No | Array de `{id, key}`. Solo lectura: cada punto final `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}`. 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). |
555| `admin_groups` | No | Nombres de grupos de IdP. Un JWT de gateway cuya reclamación `groups` incluya uno de estos tiene acceso administrativo completo, lectura y escritura, y auditorías como `oidc:<sub>`. Utilice esto para administradores humanos; utilice claves API para máquinas. Una entrada vacía en esta lista detiene el gateway al iniciar. Consulte [Valores de coincidencia que detienen el gateway al iniciar](#matcher-values-that-stop-the-gateway-at-boot). |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). |
556| `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, el gateway 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. 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). |
557| `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. |
558| `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 mantiene un año completo más el mes parcial actual para informes año a año. |
559| `identity_retention_days` | No | Predeterminado `90`. TTL de última visualización para filas `principal_emails`, que contienen el correo electrónico, nombre para mostrar y 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 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. |
560| `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. Utilizado tanto por la aplicación como por `/effective`. |
561 675
562<h3 id="enforcement">676<h3 id="enforcement">
567 681
568| Campo | Requerido | Descripción |682| Campo | Requerido | Descripción |
569| - | - | - |683| - | - | - |
570| `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 el gateway 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 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. |
571 685
572<h3 id="pricing">686<h3 id="pricing">
573 `pricing`687 `pricing`
575 689
576El 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 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:
577 691
578* Claude Code v2.1.227 o posterior en el servidor de gateway. Las versiones anteriores rechazan la clave desconocida al iniciar.692* Claude Code v2.1.227 o posterior en el servidor de puerta de enlace. Las versiones anteriores rechazan la clave desconocida al arrancar.
579* 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 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. La puerta de enlace se niega a iniciar con `pricing` establecido y ninguno de los dos bloques, porque nada lo leería.
580 694
581```yaml theme={null}695```yaml theme={null}
582pricing:696pricing:
597 711
598Cómo el medidor coincide con una fila de anulación:712Cómo el medidor coincide con una fila de anulación:
599 713
600* Una fila reemplaza el precio de lista para solicitudes que `upstream`, un [`upstreams[].name`](#upstreams), sirve para `model`. Esto incluye la tasa más alta de [modo rápido](/docs/es/fast-mode#understand-the-cost-tradeoff), 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 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.
601* Un ID integrado como `claude-sonnet-4-6`, coincidido como [`models[].id`](#models), cubre cada forma fechada, forma regional de Amazon Bedrock, o forma de Google Cloud's Agent Platform 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 el cliente envió o la cadena enviada al upstream, sin distinción de mayúsculas y minúsculas.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.
602* 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 al upstream, luego una fila que coincide con el ID exacto que el cliente envió, luego una fila que nombra el modelo integrado.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.
603* Un nombre de upstream desconocido falla al iniciar, al igual que dos filas para un upstream que nombran el mismo modelo, incluidas dos ortografías de un modelo integrado. El gateway advierte al iniciar sobre una fila que ningún modelo solicitable puede usar.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.
604* Las solicitudes de búsqueda web permanecen al precio de lista de \$0.01; el multiplicador aún se aplica a ellas.718* Las solicitudes de búsqueda web permanecen en el precio de lista de \$0.01; el multiplicador aún se aplica a ellas.
605 719
606Para tasas por región, asigne a cada región su propio upstream nombrado y una fila por upstream.720Para tasas por región, asigne a cada región su propio upstream nombrado y una fila por upstream.
607 721
609 Marcar precios hacia arriba723 Marcar precios hacia arriba
610</h4>724</h4>
611 725
612Con v2.1.271 o posterior en el servidor de gateway, 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 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:
613 727
614```yaml theme={null}728```yaml theme={null}
615pricing:729pricing:
616 multiplier: 1.2730 multiplier: 1.2
617```731```
618 732
619Con 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. El gateway registra una advertencia al iniciar que dice así.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.
620 734
621El multiplicador no cambia lo que cobra el proveedor upstream por las solicitudes.735El multiplicador no cambia lo que cobra el proveedor ascendente por las solicitudes.
622 736
623Si el gateway 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 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.
624 738
625Un servidor de gateway anterior a v2.1.271 se niega a iniciar si establece un `multiplier` superior a 1.739Un servidor de puerta de enlace anterior a v2.1.271 se niega a iniciar si establece un `multiplier` superior a 1.
626 740
627<h4 id="send-the-rates-to-signed-in-clients">741<h4 id="send-the-rates-to-signed-in-clients">
628 Enviar las tasas a clientes conectados742 Enviar las tasas a clientes conectados
629</h4>743</h4>
630 744
631Con v2.1.268 o posterior en el servidor de gateway, el gateway 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 configuraciones administradas, por lo que sus cifras permanecen al 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 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.
632 746
633* 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 pueda 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 el gateway.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.
634* Optar una política: establezca `modelPricing` en `{}` en el bloque `cli` de esa política, y sus desarrolladores permanecen al precio de lista.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.
635* 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 el gateway no agrega tasas propias a él.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.
636 750
637<h3 id="models">751<h3 id="models">
638 `models`752 `models`
639</h3>753</h3>
640 754
641El bloque `models` es una lista de modelos opcional curada por administrador, servida en `/v1/models` y utilizada para traducir IDs de modelo 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 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.
642 756
643```yaml theme={null}757```yaml theme={null}
644auto_include_builtin_models: true # false: expose only the list below758auto_include_builtin_models: true # false: exponer solo la lista a continuación
645models:759models:
646 - id: claude-opus-4-8760 - id: claude-opus-4-8
647 label: Claude Opus 4.8761 label: Claude Opus 4.8
648 # description: optional text shown in clients that surface it762 # description: texto opcional mostrado en clientes que lo muestren
649 upstream_model:763 upstream_model:
650 anthropic: claude-opus-4-8764 anthropic: claude-opus-4-8
651 bedrock: us.anthropic.claude-opus-4-8 # or an inference-profile ARN765 bedrock: us.anthropic.claude-opus-4-8 # o un ARN de perfil de inferencia
652 foundry: your-opus-deployment-name766 foundry: your-opus-deployment-name
653```767```
654 768
655Cada 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 iniciar, por lo que omita las líneas para proveedores que no utiliza.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.
656 770
657<h3 id="managed">771<h3 id="managed">
658 `managed`772 `managed`
659</h3>773</h3>
660 774
661El 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é de ETag/304.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.
662 776
663```yaml theme={null}777```yaml theme={null}
664managed:778managed:
668 cli:782 cli:
669 availableModels: [claude-sonnet-4-6]783 availableModels: [claude-sonnet-4-6]
670 permissions: { deny: ["WebFetch", "WebSearch"] }784 permissions: { deny: ["WebFetch", "WebSearch"] }
671 # Captura general predeterminada al final: coincide con todos los que se autenticaron.785 # Captura general predeterminada última: coincide con todos los que se autenticaron.
672 - match: {}786 - match: {}
673 cli:787 cli:
674 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]
675```789```
676 790
677Una captura general `match: {}`, convencionalmente enumerada al final, se trata como una capa base. Cada otra política hereda cualquier clave que no establezca 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: {}`, 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:
678 792
679* **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 completamente la de la base.
680* **Listas de denegados 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 denegación o auditoría en 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 `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.
681* **Claves de tipo registro**: `env`, `modelOverrides` y `skillOverrides`. Estas 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`. Estos se fusionan superficialmente, por lo que un bloque `env` por rol anula las claves que establece y hereda el resto de la base.
682 796
683`availableModels` también se aplica en el 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.
684 798
685El gateway 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: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:
686 800
687* 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.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.
688* 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.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.
689 803
690| Coincidencia | Comportamiento |804| Coincidencia | Comportamiento |
691| - | - |805| - | - |
692| `match: {}` | Coincide con cada usuario autenticado. 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. Comience con uno de estos y agregue políticas con alcance de grupo por encima más tarde. |
693| `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 el uso exacto de mayúsculas y minúsculas del IdP. |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. |
694| `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 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. |
695| `match: { groups: [a], email_domain: example.com }` | Ambas condiciones deben coincidir |809| `match: { groups: [a], email_domain: example.com }` | Ambas condiciones deben coincidir |
696 810
697Un usuario autenticado que no coincida con ninguna política obtiene los valores predeterminados del gateway, lo que significa cada modelo en el catálogo y sin configuraciones administradas. Agregue una captura general `match: {}` al final si desea una política predeterminada garantizada.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.
698 812
699<Note>813<Note>
700 El gateway 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 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.
701 815
702 Ejecute la gestión del ciclo de vida del usuario y el grupo en la fuente de verdad, que es el aprovisionamiento SCIM nativo de su IdP o una plataforma dedicada de gobernanza de identidades. La pertenencia y desaprovisionamiento gobernados allí fluyen hacia el gateway automáticamente a través del token. Si desea el aprovisionamiento SCIM de las propias cuentas de Claude, esa es una capacidad de [Claude for Enterprise](/docs/es/admin-setup).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).
703 817
704 Se aplican dos relojes de propagación:818 Se aplican dos relojes de propagación:
705 819
706 * **Contenidos de política**: editar una política y reimplementar llega a clientes conectados en su próxima encuesta de configuraciones administradas, 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 * **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)
707 * **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 el próximo refresco silencioso, limitado por `session.ttl_hours`.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`.
708</Note>822</Note>
709 823
710<h4 id="matcher-values-that-stop-the-gateway-at-boot">824<h4 id="matcher-values-that-stop-the-gateway-at-boot">
711 Valores de coincidencia que detienen el gateway al iniciar825 Valores de coincidencia que detienen la puerta de enlace al arrancar
712</h4>826</h4>
713 827
714Al iniciar, 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: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:
715 829
716* Una lista `groups` vacía830* Una lista `groups` vacía
717* Una entrada vacía en `groups` o en `admin_groups`831* Una entrada vacía en `groups` o en `admin_groups`
718* Un `email_domain` vacío832* Un `email_domain` vacío
719* 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. Escriba un dominio desnudo, como `example.com`.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`.
720 834
721Antes de v2.1.232, el gateway se iniciaba con estos valores. Cada valor tenía este efecto:835Antes de v2.1.232, la puerta de enlace comenzaba con estos valores. Cada valor tenía este efecto:
722 836
723* 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 cada usuario autenticado837* 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 autenticados
724* 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
725* Un `email_domain` que contiene `@`, espacios en blanco o una coma: la política no coincidía con nadie839* Un `email_domain` que contiene `@`, espacios en blanco o una coma: la política no coincidía con nadie
726* 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 administrativo. Si su lista `admin_groups` nunca contenía una entrada vacía, nadie obtenía acceso administrativo 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` 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.
727 841
728<h4 id="what-goes-in-cli">842<h4 id="what-goes-in-cli">
729 Qué va en `cli`843 Qué va en `cli`
731 845
732Cada 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 `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`.
733 847
734El gateway valida cada documento contra el esquema de configuración del CLI al iniciar, por lo que una clave de nivel superior no reconocida falla al iniciar 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 del gateway no. Estas claves abiertas incluyen `env`, `pluginConfigs` y claves anidadas bajo `permissions`.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`.
735 849
736Debido a que la validación utiliza el esquema incluido con la versión instalada del gateway, 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 el gateway. Pruebe una nueva política en un cliente antes de implementarla.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.
737 851
738La 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 de clave completa está en [Configuración de Claude Code](/docs/es/settings-reference#all-settings). Las claves que los operadores buscan primero:
739 853
742 policies:856 policies:
743 - match: {}857 - match: {}
744 cli:858 cli:
745 # Acceso a modelos (también aplicado en el lado del servidor en /v1/messages)859 # Acceso a modelos (también aplicado del lado del servidor en /v1/messages)
746 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]860 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
747 861
748 # Política de permisos862 # Política de permisos
751 - "WebFetch"865 - "WebFetch"
752 - "Read(./.env)"866 - "Read(./.env)"
753 - "Read(./secrets/**)"867 - "Read(./secrets/**)"
754 disableBypassPermissionsMode: disable # blocks --dangerously-skip-permissions868 disableBypassPermissionsMode: disable # bloquea --dangerously-skip-permissions
755 allowManagedPermissionRulesOnly: true # ignore user/project permission rules869 allowManagedPermissionRulesOnly: true # ignora reglas de permisos de usuario/proyecto
756 870
757 # Entorno insertado en el proceso CLI. DISABLE_UPDATES bloquea871 # Entorno insertado en el proceso CLI. DISABLE_UPDATES bloquea
758 # actualizaciones de fondo y manuales; DISABLE_AUTOUPDATER detiene solo872 # actualizaciones de fondo y manuales; DISABLE_AUTOUPDATER detiene solo
759 # actualizaciones de fondo.873 # actualizaciones de fondo.
760 env:874 env:
761 DISABLE_UPDATES: "1" # pin versions via your own distribution875 DISABLE_UPDATES: "1" # fijar versiones a través de su propia distribución
762 876
763 # Hooks en toda la organización. Los comandos de hooks se ejecutan en máquinas de desarrolladores, no en el877 # Hooks de toda la organización. Los comandos de hook se ejecutan en máquinas de desarrollador, no en la
764 # gateway, por lo que la ruta debe existir en cada SO cliente en la política.878 # puerta de enlace, por lo que la ruta debe existir en cada SO cliente en la política.
765 hooks:879 hooks:
766 PostToolUse:880 PostToolUse:
767 - matcher: "Edit|Write"881 - matcher: "Edit|Write"
771 885
772| Clave | Aplicada por | Efecto |886| Clave | Aplicada por | Efecto |
773| - | - | - |887| - | - | - |
774| `availableModels` | Gateway + CLI | Lista de permitidos de modelos. También se comprueba en `/v1/messages`, por lo que un cliente parcheado no puede omitirlo. |888| `availableModels` | Puerta de enlace + CLI | Lista de permitidos de modelos. También se comprueba en `/v1/messages`, por lo que un cliente parcheado no puede omitirlo. |
775| `permissions.allow` / `.deny` | CLI | Reglas de herramientas y comandos. Consulte [Permisos](/docs/es/permissions). |889| `permissions.allow` / `.deny` | CLI | Reglas de herramientas y comandos. Consulte [Permisos](/docs/es/permissions). |
776| `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 | 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` |
777| `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 cada fuente que Claude Code luego ignora. |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. |
778| `env` | CLI | Variables de entorno fusionadas en el proceso CLI. Utilice para telemetría, actualización automática y anulaciones de nombres de modelos. |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. |
779| `hooks` | CLI | Hooks en toda la organización [hooks](/docs/es/hooks) |893| `hooks` | CLI | Hooks de toda la organización [hooks](/docs/es/hooks) |
780| `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 gateway y en clientes. Los clientes anteriores ignoran la clave. |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. |
781 895
782Debido 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: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:
783 897
784* `hooks`898* `hooks`
785* Variables `env` que requieren la aprobación del desarrollador, como variables de proxy y URL base899* Variables `env` que requieren la aprobación del desarrollador, como variables de proxy y URL base
786* configuraciones de ejecución de shell como `apiKeyHelper` y `statusLine`900* configuración de ejecución de shell como `apiKeyHelper` y `statusLine`
787* la configuración de binario de sandbox `sandbox.bwrapPath`, `sandbox.socatPath` y `sandbox.ripgrep`901* la configuración de binario de sandbox `sandbox.bwrapPath`, `sandbox.socatPath` y `sandbox.ripgrep`
788* Configuraciones de Sandbox que interceptan tráfico, inyectan credenciales o debilitan 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* 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.
789 903
790[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) cubre cuánto tiempo dura una aprobación y cuándo aparece el diálogo nuevamente.
791 905
792Claude Code aplica algunas variables `env` entregadas sin mostrar al desarrollador el diálogo de aprobación, como configuraciones 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 `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.
793 907
794[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 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.
795 909
796La configuración de [telemetría](#telemetry) del gateway 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 un gateway comprometido u hostil, no la organización del desarrollador.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.
797 911
798Una ejecución no interactiva con la bandera `-p` 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. 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 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.
799 913
800Si 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, 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 cada hora, y de lo contrario en el próximo inicio del desarrollador.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.
801 915
802La clave `cli` se llamaba `settings` en versiones anteriores. Esa ortografía aún se acepta como un alias, pero las nuevas implementaciones deben usar `cli`.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`.
803 917
804<h4 id="mcp-servers-in-a-policy">918<h4 id="mcp-servers-in-a-policy">
805 Servidores MCP en una política919 Servidores MCP en una política
806</h4>920</h4>
807 921
808Para 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 gateway y en clientes.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.
809 923
810El gateway comprueba cada entrada al iniciar 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, el gateway se niega a iniciar y nombra la entrada.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.
811 925
812Si escribe una referencia `${VAR}` en `gateway.yaml`, el gateway la resuelve desde su entorno al iniciar 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.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.
813 927
814El gateway rechaza la ortografía `.mcp.json` `mcpServers` en un bloque `cli`, y su error de inicio nombra `managedMcpServers` como la clave a usar. Antes de v2.1.259, el gateway rechazaba cualquier definición de servidor MCP en un bloque `cli`.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`.
815 929
816<h4 id="claude-desktop-overlay">930<h4 id="claude-desktop-overlay">
817 Superposición de Claude Desktop931 Superposición de Claude Desktop
818</h4>932</h4>
819 933
820Si su organización también implementa [Claude Desktop](/docs/es/desktop), el mismo gateway 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 este gateway y obtiene su configuración de la respuesta.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.
821 935
822<Note>936<Note>
823 Requiere Claude Code v2.1.203 o posterior en el servidor de gateway, 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`.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`.
824</Note>938</Note>
825 939
826El gateway deriva gran parte de la respuesta del bloque `cli` de la política coincidente y de la configuración del gateway de nivel superior: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:
827 941
828* La lista de modelos, de `availableModels`942* La lista de modelos, de `availableModels`
829* Herramientas deshabilitadas, de entradas `permissions.deny` de nombre de herramienta desnudo. Si establece `disabledBuiltinTools` en el bloque `desktop` de la política, el gateway 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`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`
830* La lista de permitidos de salida, de `sandbox.network.allowedDomains`. Si establece `coworkEgressAllowedHosts` en el bloque `desktop` de la política, el gateway usa ese valor en lugar de la lista derivada944* 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
831* Un punto final OTLP que apunta al gateway mismo, y los atributos de identidad del usuario conectado. El gateway 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`.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`.
832 946
833 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 `env` de la política. Antes de Claude Code v2.1.261 en el servidor de gateway, la respuesta establecía `http/json` independientemente, por lo que un recopilador que acepta solo protobuf rechazaba las exportaciones de Claude Desktop947 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 Desktop
834 948
835Para 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 gateway. El `managedMcpServers` de Claude Desktop toma un valor de array en lugar de un objeto.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.
836 950
837El gateway omite claves sin equivalente de Claude Desktop, como `hooks` y reglas de permisos con alcance como `Bash(npm *)`, de la respuesta de bootstrap.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.
838 952
839Agregue 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`; el gateway las rechaza al iniciar. Antes de v2.1.232, el gateway aceptaba una lista fija de 11 claves de puerta de características, como `chatTabEnabled` y `disableAutoUpdates`, y rechazaba todas las demás claves al iniciar. Antes de v2.1.227, el gateway también rechazaba `chatTabEnabled` y `chatAdvancedFileAnalysisEnabled` al iniciar.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.
840 954
841```yaml theme={null}955```yaml theme={null}
842managed:956managed:
850 banner: { text: "Contractor build: internal use only" }964 banner: { text: "Contractor build: internal use only" }
851```965```
852 966
853Cada clave es opcional; Claude Desktop aplica su propio valor predeterminado para cualquier clave que omita. El gateway valida cada bloque `desktop` al iniciar contra el esquema de configuración que el propio Claude Desktop usa, por lo que un error aparece al inicio del gateway como un error que nombra la clave en lugar de llegar a cada desktop conectado. El gateway falla al iniciar cuando un bloque contiene: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:
854 968
855* Una clave desconocida969* Una clave desconocida
856* 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, el gateway dejaba caer silenciosamente un campo mal escrito dentro de un objeto anidado de una entrada `managedMcpServers` u `orgPluginSettings` en lugar de fallar al iniciar.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.
857* Una clave que el gateway calcula a sí mismo: 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`.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`.
858* Un alias heredado de una clave actual. En el error de inicio, el gateway nombra la clave canónica a escribir.972* Un alias heredado de una clave actual. En el error de arranque, la puerta de enlace nombra la clave canónica a escribir.
973
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.
859 975
860Si utiliza un valor o forma de entrada obsoleta, como una entrada `managedMcpServers` sin `transport`, el gateway se inicia y registra una advertencia que nombra el reemplazo.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.
861 977
862El gateway 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 el gateway. Por ejemplo, `userPluginMarketplacesEnabled` y `userPluginUploadsEnabled` necesitan Claude Code v2.1.260 o posterior en el servidor de gateway y Claude Desktop 1.37937.0 o posterior en las máquinas de los miembros.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.
863 979
864Si establece `orgPluginSettings` en el bloque `desktop` de una política, el gateway lo sirve en la forma de array que Claude Desktop 1.15200.0 y posterior lee. Los desktops más antiguos ignoran el array y no aplican ninguna política de herramientas de plugins, por lo que actualice a los miembros a 1.15200.0 o posterior antes de confiar en ello.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.
865 981
866El gateway 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, el gateway mantiene la restricción de la base: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:
867 983
868* `disabledBuiltinTools`: el gateway usa la unión de la lista de la base y la lista de la política984* `disabledBuiltinTools`: la puerta de enlace usa la unión de la lista de la base y la lista de la política
869* `builtinToolPolicy`: si establece una herramienta en un valor distinto de `allow` en la base, el gateway mantiene ese valor incluso si establece `allow` para la misma herramienta en una política de rol985* `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
870 986
871Para todas las demás claves, si las establece en la política de rol, el gateway usa el valor de la política de rol. El gateway reemplaza un array o un objeto anidado como `banner` completo, por lo que si establece `banner.text` en una política de rol, el gateway descarta el `banner.backgroundColor` de la base.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.
872 988
873Si no implementa Claude Desktop, deje `desktop` completamente fuera de sus políticas; el gateway luego devuelve 404 desde `/user/bootstrap` para cada usuario.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.
874 990
875<h4 id="precedence-with-other-managed-sources">991<h4 id="precedence-with-other-managed-sources">
876 Precedencia con otras fuentes administradas992 Precedencia con otras fuentes administradas
877</h4>993</h4>
878 994
879Si un dispositivo también tiene una política entregada por MDM o un `managed-settings.json` local, la configuración entregada por gateway ocupa el primer lugar. [Precedencia dentro del nivel administrado](/docs/es/managed-settings#precedence-within-the-managed-tier) en la página de configuraciones administradas dice cuándo se aplican las fuentes locales, y tiene las [claves que Claude Code lee de cada fuente de administrador](/docs/es/managed-settings#keys-read-from-every-admin-source) independientemente de qué fuente seleccionó, como las claves de bloqueo de sandbox, `forceRemoteSettingsRefresh` y el `env` por variable. Un [`policyHelper`](/docs/es/settings-reference#policyhelper) configurado en un perfil MDM o el archivo de configuraciones administradas se ejecuta solo cuando el gateway no entrega configuraciones; la entrada dice qué reemplaza su salida.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.
880 996
881Los hosts de incrustación como [Claude Desktop](/docs/es/desktop) pueden suministrar política a través de la opción SDK `managedSettings`. [Configuraciones principales de hosts de incrustación](/docs/es/managed-settings#parent-settings-from-embedding-hosts) dice cuándo Claude Code la aplica, y [Restringir configuraciones principales](/docs/es/claude-apps-gateway#restrict-parent-settings) enumera qué configuraciones de dirección de permitidos aún se aplican sin los bloqueos `allowManaged*Only`.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`.
882 998
883Las políticas de gateway 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 de Agent. Si el gateway es inaccesible al iniciar, las sesiones conectadas salen con un error en lugar de ejecutarse sin su política.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.
884 1000
885<h3 id="telemetry">1001<h3 id="telemetry">
886 `telemetry`1002 `telemetry`
887</h3>1003</h3>
888 1004
889El CLI envía métricas, registros y, cuando está habilitado, trazas al gateway, 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.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.
890 1006
891El 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`. La atribución de costo y uso por desarrollador funciona sin configuración en el lado del desarrollador.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.
892 1008
893[Claude Desktop](#claude-desktop-overlay) y las sesiones de Cowork conectadas a través del gateway 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.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.
894 1010
895La telemetría de Desktop y Cowork también lleva `enduser.sub`, la reclamación `sub` que su proveedor de identidades 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 con `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.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.
896 1012
897Como todos los datos de OpenTelemetry de Claude Code, estos atributos van solo a destinos que su organización configura, nunca a Anthropic.1013Como todos los datos de OpenTelemetry de Claude Code, estos atributos van solo a destinos que su organización configura, nunca a Anthropic.
898 1014
899Si 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, el gateway 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.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.
900 1016
901El gateway deja `enduser.sub` 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.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.
902 1018
903Necesita Claude Code v2.1.265 o posterior en el servidor de 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`.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`.
904 1020
905Necesita Claude Code v2.1.274 o posterior en el servidor de gateway para `enduser.sub`.1021Necesita Claude Code v2.1.274 o posterior en el servidor de puerta de enlace para `enduser.sub`.
906 1022
907```yaml theme={null}1023```yaml theme={null}
908telemetry:1024telemetry:
910 - url: https://otel-collector.internal.example.com1026 - url: https://otel-collector.internal.example.com
911 headers:1027 headers:
912 Authorization: ${OTLP_TOKEN}1028 Authorization: ${OTLP_TOKEN}
913 # Opción por señal. Predeterminado: solo métricas.1029 # Opción de participación por señal. Predeterminado: solo métricas.
914 metrics: true1030 metrics: true
915 logs: false1031 logs: false
916 traces: false1032 traces: false
928 Habilite registros y trazas solo en destinos con los controles de acceso y la política de retención que esos datos justifican.1044 Habilite registros y trazas solo en destinos con los controles de acceso y la política de retención que esos datos justifican.
929</Warning>1045</Warning>
930 1046
931Cada URL `forward_to` debe usar `https://`, con una excepción para un recopilador en la interfaz de loopback del gateway: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:
932 1048
933* `http://localhost:<port>` pasa la validación de configuración, pero la [guardia 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 del gateway1049* `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 enlace
934* `http://127.0.0.1:<port>` o `http://[::1]:<port>` falla al iniciar a menos que esa variable esté establecida1050* `http://127.0.0.1:<port>` o `http://[::1]:<port>` falla al arrancar a menos que esa variable esté establecida
935 1051
936Para un recopilador en el clúster, expóngalo sobre HTTPS en su propia dirección interna, o ejecútelo como un sidecar con la variable establecida.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.
937 1053
938Cuando `HTTPS_PROXY` está establecido, el gateway envía exportaciones a través de ese proxy.1054Cuando se establece `HTTPS_PROXY`, la puerta de enlace envía exportaciones a través de ese proxy.
939 1055
940Para 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 gateway. Asegúrese de que el gateway 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.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.
941 1057
942Con [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.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.
943 1059
944La telemetría está desactivada en el CLI de forma predeterminada. Cuando establece tanto `telemetry.forward_to` como `listen.public_url`, el gateway la activa para clientes conectados insertando seis variables de entorno a través de `/managed/settings`: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`:
945 1061
946* `CLAUDE_CODE_ENABLE_TELEMETRY=1`1062* `CLAUDE_CODE_ENABLE_TELEMETRY=1`
947* `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 contrario1063* `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
948* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`1064* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`
949* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`1065* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`
950 1066
951Cuando agrega [sus propias etiquetas](#add-your-own-labels), el gateway también inserta `OTEL_RESOURCE_ATTRIBUTES`.1067Cuando [agrega sus propias etiquetas](#add-your-own-labels), la puerta de enlace también inserta `OTEL_RESOURCE_ATTRIBUTES`.
952 1068
953Antes de Claude Code v2.1.265 en el servidor de gateway, el gateway insertaba los tres selectores de exportador como `otlp`, incluido para señales que ningún destino optó.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ó.
954 1070
955El 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.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.
956 1072
957Los desarrolladores conectados a través de `/login` no pueden redirigir exportaciones con su propia configuración OTEL:1073Los desarrolladores conectados a través de `/login` no pueden redirigir exportaciones con su propia configuración OTEL:
958 1074
959* **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.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.
960* **Puntos finales configurados localmente**: con la exportación OTLP/HTTP habilitada, el CLI ignora cualquier punto final configurado localmente, independientemente de si el gateway insertó las variables de telemetría. Sus exportaciones van al gateway a menos que una política [nombre su recopilador como punto final](#export-directly-to-your-collector).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).
961 1077
962Sin un destino `forward_to` para una señal, el gateway 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).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).
963 1079
964[Trazas](/docs/es/monitoring-usage#traces-beta) también requieren `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` en cada cliente. Establézcalo en el bloque `env` de una política administrada, ya que el gateway 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.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.
965 1081
966Establé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.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.
967 1083
968Tanto las codificaciones OTLP de protobuf como JSON se retransmiten, y cualquier backend compatible con OpenTelemetry funciona como destino.1084Tanto las codificaciones OTLP de protobuf como JSON se retransmiten, y cualquier backend compatible con OpenTelemetry funciona como destino.
969 1085
970<h4 id="add-your-own-labels">1086<h4 id="add-your-own-labels">
971 Agregar sus propias etiquetas1087 Agregue sus propias etiquetas
972</h4>1088</h4>
973 1089
974Para poner etiquetas fijas como `service.namespace` o `deployment.environment.name` en la telemetría de sesiones conectadas a través del gateway, establezca `telemetry.resource_attributes`. Cada etiqueta es un atributo de recurso de OpenTelemetry, y cada destino recibe las mismas etiquetas.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.
975 1091
976Las sesiones obtienen las etiquetas solo cuando también establece `telemetry.forward_to` y `listen.public_url`. Este ejemplo agrega dos etiquetas:1092Las sesiones obtienen las etiquetas solo cuando también establece `telemetry.forward_to` y `listen.public_url`. Este ejemplo agrega dos etiquetas:
977 1093
984 deployment.environment.name: prod1100 deployment.environment.name: prod
985```1101```
986 1102
987El gateway se niega a iniciar cuando una etiqueta rompe una de estas reglas, y el error de inicio nombra la etiqueta:1103La puerta de enlace se niega a iniciar cuando una etiqueta rompe una de estas reglas, y el error de inicio nombra la etiqueta:
988 1104
989* Los nombres usan solo letras, dígitos, `.`, `_` y `-`1105* Los nombres usan solo letras, dígitos, `.`, `_` y `-`
990* 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`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`
991* Los valores son ASCII imprimible no vacío sin espacio y ninguno de `, ; = \ " %`1107* Los valores son ASCII imprimible no vacío sin espacio y ninguno de `, ; = \ " %`
992* Los valores tienen como máximo 255 caracteres tal como los cuenta el gateway después de la codificación en porcentaje, por lo que `/`, `:` y `@` cada uno cuentan como tres1108* 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 tres
993* Los valores son texto, por lo que cite un número, `true` o `false`1109* Los valores son texto, así que cite un número, `true` o `false`
994 1110
995Necesita Claude Code v2.1.281 o posterior en el servidor de gateway para establecer `telemetry.resource_attributes`. Un gateway 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.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.
996 1112
997Las 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 el bloque `env` de una política, las sesiones de terminal que esa política coincide obtienen ese valor en lugar de las etiquetas. Claude Desktop recibe las etiquetas del gateway junto a `user.email` y los otros atributos de identidad.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.
998 1114
999Claude 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 indexa atributos de recurso. Para desactivar esa copia, consulte [Control de cardinalidad de métricas](/docs/es/monitoring-usage#metrics-cardinality-control).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).
1000 1116
1001<h4 id="export-directly-to-your-collector">1117<h4 id="export-directly-to-your-collector">
1002 Exportar directamente a su recopilador1118 Exportar directamente a su recopilador
1004 1120
1005Para 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é.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é.
1006 1122
1007Para 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 gateway del desarrollador a un recopilador nombrado de esta manera.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.
1008 1124
1009Cuando 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.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.
1010 1126
1011Claude 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: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:
1012 1128
1013* El punto final proviene del gateway mismo. Si establece la misma variable en un perfil MDM o un `managed-settings.json` local, las exportaciones permanecen en el relé.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é.
1014* La URL usa `https://`, o `http://` a una dirección de loopback1130* La URL usa `https://`, o `http://` a una dirección de bucle de retorno
1015* La URL se resuelve en una ruta que termina en `/v1/<signal>`, sin consulta o fragmento. Claude Code construye esa ruta a sí mismo desde la variable genérica. Utiliza una variable por señal como `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` tal como está escrita, por lo que incluya la ruta completa allí.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í.
1016* La URL no es el host del gateway. Un punto final dirigido al gateway mantiene la ruta de relé y su token de sesión.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.
1017* 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é.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é.
1018 1134
1019El 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`.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`.
1020 1136
1021El punto final solo no activa la exportación, por lo que también establezca las variables que lo hacen, a menos que el gateway ya las inserte: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:
1022 1138
1023* Si el gateway 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.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.
1024* Si no, también establezca `CLAUDE_CODE_ENABLE_TELEMETRY=1`, los selectores `OTEL_*_EXPORTER` y `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`.1140* Si no, también establezca `CLAUDE_CODE_ENABLE_TELEMETRY=1`, los selectores `OTEL_*_EXPORTER` y `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`.
1025 1141
1026Cuando el desarrollador se desconecta, o se conecta a un gateway diferente, las exportaciones al recopilador se detienen y Claude Code descarta cada lote restante en lugar de enviarlo.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.
1027 1143
1028<h4 id="when-a-destination-fails">1144<h4 id="when-a-destination-fails">
1029 Cuando un destino falla1145 Cuando un destino falla
1030</h4>1146</h4>
1031 1147
1032El gateway 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 del gateway.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.
1033 1149
1034Después de cinco entregas consecutivas fallidas a un destino, el gateway 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.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.
1035 1151
1036Una carga útil rechazada ni avanza ni reinicia el contador de fallos: el gateway 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.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.
1037 1153
1038<h3 id="http-tuning">1154<h3 id="http-tuning">
1039 Ajuste HTTP1155 Ajuste HTTP
1043 1159
1044| Bloque | Clave | Predeterminado | Descripción |1160| Bloque | Clave | Predeterminado | Descripción |
1045| - | - | - | - |1161| - | - | - | - |
1046| `access_control` | `allow_cidrs` / `deny_cidrs` | vacío | Permitir/denegar IP de entrada 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, el gateway 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 el gateway 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. |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. |
1047| `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. |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. |
1048| `limits` | `max_request_header_bytes` | sin establecer | Cuando se establece, los encabezados de tamaño excesivo devuelven `431` |1164| `limits` | `max_request_header_bytes` | sin establecer | Cuando se establece, los encabezados de tamaño excesivo devuelven `431` |
1049| `limits` | `max_url_length` | sin establecer | Cuando se establece, una URL demasiado larga devuelve `414` |1165| `limits` | `max_url_length` | sin establecer | Cuando se establece, una URL demasiado larga devuelve `414` |
1050| `timeouts` | `upstream_ttfb_ms` | 120000 | Espera máxima para los encabezados de respuesta del upstream (tiempo hasta el 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, el gateway espera hasta una hora a que comience la respuesta. |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. |
1051| `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 dirección 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). |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). |
1052| `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 aumentarlo. |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. |
1053 1169
1054Si deja ambas listas `access_control` vacías, que es el valor predeterminado, el gateway sirve cualquier dirección de cliente, por lo que solo su red restringe quién puede alcanzarlo. Eso importa porque un gateway puede insertar [configuraciones administradas](#managed) que ejecutan comandos en máquinas de desarrolladores.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.
1055 1171
1056Mientras `allow_cidrs` esté vacío, el gateway advierte en dos lugares, sin cambiar cómo responde a ninguna solicitud:1172Mientras `allow_cidrs` está vacío, la puerta de enlace advierte en dos lugares, sin cambiar cómo responde a ninguna solicitud:
1057 1173
1058* **Al iniciar**: 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 el gateway a una dirección de loopback y no establece ni `trusted_proxies` ni `public_url`, como en desarrollo local, la advertencia no aparece.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.
1059* **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 lleva la dirección 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. El gateway 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.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.
1060 1176
1061Ambas señales utilizan la dirección del cliente tal como la resuelve el gateway. Si un equilibrador de carga, reenvío de puerto o túnel retransmite tráfico y no está enumerado en `listen.trusted_proxies`, el gateway 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.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.
1062 1178
1063Detrás de tal front end, establezca primero [`listen.trusted_proxies`](#listen) para que el gateway vea direcciones de cliente reales, y mantenga el gateway y todo lo que está frente a él inaccesible desde la internet pública independientemente.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.
1064 1180
1065<h3 id="load_test_mode">1181<h3 id="load_test_mode">
1066 `load_test_mode`1182 `load_test_mode`
1067</h3>1183</h3>
1068 1184
1069El bloque `load_test_mode` le permite hacer pruebas de carga en un gateway sin llamar a un proveedor de modelos. Mientras está activado, el gateway 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.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.
1070 1186
1071Requiere Claude Code v2.1.282 o posterior en el servidor de gateway. Las versiones anteriores se niegan a iniciar cuando encuentran la clave. Actualice cada réplica antes de agregar el bloque y elimine el bloque antes de revertir.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.
1072 1188
1073El ejemplo a continuación activa el modo con los valores predeterminados, una respuesta de aproximadamente 750 tokens de texto transmitida durante aproximadamente 10 segundos: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:
1074 1190
1075```yaml theme={null}1191```yaml theme={null}
1076load_test_mode:1192load_test_mode:
1077 enabled: true1193 enabled: true
1078 reply_tokens: 750 # roughly how many tokens of text each canned reply carries1194 reply_tokens: 750 # aproximadamente cuántos tokens de texto lleva cada respuesta enlatada
1079 reply_seconds: 9.5 # how long a streamed reply takes1195 reply_seconds: 9.5 # cuánto tiempo tarda una respuesta transmitida
1080```1196```
1081 1197
1082| Campo | Requerido | Descripción |1198| Campo | Requerido | Descripción |
1083| - | - | - |1199| - | - | - |
1084| `enabled` | Sí | `true` activa el modo. `false` mantiene sus números en el archivo con el modo desactivado. El gateway se niega a iniciar si el bloque está presente sin él. |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. |
1085| `reply_tokens` | No | Predeterminado `750`. Aproximadamente cuántos tokens de texto lleva cada respuesta enlatada, un número entero de 1 a 100000. |1201| `reply_tokens` | No | Predeterminado `750`. Aproximadamente cuántos tokens de texto lleva cada respuesta enlatada, un número entero de 1 a 100000. |
1086| `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. |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. |
1087 1203
1088Una prueba de carga en este modo cubre el gateway, su Postgres y todo lo que está frente al gateway. No cubre los límites, velocidad o ruta de red del proveedor.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.
1089 1205
1090Ninguna solicitud de modelo se envía 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.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.
1091 1207
1092Mientras 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. El gateway cuenta cada número como un desarrollador separado, con el correo electrónico y grupos del desarrollador cuyo token vino con la solicitud.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.
1093 1209
1094Asigne a la implementación de prueba 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 ha gastado algo.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.
1095 1211
1096<Warning>1212<Warning>
1097 Nunca active esto para un gateway que los desarrolladores usan. Cada solicitud obtiene la respuesta enlatada y ningún modelo se llama. El gateway registra una advertencia `load_test_mode is on` al iniciar y marca cada evento de auditoría [`inference`](/docs/es/claude-apps-gateway-deploy#logs) con `load_test: true` mientras el modo está activado.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.
1098</Warning>1214</Warning>
1099 1215
1100<h2 id="complete-example">1216<h2 id="complete-example">
