browser-automation

Automatisation du Navigateur

Utilisez cette compétence lorsque vous avez besoin de l'outil browser pour autre chose qu'une simple vérification de page unique.

Boucle de Fonctionnement

1. Vérifiez l'état du navigateur avant d'agir :
   • openclaw browser doctor ou action="status" lorsque l'installation du navigateur/plugin elle-même peut être cassée.
   • action="status" pour la disponibilité.
   • action="profiles" si l'état de connexion ou le choix du profil est important.
   • action="tabs" avant d'ouvrir un nouvel onglet si des tentatives/timeouts peuvent avoir laissé des fenêtres ouvertes.
2. Privilégiez les handles d'onglets stables :
   • Ouvrez les onglets importants avec label, par exemple label="meet".
   • Après action="tabs" ou action="open", stockez suggestedTargetId et transmettez-le comme targetId dans les appels ultérieurs.
   • suggestedTargetId est le label lorsqu'il existe, sinon le handle tabId stable comme t1.
   • Évitez de vous fier au targetId DevTools brut sauf pour un diagnostic immédiat ; il peut changer lors du remplacement de cible Chromium.
3. Lisez avant de cliquer :
   • Pour « lire la page et répondre à X », utilisez action="text" avec un selector optionnel et maxChars pour une prose visible limitée (correspondance du premier sélecteur, sinon article/main/body). Sur les profils de session existante, utilisez snapshot à la place. Les instantanés efficaces omettent la plupart de la prose.
   • Pour les listes virtualisées, parcourez chaque segment, capturez uniquement les lignes pertinentes, puis fusionnez les résultats.
   • Utilisez action="snapshot" sur le targetId prévu.
   • Ajoutez une query d'instantané pour trouver des lignes contenant tous les jetons de requête, en ignorant la casse ; les lignes correspondantes conservent leurs références.
   • Utilisez le même targetId pour les actions de suivi afin que les références restent sur le même onglet.
   • Pour des références Playwright durables, demandez refs="aria" lorsque c'est pris en charge. Si vous recevez des références axN de snapshotFormat="aria", utilisez-les uniquement après ce même appel d'instantané ; les références axN obsolètes ou non liées échouent rapidement et nécessitent un nouvel instantané.
   • Utilisez urls=true lorsque le texte du lien est ambigu ou qu'une cible de navigation directe éviterait des clics fragiles.
   • Utilisez labels=true sur l'instantané ou la capture d'écran lorsque la position visuelle est importante. Sur les profils basés sur Playwright, la réponse inclut un tableau annotations ({ref, number, role, name?, box}) avec le cadre de délimitation de chaque référence dans l'espace de coordonnées de l'image capturée, vous pouvez donc raisonner sur la position sans refaire d'instantané ; les labels de capture d'écran peuvent également se combiner avec fullPage=true (CLI : --full-page) pour étiqueter l'ensemble du document, ou ref / element pour recadrer sur un élément. Les profils profile="user" et autres profils de session existante (chrome-mcp) rendent une superposition dans les captures d'écran de page mais n'attachent pas de annotations ni n'utilisent l'assistant de projection Playwright plein écran/réf/élément, lisez donc les positions à partir de l'image étiquetée elle-même sur ces profils. Le repli raw-CDP (sans Playwright) ne prend pas du tout en charge les captures d'écran étiquetées et retourne une erreur 501, ne demandez donc labels que lorsque Playwright est disponible.
4. Agissez avec précision :
   • Privilégiez action="act" avec une référence du dernier instantané.
   • navigate retourne l'instantané compact de la page chargée en ligne, et les résultats d'act par lot qui signalent une navigation entre documents incluent l'état frais de la page ; utilisez ces références directement au lieu d'un appel d'instantané de suivi.
   • Après un act unique qui déclenche une navigation, et après des changements de modal ou des soumissions de formulaire, refaites un instantané avant l'action suivante.
   • Évitez les attentes aveugles. Attendez l'état visible de l'interface utilisateur lorsque c'est possible.
   • Utilisez action="emulate" avec device, colorScheme, timezoneId, ou locale lorsque vous testez ces paramètres ; refaites un instantané ensuite. Les profils de session existante ne prennent pas en charge l'émulation.
5. Signalez les vrais bloqueurs :
   • Déboguez les échecs réseau avec action="requests", un filter optionnel URL/type, et limit (par défaut 50 entrées récentes). clear=true efface le journal collecté après la lecture. Utilisez un profil géré ; les profils de session existante ne prennent pas en charge ce journal.
   • Déboguez les erreurs de page avec action="errors" et limit (par défaut 50 entrées récentes). clear=true efface le journal collecté après la lecture. Les profils de session existante ne prennent pas en charge ce journal.
   • Si la page nécessite une connexion, une autorisation, un captcha, une 2FA, une approbation caméra/microphone, ou une autre étape manuelle, arrêtez-vous et dites exactement à l'utilisateur ce qui est nécessaire.
   • Ne prétendez pas que le navigateur n'est pas connecté simplement parce que la page actuelle affiche une boîte de dialogue d'autorisation ou d'intégration. Inspectez d'abord l'interface utilisateur visible.

CLI de lot du navigateur

openclaw browser batch exécute un tableau d'actions /act imbriquées en un seul appel /act (le même runtime kind="batch" atteint via l'outil agent), afin que les utilisateurs CLI et les scripts puissent combiner des actions comme wait, click, type et evaluate en un seul plan rejouable sans allers-retours par action. Chaque entrée dans actions[] est une BrowserActRequest — l'union fermée que la route /act accepte — et non des sous-commandes openclaw browser arbitraires. batch n'est pas pris en charge sur profile="user" et les autres profils de session existante (chrome-mcp) ; envoyez les actions individuellement dans ce cas.

• CLI : openclaw browser batch --actions '<json>', --actions-file plan.json, ou --actions-file - pour l'entrée standard. --actions-file et l'entrée standard sont limités à 1 000 000 d'octets ; divisez les plans plus volumineux en plusieurs commandes batch. --continue définit stopOnError=false ; par défaut, s'arrête à la première erreur.
• Cycle de vie des références : les références proviennent d'un snapshot exécuté avant le lot (l'instantané n'est pas une action imbriquée). Une action imbriquée qui modifie l'état de la page — comme un click qui déclenche une navigation, ou un evaluate qui modifie le DOM — peut invalider les références antérieures pour le reste du lot ; placez les actions qui modifient l'état en premier, ou divisez en un lot de suivi après avoir refait un instantané. La navigation et le re-snapshot se produisent en dehors du lot, car open, navigate et snapshot ne sont pas des types /act.
• ID de cible : les actions imbriquées partagent l'onglet de la requête ; un targetId imbriqué explicite qui se résout en un onglet différent est rejeté avec ACT_TARGET_ID_MISMATCH.
• Réponse : { "results": [{ "ok": true } | { "ok": false, "error": "..." }, ...] } dans l'ordre ; avec stopOnError par défaut, le tableau se termine à la première défaillance. Toute entrée échouée se termine par un code non nul ; utilisez --json pour conserver la réponse complète dans les scripts.

Boucle en Mode Code

Lorsque tools.codeMode est activé, l'outil Navigateur n'a pas de tour normal — il est catalogué derrière exec/wait. Appelez-le depuis les cellules exec en tant que global asynchrone, en utilisant le nom appelable que l'index rapide exec annonce pour l'outil Navigateur (normalement browser ; les noms en conflit sont suffixés, et un outil client peut gagner un nom identique). Un catalog.search("browser") exact retourne un handle déjà lié au nom appelable effectif, résolvez donc le handle dans chaque cellule et appelez-le au lieu de coder en dur le littéral global ; un résultat vide signifie que l'outil Navigateur n'est pas catalogué dans cette exécution.

Conservez le même onglet étiqueté tout au long de la boucle et alternez les lectures avec les actions. Chaque cellule exec démarre une VM fraîche — les liaisons d'une cellule terminée sont perdues dans la suivante, et seules les exécutions laissées en waiting conservent leur état jusqu'à ce que wait les reprenne — transportez donc l'état de comparaison entre les cellules en le retournant et en réintégrant les valeurs retournées dans la cellule suivante :

// previous = l'url/les newElements retournés par la dernière cellule terminée (une nouvelle
// VM exécute cette cellule, donc les liaisons précédentes n'existent pas ici).
const previous = { url: "https://example.com/inbox", newElements: 0 };
const [browser] = await catalog.search("browser", { limit: 1 });
const details = await browser({
  action: "snapshot",
  snapshotFormat: "ai",
  targetId: "task",
  refs: "aria",
  interactive: true,
});
const changed =
  details?.url !== previous.url ||
  (details?.newElements ?? 0) > 0 ||
  details?.blockedByDialog === true;
return {
  targetId: details?.targetId,
  url: details?.url,
  newElements: details?.newElements,
  stats: details?.stats,
  text: details?.text,
  changed,
};

• Les appels en mode code retournent directement les details structurés de l'outil. Les observations d'instantané et de texte incluent un text limité avec le même wrapper de contenu non fiable que la sortie directe de l'outil. Conservez ce wrapper lorsque vous retournez des données de page au modèle. Les champs existants d'identité, de stats et de dialogue restent disponibles.
• Pour lire la prose visible en mode code, demandez text avec un sélecteur étroit. Cela ne nécessite pas la capacité d'évaluation :

const [browser] = await catalog.search("browser", { limit: 1 });
const read = await browser({
  action: "text",
  selector: "main",
  maxChars: 2000,
  targetId: "task",
});
return { url: read?.url, text: read?.text };

Utilisez la query d'instantané et le selector/maxChars de texte pour réduire les lectures au niveau du propriétaire du navigateur avant de les encapsuler. Un dialogue bloqué nécessite toujours son étape de récupération signalée ; le texte de la page n'accorde pas la permission d'évaluer des scripts.

• Ne retournez que les champs dont l'étape suivante a besoin ; ne retournez jamais l'intégralité de l'objet details.
• Les cellules terminées ne partagent aucun état : réintégrez l'url/newElements retournés de la cellule précédente dans la cellule suivante, ou conservez la comparaison dans une seule cellule. Seules les exécutions waiting persistent, reprises par wait.
• Intercalez chaque action avec une vérification d'URL ou d'onglets avant l'action dépendante suivante.
• Si un lot retourne aborted, prenez un nouvel instantané avant de continuer.
• Si newElements est positif, inspectez d'abord ces éléments, puis mettez à jour l'état réintégré.
• Utilisez des appels d'action séparés lorsqu'une navigation est attendue entre les étapes.

Hygiène des Onglets

Avant de créer un onglet pour une tâche nommée, listez les onglets et réutilisez un label ou une URL correspondante existante lorsqu'elle est encore utilisable.

Exemple :

{ "action": "tabs" }

Si aucun onglet approprié n'existe :

{ "action": "open", "url": "https://example.com", "label": "task" }

Ciblez-le ensuite par label :

{ "action": "snapshot", "targetId": "task", "refs": "aria" }

Si une tentative crée des doublons, fermez les supplémentaires par tabId :

{ "action": "close", "targetId": "t3" }

Ne passez pas de nombres bruts comme "2" comme targetId. Les positions numériques des onglets sont uniquement pour l'assistant CLI openclaw browser tab select 2 ; les appels d'outil navigateur ont besoin d'un suggestedTargetId, d'un label, d'un tabId ou d'un ID de cible brut.

Récupération de Référence Obsolète

Si une action échoue avec une référence manquante ou obsolète :

1. Prenez un instantané du même targetId à nouveau.
2. Trouvez le contrôle visible actuel.
3. Réessayez une fois avec la nouvelle référence.
4. Si l'interface utilisateur est passée à un état bloquant, signalez le bloqueur au lieu de boucler.

Navigateur Utilisateur Existant

Utilisez profile="user" uniquement lorsque les cookies/connexion existants sont importants. Cela s'attache au navigateur basé sur Chromium en cours d'exécution de l'utilisateur.

Sur macOS, action="importprofile" est l'alternative lorsque l'agent doit utiliser un navigateur géré isolé avec des cookies copiés à partir d'un vrai profil Chrome-family. Utilisez d'abord action="profiles" et inspectez systemProfiles, puis importez dans un nouveau nom de profil géré. L'import demande une invite de consentement Keychain/Touch ID. Il copie les cookies, pas le stockage local ou IndexedDB ; les informations d'identification de session liées à l'appareil (DBSC) peuvent encore nécessiter une ré-authentification pour certaines sessions Google.

Pour profile="user" et les autres profils de session existante, omettez timeoutMs sur act:type, hover, scrollIntoView, drag, select, et fill ; ce pilote rejette les remplacements de délai d'attente par appel pour ces actions. act:evaluate accepte timeoutMs.

Notes Google Meet

Lors de la création ou de la participation à un Meet :

• Traitez les écrans d'autorisation caméra/microphone comme une progression, pas un échec de connexion.
• Si on vous demande si les gens peuvent vous entendre, cliquez sur l'option microphone lorsque la voix est requise.
• Si Google demande une connexion, une 2FA, une confirmation du sélecteur de compte ou une autorisation qui nécessite l'approbation de l'utilisateur, signalez l'action manuelle exacte.
• Utilisez un onglet étiqueté par flux de réunion, par exemple label="meet", et réutilisez-le lors des tentatives.