Proxy de rede

O OpenClaw pode rotear o tráfego HTTP e WebSocket de runtime por meio de um proxy de encaminhamento gerenciado pelo operador. Essa é uma defesa opcional em profundidade para implantações que desejam controle central de egresso, proteção SSRF mais forte e melhor auditabilidade de rede.

O OpenClaw não distribui, baixa, inicia, configura nem certifica um proxy. Você executa a tecnologia de proxy adequada ao seu ambiente, e o OpenClaw roteia clientes HTTP e WebSocket normais locais ao processo por meio dela.

Por que usar um proxy

Um proxy oferece aos operadores um único ponto de controle de rede para tráfego HTTP e WebSocket de saída. Isso pode ser útil mesmo fora do reforço contra SSRF:

• Política central: mantenha uma única política de egresso em vez de depender de cada ponto de chamada HTTP da aplicação para acertar as regras de rede.
• Verificações no momento da conexão: avalie o destino após a resolução de DNS e imediatamente antes de o proxy abrir a conexão upstream.
• Defesa contra DNS rebinding: reduza a lacuna entre uma verificação de DNS no nível da aplicação e a conexão de saída real.
• Cobertura JavaScript mais ampla: roteie clientes comuns como fetch, node:http, node:https, WebSocket, axios, got, node-fetch e similares pelo mesmo caminho.
• Auditabilidade: registre destinos permitidos e negados no limite de egresso.
• Controle operacional: imponha regras de destino, segmentação de rede, limites de taxa ou allowlists de saída sem reconstruir o OpenClaw.

O roteamento por proxy é uma proteção no nível do processo para egresso HTTP e WebSocket normal. Ele oferece aos operadores um caminho fail-closed para rotear clientes HTTP JavaScript compatíveis por meio do seu próprio proxy de filtragem, mas não é um sandbox de rede no nível do sistema operacional e não faz o OpenClaw certificar a política de destinos do proxy.

Como o OpenClaw roteia tráfego

Quando proxy.enabled=true e uma URL de proxy está configurada, processos de runtime protegidos, como openclaw gateway run, openclaw node run e openclaw agent --local, roteiam o egresso HTTP e WebSocket normal por meio do proxy configurado:

OpenClaw process  fetch                  -> operator-managed filtering proxy -> public internet  node:http and https    -> operator-managed filtering proxy -> public internet  WebSocket clients      -> operator-managed filtering proxy -> public internet

O contrato público é o comportamento de roteamento, não os hooks internos do Node usados para implementá-lo. Clientes WebSocket do plano de controle do OpenClaw Gateway usam um caminho direto estreito para tráfego RPC do Gateway em local loopback quando a URL do Gateway usa localhost ou um IP literal de loopback, como 127.0.0.1 ou [::1]. Esse caminho do plano de controle deve conseguir alcançar Gateways em loopback mesmo quando o proxy do operador bloqueia destinos de loopback. Requisições HTTP e WebSocket normais de runtime continuam usando o proxy configurado.

Internamente, o OpenClaw usa dois hooks de roteamento no nível do processo para esse recurso:

• O roteamento por dispatcher do Undici cobre fetch, clientes baseados em undici e transportes que fornecem seu próprio dispatcher undici.
• O roteamento por global-agent cobre chamadores do core do Node node:http e node:https, incluindo muitas bibliotecas construídas sobre http.request, https.request, http.get e https.get. O modo de proxy gerenciado força esse agente global para que agentes HTTP explícitos do Node não contornem acidentalmente o proxy do operador.

Alguns plugins possuem transportes personalizados que precisam de configuração explícita de proxy mesmo quando existe roteamento no nível do processo. Por exemplo, o transporte da Bot API do Telegram usa seu próprio dispatcher undici HTTP/1 e, portanto, respeita o ambiente de proxy do processo mais o fallback gerenciado OPENCLAW_PROXY_URL nesse caminho de transporte específico do proprietário.

A própria URL do proxy deve usar http://. Destinos HTTPS continuam sendo compatíveis por meio do proxy com HTTP CONNECT; isso significa apenas que o OpenClaw espera um listener de proxy de encaminhamento HTTP simples, como http://127.0.0.1:3128.

Enquanto o proxy está ativo, o OpenClaw limpa no_proxy, NO_PROXY e GLOBAL_AGENT_NO_PROXY. Essas listas de bypass são baseadas em destino, então deixar localhost ou 127.0.0.1 ali permitiria que alvos SSRF de alto risco pulassem o proxy de filtragem.

No encerramento, o OpenClaw restaura o ambiente de proxy anterior e redefine o estado de roteamento em cache do processo.

Termos relacionados a proxy

• proxy.enabled / proxy.proxyUrl: roteamento de proxy de encaminhamento de saída para egresso de runtime do OpenClaw. Esta página documenta esse recurso.
• gateway.auth.mode: "trusted-proxy": autenticação de proxy reverso de entrada com identidade para acesso ao Gateway. Consulte Autenticação por proxy confiável.
• openclaw proxy: proxy de depuração local e inspetor de captura para desenvolvimento e suporte. Consulte openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy: opção de adesão para web_fetch permitir que um proxy de ambiente HTTP(S) controlado pelo operador resolva DNS mantendo a política padrão estrita de pinning de DNS e hostname. Consulte Web fetch.
• Configurações de proxy específicas de canal ou provedor: substituições específicas do proprietário para um transporte específico. Prefira o proxy de rede gerenciado quando o objetivo for controle central de egresso em todo o runtime.

Configuração

proxy:  enabled: true  proxyUrl: http://127.0.0.1:3128

Você também pode fornecer a URL por meio do ambiente, mantendo proxy.enabled=true na configuração:

OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run

proxy.proxyUrl tem precedência sobre OPENCLAW_PROXY_URL.

Modo de Loopback do Gateway

Clientes locais do plano de controle do Gateway geralmente se conectam a um WebSocket de loopback, como ws://127.0.0.1:18789. Use proxy.loopbackMode para escolher como esse tráfego se comporta enquanto o proxy gerenciado está ativo:

proxy:  enabled: true  proxyUrl: http://127.0.0.1:3128  loopbackMode: gateway-only # gateway-only, proxy, or block

• gateway-only (padrão): o OpenClaw registra a autoridade de loopback do Gateway no controlador NO_PROXY ativo do global-agent para que o tráfego WebSocket local do Gateway possa se conectar diretamente. Portas personalizadas de Gateway em loopback funcionam porque o host e a porta da URL ativa do Gateway são registrados.
• proxy: o OpenClaw não registra uma autoridade NO_PROXY de loopback do Gateway, então o tráfego local do Gateway é enviado pelo proxy gerenciado. Se o proxy for remoto, ele deve fornecer roteamento especial para o serviço de loopback do host do OpenClaw, como mapeá-lo para um hostname, IP ou túnel alcançável pelo proxy. Proxies remotos padrão resolvem 127.0.0.1 e localhost a partir do host do proxy, não do host do OpenClaw.
• block: o OpenClaw nega conexões de plano de controle do Gateway em loopback antes de abrir um socket.

Se enabled=true, mas nenhuma URL de proxy válida estiver configurada, comandos protegidos falham na inicialização em vez de voltar para acesso direto à rede.

Para serviços gerenciados do Gateway iniciados com openclaw gateway start, prefira armazenar a URL na configuração:

openclaw config set proxy.enabled trueopenclaw config set proxy.proxyUrl http://127.0.0.1:3128openclaw gateway install --forceopenclaw gateway start

O fallback de ambiente é melhor para execuções em primeiro plano. Se você usá-lo com um serviço instalado, coloque OPENCLAW_PROXY_URL no ambiente durável do serviço, como $OPENCLAW_STATE_DIR/.env ou ~/.openclaw/.env, e então reinstale o serviço para que launchd, systemd ou Tarefas Agendadas iniciem o gateway com esse valor.

Para comandos openclaw --container ..., o OpenClaw encaminha OPENCLAW_PROXY_URL para a CLI filha direcionada ao contêiner quando ele está definido. A URL deve ser alcançável de dentro do contêiner; 127.0.0.1 se refere ao próprio contêiner, não ao host. O OpenClaw rejeita URLs de proxy de loopback para comandos direcionados a contêiner, a menos que você substitua explicitamente essa verificação de segurança.

Requisitos do Proxy

A política do proxy é o limite de segurança. O OpenClaw não consegue verificar se o proxy bloqueia os alvos corretos.

Configure o proxy para:

• Vincular-se apenas a loopback ou a uma interface privada confiável.
• Restringir o acesso para que apenas o processo, host, contêiner ou conta de serviço do OpenClaw possa usá-lo.
• Resolver destinos por conta própria e bloquear IPs de destino após a resolução de DNS.
• Aplicar a política no momento da conexão tanto para requisições HTTP simples quanto para túneis HTTPS CONNECT.
• Rejeitar bypasses baseados em destino para intervalos de loopback, privados, link-local, metadados, multicast, reservados ou de documentação.
• Evitar allowlists de hostname a menos que você confie totalmente no caminho de resolução de DNS.
• Registrar destino, decisão, status e motivo sem registrar corpos de requisição, cabeçalhos de autorização, cookies ou outros segredos.
• Manter a política de proxy sob controle de versão e revisar alterações como configuração sensível à segurança.

Destinos bloqueados recomendados

Use esta denylist como ponto de partida para qualquer proxy de encaminhamento, firewall ou política de egresso.

A lógica de classificador no nível da aplicação do OpenClaw fica em src/infra/net/ssrf.ts e src/shared/net/ip.ts. Os hooks de paridade relevantes são BLOCKED_HOSTNAMES, BLOCKED_IPV4_SPECIAL_USE_RANGES, BLOCKED_IPV6_SPECIAL_USE_RANGES, RFC2544_BENCHMARK_PREFIX e o tratamento de sentinela IPv4 incorporado para NAT64, 6to4, Teredo, ISATAP e formas mapeadas para IPv4. Esses arquivos são referências úteis ao manter uma política externa de proxy, mas o OpenClaw não exporta nem impõe automaticamente essas regras no seu proxy.

Se seu provedor de nuvem ou plataforma de rede documentar hosts de metadados ou intervalos reservados adicionais, adicione-os também.

Validação

Valide o proxy a partir do mesmo host, contêiner ou conta de serviço que executa o OpenClaw:

openclaw proxy validate --proxy-url http://127.0.0.1:3128

Por padrão, quando nenhum destino personalizado é fornecido, o comando verifica se https://example.com/ é bem-sucedido e inicia um canário de loopback temporário que o proxy não deve alcançar. A verificação negada padrão passa quando o proxy retorna uma resposta de negação não 2xx ou bloqueia o canário com uma falha de transporte; ela falha se uma resposta bem-sucedida alcançar o canário. Se nenhum proxy estiver habilitado e configurado, a validação relata um problema de configuração; use --proxy-url para uma pré-verificação pontual antes de alterar a configuração. Use --allowed-url e --denied-url para testar expectativas específicas da implantação. Adicione --apns-reachable para também verificar se a entrega HTTP/2 direta de APNs consegue abrir um túnel CONNECT pelo proxy e receber uma resposta de APNs de sandbox; a sondagem usa um token de provedor intencionalmente inválido, portanto 403 InvalidProviderToken é esperado e conta como alcançável. Destinos negados personalizados falham fechados: qualquer resposta HTTP significa que o destino era alcançável pelo proxy, e qualquer erro de transporte é relatado como inconclusivo porque o OpenClaw não consegue provar que o proxy bloqueou uma origem alcançável. Em caso de falha na validação, o comando sai com código 1.

Use --json para automação. A saída JSON contém o resultado geral, a origem efetiva da configuração do proxy, quaisquer erros de configuração e cada verificação de destino. Credenciais da URL do proxy são redigidas na saída de texto e JSON:

{  "ok": true,  "config": {    "enabled": true,    "proxyUrl": "http://127.0.0.1:3128/",    "source": "override",    "errors": []  },  "checks": [    {      "kind": "allowed",      "url": "https://example.com/",      "ok": true,      "status": 200    },    {      "kind": "apns",      "url": "https://api.sandbox.push.apple.com",      "ok": true,      "status": 403    }  ]}

Você também pode validar manualmente com curl:

curl -x http://127.0.0.1:3128 https://example.com/curl -x http://127.0.0.1:3128 http://127.0.0.1/curl -x http://127.0.0.1:3128 http://169.254.169.254/

A solicitação pública deve ser bem-sucedida. As solicitações de loopback e de metadados devem ser bloqueadas pelo proxy. Para openclaw proxy validate, o canário de loopback integrado consegue distinguir uma negação do proxy de uma origem alcançável. Verificações --denied-url personalizadas não têm esse canário, então trate tanto respostas HTTP quanto falhas de transporte ambíguas como falhas de validação, a menos que seu proxy exponha um sinal de negação específico da implantação que você consiga verificar separadamente.

Em seguida, habilite o roteamento por proxy do OpenClaw:

openclaw config set proxy.enabled trueopenclaw config set proxy.proxyUrl http://127.0.0.1:3128openclaw gateway run

ou defina:

proxy:  enabled: true  proxyUrl: http://127.0.0.1:3128

Limites

• O proxy melhora a cobertura para clientes HTTP e WebSocket JavaScript locais ao processo, mas não é uma sandbox de rede no nível do SO.
• O tráfego de plano de controle de loopback do Gateway usa por padrão um desvio local direto por meio de proxy.loopbackMode: "gateway-only". O OpenClaw implementa esse desvio registrando a autoridade de loopback ativa do Gateway no controlador NO_PROXY gerenciado do global-agent. Operadores podem definir proxy.loopbackMode: "proxy" para enviar o tráfego de loopback do Gateway pelo proxy gerenciado, ou proxy.loopbackMode: "block" para negar conexões de loopback do Gateway. Consulte Modo de Loopback do Gateway para a ressalva sobre proxy remoto.
• Sockets brutos net, tls e http2, addons nativos e processos filhos que não são do OpenClaw podem ignorar o roteamento por proxy no nível do Node, a menos que herdem e respeitem variáveis de ambiente de proxy. CLIs filhas bifurcadas do OpenClaw herdam a URL do proxy gerenciado e o estado de proxy.loopbackMode.
• IRC é um canal TCP/TLS bruto fora do roteamento de proxy de encaminhamento gerenciado pelo operador. Em implantações que exigem toda saída por esse proxy de encaminhamento, defina channels.irc.enabled=false, a menos que a saída direta de IRC seja explicitamente aprovada.
• O proxy de depuração local é uma ferramenta de diagnóstico, e seu encaminhamento upstream direto para solicitações de proxy e túneis CONNECT fica desabilitado por padrão enquanto o modo de proxy gerenciado está ativo; habilite o encaminhamento direto apenas para diagnósticos locais aprovados.
• WebUIs locais do usuário e servidores de modelo locais devem ser incluídos na lista de permissões na política de proxy do operador quando necessário; o OpenClaw não expõe um desvio geral de rede local para eles.
• O desvio de proxy do plano de controle do Gateway é intencionalmente limitado a localhost e URLs de IP de loopback literais. Use ws://127.0.0.1:18789, ws://[::1]:18789 ou ws://localhost:18789 para conexões locais diretas do plano de controle do Gateway; outros nomes de host são roteados como tráfego comum baseado em nome de host.
• O OpenClaw não inspeciona, testa nem certifica sua política de proxy.
• Trate alterações na política de proxy como alterações operacionais sensíveis à segurança.