openclaw browser

Gérez la surface de contrôle du navigateur d’OpenClaw et exécutez des actions de navigateur (cycle de vie, profils, onglets, instantanés, captures d’écran, navigation, saisie, émulation d’état et débogage).

Associé :

• Outil de navigateur + API : Outil de navigateur

Indicateurs courants

• --url <gatewayWsUrl> : URL WebSocket du Gateway (par défaut depuis la configuration).
• --token <token> : jeton du Gateway (si requis).
• --timeout <ms> : délai d’expiration de la requête (ms).
• --expect-final : attendre une réponse finale du Gateway.
• --browser-profile <name> : choisir un profil de navigateur (par défaut depuis la configuration).
• --json : sortie lisible par machine (lorsque pris en charge).

Démarrage rapide (local)

openclaw browser profilesopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

Les agents peuvent exécuter le même contrôle de disponibilité avec browser({ action: "doctor" }).

Dépannage rapide

Si start échoue avec not reachable after start, dépannez d’abord la disponibilité CDP. Si start et tabs réussissent mais que open ou navigate échoue, le plan de contrôle du navigateur est sain et l’échec relève généralement de la politique SSRF de navigation.

Séquence minimale :

openclaw browser --browser-profile openclaw doctoropenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw tabsopenclaw browser --browser-profile openclaw open https://example.com

Guide détaillé : Dépannage du navigateur

Cycle de vie

openclaw browser statusopenclaw browser doctoropenclaw browser doctor --deepopenclaw browser startopenclaw browser start --headlessopenclaw browser stopopenclaw browser --browser-profile openclaw reset-profile

Notes :

• doctor --deep ajoute une sonde d’instantané en direct. C’est utile lorsque la disponibilité CDP de base est au vert, mais que vous voulez prouver que l’onglet actuel peut être inspecté.
• Pour les profils attachOnly et CDP distants, openclaw browser stop ferme la session de contrôle active et efface les surcharges d’émulation temporaires même lorsque OpenClaw n’a pas lancé lui-même le processus du navigateur.
• Pour les profils locaux gérés, openclaw browser stop arrête le processus de navigateur lancé.
• openclaw browser start --headless s’applique uniquement à cette requête de démarrage et seulement quand OpenClaw lance un navigateur local géré. Cela ne réécrit pas browser.headless ni la configuration du profil, et c’est sans effet pour un navigateur déjà en cours d’exécution.
• Sur les hôtes Linux sans DISPLAY ni WAYLAND_DISPLAY, les profils locaux gérés s’exécutent automatiquement en mode headless, sauf si OPENCLAW_BROWSER_HEADLESS=0, browser.headless=false ou browser.profiles.<name>.headless=false demande explicitement un navigateur visible.

Si la commande est absente

Si openclaw browser est une commande inconnue, vérifiez plugins.allow dans ~/.openclaw/openclaw.json.

Lorsque plugins.allow est présent, listez explicitement le Plugin de navigateur groupé, sauf si la configuration possède déjà un bloc racine browser :

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

Un bloc racine browser explicite, par exemple browser.enabled=true ou browser.profiles.<name>, active également le Plugin de navigateur groupé avec une liste d’autorisation de Plugins restrictive.

Associé : Outil de navigateur

Profils

Les profils sont des configurations de routage de navigateur nommées. En pratique :

• openclaw : lance ou s’attache à une instance Chrome dédiée gérée par OpenClaw (répertoire de données utilisateur isolé).
• user : contrôle votre session Chrome connectée existante via Chrome DevTools MCP.
• profils CDP personnalisés : pointent vers un point de terminaison CDP local ou distant.

openclaw browser profilesopenclaw browser create-profile --name work --color "#FF5A36"openclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name remote --cdp-url https://browser-host.example.comopenclaw browser delete-profile --name work

Utiliser un profil spécifique :

openclaw browser --browser-profile work tabs

Onglets

openclaw browser tabsopenclaw browser tab new --label docsopenclaw browser tab label t1 docsopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://docs.openclaw.ai --label docsopenclaw browser focus docsopenclaw browser close t1

tabs renvoie d’abord suggestedTargetId, puis le tabId stable comme t1, l’étiquette facultative et le targetId brut. Les agents doivent repasser suggestedTargetId à focus, close, aux instantanés et aux actions. Vous pouvez attribuer une étiquette avec open --label, tab new --label ou tab label ; les étiquettes, les ids d’onglet, les ids de cible bruts et les préfixes uniques d’id de cible sont tous acceptés. Le champ de requête s’appelle toujours targetId pour compatibilité, mais il accepte ces références d’onglet. Traitez les ids de cible bruts comme des identifiants de diagnostic, pas comme une mémoire d’agent durable. Lorsque Chromium remplace la cible brute sous-jacente pendant une navigation ou un envoi de formulaire, OpenClaw conserve le tabId stable ou l’étiquette attachés à l’onglet de remplacement lorsqu’il peut prouver la correspondance. Les ids de cible bruts restent volatils ; préférez suggestedTargetId.

Instantané / capture d’écran / actions

Instantané :

openclaw browser snapshotopenclaw browser snapshot --urls

Capture d’écran :

openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref e12openclaw browser screenshot --labels

Notes :

• --full-page est réservé aux captures de page ; il ne peut pas être combiné avec --ref ni --element.
• Les profils existing-session / user prennent en charge les captures d’écran de page et les captures --ref depuis la sortie d’instantané, mais pas les captures d’écran CSS --element.
• --labels superpose les refs de l’instantané actuel sur la capture d’écran. Sur les profils adossés à Playwright, cela fonctionne avec --full-page (superposition d’étiquettes pleine page), --ref (superposition d’étiquettes par découpe d’élément selon la ref ARIA) et --element (superposition d’étiquettes par découpe d’élément selon le sélecteur CSS) ; dans les modes de découpe d’élément, les étiquettes sont projetées relativement à l’élément. La réponse inclut aussi un tableau annotations avec la boîte englobante de chaque ref. Chaque élément contient ref, number, role, name facultatif et box: {x, y, width, height} ; les coordonnées sont dans l’espace de l’image capturée (viewport / fullpage / relatif à l’élément). Le champ est omis lorsqu’il est vide. Les profils existing-session affichent une superposition chrome-mcp sur les captures d’écran de page, mais n’utilisent pas l’assistant de projection Playwright et n’incluent pas annotations ; les captures d’écran CSS --element n’y sont pas prises en charge. Sans Playwright ni chrome-mcp, les captures d’écran étiquetées ne sont pas disponibles. Les versions précédentes ignoraient --full-page, --ref et --element sur les captures d’écran Playwright étiquetées et renvoyaient toujours une capture du viewport ; les captures d’écran étiquetées respectent désormais ces portées.
• snapshot --urls ajoute les destinations de liens découvertes aux instantanés IA afin que les agents puissent choisir des cibles de navigation directes au lieu de déduire uniquement depuis le texte des liens.

Naviguer/cliquer/saisir (automatisation d’interface fondée sur des refs) :

openclaw browser navigate https://example.comopenclaw browser click <ref>openclaw browser click-coords 120 340openclaw browser type <ref> "hello"openclaw browser press Enteropenclaw browser hover <ref>openclaw browser scrollintoview <ref>openclaw browser drag <startRef> <endRef>openclaw browser select <ref> OptionA OptionBopenclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'openclaw browser wait --text "Done"openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>openclaw browser evaluate --fn 'const title = document.title; return title;'openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'

evaluate --fn accepte une source de fonction, une expression ou un corps d’instruction. Les corps d’instruction sont enveloppés comme des fonctions async, donc utilisez return pour la valeur que vous voulez récupérer. Utilisez evaluate --timeout-ms <ms> lorsque la fonction côté page peut avoir besoin de plus de temps que le délai d’expiration d’évaluation par défaut.

Les réponses d’action renvoient le targetId brut actuel après un remplacement de page déclenché par l’action lorsqu’OpenClaw peut prouver l’onglet de remplacement. Les scripts doivent tout de même stocker et transmettre suggestedTargetId/les étiquettes pour les workflows de longue durée.

Assistants de fichiers et de boîtes de dialogue :

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>openclaw browser upload media://inbound/file.pdf --ref <ref>openclaw browser waitfordownloadopenclaw browser download <ref> report.pdfopenclaw browser dialog --acceptopenclaw browser dialog --dismiss --dialog-id d1

Les profils Chrome gérés enregistrent les téléchargements ordinaires déclenchés par clic dans le répertoire de téléchargements d’OpenClaw (/tmp/openclaw/downloads par défaut, ou la racine temporaire configurée). Utilisez waitfordownload ou download lorsque l’agent doit attendre un fichier spécifique et renvoyer son chemin ; ces attentes explicites possèdent le prochain téléchargement. Les téléversements acceptent les fichiers depuis la racine temporaire des téléversements d’OpenClaw et les médias entrants gérés par OpenClaw, notamment les références media://inbound/<id> et media/inbound/<id> relatives au bac à sable. Les refs de médias imbriquées, la traversée et les chemins locaux arbitraires restent rejetés. Lorsqu’une action ouvre une boîte de dialogue modale, la réponse d’action renvoie blockedByDialog avec browserState.dialogs.pending ; transmettez --dialog-id pour y répondre directement. Les boîtes de dialogue gérées hors d’OpenClaw apparaissent sous browserState.dialogs.recent.

État et stockage

Viewport + émulation :

openclaw browser resize 1280 720openclaw browser set viewport 1280 720openclaw browser set offline onopenclaw browser set media darkopenclaw browser set timezone Europe/Londonopenclaw browser set locale en-GBopenclaw browser set geo 51.5074 -0.1278 --accuracy 25openclaw browser set device "iPhone 14"openclaw browser set headers '{"x-test":"1"}'openclaw browser set credentials myuser mypass

Cookies + stockage :

openclaw browser cookiesopenclaw browser cookies set session abc123 --url https://example.comopenclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set token abc123openclaw browser storage session clear

Débogage

openclaw browser console --level erroropenclaw browser pdfopenclaw browser responsebody "**/api"openclaw browser highlight <ref>openclaw browser errors --clearopenclaw browser requests --filter apiopenclaw browser trace startopenclaw browser trace stop --out trace.zip

Chrome existant via MCP

Utilisez le profil user intégré, ou créez votre propre profil existing-session :

openclaw browser --browser-profile user tabsopenclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"openclaw browser create-profile --name chrome-port --driver existing-session --cdp-url http://127.0.0.1:9222openclaw browser --browser-profile chrome-live tabs

Le chemin existing-session par défaut est une connexion automatique Chrome MCP locale à l’hôte. Si le navigateur est déjà en cours d’exécution avec un point de terminaison DevTools, transmettez --cdp-url pour que Chrome MCP s’attache plutôt à ce point de terminaison. Pour Docker, Browserless ou d’autres configurations distantes où la sémantique de Chrome MCP n’est pas nécessaire, utilisez un profil CDP.

Limites actuelles de existing-session :

• les actions pilotées par instantané utilisent des refs, pas des sélecteurs CSS
• browser.actionTimeoutMs définit par défaut les requêtes act prises en charge à 60000 ms lorsque les appelants omettent timeoutMs; le timeoutMs par appel reste prioritaire.
• click correspond uniquement au clic gauche
• type ne prend pas en charge slowly=true
• press ne prend pas en charge delayMs
• hover, scrollintoview, drag, select, fill et evaluate rejettent les remplacements de délai d’expiration par appel
• select prend en charge une seule valeur
• wait --load networkidle n’est pas pris en charge sur les profils de session existants (fonctionne sur les profils CDP gérés et bruts/distants)
• les téléversements de fichiers nécessitent --ref / --input-ref, ne prennent pas en charge --element CSS, et prennent actuellement en charge un seul fichier à la fois
• les hooks de boîte de dialogue ne prennent pas en charge --timeout
• les captures d’écran prennent en charge les captures de page et --ref, mais pas --element CSS
• responsebody, l’interception des téléchargements, l’export PDF et les actions par lots nécessitent encore un navigateur géré ou un profil CDP brut

Contrôle de navigateur distant (proxy d’hôte Node)

Si le Gateway s’exécute sur une machine différente de celle du navigateur, exécutez un hôte Node sur la machine qui dispose de Chrome/Brave/Edge/Chromium. Le Gateway transmettra les actions du navigateur à ce nœud (aucun serveur de contrôle de navigateur séparé n’est requis).

Utilisez gateway.nodes.browser.mode pour contrôler le routage automatique et gateway.nodes.browser.node pour épingler un nœud précis si plusieurs sont connectés.

Sécurité + configuration distante : Outil de navigateur, Accès distant, Tailscale, Sécurité

Connexe

• Référence CLI
• Navigateur