Chrome Extension (Browser-Relay)

Die OpenClaw Chrome Extension lÀsst den Agenten deine bestehenden Chrome-Tabs (dein normales Chrome-Fenster) steuern, anstatt ein separates OpenClaw-verwaltetes Chrome-Profil zu starten.

An-/AbhĂ€ngen erfolgt ĂŒber einen einzigen Chrome-Toolbar-Button.

Wenn du stattdessen den offiziellen Chrome DevTools MCP Attach-Flow möchtest anstelle des OpenClaw Extension Relays, verwende ein existing-session-Browserprofil. Siehe Browser. FĂŒr Chromes eigene Setup-Dokumentation, siehe Chrome for Developers: Use Chrome DevTools MCP with your browser session und das Chrome DevTools MCP README.

Was es ist (Konzept)

Es gibt drei Teile:

  • Browser-Steuerungsdienst (Gateway oder Node): die API, die der Agent/das Tool aufruft (ĂŒber das Gateway)
  • Lokaler Relay-Server (Loopback-CDP): BrĂŒcke zwischen dem Steuerungsserver und der Extension (http://127.0.0.1:18792 standardmĂ€ĂŸig)
  • Chrome MV3 Extension: hĂ€ngt sich ĂŒber chrome.debugger an den aktiven Tab an und leitet CDP-Nachrichten an das Relay weiter

OpenClaw steuert dann den angehĂ€ngten Tab ĂŒber die normale browser-Tool-OberflĂ€che (mit Auswahl des richtigen Profils).

Installieren / Laden (entpackt)

  1. Extension an einem stabilen lokalen Pfad installieren:
openclaw browser extension install
  1. Den installierten Extension-Verzeichnispfad ausgeben:
openclaw browser extension path
  1. Chrome → chrome://extensions
  • „Entwicklermodus” aktivieren
  • „Entpackte Erweiterung laden” → das oben ausgegebene Verzeichnis auswĂ€hlen
  1. Extension anpinnen.

Updates (kein Build-Schritt)

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

Nach dem Upgrade von OpenClaw:

  • openclaw browser extension install erneut ausfĂŒhren, um die installierten Dateien unter deinem OpenClaw-Statusverzeichnis zu aktualisieren.
  • Chrome → chrome://extensions → bei der Extension auf „Neu laden” klicken.

Verwenden (Gateway-Token einmal setzen)

OpenClaw liefert ein eingebautes Browserprofil namens chrome mit, das auf das Extension Relay am Standard-Port zeigt.

Vor dem ersten AnhÀngen die Extension-Optionen öffnen und setzen:

  • Port (Standard 18792)
  • Gateway token (muss mit gateway.auth.token / OPENCLAW_GATEWAY_TOKEN ĂŒbereinstimmen)

Verwenden:

  • 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"

Benutzerdefinierte Gateway-Ports

Wenn du einen benutzerdefinierten Gateway-Port verwendest, wird der Extension Relay-Port automatisch abgeleitet:

Extension Relay Port = Gateway Port + 3

Beispiel: wenn gateway.port: 19001, dann:

  • Extension Relay-Port: 19004 (Gateway + 3)

Konfiguriere die Extension auf der Extension-Optionsseite, um den abgeleiteten Relay-Port zu verwenden.

AnhÀngen / Trennen (Toolbar-Button)

  • Öffne den Tab, den OpenClaw steuern soll.
  • Klicke auf das Extension-Symbol.
    • Badge zeigt ON, wenn angehĂ€ngt.
  • Erneut klicken zum Trennen.

Welchen Tab steuert es?

  • Es steuert nicht automatisch „den Tab, den du gerade anschaust”.
  • Es steuert nur den/die Tab(s), die du explizit angehĂ€ngt hast, indem du den Toolbar-Button geklickt hast.
  • Zum Wechseln: den anderen Tab öffnen und dort das Extension-Symbol klicken.

Badge + hÀufige Fehler

  • ON: angehĂ€ngt; OpenClaw kann diesen Tab steuern.
  • 
: verbindet sich mit dem lokalen Relay.
  • !: Relay nicht erreichbar/authentifiziert (hĂ€ufigster Grund: Relay-Server lĂ€uft nicht, oder Gateway-Token fehlt/falsch).

Wenn du ! siehst:

  • Stelle sicher, dass das Gateway lokal lĂ€uft (Standard-Setup), oder starte einen Node Host auf diesem Rechner, wenn das Gateway woanders lĂ€uft.
  • Öffne die Extension-Optionsseite; sie validiert Relay-Erreichbarkeit + Gateway-Token-Auth.

Remote-Gateway (Node Host verwenden)

Lokales Gateway (gleicher Rechner wie Chrome) — normalerweise keine zusĂ€tzlichen Schritte

Wenn das Gateway auf dem gleichen Rechner wie Chrome lÀuft, startet es den Browser-Steuerungsdienst auf Loopback und startet den Relay-Server automatisch. Die Extension kommuniziert mit dem lokalen Relay; CLI/Tool-Aufrufe gehen an das 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, der Chrome ausfĂŒhrt. Das Gateway leitet Browser-Aktionen an diesen Node weiter; die Extension + das Relay bleiben lokal auf dem Browser-Rechner.

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

Sandboxing (Tool-Container)

Wenn deine Agent-Sitzung gesandboxt ist (agents.defaults.sandbox.mode != "off"), kann das browser-Tool eingeschrÀnkt sein:

  • StandardmĂ€ĂŸig zielen gesandboxte Sitzungen oft auf den Sandbox-Browser (target="sandbox"), nicht auf dein Host-Chrome.
  • Chrome Extension Relay-Übernahme erfordert Steuerung des Host-Browser-Steuerungsservers.

Optionen:

  • Einfachste Lösung: die Extension aus einer nicht-gesandboxten Sitzung/Agent verwenden.
  • Oder Host-Browsersteuerung fĂŒr gesandboxte Sitzungen erlauben:
{
  agents: {
    defaults: {
      sandbox: {
        browser: {
          allowHostControl: true,
        },
      },
    },
  },
}

Dann sicherstellen, dass das Tool nicht durch Tool-Policy verweigert wird, und (falls nötig) browser mit target="host" aufrufen.

Debugging: openclaw sandbox explain

Remote-Zugriff-Tipps

  • Gateway und Node Host im selben Tailnet halten; Relay-Ports nicht ins LAN oder öffentliche Internet exponieren.
  • Nodes bewusst pairen; Browser-Proxy-Routing deaktivieren, wenn du keine Remote-Steuerung möchtest (gateway.nodes.browser.mode="off").
  • Das Relay standardmĂ€ĂŸig auf Loopback lassen, es sei denn, du hast einen echten Cross-Namespace-Bedarf. FĂŒr WSL2 oder Ă€hnliche Split-Host-Setups setze browser.relayBindHost auf eine explizite Bind-Adresse wie 0.0.0.0 und halte dabei den Zugriff mit Gateway-Auth, Node-Pairing und einem privaten Netzwerk eingeschrĂ€nkt.

Wie „extension path” funktioniert

openclaw browser extension path gibt den installierten Pfad auf der Festplatte aus, der 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 unter deinem OpenClaw-Statusverzeichnis 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.

Sicherheitsimplikationen (lies das)

Das ist mĂ€chtig und riskant. Behandle es so, als wĂŒrdest du dem Modell „HĂ€nde an deinem Browser” geben.

  • Die Extension nutzt Chromes Debugger-API (chrome.debugger). Wenn angehĂ€ngt, kann das Modell:
    • in diesem Tab klicken/tippen/navigieren
    • Seiteninhalt lesen
    • auf alles zugreifen, auf das die angemeldete Sitzung des Tabs Zugriff hat
  • Das ist nicht isoliert wie das dedizierte OpenClaw-verwaltete Profil.
    • Wenn du an dein Alltagsprofil/deinen Tab anhĂ€ngst, gewĂ€hrst du Zugriff auf diesen Kontostatus.

Empfehlungen:

  • Ein dediziertes Chrome-Profil (getrennt von deinem persönlichen Browsen) fĂŒr Extension Relay-Nutzung bevorzugen.
  • Gateway und Node Hosts Tailnet-only halten; auf Gateway-Auth + Node-Pairing setzen.
  • Relay-Ports nicht ĂŒber LAN (0.0.0.0) exponieren und kein Funnel (öffentlich) nutzen.
  • Das Relay blockiert Nicht-Extension-Origins und erfordert Gateway-Token-Auth sowohl fĂŒr /cdp als auch /extension.

Verwandt:

arrow_back
ZurĂŒck
Browser Login
Weiter
Browser Linux Troubleshooting
arrow_forward