Proxy réseau

​

Pourquoi utiliser un proxy

• Politique centrale : maintenez une seule politique de sortie réseau au lieu de compter sur chaque point d’appel HTTP d’application pour appliquer correctement les règles réseau.
• Vérifications au moment de la connexion : évaluez la destination après la résolution DNS et immédiatement avant que le proxy ouvre la connexion amont.
• Défense contre le DNS rebinding : réduisez l’écart entre une vérification DNS au niveau de l’application et la connexion sortante réelle.
• Couverture JavaScript plus large : acheminez les clients ordinaires fetch, node:http, node:https, WebSocket, axios, got, node-fetch et similaires par le même chemin.
• Auditabilité : journalisez les destinations autorisées et refusées à la frontière de sortie.
• Contrôle opérationnel : appliquez des règles de destination, une segmentation réseau, des limites de débit ou des listes d’autorisation sortantes sans reconstruire OpenClaw.

​

Comment OpenClaw achemine le trafic

Processus OpenClaw
  fetch                  -> proxy de filtrage géré par l’opérateur -> Internet public
  node:http et https     -> proxy de filtrage géré par l’opérateur -> Internet public
  clients WebSocket      -> proxy de filtrage géré par l’opérateur -> Internet public

• http://proxy.example:3128 : OpenClaw ouvre une connexion TCP en clair vers le proxy direct et envoie des requêtes de proxy HTTP, y compris CONNECT pour les destinations HTTPS.
• https://proxy.example:8443 : OpenClaw ouvre une connexion TLS vers le point de terminaison du proxy, vérifie le certificat du proxy, puis envoie des requêtes de proxy HTTP à l’intérieur de cette session TLS.

​

Termes associés au proxy

• proxy.enabled / proxy.proxyUrl : routage sortant via proxy direct pour les sorties d’exécution OpenClaw. Cette page documente cette fonctionnalité.
• gateway.auth.mode: "trusted-proxy" : authentification entrante par proxy inverse sensible à l’identité pour l’accès au Gateway. Consultez Authentification par proxy de confiance.
• openclaw proxy : proxy de débogage local et inspecteur de capture pour le développement et le support. Consultez openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy : option d’activation pour web_fetch permettant à un proxy HTTP(S) d’environnement contrôlé par l’opérateur de résoudre le DNS tout en conservant par défaut l’épinglage DNS strict et la politique de nom d’hôte. Consultez Récupération Web.
• Paramètres de proxy propres à un canal ou fournisseur : remplacements propres au propriétaire pour un transport particulier. Préférez le proxy réseau géré lorsque l’objectif est le contrôle centralisé des sorties réseau sur l’ensemble du runtime.

​

Configuration

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

proxy:
  enabled: true
  proxyUrl: https://proxy.corp.example:8443
  tls:
    caFile: /etc/openclaw/proxy-ca.pem

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

​

Mode Gateway Loopback

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

• gateway-only (par défaut) : OpenClaw enregistre l’autorité loopback du Gateway dans la politique de contournement gérée de Proxyline afin que le trafic WebSocket local du Gateway puisse se connecter directement. Les ports Gateway loopback personnalisés fonctionnent parce que l’hôte et le port de l’URL Gateway active sont enregistrés. Le plugin de navigateur intégré peut aussi enregistrer les points de terminaison exacts locaux de disponibilité CDP et WebSocket DevTools pour les navigateurs gérés lancés par OpenClaw, et le fournisseur intégré d’embeddings mémoire Ollama peut utiliser son propre chemin direct gardé, plus étroit, pour l’origine exacte d’embedding loopback locale à l’hôte configurée.
• proxy : OpenClaw n’enregistre pas de contournements loopback Gateway ou Ollama ; ce trafic loopback est donc envoyé via le proxy géré. Si le proxy est distant, il doit fournir un routage spécial vers le service loopback de l’hôte OpenClaw, par exemple en le mappant à un nom d’hôte, une IP ou un tunnel joignable par le proxy. Les proxys distants standard résolvent 127.0.0.1 et localhost depuis l’hôte du proxy, pas depuis l’hôte OpenClaw.
• block : OpenClaw refuse les connexions du plan de contrôle Gateway en loopback et les connexions d’embedding Ollama en loopback locale à l’hôte gardées avant d’ouvrir 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

​

Exigences du proxy

• Se lier uniquement au loopback ou à une interface privée de confiance.
• Restreindre l’accès afin que seuls le processus, l’hôte, le conteneur ou le compte de service OpenClaw puisse l’utiliser.
• Résoudre lui-même les destinations et bloquer les IP de destination après résolution DNS.
• Appliquer la politique au moment de la connexion pour les requêtes HTTP en clair comme pour les tunnels HTTPS CONNECT.
• Refuser les contournements basés sur la destination pour les plages loopback, privées, link-local, metadata, multicast, réservées ou de documentation.
• Éviter les listes d’autorisation de noms d’hôtes sauf si vous faites entièrement confiance au chemin de résolution DNS.
• Journaliser la destination, la décision, l’état et la raison sans journaliser les corps de requête, les en-têtes d’autorisation, les cookies ou d’autres secrets.
• Garder la politique du proxy sous contrôle de version et examiner les changements comme une configuration sensible pour la sécurité.

​

Destinations bloquées recommandées

​

Validation

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

openclaw proxy validate --proxy-url https://proxy.corp.example:8443 --proxy-ca-file /etc/openclaw/proxy-ca.pem

{
  "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/

​

Confiance dans l’AC du proxy

proxy:
  enabled: true
  proxyUrl: https://proxy.corp.example:8443
  tls:
    caFile: /etc/openclaw/proxy-ca.pem

openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl https://proxy.corp.example:8443
openclaw config set proxy.tls.caFile /etc/openclaw/proxy-ca.pem
openclaw gateway run

proxy:
  enabled: true
  proxyUrl: https://proxy.corp.example:8443
  tls:
    caFile: /etc/openclaw/proxy-ca.pem

​

Limites

• Le proxy améliore la couverture pour les clients HTTP JavaScript et WebSocket locaux au processus, mais ce n’est pas un bac à sable réseau au niveau du système d’exploitation.
• Le trafic de plan de contrôle loopback du Gateway utilise par défaut un contournement local direct via proxy.loopbackMode: "gateway-only". OpenClaw implémente ce contournement en enregistrant l’autorité loopback active du Gateway dans la politique de contournement gérée de Proxyline. Les opérateurs peuvent définir proxy.loopbackMode: "proxy" pour envoyer le trafic loopback du Gateway via le proxy géré, ou proxy.loopbackMode: "block" pour refuser les connexions loopback du Gateway. Consultez Mode loopback du Gateway pour la mise en garde concernant les proxys distants.
• Les sockets bruts net, tls et http2, les modules natifs et les processus enfants non OpenClaw peuvent contourner le routage par proxy au niveau de Node, sauf s’ils héritent des variables d’environnement de proxy et les respectent. Les CLI enfants OpenClaw forkés héritent de l’URL du proxy géré et de l’état proxy.loopbackMode.
• IRC est un canal TCP/TLS brut en dehors du routage par proxy direct géré par l’opérateur. Dans les déploiements qui exigent que toute sortie passe par ce proxy direct, définissez channels.irc.enabled=false, sauf si la sortie IRC directe est explicitement approuvée.
• Le proxy de débogage local est un outil de diagnostic, et son transfert amont direct pour les requêtes proxy et les tunnels CONNECT est désactivé par défaut lorsque le mode proxy géré est actif ; activez le transfert direct uniquement pour les diagnostics locaux approuvés.
• Les interfaces Web locales utilisateur et les serveurs de modèles locaux doivent être ajoutés à la liste d’autorisation dans la politique de proxy de l’opérateur si nécessaire ; OpenClaw n’expose pas de contournement général du réseau local pour eux. Le fournisseur groupé d’embeddings mémoire Ollama est plus limité : il peut utiliser un chemin direct protégé uniquement pour l’origine exacte d’embedding loopback locale à l’hôte dérivée du baseUrl configuré, afin que les embeddings locaux à l’hôte continuent de fonctionner lorsque le proxy géré ne peut pas atteindre le loopback de l’hôte. Les hôtes d’embedding Ollama sur LAN, tailnet, réseau privé et publics utilisent toujours le chemin du proxy géré. proxy.loopbackMode: "proxy" envoie ce trafic loopback Ollama via le proxy géré, et proxy.loopbackMode: "block" le refuse avant d’ouvrir une connexion.
• Le contournement du proxy du plan de contrôle Gateway est intentionnellement limité à localhost et aux URL d’IP loopback littérales. Utilisez ws://127.0.0.1:18789, ws://[::1]:18789 ou ws://localhost:18789 pour les connexions locales directes au plan de contrôle Gateway ; les autres noms d’hôte sont routés comme le trafic ordinaire basé sur un nom d’hôte.
• OpenClaw n’inspecte pas, ne teste pas et ne certifie pas votre politique de proxy.
• Traitez les changements de politique de proxy comme des changements opérationnels sensibles pour la sécurité.