Passer au contenu principal

​
Extension Chrome (relais du navigateur)

L’extension Chrome OpenClaw permet à l’agent de contrôler vos onglets Chrome existants (votre fenêtre Chrome habituelle) au lieu de lancer un profil Chrome distinct géré par openclaw. L’attachement/le détachement se fait via un seul bouton de la barre d’outils Chrome.

​
Ce que c’est (concept)

Il y a trois composants :
  • Service de contrôle du navigateur (Gateway ou nœud) : l’API que l’agent/l’outil appelle (via le Gateway)
  • Serveur de relais local (CDP en local loopback) : fait le pont entre le serveur de contrôle et l’extension (http://127.0.0.1:18792 par défaut)
  • Extension Chrome MV3 : s’attache à l’onglet actif à l’aide de chrome.debugger et achemine les messages CDP vers le relais
OpenClaw contrôle ensuite l’onglet attaché via la surface d’outil browser habituelle (en sélectionnant le bon profil).

​
Installer / charger (non empaqueté)

  1. Installez l’extension dans un chemin local stable :
openclaw browser extension install
  1. Affichez le chemin du répertoire de l’extension installée :
openclaw browser extension path
  1. Chrome → chrome://extensions
  • Activez « Mode développeur »
  • « Charger l’extension non empaquetée » → sélectionnez le répertoire affiché ci-dessus
  1. Épinglez l’extension.

​
Mises à jour (sans étape de build)

L’extension est fournie dans la version OpenClaw (package npm) sous forme de fichiers statiques. Il n’y a pas d’étape de « build » séparée. Après la mise à niveau d’OpenClaw :
  • Relancez openclaw browser extension install pour actualiser les fichiers installés sous votre répertoire d’état OpenClaw.
  • Chrome → chrome://extensions → cliquez sur « Recharger » pour l’extension.

​
L’utiliser (sans configuration supplémentaire)

OpenClaw fournit un profil de navigateur intégré nommé chrome qui cible le relais de l’extension sur le port par défaut. Utilisation :
  • CLI : openclaw browser --browser-profile chrome tabs
  • Outil d’agent : browser avec profile="chrome"
Si vous souhaitez un autre nom ou un autre port de relais, créez votre propre profil : 
openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

​
Attacher / détacher (bouton de la barre d’outils)

  • Ouvrez l’onglet que vous voulez faire contrôler par OpenClaw.
  • Cliquez sur l’icône de l’extension.
    • Le badge affiche ON lorsqu’il est attaché.
  • Cliquez à nouveau pour détacher.

​
Quel onglet est contrôlé ?

  • Il ne contrôle pas automatiquement « l’onglet que vous regardez ».
  • Il contrôle uniquement l’/les onglet(s) que vous avez explicitement attaché(s) en cliquant sur le bouton de la barre d’outils.
  • Pour changer : ouvrez l’autre onglet et cliquez sur l’icône de l’extension dans cet onglet.

​
Badge + erreurs courantes

  • ON : attaché ; OpenClaw peut piloter cet onglet.
  • … : connexion au relais local.
  • ! : relais injoignable (le plus courant : le serveur de relais du navigateur n’est pas en cours d’exécution sur cette machine).
Si vous voyez ! :
  • Assurez-vous que le Gateway s’exécute localement (configuration par défaut), ou lancez un hôte de nœud sur cette machine si le Gateway s’exécute ailleurs.
  • Ouvrez la page Options de l’extension ; elle indique si le relais est joignable.

​
Gateway distant (utiliser un hôte de nœud)

​
Gateway local (même machine que Chrome) — généralement aucune étape supplémentaire

Si le Gateway s’exécute sur la même machine que Chrome, il démarre le service de contrôle du navigateur en local loopback et lance automatiquement le serveur de relais. L’extension communique avec le relais local ; les appels CLI/outil vont vers le Gateway.

​
Gateway distant (le Gateway s’exécute ailleurs) — exécuter un hôte de nœud

Si votre Gateway s’exécute sur une autre machine, démarrez un hôte de nœud sur la machine qui exécute Chrome. Le Gateway proxifiera les actions du navigateur vers ce nœud ; l’extension + le relais restent locaux à la machine du navigateur. Si plusieurs nœuds sont connectés, épinglez-en un avec gateway.nodes.browser.node ou définissez gateway.nodes.browser.mode.

​
Sandboxing (conteneurs d’outils)

Si votre session d’agent est en sandbox (agents.defaults.sandbox.mode != "off"), l’outil browser peut être restreint :
  • Par défaut, les sessions en sandbox ciblent souvent le navigateur sandbox (target="sandbox"), et non votre Chrome hôte.
  • La prise de contrôle via le relais de l’extension Chrome nécessite de contrôler le serveur de contrôle du navigateur hôte.
Options :
  • Le plus simple : utiliser l’extension depuis une session/un agent non en sandbox.
  • Ou autoriser le contrôle du navigateur hôte pour les sessions en sandbox :
{
  agents: {
    defaults: {
      sandbox: {
        browser: {
          allowHostControl: true,
        },
      },
    },
  },
}
Assurez-vous ensuite que l’outil n’est pas refusé par la politique d’outils et (si nécessaire) appelez browser avec target="host". Débogage : openclaw sandbox explain

​
Conseils d’accès distant

  • Conservez le Gateway et l’hôte de nœud sur le même tailnet ; évitez d’exposer les ports du relais au LAN ou à l’Internet public.
  • Appariez les nœuds intentionnellement ; désactivez le routage proxy du navigateur si vous ne souhaitez pas de contrôle à distance (gateway.nodes.browser.mode="off").

​
Fonctionnement du « chemin de l’extension »

openclaw browser extension path affiche le répertoire installé sur disque contenant les fichiers de l’extension. La CLI n’affiche intentionnellement pas un chemin node_modules. Exécutez toujours openclaw browser extension install en premier pour copier l’extension vers un emplacement stable sous votre répertoire d’état OpenClaw. Si vous déplacez ou supprimez ce répertoire d’installation, Chrome marquera l’extension comme défectueuse jusqu’à ce que vous la rechargiez depuis un chemin valide.

​
Implications de sécurité (à lire)

C’est puissant et risqué. Traitez cela comme si vous donniez au modèle « les mains sur votre navigateur ».
  • L’extension utilise l’API de débogage de Chrome (chrome.debugger). Lorsqu’elle est attachée, le modèle peut :
    • cliquer/taper/naviguer dans cet onglet
    • lire le contenu de la page
    • accéder à tout ce à quoi la session connectée de l’onglet peut accéder
  • Ce n’est pas isolé comme le profil dédié géré par openclaw.
    • Si vous vous attachez à votre profil/onglet de navigation quotidien, vous accordez l’accès à l’état de ce compte.
Recommandations :
  • Préférez un profil Chrome dédié (séparé de votre navigation personnelle) pour l’utilisation du relais d’extension.
  • Conservez le Gateway et les hôtes de nœud en accès tailnet uniquement ; fiez-vous à l’authentification du Gateway + à l’appariement des nœuds.
  • Évitez d’exposer les ports du relais sur le LAN (0.0.0.0) et évitez Funnel (public).
  • Le relais bloque les origines non liées à l’extension et exige un jeton d’authentification interne pour les clients CDP.
Liens associés :
  • Vue d’ensemble de l’outil Navigateur : Browser
  • Audit de sécurité : Security
  • Configuration Tailscale : Tailscale