Proxy réseau

OpenClaw peut acheminer le trafic HTTP et WebSocket d’exécution via un proxy direct géré par l’opérateur. Il s’agit d’une défense en profondeur facultative : contrôle centralisé du trafic sortant, protection renforcée contre les SSRF et auditabilité des destinations à la frontière du réseau. Comme le proxy évalue la destination au moment de la connexion, après la résolution DNS et juste avant d’ouvrir la connexion en amont, il réduit également l’intervalle exploité par une attaque de réassociation DNS entre une vérification DNS antérieure au niveau de l’application et la connexion sortante effective. Une politique de proxy unique offre également aux opérateurs un point central pour appliquer des règles de destination, la segmentation du réseau, des limites de débit ou des listes d’autorisation de trafic sortant sans reconstruire OpenClaw.

OpenClaw ne fournit, ne télécharge, ne démarre, ne configure ni ne certifie aucun proxy. Vous exécutez la technologie de proxy adaptée à votre environnement ; OpenClaw y achemine ses propres clients HTTP et WebSocket.

Configuration

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

Vous pouvez également définir l’URL par l’intermédiaire de l’environnement tant que proxy.enabled: true reste dans la configuration :

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

proxy.proxyUrl prévaut sur OPENCLAW_PROXY_URL. Si proxy.enabled vaut true, mais qu’aucune URL valide n’est résolue, les commandes protégées échouent au démarrage au lieu de revenir à un accès réseau direct.

Pour les services Gateway gérés, stockez l’URL dans la configuration afin qu’elle soit conservée après une réinstallation, plutôt que de dépendre de l’environnement d’un processus au premier plan :

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

Le recours à la variable d’environnement OPENCLAW_PROXY_URL convient surtout aux exécutions au premier plan. Pour l’utiliser avec un service installé, placez-la dans l’environnement persistant du service ($OPENCLAW_STATE_DIR/.env, par défaut ~/.openclaw/.env), puis réinstallez le service afin que launchd, systemd ou Scheduled Tasks la prenne en compte.

Point de terminaison de proxy HTTPS avec une AC privée

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

proxy.tls.caFile vérifie le propre certificat TLS du point de terminaison du proxy. Il ne s’agit ni d’un paramètre d’approbation d’interception de la destination, ni d’un certificat client, ni d’un substitut à la politique de destination du proxy. Utilisez plutôt NODE_EXTRA_CA_CERTS uniquement lorsque l’ensemble du processus Node doit approuver une AC supplémentaire dès son démarrage, par exemple lorsqu’un système d’inspection TLS d’entreprise signe de nouveau chaque certificat de destination HTTPS. Cette variable s’applique à l’ensemble du processus et doit être définie avant le démarrage de Node ; OpenClaw ne peut donc pas l’appliquer en cours d’exécution comme il le fait pour proxy.tls.caFile. Préférez proxy.tls.caFile pour établir la confiance envers le point de terminaison d’un proxy HTTPS : sa portée se limite au routage par proxy géré au lieu de s’étendre à l’ensemble du processus.

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

Fonctionnement du routage

Lorsque proxy.enabled: true est défini avec une URL valide, les processus d’exécution protégés (openclaw gateway run, openclaw node run, openclaw agent --local) acheminent le trafic sortant HTTP et WebSocket ordinaire via le proxy :

Processus OpenClaw  fetch, node:http, node:https, clients WebSocket  -> proxy de l’opérateur -> destination

En interne, OpenClaw installe Proxyline comme environnement d’exécution de routage au niveau du processus. Il prend en charge fetch, les clients reposant sur undici, node:http/node:https, les clients WebSocket courants et les tunnels CONNECT créés par des fonctions auxiliaires. Il remplace également les agents HTTP Node fournis par l’appelant afin que les agents explicites, notamment axios, got, node-fetch et les clients similaires reposant sur des agents Node, ne puissent pas contourner silencieusement le proxy.

Le schéma de l’URL du proxy décrit le saut entre OpenClaw et le proxy, et non celui vers la destination finale :

• http://proxy.example:3128 — connexion TCP non chiffrée au proxy ; OpenClaw envoie des requêtes de proxy HTTP, notamment CONNECT pour les destinations HTTPS.
• https://proxy.example:8443 — OpenClaw établit une connexion TLS avec le proxy lui-même, en vérifiant son certificat, puis envoie les requêtes de proxy HTTP dans cette session.

Le protocole TLS de la destination est indépendant de celui du point de terminaison du proxy : pour une destination HTTPS, OpenClaw demande toujours au proxy un tunnel CONNECT et établit la connexion TLS avec la destination dans ce tunnel.

Lorsque le proxy est actif, OpenClaw efface no_proxy/NO_PROXY. Ces listes de contournement reposent sur la destination ; y laisser localhost ou 127.0.0.1 permettrait aux cibles SSRF de contourner entièrement le proxy. Lors de l’arrêt, OpenClaw restaure l’environnement de proxy précédent et réinitialise l’état de routage mis en cache.

Certains plugins possèdent un transport personnalisé qui nécessite sa propre configuration de proxy, même lorsque le routage au niveau du processus est actif. Le client de l’API Bot de Telegram utilise son propre répartiteur HTTP/1 undici et respecte séparément les variables d’environnement de proxy du processus ainsi que le recours à OPENCLAW_PROXY_URL.

Mode de bouclage du Gateway

Les clients locaux du plan de contrôle du Gateway se connectent normalement à un WebSocket sur l’interface de bouclage, tel que ws://127.0.0.1:18789. proxy.loopbackMode détermine si ce trafic contourne le proxy géré :

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

Le contournement du plan de contrôle du Gateway est limité à localhost et aux URL contenant des adresses IP de bouclage littérales : utilisez ws://127.0.0.1:18789, ws://[::1]:18789 ou ws://localhost:18789. Les autres noms d’hôte sont acheminés comme du trafic ordinaire.

Conteneurs

Pour les commandes openclaw --container ..., OpenClaw transmet OPENCLAW_PROXY_URL à la CLI enfant ciblant le conteneur lorsque cette variable est définie. L’URL doit être accessible depuis l’intérieur du conteneur ; 127.0.0.1 y désigne le conteneur lui-même, et non l’hôte. OpenClaw refuse les URL de proxy en bouclage pour les commandes ciblant un conteneur, sauf si vous définissez OPENCLAW_CONTAINER_ALLOW_LOOPBACK_PROXY_URL=1 afin de contourner explicitement cette vérification.

Termes associés aux proxys

• proxy.enabled / proxy.proxyUrl — routage par proxy direct sortant pour le trafic d’exécution. Page actuelle.
• gateway.auth.mode: "trusted-proxy" — authentification entrante par proxy inverse tenant compte de l’identité pour accéder au Gateway. Consultez Authentification par proxy de confiance.
• openclaw proxy — proxy de débogage local et inspecteur de capture pour le développement et l’assistance. Consultez openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy — option permettant à web_fetch de laisser un proxy d’environnement HTTP(S) contrôlé par l’opérateur effectuer la résolution DNS, tout en conservant par défaut un épinglage DNS strict et une politique de noms d’hôte. Consultez Récupération Web.
• Paramètres de proxy propres à un canal ou à un fournisseur — remplacements spécifiques au propriétaire pour un transport donné. Préférez le proxy réseau géré pour contrôler centralement le trafic sortant dans tout l’environnement d’exécution.

Validation du proxy

La politique de destination du proxy constitue la véritable frontière de sécurité ; OpenClaw ne peut pas vérifier que votre proxy bloque les bonnes cibles. Configurez-le pour :

• N’écouter que sur l’interface de bouclage ou sur une interface privée de confiance, accessible uniquement par le processus, l’hôte, le conteneur ou le compte de service OpenClaw.
• Résoudre lui-même les destinations et les bloquer selon leur adresse IP après la résolution DNS, au moment de la connexion, pour le trafic HTTP non chiffré comme pour les tunnels HTTPS CONNECT.
• Refuser les contournements fondés sur la destination pour les plages de bouclage, privées, lien-local, de métadonnées, de multidiffusion, réservées et 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 la raison, mais jamais le corps des requêtes, les en-têtes d’autorisation, les cookies ni d’autres secrets.
• Conserver la politique sous contrôle de version et examiner ses modifications comme des changements sensibles pour la sécurité.

Effectuez la validation depuis le même hôte, conteneur ou compte de service qui exécute OpenClaw :

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

Avec un point de terminaison de proxy HTTPS utilisant une AC privée :

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

Si proxy.enabled n’est pas défini sur true et qu’aucune option --proxy-url n’est fournie, la commande signale un problème de configuration au lieu d’effectuer la validation ; transmettez --proxy-url pour une vérification préalable ponctuelle avant de modifier la configuration.

Sans --allowed-url/--denied-url, les vérifications par défaut sont les suivantes : https://example.com/ doit être accessible, et un serveur sentinelle temporaire en local loopback, que le proxy ne doit pas pouvoir atteindre, doit être bloqué. La vérification du local loopback réussit en cas d’échec de transport ou de réponse non-2xx ne contenant pas le jeton propre à l’exécution de la sentinelle ; elle échoue en cas de réponse 2xx sans le jeton (réussite inattendue provenant d’un autre élément que la sentinelle) et, en particulier, en cas de réponse contenant le jeton correspondant, car cela prouve que le proxy a effectivement transmis une destination en local loopback qu’il aurait dû refuser. Les cibles --denied-url personnalisées ne disposent pas d’un tel jeton sentinelle et appliquent donc une stratégie de refus par défaut : toute réponse HTTP signifie que la cible est accessible (échec), et une erreur de transport est signalée comme non concluante plutôt que comme un blocage avéré, car OpenClaw ne peut pas confirmer si votre proxy a refusé une origine accessible ou si un autre problème est survenu. --apns-reachable envoie intentionnellement un jeton de fournisseur non valide ; une réponse 403 InvalidProviderToken prouve donc que le tunnel a atteint Apple. La commande se termine avec le code 1 en cas d’échec de validation ; les identifiants présents dans l’URL du proxy sont masqués dans les sorties texte et 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 }  ]}

Vérification manuelle avec curl (la requête publique doit réussir ; les requêtes vers le local loopback et les métadonnées doivent être bloquées par le proxy lui-même — curl seul ne peut pas distinguer un refus du proxy d’une origine inaccessible comme le peut la sentinelle intégrée d’openclaw proxy validate) :

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/

Destinations qu’il est recommandé de bloquer

Liste de refus initiale pour tout proxy direct, pare-feu ou toute politique de trafic sortant. Le classificateur SSRF d’OpenClaw se trouve dans src/infra/net/ssrf.ts et packages/net-policy/src/ip.ts (BLOCKED_HOSTNAMES, BLOCKED_IPV4_SPECIAL_USE_RANGES, BLOCKED_IPV6_SPECIAL_USE_RANGES, le préfixe de test de performance RFC 2544 et la gestion de l’IPv4 incorporée pour les formes NAT64/6to4/Teredo/ISATAP/IPv4 mappées) — ce sont des références utiles, mais OpenClaw n’exporte ni n’applique ces règles dans votre proxy externe.

Ajoutez tous les hôtes de métadonnées ou toutes les plages réservées supplémentaires documentés par votre fournisseur de cloud ou votre plateforme réseau.

Limites

• Cette couverture s’applique au niveau du processus pour les clients HTTP/WebSocket JavaScript ; il ne s’agit pas d’un bac à sable réseau au niveau du système d’exploitation.
• Les sockets net, tls et http2 bruts, les modules complémentaires natifs et les processus enfants ne provenant pas d’OpenClaw peuvent contourner le routage au niveau de Node, sauf s’ils héritent des variables d’environnement du proxy et les respectent. Les CLI enfants d’OpenClaw créées par duplication de processus héritent de l’URL du proxy géré et de l’état proxy.loopbackMode.
• Les interfaces Web locales de l’utilisateur et les serveurs de modèles locaux ne bénéficient pas d’un contournement général du réseau local — ajoutez-les à la liste d’autorisation de la politique de proxy de l’opérateur si nécessaire. L’exception est le chemin direct protégé du fournisseur intégré d’incorporations de mémoire Ollama, limité à l’origine exacte en local loopback de l’hôte définie dans son baseUrl configuré ; les hôtes Ollama du réseau local, du réseau Tailscale, des réseaux privés et publics utilisent toujours le proxy géré.
• Le transfert amont direct du proxy de débogage local (pour les requêtes de proxy et les tunnels CONNECT) est désactivé par défaut lorsque le mode proxy géré est actif ; ne l’activez que pour des diagnostics locaux approuvés.
• OpenClaw n’inspecte, ne teste ni ne certifie votre politique de proxy. Traitez les modifications de cette politique comme des changements opérationnels sensibles sur le plan de la sécurité.