Proxy de red

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 qué usar un proxy

• Política central: mantener una sola política de salida en lugar de depender de que cada punto de llamada HTTP de la aplicación aplique correctamente las reglas de red.
• Comprobaciones en tiempo de conexión: evaluar el destino después de la resolución DNS e inmediatamente antes de que el proxy abra la conexión ascendente.
• Defensa contra DNS rebinding: reducir la brecha entre una comprobación DNS a nivel de aplicación y la conexión saliente real.
• Cobertura más amplia de JavaScript: enrutar clientes ordinarios como fetch, node:http, node:https, WebSocket, axios, got, node-fetch y similares por la misma ruta.
• Auditabilidad: registrar destinos permitidos y denegados en el límite de salida.
• Control operativo: aplicar reglas de destino, segmentación de red, límites de tasa o listas de permitidos salientes sin reconstruir OpenClaw.

​

Cómo enruta OpenClaw el tráfico

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

• El enrutamiento del despachador de Undici cubre fetch, clientes respaldados por undici y transportes que proporcionan su propio despachador de undici.
• El enrutamiento de global-agent cubre llamadores del núcleo de Node node:http y node:https, incluidas muchas bibliotecas construidas sobre http.request, https.request, http.get y https.get. El modo de proxy gestionado fuerza ese agente global para que los agentes HTTP explícitos de Node no eviten accidentalmente el proxy del operador.

​

Términos de proxy relacionados

• proxy.enabled / proxy.proxyUrl: enrutamiento saliente por proxy directo para la salida de tiempo de ejecución de OpenClaw. Esta página documenta esa función.
• gateway.auth.mode: "trusted-proxy": autenticación entrante mediante proxy inverso con identidad para el acceso a Gateway. Consulta Autenticación de proxy de confianza.
• openclaw proxy: proxy local de depuración e inspector de captura para desarrollo y soporte. Consulta openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy: opción explícita para que web_fetch permita que un proxy HTTP(S) de entorno controlado por el operador resuelva DNS, manteniendo la fijación DNS estricta predeterminada y la política de nombres de host. Consulta Web fetch.
• Configuración de proxy específica de canal o proveedor: anulaciones específicas del propietario para un transporte concreto. Prefiere el proxy de red gestionado cuando el objetivo sea el control centralizado de salida en todo el tiempo de ejecución.

​

Configuración

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 de Gateway

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

• gateway-only (predeterminado): OpenClaw registra la autoridad de loopback de Gateway en el controlador NO_PROXY activo de global-agent para que el tráfico WebSocket local de Gateway pueda conectarse directamente. Los puertos personalizados de Gateway en loopback funcionan porque se registran el host y el puerto de la URL activa de Gateway.
• proxy: OpenClaw no registra una autoridad NO_PROXY de loopback de Gateway, por lo que el tráfico local de Gateway se envía a través del proxy gestionado. Si el proxy es remoto, debe proporcionar enrutamiento especial para el servicio de loopback del host de OpenClaw, como asignarlo a un nombre de host, IP o túnel alcanzable por el proxy. Los proxies remotos estándar resuelven 127.0.0.1 y localhost desde el host del proxy, no desde el host de OpenClaw.
• block: OpenClaw deniega las conexiones del plano de control de Gateway por loopback antes de abrir un 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 del proxy

• Escuchar solo en loopback o en una interfaz privada de confianza.
• Restringir el acceso para que solo el proceso, host, contenedor o cuenta de servicio de OpenClaw pueda usarlo.
• Resolver los destinos por sí mismo y bloquear las IP de destino después de la resolución DNS.
• Aplicar la política en tiempo de conexión tanto para solicitudes HTTP simples como para túneles HTTPS CONNECT.
• Rechazar bypasses basados en destino para rangos de loopback, privados, link-local, metadatos, multicast, reservados o de documentación.
• Evitar listas de permitidos de nombres de host salvo que confíes plenamente en la ruta de resolución DNS.
• Registrar destino, decisión, estado y motivo sin registrar cuerpos de solicitud, encabezados de autorización, cookies u otros secretos.
• Mantener la política del proxy bajo control de versiones y revisar los cambios como configuración sensible para la seguridad.

​

Destinos bloqueados recomendados

​

Validación

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

​

Límites

• El proxy mejora la cobertura para clientes HTTP y WebSocket de JavaScript locales al proceso, pero no es un sandbox de red a nivel de sistema operativo.
• El tráfico de plano de control de loopback del Gateway usa de forma predeterminada una omisión local directa mediante proxy.loopbackMode: "gateway-only". OpenClaw implementa esa omisión registrando la autoridad de loopback activa del Gateway en el controlador gestionado global-agent NO_PROXY. Los operadores pueden establecer proxy.loopbackMode: "proxy" para enviar el tráfico de loopback del Gateway a través del proxy gestionado, o proxy.loopbackMode: "block" para denegar conexiones de loopback del Gateway. Consulta Modo de loopback del Gateway para la salvedad del proxy remoto.
• Los sockets net, tls y http2 sin procesar, los complementos nativos y los procesos secundarios que no son de OpenClaw pueden omitir el enrutamiento de proxy a nivel de Node, a menos que hereden y respeten las variables de entorno del proxy. Las CLI secundarias bifurcadas de OpenClaw heredan la URL del proxy gestionado y el estado de proxy.loopbackMode.
• IRC es un canal TCP/TLS sin procesar fuera del enrutamiento por proxy directo gestionado por el operador. En despliegues que requieren toda la salida a través de ese proxy directo, establece channels.irc.enabled=false a menos que la salida directa de IRC esté aprobada explícitamente.
• El proxy de depuración local es una herramienta de diagnóstico, y su reenvío ascendente directo para solicitudes de proxy y túneles CONNECT está deshabilitado de forma predeterminada mientras el modo de proxy gestionado está activo; habilita el reenvío directo solo para diagnósticos locales aprobados.
• Las WebUI locales del usuario y los servidores de modelos locales deben incluirse en la lista de permitidos de la política de proxy del operador cuando sea necesario; OpenClaw no expone una omisión general de red local para ellos.
• La omisión de proxy del plano de control del Gateway se limita intencionalmente a localhost y a URL con IP de loopback literales. Usa ws://127.0.0.1:18789, ws://[::1]:18789 o ws://localhost:18789 para conexiones locales directas del plano de control del Gateway; otros nombres de host se enrutan como tráfico ordinario basado en nombre de host.
• OpenClaw no inspecciona, prueba ni certifica tu política de proxy.
• Trata los cambios de política de proxy como cambios operativos sensibles para la seguridad.