Zum Hauptinhalt springen

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw kann ein dediziertes Chrome/Brave/Edge/Chromium-Profil ausführen, das der Agent steuert. Es ist von Ihrem persönlichen Browser getrennt und wird über einen kleinen lokalen Steuerungsdienst innerhalb des Gateway verwaltet (nur loopback). Einsteigeransicht:
  • Stellen Sie es sich als separaten Browser nur für Agents vor.
  • Das openclaw-Profil greift nicht auf Ihr persönliches Browser-Profil zu.
  • Der Agent kann in einem sicheren Bereich Tabs öffnen, Seiten lesen, klicken und tippen.
  • Das integrierte user-Profil verbindet sich über Chrome MCP mit Ihrer echten angemeldeten Chrome-Sitzung.

​
Was Sie erhalten

  • Ein separates Browser-Profil namens openclaw (standardmäßig mit orangefarbener Akzentfarbe).
  • Deterministische Tab-Steuerung (auflisten/öffnen/fokussieren/schließen).
  • Agent-Aktionen (klicken/tippen/ziehen/auswählen), Snapshots, Screenshots, PDFs.
  • Ein gebündeltes browser-automation-Skill, das Agents den Recovery-Loop für Snapshots, stabile Tabs, veraltete Referenzen und manuelle Blocker vermittelt, wenn das Browser- Plugin aktiviert ist.
  • Optionale Unterstützung für mehrere Profile (openclaw, work, remote, …).
Dieser Browser ist nicht Ihr Alltagsbrowser. Er ist eine sichere, isolierte Oberfläche für Agent-Automatisierung und Verifizierung.

​
Schnellstart

openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw doctor --deep
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
Wenn Sie „Browser disabled“ erhalten, aktivieren Sie ihn in der Konfiguration (siehe unten) und starten Sie den Gateway neu. Wenn openclaw browser vollständig fehlt oder der Agent meldet, dass das Browser-Tool nicht verfügbar ist, springen Sie zu Fehlender Browser-Befehl oder fehlendes Tool.

​
Plugin-Steuerung

Das standardmäßige browser-Tool ist ein gebündeltes Plugin. Deaktivieren Sie es, um es durch ein anderes Plugin zu ersetzen, das denselben browser-Toolnamen registriert: 
{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}
Für Standardwerte sind sowohl plugins.entries.browser.enabled als auch browser.enabled=true erforderlich. Wenn nur das Plugin deaktiviert wird, werden die openclaw browser-CLI, die Gateway-Methode browser.request, das Agent-Tool und der Steuerungsdienst als eine Einheit entfernt; Ihre browser.*-Konfiguration bleibt für einen Ersatz erhalten. Änderungen an der Browser-Konfiguration erfordern einen Gateway-Neustart, damit das Plugin seinen Dienst erneut registrieren kann.

​
Agent-Anleitung

Hinweis zum Tool-Profil: tools.profile: "coding" enthält web_search und web_fetch, aber nicht das vollständige browser-Tool. Wenn der Agent oder ein gestarteter Sub-Agent Browser-Automatisierung verwenden soll, fügen Sie Browser in der Profilphase hinzu: 
{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}
Verwenden Sie für einen einzelnen Agent agents.list[].tools.alsoAllow: ["browser"]. tools.subagents.tools.allow: ["browser"] allein reicht nicht aus, da die Sub-Agent- Richtlinie nach der Profilfilterung angewendet wird. Das Browser-Plugin liefert zwei Ebenen von Agent-Anleitungen:
  • Die Beschreibung des browser-Tools enthält den kompakten, immer aktiven Vertrag: das richtige Profil wählen, Referenzen auf demselben Tab halten, tabId/Labels für die Tab-Zielauswahl verwenden und das Browser-Skill für mehrstufige Arbeit laden.
  • Das gebündelte browser-automation-Skill enthält den längeren Arbeitsablauf: zuerst Status/Tabs prüfen, Aufgaben-Tabs labeln, vor Aktionen einen Snapshot erstellen, nach UI-Änderungen erneut einen Snapshot erstellen, veraltete Referenzen einmal wiederherstellen und Login/2FA/Captcha- oder Kamera/Mikrofon-Blocker als manuelle Aktion melden, statt zu raten.
Vom Plugin gebündelte Skills werden in den verfügbaren Skills des Agent aufgeführt, wenn das Plugin aktiviert ist. Die vollständigen Skill-Anweisungen werden bei Bedarf geladen, sodass Routine- Turns nicht die vollen Token-Kosten verursachen.

​
Fehlender Browser-Befehl oder fehlendes Tool

Wenn openclaw browser nach einem Upgrade unbekannt ist, browser.request fehlt oder der Agent meldet, dass das Browser-Tool nicht verfügbar ist, ist die übliche Ursache eine plugins.allow-Liste, die browser auslässt und kein Root-browser-Konfigurationsblock existiert. Fügen Sie ihn hinzu: 
{
  plugins: {
    allow: ["telegram", "browser"],
  },
}
Ein expliziter Root-browser-Block, zum Beispiel browser.enabled=true oder browser.profiles.<name>, aktiviert das gebündelte Browser-Plugin auch bei restriktivem plugins.allow, entsprechend dem Verhalten der Channel-Konfiguration. plugins.entries.browser.enabled=true und tools.alsoAllow: ["browser"] ersetzen für sich genommen keine Mitgliedschaft in der Allowlist. Das vollständige Entfernen von plugins.allow stellt ebenfalls den Standard wieder her.

​
Profile: openclaw vs. user

  • openclaw: verwalteter, isolierter Browser (keine Erweiterung erforderlich).
  • user: integriertes Chrome-MCP-Anhängeprofil für Ihre echte angemeldete Chrome- Sitzung.
Für Browser-Toolaufrufe des Agent:
  • Standard: Verwenden Sie den isolierten openclaw-Browser.
  • Bevorzugen Sie profile="user", wenn vorhandene angemeldete Sitzungen wichtig sind und der Benutzer am Computer ist, um eine Anhängeaufforderung anzuklicken/zu genehmigen.
  • profile ist die explizite Überschreibung, wenn Sie einen bestimmten Browser-Modus wünschen.
Setzen Sie browser.defaultProfile: "openclaw", wenn Sie den verwalteten Modus standardmäßig verwenden möchten.

​
Konfiguration

Browser-Einstellungen befinden sich in ~/.openclaw/openclaw.json. 
{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms)
    localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms)
    actionTimeoutMs: 60000, // default browser act timeout (ms)
    tabCleanup: {
      enabled: true, // default: true
      idleMinutes: 120, // set 0 to disable idle cleanup
      maxTabsPerSession: 8, // set 0 to disable the per-session cap
      sweepMinutes: 5,
    },
    defaultProfile: "openclaw",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: {
        cdpPort: 18801,
        color: "#0066CC",
        headless: true,
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}
  • Der Steuerungsdienst bindet an loopback auf einem Port, der aus gateway.port abgeleitet wird (Standard 18791 = Gateway + 2). Das Überschreiben von gateway.port oder OPENCLAW_GATEWAY_PORT verschiebt die abgeleiteten Ports in derselben Familie.
  • Lokale openclaw-Profile weisen cdpPort/cdpUrl automatisch zu; setzen Sie diese nur für Remote-CDP. cdpUrl verwendet standardmäßig den verwalteten lokalen CDP-Port, wenn es nicht gesetzt ist.
  • remoteCdpTimeoutMs gilt für Remote- und attachOnly-CDP-HTTP-Erreichbarkeits- prüfungen sowie HTTP-Anfragen zum Öffnen von Tabs; remoteCdpHandshakeTimeoutMs gilt für deren CDP-WebSocket-Handshakes.
  • localLaunchTimeoutMs ist das Zeitbudget, damit ein lokal gestarteter verwalteter Chrome- Prozess seinen CDP-HTTP-Endpunkt bereitstellt. localCdpReadyTimeoutMs ist das anschließende Budget für die CDP-WebSocket-Bereitschaft, nachdem der Prozess erkannt wurde. Erhöhen Sie diese Werte auf Raspberry Pi, Low-End-VPS oder älterer Hardware, auf der Chromium langsam startet. Werte müssen positive ganze Zahlen bis 120000 ms sein; ungültige Konfigurationswerte werden abgelehnt.
  • Wiederholte Fehler beim Starten/Bereitwerden von verwaltetem Chrome werden pro Profil per Circuit Breaker unterbrochen. Nach mehreren aufeinanderfolgenden Fehlern pausiert OpenClaw neue Start- versuche kurz, statt Chromium bei jedem Browser-Toolaufruf zu starten. Beheben Sie das Startproblem, deaktivieren Sie den Browser, wenn er nicht benötigt wird, oder starten Sie den Gateway nach der Reparatur neu.
  • actionTimeoutMs ist das Standardbudget für Browser-act-Anfragen, wenn der Aufrufer kein timeoutMs übergibt. Der Client-Transport fügt ein kleines Pufferfenster hinzu, damit lange Wartezeiten abgeschlossen werden können, statt an der HTTP-Grenze abzulaufen.
  • tabCleanup ist eine Best-Effort-Bereinigung für Tabs, die von Browser-Sitzungen des primären Agent geöffnet wurden. Sub-Agent-, Cron- und ACP-Lifecycle-Bereinigung schließen weiterhin ihre explizit verfolgten Tabs am Sitzungsende; primäre Sitzungen halten aktive Tabs wiederverwendbar und schließen dann inaktive oder überschüssige verfolgte Tabs im Hintergrund.
  • Browser-Navigation und das Öffnen von Tabs werden vor der Navigation per SSRF geschützt und anschließend auf der finalen http(s)-URL best-effort erneut geprüft.
  • Im strikten SSRF-Modus werden auch Remote-CDP-Endpunkterkennung und /json/version-Probes (cdpUrl) geprüft.
  • Gateway/Provider-Umgebungsvariablen HTTP_PROXY, HTTPS_PROXY, ALL_PROXY und NO_PROXY proxen den von OpenClaw verwalteten Browser nicht automatisch. Verwaltetes Chrome startet standardmäßig direkt, damit Provider-Proxy-Einstellungen die Browser-SSRF-Prüfungen nicht schwächen.
  • Um den verwalteten Browser selbst zu proxen, übergeben Sie explizite Chrome-Proxy-Flags über browser.extraArgs, zum Beispiel --proxy-server=... oder --proxy-pac-url=.... Der strikte SSRF-Modus blockiert explizites Browser-Proxy-Routing, sofern privater Netzwerkzugriff des Browsers nicht absichtlich aktiviert ist.
  • browser.ssrfPolicy.dangerouslyAllowPrivateNetwork ist standardmäßig aus; aktivieren Sie es nur, wenn privater Netzwerkzugriff des Browsers absichtlich vertrauenswürdig ist.
  • browser.ssrfPolicy.allowPrivateNetwork bleibt als Legacy-Alias unterstützt.
  • attachOnly: true bedeutet: Niemals einen lokalen Browser starten; nur verbinden, wenn bereits einer ausgeführt wird.
  • headless kann global oder pro lokal verwaltetem Profil gesetzt werden. Profilbezogene Werte überschreiben browser.headless, sodass ein lokal gestartetes Profil im Headless-Modus bleiben kann, während ein anderes sichtbar bleibt.
  • POST /start?headless=true und openclaw browser start --headless fordern einen einmaligen Headless-Start für lokal verwaltete Profile an, ohne browser.headless oder die Profilkonfiguration umzuschreiben. Existing-session-, Attach-only- und Remote-CDP-Profile lehnen die Überschreibung ab, weil OpenClaw diese Browserprozesse nicht startet.
  • Auf Linux-Hosts ohne DISPLAY oder WAYLAND_DISPLAY wechseln lokal verwaltete Profile automatisch standardmäßig in den Headless-Modus, wenn weder die Umgebung noch die profilbezogene/globale Konfiguration explizit den sichtbaren Modus auswählt. openclaw browser status --json meldet headlessSource als env, profile, config, request, linux-display-fallback oder default.
  • OPENCLAW_BROWSER_HEADLESS=1 erzwingt Headless-Starts lokal verwalteter Browser für den aktuellen Prozess. OPENCLAW_BROWSER_HEADLESS=0 erzwingt den sichtbaren Modus für normale Starts und gibt auf Linux-Hosts ohne Display-Server einen handlungsorientierten Fehler zurück; eine explizite Anforderung mit start --headless hat für genau diesen einen Start weiterhin Vorrang.
  • executablePath kann global oder pro lokal verwaltetem Profil gesetzt werden. Profilbezogene Werte überschreiben browser.executablePath, sodass verschiedene verwaltete Profile unterschiedliche Chromium-basierte Browser starten können. Beide Formen akzeptieren ~ für das Home-Verzeichnis Ihres Betriebssystems.
  • color (auf oberster Ebene und pro Profil) färbt die Browser-UI ein, damit Sie sehen können, welches Profil aktiv ist.
  • Das Standardprofil ist openclaw (verwaltet, eigenständig). Verwenden Sie defaultProfile: "user", um den angemeldeten Benutzerbrowser zu verwenden.
  • Automatische Erkennungsreihenfolge: Systemstandardbrowser, wenn Chromium-basiert; andernfalls Chrome → Brave → Edge → Chromium → Chrome Canary.
  • driver: "existing-session" verwendet Chrome DevTools MCP statt rohem CDP. Setzen Sie für diesen Treiber nicht cdpUrl.
  • Setzen Sie browser.profiles.<name>.userDataDir, wenn sich ein Existing-session-Profil mit einem nicht standardmäßigen Chromium-Benutzerprofil verbinden soll (Brave, Edge usw.). Dieser Pfad akzeptiert ebenfalls ~ für das Home-Verzeichnis Ihres Betriebssystems.

​
Brave oder einen anderen Chromium-basierten Browser verwenden

Wenn Ihr Systemstandardbrowser Chromium-basiert ist (Chrome/Brave/Edge/usw.), verwendet OpenClaw ihn automatisch. Setzen Sie browser.executablePath, um die automatische Erkennung zu überschreiben. executablePath-Werte auf oberster Ebene und pro Profil akzeptieren ~ für das Home-Verzeichnis Ihres Betriebssystems: 
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
Oder setzen Sie es in der Konfiguration, je Plattform: 
{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
  },
}
Profilbezogenes executablePath wirkt sich nur auf lokal verwaltete Profile aus, die OpenClaw startet. existing-session-Profile verbinden sich stattdessen mit einem bereits laufenden Browser, und Remote-CDP-Profile verwenden den Browser hinter cdpUrl.

​
Lokale und entfernte Steuerung

  • Lokale Steuerung (Standard): Der Gateway startet den loopback-Steuerungsdienst und kann einen lokalen Browser starten.
  • Entfernte Steuerung (Node-Host): Führen Sie einen Node-Host auf dem Computer aus, auf dem sich der Browser befindet; der Gateway proxyt Browseraktionen an ihn.
  • Remote-CDP: Setzen Sie browser.profiles.<name>.cdpUrl (oder browser.cdpUrl), um sich mit einem entfernten Chromium-basierten Browser zu verbinden. In diesem Fall startet OpenClaw keinen lokalen Browser.
  • Setzen Sie für extern verwaltete CDP-Dienste auf loopback (zum Beispiel Browserless in Docker, veröffentlicht auf 127.0.0.1) auch attachOnly: true. Loopback-CDP ohne attachOnly wird als lokal von OpenClaw verwaltetes Browserprofil behandelt.
  • headless wirkt sich nur auf lokal verwaltete Profile aus, die OpenClaw startet. Es startet keine Existing-session- oder Remote-CDP-Browser neu und ändert sie auch nicht.
  • executablePath folgt derselben Regel für lokal verwaltete Profile. Wenn Sie es bei einem laufenden lokal verwalteten Profil ändern, wird dieses Profil für Neustart/Abgleich markiert, sodass der nächste Start die neue Binärdatei verwendet.
Das Stoppverhalten unterscheidet sich je nach Profilmodus:
  • lokal verwaltete Profile: openclaw browser stop stoppt den Browserprozess, den OpenClaw gestartet hat
  • Attach-only- und Remote-CDP-Profile: openclaw browser stop schließt die aktive Steuerungssitzung und gibt Playwright-/CDP-Emulationsüberschreibungen frei (Viewport, Farbschema, Locale, Zeitzone, Offlinemodus und ähnlichen Zustand), auch wenn kein Browserprozess von OpenClaw gestartet wurde
Remote-CDP-URLs können Authentifizierung enthalten:
  • Abfragetoken (z. B. https://provider.example?token=<token>)
  • HTTP Basic Auth (z. B. https://user:pass@provider.example)
OpenClaw behält die Authentifizierung beim Aufruf von /json/*-Endpunkten und beim Verbinden mit dem CDP-WebSocket bei. Verwenden Sie für Token vorzugsweise Umgebungsvariablen oder Secret-Manager, statt sie in Konfigurationsdateien zu committen.

​
Node-Browser-Proxy (Zero-Config-Standard)

Wenn Sie einen Node-Host auf dem Computer ausführen, auf dem sich Ihr Browser befindet, kann OpenClaw Browser-Tool-Aufrufe automatisch ohne zusätzliche Browserkonfiguration an diesen Node weiterleiten. Dies ist der Standardpfad für entfernte Gateways. Hinweise:
  • Der Node-Host stellt seinen lokalen Browser-Steuerungsserver über einen Proxy-Befehl bereit.
  • Profile stammen aus der eigenen browser.profiles-Konfiguration des Node (wie lokal).
  • nodeHost.browserProxy.allowProfiles ist optional. Lassen Sie es leer, um das Legacy-/Standardverhalten zu verwenden: Alle konfigurierten Profile bleiben über den Proxy erreichbar, einschließlich Routen zum Erstellen/Löschen von Profilen.
  • Wenn Sie nodeHost.browserProxy.allowProfiles setzen, behandelt OpenClaw dies als Least-Privilege-Grenze: Nur Profile auf der Allowlist können als Ziel verwendet werden, und persistente Routen zum Erstellen/Löschen von Profilen werden auf der Proxy-Oberfläche blockiert.
  • Deaktivieren Sie es, wenn Sie es nicht verwenden möchten:
    • Auf dem Node: nodeHost.browserProxy.enabled=false
    • Auf dem Gateway: gateway.nodes.browser.mode="off"

​
Browserless (gehostetes Remote-CDP)

Browserless ist ein gehosteter Chromium-Dienst, der CDP-Verbindungs-URLs über HTTPS und WebSocket bereitstellt. OpenClaw kann beide Formen verwenden, aber für ein entferntes Browserprofil ist die einfachste Option die direkte WebSocket-URL aus den Verbindungsdokumenten von Browserless. Beispiel: 
{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}
Hinweise:
  • Ersetzen Sie <BROWSERLESS_API_KEY> durch Ihr echtes Browserless-Token.
  • Wählen Sie den Regionsendpunkt, der zu Ihrem Browserless-Konto passt (siehe deren Dokumentation).
  • Wenn Browserless Ihnen eine HTTPS-Basis-URL gibt, können Sie sie entweder für eine direkte CDP-Verbindung in wss:// umwandeln oder die HTTPS-URL beibehalten und OpenClaw /json/version erkennen lassen.

​
Browserless Docker auf demselben Host

Wenn Browserless selbst gehostet in Docker läuft und OpenClaw auf dem Host ausgeführt wird, behandeln Sie Browserless als extern verwalteten CDP-Dienst: 
{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "ws://127.0.0.1:3000",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}
Die Adresse in browser.profiles.browserless.cdpUrl muss vom OpenClaw-Prozess aus erreichbar sein. Browserless muss außerdem einen passenden erreichbaren Endpunkt ankündigen; setzen Sie Browserless EXTERNAL auf dieselbe öffentliche, für OpenClaw erreichbare WebSocket-Basis, etwa ws://127.0.0.1:3000, ws://browserless:3000 oder eine stabile private Docker- Netzwerkadresse. Wenn /json/version ein webSocketDebuggerUrl zurückgibt, das auf eine Adresse verweist, die OpenClaw nicht erreichen kann, kann CDP HTTP fehlerfrei aussehen, während die WebSocket- Verbindung dennoch fehlschlägt. Lassen Sie attachOnly für ein loopback-Browserless-Profil nicht ungesetzt. Ohne attachOnly behandelt OpenClaw den loopback-Port als lokal verwaltetes Browserprofil und meldet möglicherweise, dass der Port belegt ist, aber nicht OpenClaw gehört.

​
Direkte WebSocket-CDP-Provider

Einige gehostete Browserdienste stellen einen direkten WebSocket-Endpunkt statt der standardmäßigen HTTP-basierten CDP-Erkennung (/json/version) bereit. OpenClaw akzeptiert drei CDP-URL-Formen und wählt automatisch die passende Verbindungsstrategie aus:
  • HTTP(S)-Erkennung - http://host[:port] oder https://host[:port]. OpenClaw ruft /json/version auf, um die WebSocket-Debugger-URL zu erkennen, und verbindet sich dann. Kein WebSocket-Fallback.
  • Direkte WebSocket-Endpunkte - ws://host[:port]/devtools/<kind>/<id> oder wss://... mit einem /devtools/browser|page|worker|shared_worker|service_worker/<id>- Pfad. OpenClaw verbindet sich direkt über einen WebSocket-Handshake und überspringt /json/version vollständig.
  • Bloße WebSocket-Roots - ws://host[:port] oder wss://host[:port] ohne /devtools/...-Pfad (z. B. Browserless, Browserbase). OpenClaw versucht zuerst die HTTP- Erkennung über /json/version (mit Normalisierung des Schemas zu http/https); wenn die Erkennung ein webSocketDebuggerUrl zurückgibt, wird es verwendet, andernfalls fällt OpenClaw auf einen direkten WebSocket-Handshake an der bloßen Root zurück. Wenn der angekündigte WebSocket-Endpunkt den CDP-Handshake ablehnt, aber die konfigurierte bloße Root ihn akzeptiert, fällt OpenClaw ebenfalls auf diese Root zurück. Dadurch kann eine bloße ws://- URL, die auf einen lokalen Chrome zeigt, weiterhin verbinden, da Chrome WebSocket- Upgrades nur auf dem spezifischen Zielpfad aus /json/version akzeptiert, während gehostete Provider weiterhin ihren Root-WebSocket-Endpunkt verwenden können, wenn ihr Erkennungs- Endpunkt eine kurzlebige URL ankündigt, die für Playwright CDP nicht geeignet ist.

​
Browserbase

Browserbase ist eine Cloud-Plattform zum Ausführen von Headless-Browsern mit integrierter CAPTCHA-Lösung, Stealth-Modus und Residential Proxys. 
{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}
Hinweise:
  • Registrieren Sie sich und kopieren Sie Ihren API Key aus dem Übersichts-Dashboard.
  • Ersetzen Sie <BROWSERBASE_API_KEY> durch Ihren echten Browserbase-API-Schlüssel.
  • Browserbase erstellt beim WebSocket-Verbindungsaufbau automatisch eine Browsersitzung, daher ist kein manueller Schritt zur Sitzungserstellung erforderlich.
  • Die kostenlose Stufe erlaubt eine gleichzeitige Sitzung und eine Browserstunde pro Monat. Siehe Preise für Limits kostenpflichtiger Tarife.
  • Siehe die Browserbase-Dokumentation für vollständige API- Referenz, SDK-Anleitungen und Integrationsbeispiele.

​
Sicherheit

Kernideen:
  • Browsersteuerung ist nur über local loopback erreichbar; der Zugriff läuft über die Authentifizierung des Gateway oder über Node-Pairing.
  • Die eigenständige HTTP-API für den local loopback-Browser verwendet ausschließlich Shared-Secret-Auth: Gateway-Token-Bearer-Auth, x-openclaw-password oder HTTP Basic Auth mit dem konfigurierten Gateway-Passwort.
  • Tailscale Serve-Identity-Header und gateway.auth.mode: "trusted-proxy" authentifizieren diese eigenständige API für den local loopback-Browser nicht.
  • Wenn Browsersteuerung aktiviert ist und keine Shared-Secret-Auth konfiguriert ist, generiert OpenClaw für diesen Start ein nur zur Laufzeit gültiges Gateway-Token. Konfigurieren Sie gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN oder OPENCLAW_GATEWAY_PASSWORD ausdrücklich, wenn Clients über Neustarts hinweg ein stabiles Secret benötigen.
  • OpenClaw generiert dieses Token nicht automatisch, wenn gateway.auth.mode bereits password, none oder trusted-proxy ist.
  • Halten Sie den Gateway und alle Node-Hosts in einem privaten Netzwerk (Tailscale); vermeiden Sie öffentliche Erreichbarkeit.
  • Behandeln Sie entfernte CDP-URLs/-Token als Secrets; bevorzugen Sie Umgebungsvariablen oder einen Secret-Manager.
Tipps zu entferntem CDP:
  • Bevorzugen Sie verschlüsselte Endpunkte (HTTPS oder WSS) und kurzlebige Token, wo möglich.
  • Vermeiden Sie es, langlebige Token direkt in Konfigurationsdateien einzubetten.

​
Profile (mehrere Browser)

OpenClaw unterstützt mehrere benannte Profile (Routing-Konfigurationen). Profile können sein:
  • openclaw-managed: eine dedizierte Chromium-basierte Browserinstanz mit eigenem Benutzerdatenverzeichnis + CDP-Port
  • remote: eine explizite CDP-URL (Chromium-basierter Browser, der anderswo läuft)
  • bestehende Sitzung: Ihr vorhandenes Chrome-Profil über die automatische Verbindung von Chrome DevTools MCP
Standardeinstellungen:
  • Das Profil openclaw wird automatisch erstellt, falls es fehlt.
  • Das Profil user ist für das Anhängen an eine bestehende Sitzung per Chrome MCP integriert.
  • Profile für bestehende Sitzungen sind über user hinaus optional; erstellen Sie sie mit --driver existing-session.
  • Lokale CDP-Ports werden standardmäßig aus 18800-18899 zugewiesen.
  • Beim Löschen eines Profils wird sein lokales Datenverzeichnis in den Papierkorb verschoben.
Alle Steuerungsendpunkte akzeptieren ?profile=<name>; die CLI verwendet --browser-profile.

​
Bestehende Sitzung über Chrome DevTools MCP

OpenClaw kann auch über den offiziellen Chrome DevTools MCP-Server an ein laufendes Chromium-basiertes Browserprofil anhängen. Dadurch werden die Tabs und der Anmeldestatus wiederverwendet, die in diesem Browserprofil bereits geöffnet sind. Offizielle Hintergrund- und Einrichtungsreferenzen: Integriertes Profil:
  • user
Optional: Erstellen Sie Ihr eigenes benutzerdefiniertes Profil für eine bestehende Sitzung, wenn Sie einen anderen Namen, eine andere Farbe oder ein anderes Browserdatenverzeichnis wünschen. Standardverhalten:
  • Das integrierte Profil user verwendet die automatische Verbindung von Chrome MCP, die auf das standardmäßige lokale Google Chrome-Profil abzielt.
Verwenden Sie userDataDir für Brave, Edge, Chromium oder ein nicht standardmäßiges Chrome-Profil. ~ wird zu Ihrem Home-Verzeichnis des Betriebssystems erweitert: 
{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}
Dann im passenden Browser:
  1. Öffnen Sie die Inspect-Seite dieses Browsers für Remote-Debugging.
  2. Aktivieren Sie Remote-Debugging.
  3. Lassen Sie den Browser laufen und bestätigen Sie die Verbindungsaufforderung, wenn OpenClaw anhängt.
Gängige Inspect-Seiten:
  • Chrome: chrome://inspect/#remote-debugging
  • Brave: brave://inspect/#remote-debugging
  • Edge: edge://inspect/#remote-debugging
Live-Anhang-Smoke-Test: 
openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai
So sieht Erfolg aus:
  • status zeigt driver: existing-session
  • status zeigt transport: chrome-mcp
  • status zeigt running: true
  • tabs listet Ihre bereits geöffneten Browser-Tabs auf
  • snapshot gibt Refs aus dem ausgewählten Live-Tab zurück
Was Sie prüfen sollten, wenn das Anhängen nicht funktioniert:
  • der Zielbrowser auf Chromium-Basis hat Version 144+
  • Remote-Debugging ist auf der Inspect-Seite dieses Browsers aktiviert
  • der Browser hat die Zustimmungsaufforderung zum Anhängen angezeigt und Sie haben sie akzeptiert
  • openclaw doctor migriert alte extension-basierte Browserkonfiguration und prüft, dass Chrome für standardmäßige Profile mit automatischer Verbindung lokal installiert ist, kann jedoch Remote-Debugging auf Browserseite nicht für Sie aktivieren
Agent-Nutzung:
  • Verwenden Sie profile="user", wenn Sie den angemeldeten Browserzustand des Benutzers benötigen.
  • Wenn Sie ein benutzerdefiniertes Profil für eine bestehende Sitzung verwenden, übergeben Sie diesen expliziten Profilnamen.
  • Wählen Sie diesen Modus nur, wenn der Benutzer am Computer ist, um die Aufforderung zum Anhängen zu bestätigen.
  • der Gateway oder Node-Host kann npx chrome-devtools-mcp@latest --autoConnect starten
Hinweise:
  • Dieser Pfad ist riskanter als das isolierte Profil openclaw, weil er in Ihrer angemeldeten Browsersitzung handeln kann.
  • OpenClaw startet den Browser für diesen Treiber nicht; es hängt nur an.
  • OpenClaw verwendet hier den offiziellen Chrome DevTools MCP-Flow --autoConnect. Wenn userDataDir gesetzt ist, wird es durchgereicht, um dieses Benutzerdatenverzeichnis anzuzielen.
  • Bestehende Sitzungen können auf dem ausgewählten Host oder über einen verbundenen Browser-Node anhängen. Wenn Chrome anderswo läuft und kein Browser-Node verbunden ist, verwenden Sie stattdessen Remote-CDP oder einen Node-Host.

​
Benutzerdefinierter Chrome MCP-Start

Überschreiben Sie den gestarteten Chrome DevTools MCP-Server pro Profil, wenn der Standard-Flow npx chrome-devtools-mcp@latest nicht Ihren Anforderungen entspricht (Offline-Hosts, fixierte Versionen, vendored Binaries):
FeldWas es bewirkt
mcpCommandAusführbare Datei, die statt npx gestartet wird. Wird unverändert aufgelöst; absolute Pfade werden berücksichtigt.
mcpArgsArgument-Array, das unverändert an mcpCommand übergeben wird. Ersetzt die Standardargumente chrome-devtools-mcp@latest --autoConnect.
Wenn cdpUrl in einem Profil für eine bestehende Sitzung gesetzt ist, überspringt OpenClaw --autoConnect und leitet den Endpunkt automatisch an Chrome MCP weiter:
  • http(s)://... → --browserUrl <url> (DevTools-HTTP-Discovery-Endpunkt).
  • ws(s)://... → --wsEndpoint <url> (direkter CDP-WebSocket).
Endpunkt-Flags und userDataDir können nicht kombiniert werden: Wenn cdpUrl gesetzt ist, wird userDataDir für den Chrome MCP-Start ignoriert, da Chrome MCP an den laufenden Browser hinter dem Endpunkt anhängt, statt ein Profilverzeichnis zu öffnen.
Im Vergleich zum verwalteten Profil openclaw sind Treiber für bestehende Sitzungen stärker eingeschränkt:
  • Screenshots - Seitenerfassungen und --ref-Elementerfassungen funktionieren; CSS---element-Selektoren nicht. --full-page kann nicht mit --ref oder --element kombiniert werden. Playwright ist für Seiten- oder ref-basierte Element-Screenshots nicht erforderlich.
  • Aktionen - click, type, hover, scrollIntoView, drag und select erfordern Snapshot-Refs (keine CSS-Selektoren). click-coords klickt sichtbare Viewport-Koordinaten und erfordert keine Snapshot-Ref. click ist nur die linke Maustaste. type unterstützt slowly=true nicht; verwenden Sie fill oder press. press unterstützt delayMs nicht. type, hover, scrollIntoView, drag, select, fill und evaluate unterstützen keine Timeouts pro Aufruf. select akzeptiert einen einzelnen Wert.
  • Warten / Upload / Dialog - wait --url unterstützt exakte Muster, Teilzeichenfolgen und Glob-Muster; wait --load networkidle wird nicht unterstützt. Upload-Hooks erfordern ref oder inputRef, jeweils eine Datei, kein CSS-element. Dialog-Hooks unterstützen keine Timeout-Überschreibungen.
  • Nur verwaltete Funktionen - Batch-Aktionen, PDF-Export, Download-Interception und responsebody erfordern weiterhin den verwalteten Browserpfad.

​
Isolationsgarantien

  • Dediziertes Benutzerdatenverzeichnis: berührt niemals Ihr persönliches Browserprofil.
  • Dedizierte Ports: vermeidet 9222, um Kollisionen mit Entwicklungsworkflows zu verhindern.
  • Deterministische Tab-Steuerung: tabs gibt zuerst suggestedTargetId zurück, dann stabile tabId-Handles wie t1, optionale Labels und die rohe targetId. Agents sollten suggestedTargetId wiederverwenden; rohe IDs bleiben für Debugging und Kompatibilität verfügbar.

​
Browserauswahl

Beim lokalen Start wählt OpenClaw den ersten verfügbaren:
  1. Chrome
  2. Brave
  3. Edge
  4. Chromium
  5. Chrome Canary
Sie können dies mit browser.executablePath überschreiben. Plattformen:
  • macOS: prüft /Applications und ~/Applications.
  • Linux: prüft gängige Chrome/Brave/Edge/Chromium-Speicherorte unter /usr/bin, /snap/bin, /opt/google, /opt/brave.com, /usr/lib/chromium und /usr/lib/chromium-browser sowie Playwright-verwaltetes Chromium unter PLAYWRIGHT_BROWSERS_PATH oder ~/.cache/ms-playwright.
  • Windows: prüft gängige Installationsorte.

​
Steuerungs-API (optional)

Für Skripting und Debugging stellt der Gateway eine kleine, nur über local loopback erreichbare HTTP-Steuerungs-API sowie eine passende openclaw browser-CLI bereit (Snapshots, Refs, Wait-Power-ups, JSON-Ausgabe, Debug-Workflows). Die vollständige Referenz finden Sie unter Browsersteuerungs-API.

​
Fehlerbehebung

Linux-spezifische Probleme (insbesondere snap Chromium) finden Sie unter Browser-Fehlerbehebung. Für Split-Host-Setups mit WSL2 Gateway + Windows Chrome siehe Fehlerbehebung für WSL2 + Windows + Remote-Chrome-CDP.

​
CDP-Startfehler vs. Navigations-SSRF-Blockierung

Dies sind unterschiedliche Fehlerklassen, und sie verweisen auf unterschiedliche Codepfade.
  • CDP-Start- oder Bereitschaftsfehler bedeutet, dass OpenClaw nicht bestätigen kann, dass die Browsersteuerungsebene funktionsfähig ist.
  • Navigations-SSRF-Blockierung bedeutet, dass die Browsersteuerungsebene funktionsfähig ist, ein Seitennavigationsziel jedoch per Richtlinie abgelehnt wird.
Gängige Beispiele:
  • CDP-Start- oder Bereitschaftsfehler:
    • Chrome CDP websocket for profile "openclaw" is not reachable after start
    • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
    • Port <port> is in use for profile "<name>" but not by openclaw, wenn ein externer CDP-Dienst über local loopback ohne attachOnly: true konfiguriert ist
  • Navigations-SSRF-Blockierung:
    • open-, navigate-, Snapshot- oder Tab-Öffnungs-Flows schlagen mit einem Browser-/Netzwerkrichtlinienfehler fehl, während start und tabs weiterhin funktionieren
Verwenden Sie diese minimale Sequenz, um die beiden zu trennen: 
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com
So interpretieren Sie die Ergebnisse:
  • Wenn start mit not reachable after start fehlschlägt, beheben Sie zuerst die CDP-Bereitschaft.
  • Wenn start erfolgreich ist, aber tabs fehlschlägt, ist die Steuerungsebene weiterhin fehlerhaft. Behandeln Sie dies als CDP-Erreichbarkeitsproblem, nicht als Seitennavigationsproblem.
  • Wenn start und tabs erfolgreich sind, aber open oder navigate fehlschlägt, läuft die Browsersteuerungsebene, und der Fehler liegt in der Navigationsrichtlinie oder auf der Zielseite.
  • Wenn start, tabs und open alle erfolgreich sind, ist der grundlegende Steuerungspfad für verwaltete Browser funktionsfähig.
Wichtige Verhaltensdetails:
  • Die Browserkonfiguration verwendet standardmäßig ein Fail-Closed-SSRF-Richtlinienobjekt, selbst wenn Sie browser.ssrfPolicy nicht konfigurieren.
  • Für das lokale verwaltete Profil openclaw über local loopback überspringen CDP-Integritätsprüfungen absichtlich die Browser-SSRF-Erreichbarkeitserzwingung für OpenClaws eigene lokale Steuerungsebene.
  • Navigationsschutz ist getrennt. Ein erfolgreiches Ergebnis von start oder tabs bedeutet nicht, dass ein späteres Ziel für open oder navigate zulässig ist.
Sicherheitsleitfaden:
  • Lockern Sie die Browser-SSRF-Richtlinie nicht standardmäßig.
  • Bevorzugen Sie enge Host-Ausnahmen wie hostnameAllowlist oder allowedHostnames gegenüber breitem Zugriff auf private Netzwerke.
  • Verwenden Sie dangerouslyAllowPrivateNetwork: true nur in bewusst vertrauenswürdigen Umgebungen, in denen Browser-Zugriff auf private Netzwerke erforderlich und geprüft ist.

​
Agentenwerkzeuge + Funktionsweise der Steuerung

Der Agent erhält ein Werkzeug für Browser-Automatisierung:
  • browser - doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
Zuordnung:
  • browser snapshot gibt einen stabilen UI-Baum zurück (AI oder ARIA).
  • browser act verwendet die ref-IDs des Snapshots zum Klicken/Tippen/Ziehen/Auswählen.
  • browser screenshot erfasst Pixel (ganze Seite, Element oder beschriftete Referenzen).
  • browser doctor prüft Gateway, Plugin, Profil, Browser und Tab-Bereitschaft.
  • browser akzeptiert:
    • profile, um ein benanntes Browser-Profil auszuwählen (openclaw, chrome oder remote CDP).
    • target (sandbox | host | node), um auszuwählen, wo der Browser läuft.
    • In Sandbox-Sitzungen erfordert target: "host" agents.defaults.sandbox.browser.allowHostControl=true.
    • Wenn target ausgelassen wird: Sandbox-Sitzungen verwenden standardmäßig sandbox, Nicht-Sandbox-Sitzungen standardmäßig host.
    • Wenn eine browserfähige Node verbunden ist, kann das Werkzeug automatisch dorthin weiterleiten, sofern Sie nicht target="host" oder target="node" festlegen.
Dadurch bleibt der Agent deterministisch und vermeidet fragile Selektoren.

​
Verwandt