​

Navigateur (géré par openclaw)

• Considérez-le comme un navigateur séparé, réservé à l’agent.
• Le profil openclaw ne touche pas à votre profil de navigateur personnel.
• L’agent peut ouvrir des onglets, lire des pages, cliquer et saisir dans un environnement sûr.
• Le profil intégré user se connecte à votre véritable session Chrome connectée via Chrome MCP.

​

Ce que vous obtenez

• Un profil de navigateur séparé nommé openclaw (accent orange par défaut).
• Contrôle déterministe des onglets (lister/ouvrir/focaliser/fermer).
• Actions de l’agent (cliquer/saisir/faire glisser/sélectionner), snapshots, captures d’écran, PDF.
• Prise en charge facultative de plusieurs profils (openclaw, work, remote, …).

​

Démarrage rapide

openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

​

Contrôle du plugin

{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

• plugins.entries.browser.enabled non désactivé
• browser.enabled=true

​

Commande ou outil de navigateur manquant

{
  plugins: {
    allow: ["telegram"],
  },
}

{
  plugins: {
    allow: ["telegram", "browser"],
  },
}

• browser.enabled=true ne suffit pas à lui seul lorsque plugins.allow est défini.
• plugins.entries.browser.enabled=true ne suffit pas non plus à lui seul lorsque plugins.allow est défini.
• tools.alsoAllow: ["browser"] ne charge pas le plugin de navigateur intégré. Cela ajuste seulement la politique des outils une fois le plugin déjà chargé.
• Si vous n’avez pas besoin d’une liste d’autorisation restrictive pour les plugins, supprimer plugins.allow rétablit aussi le comportement par défaut du navigateur intégré.

• openclaw browser est une commande inconnue.
• browser.request est manquant.
• L’agent signale que l’outil de navigateur est indisponible ou manquant.

​

Profils : openclaw vs user

• openclaw : navigateur géré et isolé (aucune extension requise).
• user : profil intégré de connexion Chrome MCP à votre véritable Chrome connecté session.

• Par défaut : utilisez le navigateur isolé openclaw.
• Préférez profile="user" lorsque les sessions déjà connectées comptent et que l’utilisateur est devant l’ordinateur pour cliquer/approuver toute invite de connexion.
• profile est la surcharge explicite lorsque vous voulez un mode de navigateur spécifique.

​

Configuration

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // default trusted-network mode
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    defaultProfile: "openclaw",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

• Le service de contrôle du navigateur se lie au loopback sur un port dérivé de gateway.port (par défaut : 18791, soit gateway + 2).
• Si vous surchargez le port du Gateway (gateway.port ou OPENCLAW_GATEWAY_PORT), les ports de navigateur dérivés se décalent pour rester dans la même « famille ».
• cdpUrl utilise par défaut le port CDP local géré lorsqu’il n’est pas défini.
• remoteCdpTimeoutMs s’applique aux vérifications d’accessibilité CDP distantes (non loopback).
• remoteCdpHandshakeTimeoutMs s’applique aux vérifications d’accessibilité de handshake WebSocket CDP distantes.
• La navigation/l’ouverture d’onglet du navigateur est protégée contre la SSRF avant la navigation et revérifiée au mieux sur l’URL finale http(s) après la navigation.
• En mode SSRF strict, la découverte/les sondes de point de terminaison CDP distant (cdpUrl, y compris les recherches /json/version) sont également vérifiées.
• browser.ssrfPolicy.dangerouslyAllowPrivateNetwork vaut true par défaut (modèle de réseau de confiance). Définissez-le sur false pour une navigation stricte sur l’Internet public uniquement.
• browser.ssrfPolicy.allowPrivateNetwork reste pris en charge comme alias hérité pour compatibilité.
• attachOnly: true signifie « ne jamais lancer un navigateur local ; s’y attacher uniquement s’il est déjà en cours d’exécution ».
• color + color par profil teintent l’interface du navigateur afin que vous puissiez voir quel profil est actif.
• Le profil par défaut est openclaw (navigateur autonome géré par OpenClaw). Utilisez defaultProfile: "user" pour opter pour le navigateur connecté de l’utilisateur.
• Ordre de détection automatique : navigateur système par défaut s’il est basé sur Chromium ; sinon Chrome → Brave → Edge → Chromium → Chrome Canary.
• Les profils locaux openclaw attribuent automatiquement cdpPort/cdpUrl — définissez-les uniquement pour le CDP distant.
• driver: "existing-session" utilise Chrome DevTools MCP au lieu du CDP brut. Ne définissez pas cdpUrl pour ce driver.
• Définissez browser.profiles.<name>.userDataDir lorsqu’un profil existing-session doit se connecter à un profil utilisateur Chromium non par défaut tel que Brave ou Edge.

​

Utiliser Brave (ou un autre navigateur basé sur Chromium)

openclaw config set browser.executablePath "/usr/bin/google-chrome"

// macOS
{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
  }
}

// Windows
{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
  }
}

// Linux
{
  browser: {
    executablePath: "/usr/bin/brave-browser"
  }
}

​

Contrôle local vs distant

• Contrôle local (par défaut) : le Gateway démarre le service de contrôle loopback et peut lancer un navigateur local.
• Contrôle distant (hôte de nœud) : exécutez un hôte de nœud sur la machine qui possède le navigateur ; le Gateway y proxifie les actions du navigateur.
• CDP distant : définissez browser.profiles.<name>.cdpUrl (ou browser.cdpUrl) pour vous connecter à un navigateur distant basé sur Chromium. Dans ce cas, OpenClaw ne lancera pas de navigateur local.

• profils locaux gérés : openclaw browser stop arrête le processus du navigateur que OpenClaw a lancé
• profils attach-only et CDP distant : openclaw browser stop ferme la session de contrôle active et libère les surcharges d’émulation Playwright/CDP (viewport, schéma de couleurs, langue, fuseau horaire, mode hors ligne et état similaire), même si aucun processus de navigateur n’a été lancé par OpenClaw

• Jetons de requête (par ex. https://provider.example?token=<token>)
• Authentification HTTP Basic (par ex. https://user:pass@provider.example)

​

Proxy de navigateur de nœud (zéro configuration par défaut)

• L’hôte de nœud expose son serveur local de contrôle du navigateur via une commande proxy.
• Les profils proviennent de la propre configuration browser.profiles du nœud (identique au local).
• nodeHost.browserProxy.allowProfiles est facultatif. Laissez-le vide pour le comportement hérité/par défaut : tous les profils configurés restent accessibles via le proxy, y compris les routes de création/suppression de profils.
• Si vous définissez nodeHost.browserProxy.allowProfiles, OpenClaw le traite comme une limite de moindre privilège : seuls les profils de la liste d’autorisation peuvent être ciblés, et les routes persistantes de création/suppression de profils sont bloquées sur la surface proxy.
• Désactivez-le si vous n’en voulez pas :
  • Sur le nœud : nodeHost.browserProxy.enabled=false
  • Sur le gateway : gateway.nodes.browser.mode="off"

​

Browserless (CDP distant hébergé)

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

• Remplacez <BROWSERLESS_API_KEY> par votre véritable jeton Browserless.
• Choisissez le point de terminaison régional correspondant à votre compte Browserless (voir leur documentation).
• Si Browserless vous fournit une URL de base HTTPS, vous pouvez soit la convertir en wss:// pour une connexion CDP directe, soit conserver l’URL HTTPS et laisser OpenClaw découvrir /json/version.

​

Providers CDP WebSocket directs

• Points de terminaison HTTP(S) — OpenClaw appelle /json/version pour découvrir l’URL du débogueur WebSocket, puis s’y connecte.
• Points de terminaison WebSocket (ws:// / wss://) — OpenClaw s’y connecte directement, en ignorant /json/version. Utilisez cela pour des services comme Browserless, Browserbase, ou tout provider qui vous fournit une URL WebSocket.

​

Browserbase

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

• Inscrivez-vous et copiez votre clé API depuis le tableau de bord Overview.
• Remplacez <BROWSERBASE_API_KEY> par votre véritable clé API Browserbase.
• Browserbase crée automatiquement une session de navigateur à la connexion WebSocket, donc aucune étape manuelle de création de session n’est nécessaire.
• Le niveau gratuit autorise une session simultanée et une heure de navigateur par mois. Consultez les tarifs pour les limites des forfaits payants.
• Consultez la documentation Browserbase pour la référence API complète, les guides SDK et les exemples d’intégration.

​

Sécurité

• Le contrôle du navigateur est limité au loopback ; l’accès passe par l’authentification du Gateway ou l’appairage de nœud.
• L’API HTTP autonome de navigateur en loopback utilise uniquement une authentification à secret partagé : authentification bearer par jeton gateway, x-openclaw-password, ou authentification HTTP Basic avec le mot de passe gateway configuré.
• Les en-têtes d’identité Tailscale Serve et gateway.auth.mode: "trusted-proxy" n’authentifient pas cette API autonome de navigateur en loopback.
• Si le contrôle du navigateur est activé et qu’aucune authentification à secret partagé n’est configurée, OpenClaw génère automatiquement gateway.auth.token au démarrage et le persiste dans la configuration.
• OpenClaw ne génère pas automatiquement ce jeton lorsque gateway.auth.mode vaut déjà password, none ou trusted-proxy.
• Conservez le Gateway et tous les hôtes de nœud sur un réseau privé (Tailscale) ; évitez toute exposition publique.
• Traitez les URL/jetons CDP distants comme des secrets ; préférez les variables d’environnement ou un gestionnaire de secrets.

• Préférez des points de terminaison chiffrés (HTTPS ou WSS) et des jetons de courte durée de vie lorsque c’est possible.
• Évitez d’intégrer directement des jetons de longue durée dans les fichiers de configuration.

​

Profils (multi-navigateurs)

• gérés par openclaw : une instance dédiée de navigateur basé sur Chromium avec son propre répertoire de données utilisateur + port CDP
• distant : une URL CDP explicite (navigateur basé sur Chromium exécuté ailleurs)
• session existante : votre profil Chrome existant via auto-connexion Chrome DevTools MCP

• Le profil openclaw est créé automatiquement s’il est absent.
• Le profil user est intégré pour la connexion existing-session via Chrome MCP.
• Les profils existing-session sont opt-in au-delà de user ; créez-les avec --driver existing-session.
• Les ports CDP locaux sont alloués dans la plage 18800–18899 par défaut.
• Supprimer un profil déplace son répertoire de données local vers la corbeille.

​

Existing-session via Chrome DevTools MCP

• Chrome for Developers: Use Chrome DevTools MCP with your browser session
• Chrome DevTools MCP README

• user

• Le profil intégré user utilise l’auto-connexion Chrome MCP, qui cible le profil local Google Chrome par défaut.

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

1. Ouvrez la page d’inspection de ce navigateur pour le débogage à distance.
2. Activez le débogage à distance.
3. Laissez le navigateur ouvert et approuvez l’invite de connexion quand OpenClaw s’y attache.

• Chrome : chrome://inspect/#remote-debugging
• Brave : brave://inspect/#remote-debugging
• Edge : edge://inspect/#remote-debugging

openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai

• status affiche driver: existing-session
• status affiche transport: chrome-mcp
• status affiche running: true
• tabs liste les onglets déjà ouverts dans votre navigateur
• snapshot renvoie des refs à partir de l’onglet actif sélectionné

• le navigateur cible basé sur Chromium est en version 144+
• le débogage à distance est activé dans la page d’inspection de ce navigateur
• le navigateur a affiché l’invite de consentement à la connexion et vous l’avez acceptée
• openclaw doctor migre l’ancienne configuration de navigateur basée sur extension et vérifie que Chrome est installé localement pour les profils d’auto-connexion par défaut, mais il ne peut pas activer pour vous le débogage à distance côté navigateur

• Utilisez profile="user" lorsque vous avez besoin de l’état du navigateur connecté de l’utilisateur.
• Si vous utilisez un profil existing-session personnalisé, passez ce nom de profil explicite.
• Choisissez ce mode uniquement lorsque l’utilisateur est devant l’ordinateur pour approuver l’invite de connexion.
• le Gateway ou l’hôte de nœud peut lancer npx chrome-devtools-mcp@latest --autoConnect

• Cette voie est plus risquée que le profil isolé openclaw car elle peut agir dans votre session de navigateur connectée.
• OpenClaw ne lance pas le navigateur pour ce driver ; il se connecte uniquement à une session existante.
• OpenClaw utilise ici le flux officiel --autoConnect de Chrome DevTools MCP. Si userDataDir est défini, OpenClaw le transmet pour cibler ce répertoire explicite de données utilisateur Chromium.
• Les captures d’écran existing-session prennent en charge les captures de page et les captures d’élément --ref à partir des snapshots, mais pas les sélecteurs CSS --element.
• Les captures d’écran de page existing-session fonctionnent sans Playwright via Chrome MCP. Les captures d’élément basées sur des refs (--ref) y fonctionnent aussi, mais --full-page ne peut pas être combiné avec --ref ou --element.
• Les actions existing-session restent plus limitées que la voie du navigateur géré :
  • click, type, hover, scrollIntoView, drag et select nécessitent des refs de snapshot au lieu de sélecteurs CSS
  • click est limité au bouton gauche (pas de surcharge de bouton ni de modificateurs)
  • type ne prend pas en charge slowly=true ; utilisez fill ou press
  • press ne prend pas en charge delayMs
  • hover, scrollIntoView, drag, select, fill et evaluate ne prennent pas en charge les surcharges de délai d’attente par appel
  • select ne prend actuellement en charge qu’une seule valeur
• wait --url en existing-session prend en charge les motifs exacts, de sous-chaîne et glob comme les autres drivers de navigateur. wait --load networkidle n’est pas encore pris en charge.
• Les hooks d’upload existing-session nécessitent ref ou inputRef, prennent en charge un seul fichier à la fois, et ne prennent pas en charge le ciblage CSS element.
• Les hooks de boîte de dialogue existing-session ne prennent pas en charge les surcharges de délai d’attente.
• Certaines fonctionnalités nécessitent toujours la voie du navigateur géré, notamment les actions par lots, l’export PDF, l’interception de téléchargement et responsebody.
• Existing-session est local à l’hôte. Si Chrome se trouve sur une autre machine ou dans un autre espace de noms réseau, utilisez plutôt le CDP distant ou un hôte de nœud.

​

Garanties d’isolation

• Répertoire de données utilisateur dédié : ne touche jamais à votre profil de navigateur personnel.
• Ports dédiés : évite 9222 pour prévenir les collisions avec les workflows de développement.
• Contrôle déterministe des onglets : cible les onglets par targetId, pas par « dernier onglet ».

​

Sélection du navigateur

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

• macOS : vérifie /Applications et ~/Applications.
• Linux : recherche google-chrome, brave, microsoft-edge, chromium, etc.
• Windows : vérifie les emplacements d’installation courants.

​

API de contrôle (facultatif)

• État/démarrage/arrêt : GET /, POST /start, POST /stop
• Onglets : GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
• Snapshot/capture d’écran : GET /snapshot, POST /screenshot
• Actions : POST /navigate, POST /act
• Hooks : POST /hooks/file-chooser, POST /hooks/dialog
• Téléchargements : POST /download, POST /wait/download
• Débogage : GET /console, POST /pdf
• Débogage : GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
• Réseau : POST /response/body
• État : GET /cookies, POST /cookies/set, POST /cookies/clear
• État : GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
• Paramètres : POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

• Authorization: Bearer <gateway token>
• x-openclaw-password: <gateway password> ou authentification HTTP Basic avec ce mot de passe

• Cette API autonome de navigateur en loopback ne consomme pas les en-têtes d’identité trusted-proxy ou Tailscale Serve.
• Si gateway.auth.mode vaut none ou trusted-proxy, ces routes de navigateur en loopback n’héritent pas de ces modes porteurs d’identité ; gardez-les limitées au loopback.

​

Exigence Playwright

• Snapshots ARIA
• Captures d’écran de page pour le navigateur géré openclaw lorsqu’un WebSocket CDP par onglet est disponible
• Captures d’écran de page pour les profils existing-session / Chrome MCP
• Captures d’écran existing-session basées sur --ref à partir de la sortie de snapshot

• navigate
• act
• AI snapshots / role snapshots
• Captures d’écran d’élément par sélecteur CSS (--element)
• Export PDF complet du navigateur

​

Installation de Playwright dans Docker

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

​

Fonctionnement (interne)

• Un petit serveur de contrôle accepte les requêtes HTTP.
• Il se connecte aux navigateurs basés sur Chromium (Chrome/Brave/Edge/Chromium) via CDP.
• Pour les actions avancées (click/type/snapshot/PDF), il utilise Playwright au-dessus de CDP.
• Lorsque Playwright est absent, seules les opérations sans Playwright sont disponibles.

​

Référence rapide CLI

• openclaw browser status
• openclaw browser start
• openclaw browser stop
• openclaw browser tabs
• openclaw browser tab
• openclaw browser tab new
• openclaw browser tab select 2
• openclaw browser tab close 2
• openclaw browser open https://example.com
• openclaw browser focus abcd1234
• openclaw browser close abcd1234

• openclaw browser screenshot
• openclaw browser screenshot --full-page
• openclaw browser screenshot --ref 12
• openclaw browser screenshot --ref e12
• openclaw browser snapshot
• openclaw browser snapshot --format aria --limit 200
• openclaw browser snapshot --interactive --compact --depth 6
• openclaw browser snapshot --efficient
• openclaw browser snapshot --labels
• openclaw browser snapshot --selector "#main" --interactive
• openclaw browser snapshot --frame "iframe#main" --interactive
• openclaw browser console --level error

• Pour les profils attach-only et CDP distants, openclaw browser stop reste la bonne commande de nettoyage après les tests. Elle ferme la session de contrôle active et efface les surcharges temporaires d’émulation au lieu de tuer le navigateur sous-jacent.
• openclaw browser errors --clear
• openclaw browser requests --filter api --clear
• openclaw browser pdf
• openclaw browser responsebody "**/api" --max-chars 5000

• openclaw browser navigate https://example.com
• openclaw browser resize 1280 720
• openclaw browser click 12 --double
• openclaw browser click e12 --double
• openclaw browser type 23 "hello" --submit
• openclaw browser press Enter
• openclaw browser hover 44
• openclaw browser scrollintoview e12
• openclaw browser drag 10 11
• openclaw browser select 9 OptionA OptionB
• openclaw browser download e12 report.pdf
• openclaw browser waitfordownload report.pdf
• openclaw browser upload /tmp/openclaw/uploads/file.pdf
• openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
• openclaw browser dialog --accept
• openclaw browser wait --text "Done"
• openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
• openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
• openclaw browser highlight e12
• openclaw browser trace start
• openclaw browser trace stop

• openclaw browser cookies
• openclaw browser cookies set session abc123 --url "https://example.com"
• openclaw browser cookies clear
• openclaw browser storage local get
• openclaw browser storage local set theme dark
• openclaw browser storage session clear
• openclaw browser set offline on
• openclaw browser set headers --headers-json '{"X-Debug":"1"}'
• openclaw browser set credentials user pass
• openclaw browser set credentials --clear
• openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
• openclaw browser set geo --clear
• openclaw browser set media dark
• openclaw browser set timezone America/New_York
• openclaw browser set locale en-US
• openclaw browser set device "iPhone 14"

• upload et dialog sont des appels d’armement ; exécutez-les avant le click/la pression qui déclenche le sélecteur/la boîte de dialogue.
• Les chemins de sortie de téléchargement et de trace sont limités aux racines temporaires OpenClaw :
  • traces : /tmp/openclaw (repli : ${os.tmpdir()}/openclaw)
  • téléchargements : /tmp/openclaw/downloads (repli : ${os.tmpdir()}/openclaw/downloads)
• Les chemins d’upload sont limités à une racine temporaire d’uploads OpenClaw :
  • uploads : /tmp/openclaw/uploads (repli : ${os.tmpdir()}/openclaw/uploads)
• upload peut aussi définir directement des entrées de fichier via --input-ref ou --element.
• snapshot :
  • --format ai (par défaut lorsque Playwright est installé) : renvoie un AI snapshot avec des refs numériques (aria-ref="<n>").
  • --format aria : renvoie l’arbre d’accessibilité (sans refs ; inspection uniquement).
  • --efficient (ou --mode efficient) : preset compact de role snapshot (interactive + compact + depth + maxChars réduit).
  • Valeur par défaut de configuration (outil/CLI uniquement) : définissez browser.snapshotDefaults.mode: "efficient" pour utiliser des snapshots efficaces lorsque l’appelant ne passe pas de mode (voir Configuration du Gateway).
  • Les options de role snapshot (--interactive, --compact, --depth, --selector) forcent un snapshot basé sur les rôles avec des refs comme ref=e12.
  • --frame "<iframe selector>" limite les role snapshots à un iframe (associé à des refs de rôle comme e12).
  • --interactive produit une liste plate, facile à sélectionner, d’éléments interactifs (le mieux pour piloter des actions).
  • --labels ajoute une capture d’écran du viewport avec des libellés de ref superposés (affiche MEDIA:<path>).
• click/type/etc nécessitent une ref provenant de snapshot (soit numérique 12, soit ref de rôle e12). Les sélecteurs CSS ne sont volontairement pas pris en charge pour les actions.

​

Snapshots et refs

• AI snapshot (refs numériques) : openclaw browser snapshot (par défaut ; --format ai)
  • Sortie : un snapshot texte qui inclut des refs numériques.
  • Actions : openclaw browser click 12, openclaw browser type 23 "hello".
  • En interne, la ref est résolue via aria-ref de Playwright.
• Role snapshot (refs de rôle comme e12) : openclaw browser snapshot --interactive (ou --compact, --depth, --selector, --frame)
  • Sortie : une liste/arborescence basée sur les rôles avec [ref=e12] (et éventuellement [nth=1]).
  • Actions : openclaw browser click e12, openclaw browser highlight e12.
  • En interne, la ref est résolue via getByRole(...) (plus nth() pour les doublons).
  • Ajoutez --labels pour inclure une capture d’écran du viewport avec les libellés e12 superposés.

• Les refs ne sont pas stables entre les navigations ; si quelque chose échoue, relancez snapshot et utilisez une ref fraîche.
• Si le role snapshot a été pris avec --frame, les refs de rôle sont limitées à cet iframe jusqu’au prochain role snapshot.

​

Super-pouvoirs de wait

• Attendre une URL (globs pris en charge par Playwright) :
  • openclaw browser wait --url "**/dash"
• Attendre un état de chargement :
  • openclaw browser wait --load networkidle
• Attendre un prédicat JS :
  • openclaw browser wait --fn "window.ready===true"
• Attendre qu’un sélecteur devienne visible :
  • openclaw browser wait "#main"

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

​

Workflows de débogage

1. openclaw browser snapshot --interactive
2. Utilisez click <ref> / type <ref> (préférez les refs de rôle en mode interactif)
3. Si cela échoue encore : openclaw browser highlight <ref> pour voir ce que Playwright cible
4. Si la page se comporte de façon étrange :
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. Pour un débogage approfondi : enregistrez une trace :
   • openclaw browser trace start
   • reproduisez le problème
   • openclaw browser trace stop (affiche TRACE:<path>)

​

Sortie JSON

openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

​

Réglages d’état et d’environnement

• Cookies : cookies, cookies set, cookies clear
• Storage : storage local|session get|set|clear
• Hors ligne : set offline on|off
• En-têtes : set headers --headers-json '{"X-Debug":"1"}' (l’ancien set headers --json '{"X-Debug":"1"}' reste pris en charge)
• Authentification HTTP basic : set credentials user pass (ou --clear)
• Géolocalisation : set geo <lat> <lon> --origin "https://example.com" (ou --clear)
• Médias : set media dark|light|no-preference|none
• Fuseau horaire / langue :
  • set timezone ..., set locale ...
• Appareil / viewport :
  • set device "iPhone 14" (presets d’appareil Playwright)
  • set viewport 1280 720

​

Sécurité et confidentialité

• Le profil de navigateur openclaw peut contenir des sessions connectées ; traitez-le comme sensible.
• browser act kind=evaluate / openclaw browser evaluate et wait --fn exécutent du JavaScript arbitraire dans le contexte de la page. Une injection de prompt peut orienter cela. Désactivez-le avec browser.evaluateEnabled=false si vous n’en avez pas besoin.
• Pour les connexions et les notes anti-bot (X/Twitter, etc.), consultez Connexion navigateur + publication X/Twitter.
• Gardez le Gateway/l’hôte de nœud privé (loopback ou tailnet uniquement).
• Les points de terminaison CDP distants sont puissants ; tunnelisez-les et protégez-les.

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // optional exact allow
    },
  },
}

​

Dépannage

​

Outils d’agent + fonctionnement du contrôle

• browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

• browser snapshot renvoie un arbre d’interface stable (AI ou ARIA).
• browser act utilise les ID ref du snapshot pour cliquer/saisir/faire glisser/sélectionner.
• browser screenshot capture les pixels (page complète ou élément).
• browser accepte :
  • profile pour choisir un profil de navigateur nommé (openclaw, chrome ou CDP distant).
  • target (sandbox | host | node) pour sélectionner l’emplacement du navigateur.
  • Dans les sessions en sandbox, target: "host" nécessite agents.defaults.sandbox.browser.allowHostControl=true.
  • Si target est omis : les sessions en sandbox utilisent par défaut sandbox, les sessions hors sandbox utilisent par défaut host.
  • Si un nœud capable de gérer le navigateur est connecté, l’outil peut y être acheminé automatiquement sauf si vous fixez target="host" ou target="node".

​

Liens associés

• Vue d’ensemble des outils — tous les outils d’agent disponibles
• Sandboxing — contrôle du navigateur dans des environnements sandboxés
• Sécurité — risques et durcissement du contrôle du navigateur