Chrome Extension (Browser Relay)

Die OpenClaw Chrome Extension ermöglicht es dem Agent, deine bestehenden Chrome-Tabs (dein normales Chrome-Fenster) zu steuern, anstatt ein separates openclaw-verwaltetes Chrome-Profil zu starten.

Das Verbinden und Trennen funktioniert über einen einzelnen Chrome-Toolbar-Button.

Was ist das (Konzept)

Es gibt drei Komponenten:

Browser Control Service (Gateway oder Node): die API, die der Agent/das Tool aufruft (über das Gateway)
Lokaler Relay-Server (Loopback CDP): verbindet den Control-Server mit der Extension (http://127.0.0.1:18792 standardmäßig)
Chrome MV3 Extension: verbindet sich mit dem aktiven Tab über chrome.debugger und leitet CDP-Nachrichten an den Relay weiter

OpenClaw steuert dann den verbundenen Tab über die normale browser-Tool-Oberfläche (durch Auswahl des richtigen Profils).

Installation / Laden (unpacked)

Installiere die Extension in einem stabilen lokalen Pfad:

openclaw browser extension install

Zeige den Pfad zum installierten Extension-Verzeichnis an:

openclaw browser extension path

Chrome → chrome://extensions

Aktiviere “Entwicklermodus”
“Entpackte Erweiterung laden” → wähle das oben angezeigte Verzeichnis

Pinne die Extension.

Updates (kein Build-Schritt)

Die Extension wird als Teil des OpenClaw-Releases (npm-Paket) als statische Dateien ausgeliefert. Es gibt keinen separaten “Build”-Schritt.

Nach einem OpenClaw-Upgrade:

Führe openclaw browser extension install erneut aus, um die installierten Dateien in deinem OpenClaw-State-Verzeichnis zu aktualisieren.
Chrome → chrome://extensions → klicke auf “Neu laden” bei der Extension.

Verwendung (keine Extra-Konfiguration)

OpenClaw wird mit einem eingebauten Browser-Profil namens chrome ausgeliefert, das auf den Extension-Relay am Standard-Port zielt.

So verwendest du es:

CLI: openclaw browser --browser-profile chrome tabs
Agent-Tool: browser mit profile="chrome"

Wenn du einen anderen Namen oder einen anderen Relay-Port möchtest, erstelle dein eigenes Profil:

openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

Öffne den Tab, den OpenClaw steuern soll.
Klicke auf das Extension-Icon.
- Das Badge zeigt ON, wenn verbunden.
Klicke erneut, um die Verbindung zu trennen.

Welchen Tab steuert es?

Es steuert nicht automatisch “den Tab, den du gerade anschaust”.
Es steuert nur die Tab(s), die du explizit verbunden hast, indem du auf den Toolbar-Button geklickt hast.
Zum Wechseln: Öffne den anderen Tab und klicke dort auf das Extension-Icon.

Badge + häufige Fehler

ON: verbunden; OpenClaw kann diesen Tab steuern.
…: verbindet sich mit dem lokalen Relay.
!: Relay nicht erreichbar (häufigster Grund: Browser-Relay-Server läuft nicht auf diesem Rechner).

Wenn du ! siehst:

Stelle sicher, dass das Gateway lokal läuft (Standard-Setup), oder starte einen Node-Host auf diesem Rechner, falls das Gateway woanders läuft.
Öffne die Extension-Optionsseite; sie zeigt an, ob der Relay erreichbar ist.

Remote-Gateway (Node-Host verwenden)

Lokales Gateway (gleicher Rechner wie Chrome) — normalerweise keine Extra-Schritte

Wenn das Gateway auf dem gleichen Rechner wie Chrome läuft, startet es den Browser Control Service auf Loopback und startet den Relay-Server automatisch. Die Extension kommuniziert mit dem lokalen Relay; die CLI/Tool-Aufrufe gehen ans Gateway.

Remote-Gateway (Gateway läuft woanders) — Node-Host starten

Wenn dein Gateway auf einem anderen Rechner läuft, starte einen Node-Host auf dem Rechner, auf dem Chrome läuft. Das Gateway leitet Browser-Aktionen an diesen Node weiter; Extension + Relay bleiben lokal auf dem Browser-Rechner.

Wenn mehrere Nodes verbunden sind, fixiere einen mit gateway.nodes.browser.node oder setze gateway.nodes.browser.mode.

Sandboxing (Tool-Container)

Wenn deine Agent-Session in einer Sandbox läuft (agents.defaults.sandbox.mode != "off"), kann das browser-Tool eingeschränkt sein:

Standardmäßig zielen Sandbox-Sessions oft auf den Sandbox-Browser (target="sandbox"), nicht auf dein Host-Chrome.
Die Chrome Extension Relay-Übernahme erfordert die Kontrolle über den Host-Browser-Control-Server.

Optionen:

Am einfachsten: Verwende die Extension aus einer nicht-gesandboxten Session/Agent.
Oder erlaube Host-Browser-Kontrolle für Sandbox-Sessions:

{
  agents: {
    defaults: {
      sandbox: {
        browser: {
          allowHostControl: true,
        },
      },
    },
  },
}

Stelle dann sicher, dass das Tool nicht durch die Tool-Policy blockiert wird, und rufe (falls nötig) browser mit target="host" auf.

Debugging: openclaw sandbox explain

Remote-Access-Tipps

Halte Gateway und Node-Host im gleichen Tailnet; vermeide es, Relay-Ports im LAN oder öffentlichen Internet freizugeben.
Verbinde Nodes gezielt; deaktiviere Browser-Proxy-Routing, wenn du keine Fernsteuerung möchtest (gateway.nodes.browser.mode="off").

Wie “extension path” funktioniert

openclaw browser extension path gibt das installierte On-Disk-Verzeichnis aus, das die Extension-Dateien enthält.

Die CLI gibt absichtlich keinen node_modules-Pfad aus. Führe immer zuerst openclaw browser extension install aus, um die Extension an einen stabilen Ort in deinem OpenClaw-State-Verzeichnis zu kopieren.

Wenn du dieses Installationsverzeichnis verschiebst oder löschst, markiert Chrome die Extension als defekt, bis du sie von einem gültigen Pfad neu lädst.

Sicherheitsaspekte (lies das)

Das ist mächtig und riskant. Behandle es so, als würdest du dem Modell “Hände auf deinen Browser” geben.

Die Extension verwendet Chromes Debugger-API (chrome.debugger). Wenn verbunden, kann das Modell:
- in diesem Tab klicken/tippen/navigieren
- Seiteninhalte lesen
- auf alles zugreifen, worauf die eingeloggte Session des Tabs zugreifen kann
Das ist nicht isoliert wie das dedizierte openclaw-verwaltete Profil.
- Wenn du dich mit deinem täglichen Profil/Tab verbindest, gewährst du Zugriff auf diesen Account-Status.

Empfehlungen:

Bevorzuge ein dediziertes Chrome-Profil (getrennt von deinem persönlichen Browsing) für die Extension-Relay-Nutzung.
Halte Gateway und alle Node-Hosts nur im Tailnet; verlasse dich auf Gateway-Auth + Node-Pairing.
Vermeide es, Relay-Ports über LAN (0.0.0.0) freizugeben, und vermeide Funnel (öffentlich).
Der Relay blockiert Nicht-Extension-Origins und erfordert ein internes Auth-Token für CDP-Clients.

Verwandte Themen:

Browser-Tool-Übersicht: Browser
Sicherheitsaudit: Security
Tailscale-Setup: Tailscale