Autenticación de proxy de confianza

Cuándo usarlo

Usa el modo de autenticación trusted-proxy cuando:

• Ejecutas OpenClaw detrás de un proxy con identidad integrada (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Tu proxy gestiona toda la autenticación y pasa la identidad del usuario mediante encabezados.
• Estás en un entorno Kubernetes o de contenedores donde el proxy es la única ruta hacia el Gateway.
• Te encuentras con errores WebSocket 1008 unauthorized porque los navegadores no pueden pasar tokens en las cargas útiles de WS.

Cuándo NO usarlo

• Si tu proxy no autentica usuarios (solo es un terminador TLS o balanceador de carga).
• Si existe alguna ruta hacia el Gateway que omite el proxy (huecos de firewall, acceso desde la red interna).
• Si no tienes certeza de que tu proxy elimine o sobrescriba correctamente los encabezados reenviados.
• Si solo necesitas acceso personal de un único usuario (considera Tailscale Serve + loopback para una configuración más sencilla).

Cómo funciona

Comportamiento de emparejamiento de la Control UI

Cuando gateway.auth.mode = "trusted-proxy" está activo y la solicitud supera las comprobaciones de trusted-proxy, las sesiones WebSocket de la Control UI pueden conectarse sin identidad de emparejamiento de dispositivo.

Implicaciones de alcance:

• Las sesiones WebSocket de la Control UI sin dispositivo se conectan, pero no reciben alcances de operador de forma predeterminada. OpenClaw vacía la lista de alcances solicitados a [] para que una sesión que no está vinculada a un dispositivo/token emparejado aprobado no pueda autodeclarar permisos.
• Si los métodos fallan con missing scope después de una conexión WebSocket correcta, usa HTTPS para que el navegador pueda generar identidad de dispositivo y completar el emparejamiento. Consulta HTTP inseguro de la Control UI.
• Solo para emergencia: gateway.controlUi.dangerouslyDisableDeviceAuth=true conserva los alcances solicitados incluso sin identidad de dispositivo. Esto supone una degradación grave de la seguridad; revierte el cambio rápidamente. Consulta HTTP inseguro de la Control UI.

Limitación de alcances mediante proxy inverso:

• Si tu proxy envía x-openclaw-scopes en la solicitud de actualización WebSocket de la Control UI, OpenClaw limita los alcances de la sesión a la intersección entre los alcances solicitados y los declarados. Este encabezado no concede alcances; solo reduce lo que la sesión puede conservar.

Implicaciones:

• El emparejamiento ya no es la puerta principal para acceder a la Control UI en este modo.
• La política de autenticación de tu proxy inverso y allowUsers se convierten en el control de acceso efectivo.
• Mantén el ingreso del Gateway restringido solo a las IP de proxy de confianza (gateway.trustedProxies + firewall).

Los clientes WebSocket personalizados no son sesiones de la Control UI. gateway.controlUi.dangerouslyDisableDeviceAuth no concede alcances a clientes arbitrarios con client.mode: "backend" o con forma de CLI. La automatización personalizada debe usar identidad/emparejamiento de dispositivo, la ruta auxiliar backend directa-local reservada client.id: "gateway-client" o el Plugin HTTP RPC de administración cuando una superficie HTTP de solicitud/respuesta encaje mejor.

Configuración

{  gateway: {    // Trusted-proxy auth expects requests from a non-loopback trusted proxy source by default    bind: "lan",     // CRITICAL: Only add your proxy's IP(s) here    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // Header containing authenticated user identity (required)        userHeader: "x-forwarded-user",         // Optional: headers that MUST be present (proxy verification)        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // Optional: restrict to specific users (empty = allow all)        allowUsers: ["nick@example.com", "admin@company.org"],         // Optional: allow a same-host loopback proxy after explicit opt-in        allowLoopback: false,      },    },  },}

Referencia de configuración

Terminación TLS y HSTS

Usa un único punto de terminación TLS y aplica HSTS allí.

Strict-Transport-Security: max-age=31536000; includeSubDomains

{  gateway: {    tls: { enabled: true },    http: {      securityHeaders: {        strictTransportSecurity: "max-age=31536000; includeSubDomains",      },    },  },}

Guía de despliegue gradual

• Empieza primero con una edad máxima corta (por ejemplo, max-age=300) mientras validas el tráfico.
• Aumenta a valores de larga duración (por ejemplo, max-age=31536000) solo cuando la confianza sea alta.
• Agrega includeSubDomains solo si todos los subdominios están preparados para HTTPS.
• Usa preload solo si cumples intencionalmente los requisitos de preload para todo tu conjunto de dominios.
• El desarrollo local solo con loopback no se beneficia de HSTS.

Ejemplos de configuración de proxy

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // Pomerium's IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-pomerium-claim-email",        requiredHeaders: ["x-pomerium-jwt-assertion"],      },    },  },}

routes:  - from: https://openclaw.example.com    to: http://openclaw-gateway:18789    policy:      - allow:          or:            - email:                is: nick@example.com    pass_identity_headers: true

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // Caddy/sidecar proxy IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

openclaw.example.com {    authenticate with oauth2_provider    authorize with policy1     reverse_proxy openclaw:18789 {        header_up X-Forwarded-User {http.auth.user.email}    }}

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // nginx/oauth2-proxy IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-auth-request-email",      },    },  },}

location / {    auth_request /oauth2/auth;    auth_request_set $user $upstream_http_x_auth_request_email;     proxy_pass http://openclaw:18789;    proxy_set_header X-Auth-Request-Email $user;    proxy_http_version 1.1;    proxy_set_header Upgrade $http_upgrade;    proxy_set_header Connection "upgrade";}

{  gateway: {    bind: "lan",    trustedProxies: ["172.17.0.1"], // Traefik container IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

Configuración mixta de tokens

OpenClaw rechaza configuraciones ambiguas en las que tanto un gateway.auth.token (o OPENCLAW_GATEWAY_TOKEN) como el modo trusted-proxy están activos al mismo tiempo. Las configuraciones mixtas de tokens pueden hacer que las solicitudes loopback se autentiquen silenciosamente en la ruta de autenticación equivocada.

Si ves un error mixed_trusted_proxy_token al iniciar:

• Elimina el token compartido cuando uses el modo trusted-proxy, o
• Cambia gateway.auth.mode a "token" si quieres autenticación basada en tokens.

Los encabezados de identidad de proxy de confianza de loopback siguen fallando de forma cerrada: los llamadores del mismo host no se autentican silenciosamente como usuarios del proxy. Los llamadores internos de OpenClaw que omiten el proxy pueden autenticarse con gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD en su lugar. La alternativa con token sigue sin estar admitida intencionalmente en modo trusted-proxy.

Encabezado de ámbitos de operador

La autenticación trusted-proxy es un modo HTTP portador de identidad, por lo que los llamadores pueden declarar opcionalmente ámbitos de operador con x-openclaw-scopes en solicitudes de API HTTP.

Nota: los ámbitos de WebSocket se determinan mediante el handshake del protocolo Gateway y la vinculación de identidad del dispositivo. En las solicitudes de actualización de WebSocket de Control UI, x-openclaw-scopes es solo un límite para los ámbitos de sesión negociados, no una concesión. Para el comportamiento de ámbitos de WebSocket con trusted-proxy, consulta Comportamiento de emparejamiento de Control UI.

Ejemplos:

• x-openclaw-scopes: operator.read
• x-openclaw-scopes: operator.read,operator.write
• x-openclaw-scopes: operator.admin,operator.write

Comportamiento:

• Cuando el encabezado está presente, OpenClaw respeta el conjunto de ámbitos declarado.
• Cuando el encabezado está presente pero vacío, la solicitud declara ningún ámbito de operador.
• Cuando el encabezado está ausente, las API HTTP normales portadoras de identidad recurren al conjunto estándar predeterminado de ámbitos de operador.
• Las rutas HTTP de Plugin con autenticación Gateway son más restringidas de forma predeterminada: cuando x-openclaw-scopes está ausente, su ámbito en tiempo de ejecución recurre a operator.write.
• Las solicitudes HTTP de origen de navegador aún deben pasar gateway.controlUi.allowedOrigins (o el modo deliberado de alternativa con encabezado Host) incluso después de que la autenticación trusted-proxy se complete correctamente.
• Para las sesiones WebSocket de Control UI, x-openclaw-scopes es un límite de ámbito cuando está presente en la solicitud de actualización. Un valor vacío produce cero ámbitos.

Regla práctica: envía x-openclaw-scopes explícitamente cuando quieras que una solicitud trusted-proxy sea más restringida que los valores predeterminados, o cuando una ruta de Plugin con autenticación Gateway necesite algo más fuerte que el ámbito de escritura.

Lista de verificación de seguridad

Antes de activar la autenticación trusted-proxy, verifica:

• [ ] El proxy es la única ruta: el puerto del Gateway está protegido por firewall contra todo excepto tu proxy.
• [ ] trustedProxies es mínimo: solo las IP reales de tu proxy, no subredes enteras.
• [ ] El origen del proxy de loopback es deliberado: la autenticación trusted-proxy falla de forma cerrada para solicitudes con origen de loopback, a menos que gateway.auth.trustedProxy.allowLoopback esté activado explícitamente para un proxy del mismo host.
• [ ] El proxy elimina encabezados: tu proxy sobrescribe (no añade) los encabezados x-forwarded-* de los clientes.
• [ ] Terminación TLS: tu proxy gestiona TLS; los usuarios se conectan mediante HTTPS.
• [ ] allowedOrigins es explícito: Control UI sin loopback usa gateway.controlUi.allowedOrigins explícito.
• [ ] allowUsers está configurado (recomendado): restringe a usuarios conocidos en lugar de permitir a cualquiera que esté autenticado.
• [ ] Sin configuración mixta de tokens: no configures tanto gateway.auth.token como gateway.auth.mode: "trusted-proxy".
• [ ] La alternativa de contraseña local es privada: si configuras gateway.auth.password para llamadores directos internos, mantén el puerto del Gateway protegido por firewall para que los clientes remotos que no pasen por el proxy no puedan alcanzarlo directamente.

Auditoría de seguridad

openclaw security audit marcará la autenticación trusted-proxy con un hallazgo de severidad crítica. Esto es intencional: es un recordatorio de que estás delegando la seguridad a la configuración de tu proxy.

La auditoría comprueba:

• Advertencia/recordatorio crítico base gateway.trusted_proxy_auth
• Falta de configuración trustedProxies
• Falta de configuración userHeader
• allowUsers vacío (permite cualquier usuario autenticado)
• allowLoopback activado para orígenes de proxy del mismo host
• Política de origen de navegador comodín o ausente en superficies expuestas de Control UI

Solución de problemas

Migración desde autenticación con token

Si vas a cambiar de autenticación con token a trusted-proxy:

Relacionado

• Configuración — referencia de configuración
• Acceso remoto — otros patrones de acceso remoto
• Seguridad — guía completa de seguridad
• Tailscale — alternativa más sencilla para acceso solo por tailnet