Proxy de rede

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Por que usar um proxy

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

​

Como o OpenClaw roteia tráfego

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

​

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

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

​

Modo de Loopback do Gateway

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.

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

​

Requisitos do Proxy

• 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

​

Validação

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

{
  "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
    }
  ]
}

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/

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

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.