Proxy réseau

Documentation Index

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

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

​

Pourquoi utiliser un proxy

• Politique centralisée : maintenir une seule politique de sortie au lieu de compter sur chaque point d’appel HTTP de l’application pour appliquer correctement les règles réseau.
• Contrôles au moment de la connexion : évaluer la destination après la résolution DNS et immédiatement avant que le proxy n’ouvre la connexion en amont.
• Défense contre le DNS rebinding : réduire l’écart entre une vérification DNS au niveau de l’application et la connexion sortante réelle.
• Couverture JavaScript plus large : router les clients ordinaires fetch, node:http, node:https, WebSocket, axios, got, node-fetch et similaires via le même chemin.
• Auditabilité : journaliser les destinations autorisées et refusées à la frontière de sortie.
• Contrôle opérationnel : appliquer 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 route le trafic

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

• Le routage par dispatcher Undici couvre fetch, les clients basés sur undici et les transports qui fournissent leur propre dispatcher undici.
• Le routage global-agent couvre les appelants Node core node:http et node:https, y compris de nombreuses bibliothèques construites sur http.request, https.request, http.get et https.get. Le mode proxy géré force cet agent global afin que les agents HTTP Node explicites ne contournent pas accidentellement le proxy de l’opérateur.

​

Termes de proxy associés

• proxy.enabled / proxy.proxyUrl : routage par proxy direct sortant pour la sortie d’exécution OpenClaw. Cette page documente cette fonctionnalité.
• gateway.auth.mode: "trusted-proxy" : authentification de proxy inverse entrante, consciente de 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 d’environnement HTTP(S) 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 Web fetch.
• Paramètres de proxy propres à un canal ou à un fournisseur : remplacements propres au propriétaire pour un transport particulier. Préférez le proxy réseau géré lorsque l’objectif est un contrôle centralisé de la sortie sur toute l’exécution.

​

Configuration

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

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

​

Mode de bouclage du Gateway

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é de bouclage du Gateway dans le contrôleur NO_PROXY global-agent actif afin que le trafic WebSocket local du Gateway puisse se connecter directement. Les ports de Gateway de bouclage personnalisés fonctionnent parce que l’hôte et le port de l’URL du Gateway actif sont enregistrés.
• proxy : OpenClaw n’enregistre pas d’autorité NO_PROXY de bouclage du Gateway, donc le trafic local du Gateway est envoyé via le proxy géré. Si le proxy est distant, il doit fournir un routage spécial vers le service de bouclage de l’hôte OpenClaw, par exemple en le mappant vers 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 de plan de contrôle de Gateway en bouclage 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 bouclage 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 puissent l’utiliser.
• Résoudre lui-même les destinations et bloquer les IP de destination après la résolution DNS.
• Appliquer la politique au moment de la connexion pour les requêtes HTTP simples comme pour les tunnels HTTPS CONNECT.
• Refuser les contournements basés sur la destination pour les plages de bouclage, privées, link-local, de métadonnées, de multidiffusion, réservées ou de documentation.
• Éviter les listes d’autorisation de noms d’hôte, sauf si vous faites entièrement confiance au chemin de résolution DNS.
• Journaliser la destination, la décision, l’état et le motif sans journaliser les corps de requête, les en-têtes d’autorisation, les cookies ou d’autres secrets.
• Garder la politique de proxy sous contrôle de version et examiner les changements comme une configuration sensible à la sécurité.

​

Destinations bloquées recommandées

​

Validation

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

• 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 loopback du plan de contrôle du Gateway utilise par défaut un contournement local direct via proxy.loopbackMode: "gateway-only". OpenClaw met en œuvre ce contournement en enregistrant l’autorité loopback du Gateway actif dans le contrôleur NO_PROXY global-agent géré. 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 liée au proxy distant.
• Les sockets brutes net, tls et http2, les modules natifs et les processus enfants non OpenClaw peuvent contourner le routage proxy au niveau de Node, sauf s’ils héritent des variables d’environnement du proxy et les respectent. Les CLI enfants OpenClaw issus d’un fork héritent de l’URL du proxy géré et de l’état proxy.loopbackMode.
• IRC est un canal TCP/TLS brut situé hors du routage de 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 ; n’activez le transfert direct que pour des diagnostics locaux approuvés.
• Les WebUI locales utilisateur et les serveurs de modèles locaux doivent être ajoutés à la liste d’autorisation dans la politique proxy de l’opérateur lorsque nécessaire ; OpenClaw n’expose pas de contournement général du réseau local pour eux.
• Le contournement proxy du plan de contrôle du Gateway est intentionnellement limité à localhost et aux URL 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 du Gateway ; les autres noms d’hôte sont routés comme du trafic ordinaire basé sur un nom d’hôte.
• OpenClaw n’inspecte pas, ne teste pas et ne certifie pas votre politique proxy.
• Traitez les modifications de politique proxy comme des modifications opérationnelles sensibles à la sécurité.