Passer au contenu principal

​
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é :

​
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 profiles
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw 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 doctor
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com
Guide détaillé : Dépannage du navigateur

​
Cycle de vie

openclaw browser status
openclaw browser doctor
openclaw browser doctor --deep
openclaw browser start
openclaw browser start --headless
openclaw browser stop
openclaw 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 profiles
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
openclaw browser delete-profile --name work
Utiliser un profil spécifique : 
openclaw browser --browser-profile work tabs

​
Onglets

openclaw browser tabs
openclaw browser tab new --label docs
openclaw browser tab label t1 docs
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://docs.openclaw.ai --label docs
openclaw browser focus docs
openclaw 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 snapshot
openclaw browser snapshot --urls
Capture d’écran : 
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
openclaw 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.com
openclaw browser click <ref>
openclaw browser click-coords 120 340
openclaw browser type <ref> "hello"
openclaw browser press Enter
openclaw browser hover <ref>
openclaw browser scrollintoview <ref>
openclaw browser drag <startRef> <endRef>
openclaw browser select <ref> OptionA OptionB
openclaw 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 waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
openclaw 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 720
openclaw browser set viewport 1280 720
openclaw browser set offline on
openclaw browser set media dark
openclaw browser set timezone Europe/London
openclaw browser set locale en-GB
openclaw browser set geo 51.5074 -0.1278 --accuracy 25
openclaw browser set device "iPhone 14"
openclaw browser set headers '{"x-test":"1"}'
openclaw browser set credentials myuser mypass
Cookies + stockage : 
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 token abc123
openclaw browser storage session clear

​
Débogage

openclaw browser console --level error
openclaw browser pdf
openclaw browser responsebody "**/api"
openclaw browser highlight <ref>
openclaw browser errors --clear
openclaw browser requests --filter api
openclaw browser trace start
openclaw 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 tabs
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw 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:9222
openclaw 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