Autenticação de proxy confiável

Quando usar

Use o modo de autenticação trusted-proxy quando:

• Você executa o OpenClaw atrás de um proxy com reconhecimento de identidade (Pomerium, Caddy + OAuth, nginx + oauth2-proxy, Traefik + forward auth).
• Seu proxy gerencia toda a autenticação e passa a identidade do usuário por cabeçalhos.
• Você está em um ambiente Kubernetes ou de contêiner em que o proxy é o único caminho para o Gateway.
• Você está encontrando erros WebSocket 1008 unauthorized porque os navegadores não conseguem passar tokens em payloads WS.

Quando NÃO usar

• Se seu proxy não autentica usuários (apenas um terminador TLS ou balanceador de carga).
• Se houver qualquer caminho para o Gateway que contorne o proxy (brechas no firewall, acesso pela rede interna).
• Se você não tiver certeza de que seu proxy remove/substitui corretamente os cabeçalhos encaminhados.
• Se você só precisa de acesso pessoal para um único usuário (considere Tailscale Serve + loopback para uma configuração mais simples).

Como funciona

Comportamento de pareamento da Control UI

Quando gateway.auth.mode = "trusted-proxy" está ativo e a solicitação passa nas verificações de trusted-proxy, as sessões WebSocket da Control UI podem se conectar sem identidade de pareamento de dispositivo.

Implicações de escopo:

• Sessões WebSocket da Control UI sem dispositivo se conectam, mas não recebem escopos de operador por padrão. O OpenClaw limpa a lista de escopos solicitados para [] para que uma sessão que não esteja vinculada a um dispositivo/token pareado aprovado não possa declarar permissões por conta própria.
• Se métodos falharem com missing scope após uma conexão WebSocket bem-sucedida, use HTTPS para que o navegador possa gerar identidade de dispositivo e concluir o pareamento. Consulte HTTP inseguro da Control UI.
• Apenas para emergência: gateway.controlUi.dangerouslyDisableDeviceAuth=true preserva os escopos solicitados mesmo sem identidade de dispositivo. Isso é um rebaixamento grave de segurança; reverta rapidamente. Consulte HTTP inseguro da Control UI.

Limitação de escopo por proxy reverso:

• Se seu proxy enviar x-openclaw-scopes na solicitação de upgrade WebSocket da Control UI, o OpenClaw limita os escopos da sessão à interseção entre os escopos solicitados e os escopos declarados. Esse cabeçalho não concede escopos; ele apenas restringe o que a sessão pode manter.

Implicações:

• O pareamento deixa de ser o gate principal para acesso à Control UI neste modo.
• A política de autenticação do seu proxy reverso e allowUsers passam a ser o controle de acesso efetivo.
• Mantenha a entrada do gateway bloqueada apenas para IPs de proxy confiáveis (gateway.trustedProxies + firewall).

Clientes WebSocket personalizados não são sessões da Control UI. gateway.controlUi.dangerouslyDisableDeviceAuth não concede escopos a clientes arbitrários client.mode: "backend" ou com formato de CLI. Automações personalizadas devem usar identidade/pareamento de dispositivo, o caminho auxiliar backend direto-local reservado client.id: "gateway-client" ou o Plugin HTTP RPC de administração quando uma superfície HTTP de solicitação/resposta for mais adequada.

Configuração

{  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,      },    },  },}

Referência de configuração

Terminação TLS e HSTS

Use um único ponto de terminação TLS e aplique HSTS nele.

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

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

Orientação de implantação

• Comece primeiro com uma idade máxima curta (por exemplo, max-age=300) enquanto valida o tráfego.
• Aumente para valores de longa duração (por exemplo, max-age=31536000) somente depois que a confiança estiver alta.
• Adicione includeSubDomains apenas se todos os subdomínios estiverem prontos para HTTPS.
• Use preload apenas se você atender intencionalmente aos requisitos de preload para todo o seu conjunto de domínios.
• O desenvolvimento local apenas em loopback não se beneficia de HSTS.

Exemplos de configuração 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",      },    },  },}

Configuração mista de token

O OpenClaw rejeita configurações ambíguas em que tanto um gateway.auth.token (ou OPENCLAW_GATEWAY_TOKEN) quanto o modo trusted-proxy estão ativos ao mesmo tempo. Configurações mistas de token podem fazer com que solicitações loopback sejam autenticadas silenciosamente pelo caminho de autenticação errado.

Se você vir um erro mixed_trusted_proxy_token na inicialização:

• Remova o token compartilhado ao usar o modo trusted-proxy, ou
• Altere gateway.auth.mode para "token" se você pretende usar autenticação baseada em token.

A identidade por cabeçalhos de proxy confiável em loopback ainda falha fechada: chamadores no mesmo host não são autenticados silenciosamente como usuários do proxy. Chamadores internos do OpenClaw que contornam o proxy podem se autenticar com gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD em vez disso. O fallback por token continua intencionalmente sem suporte no modo de proxy confiável.

Cabeçalho de escopos do operador

A autenticação por proxy confiável é um modo HTTP portador de identidade, portanto os chamadores podem declarar opcionalmente escopos de operador com x-openclaw-scopes em requisições da API HTTP.

Observação: os escopos de WebSocket são determinados pelo handshake do protocolo Gateway e pela vinculação de identidade do dispositivo. Em requisições de upgrade WebSocket da Control UI, x-openclaw-scopes é apenas um limite para os escopos negociados da sessão, não uma concessão. Para o comportamento de escopos WebSocket com proxy confiável, consulte comportamento de pareamento da Control UI.

Exemplos:

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

Comportamento:

• Quando o cabeçalho está presente, o OpenClaw respeita o conjunto de escopos declarado.
• Quando o cabeçalho está presente, mas vazio, a requisição declara nenhum escopo de operador.
• Quando o cabeçalho está ausente, APIs HTTP normais portadoras de identidade recorrem ao conjunto padrão de escopos padrão do operador.
• Rotas HTTP de Plugin com autenticação pelo Gateway são mais restritas por padrão: quando x-openclaw-scopes está ausente, seu escopo de runtime recai para operator.write.
• Requisições HTTP originadas no navegador ainda precisam passar por gateway.controlUi.allowedOrigins (ou pelo modo deliberado de fallback de cabeçalho Host), mesmo depois que a autenticação por proxy confiável é bem-sucedida.
• Para sessões WebSocket da Control UI, x-openclaw-scopes é um limite de escopo quando presente na requisição de upgrade. Um valor vazio resulta em nenhum escopo.

Regra prática: envie x-openclaw-scopes explicitamente quando quiser que uma requisição por proxy confiável seja mais restrita que os padrões, ou quando uma rota de Plugin com autenticação pelo Gateway precisar de algo mais forte que escopo de escrita.

Checklist de segurança

Antes de habilitar a autenticação por proxy confiável, verifique:

• [ ] Proxy é o único caminho: A porta do Gateway está protegida por firewall contra tudo, exceto seu proxy.
• [ ] trustedProxies é mínimo: Apenas os IPs reais do seu proxy, não sub-redes inteiras.
• [ ] Fonte de proxy por loopback é deliberada: a autenticação por proxy confiável falha fechada para requisições com origem em loopback, a menos que gateway.auth.trustedProxy.allowLoopback esteja explicitamente habilitado para um proxy no mesmo host.
• [ ] Proxy remove cabeçalhos: Seu proxy sobrescreve (não acrescenta) cabeçalhos x-forwarded-* dos clientes.
• [ ] Terminação TLS: Seu proxy lida com TLS; usuários se conectam via HTTPS.
• [ ] allowedOrigins é explícito: Control UI sem loopback usa gateway.controlUi.allowedOrigins explícito.
• [ ] allowUsers está definido (recomendado): Restrinja a usuários conhecidos em vez de permitir qualquer pessoa autenticada.
• [ ] Sem configuração mista de token: Não defina gateway.auth.token e gateway.auth.mode: "trusted-proxy" ao mesmo tempo.
• [ ] Fallback de senha local é privado: Se você configurar gateway.auth.password para chamadores internos diretos, mantenha a porta do Gateway protegida por firewall para que clientes remotos fora do proxy não possam alcançá-la diretamente.

Auditoria de segurança

openclaw security audit sinalizará autenticação por proxy confiável com um achado de severidade crítica. Isso é intencional: é um lembrete de que você está delegando a segurança à configuração do seu proxy.

A auditoria verifica:

• Lembrete/aviso crítico base gateway.trusted_proxy_auth
• Configuração trustedProxies ausente
• Configuração userHeader ausente
• allowUsers vazio (permite qualquer usuário autenticado)
• allowLoopback habilitado para origens de proxy no mesmo host
• Política de origem de navegador curinga ou ausente em superfícies expostas da Control UI

Solução de problemas

Migração da autenticação por token

Se você está migrando da autenticação por token para proxy confiável:

Relacionados

• Configuração — referência de configuração
• Acesso remoto — outros padrões de acesso remoto
• Segurança — guia de segurança completo
• Tailscale — alternativa mais simples para acesso somente por tailnet