Browser (von OpenClaw verwaltet)

OpenClaw kann ein dediziertes Chrome-/Brave-/Edge-/Chromium-Profil ausführen, das der Agent steuert. Es wird über einen kleinen lokalen Steuerungsdienst innerhalb des Gateway ausgeführt (nur Loopback) und ist von Ihrem persönlichen Browser isoliert.

• Betrachten Sie es als separaten Browser ausschließlich für den Agenten. Das Profil openclaw greift niemals auf Ihr persönliches Browserprofil zu.
• Der Agent öffnet Tabs, liest Seiten, klickt und gibt Text in dieser isolierten Umgebung ein.
• Das integrierte Profil user stellt stattdessen über Chrome DevTools MCP eine Verbindung zu Ihrer tatsächlich angemeldeten Chrome-Sitzung her.

Was Sie erhalten

• Ein separates Browserprofil namens openclaw (standardmäßig mit orangefarbener Akzentfarbe).
• Deterministische Tab-Steuerung (auflisten/öffnen/fokussieren/schließen).
• Agentenaktionen (klicken/eingeben/ziehen/auswählen), Snapshots, Screenshots, PDFs.
• Playwright-basierte Profile speichern direkte Navigationen zu Anhängen im verwalteten Downloadverzeichnis und geben nach der Richtlinienprüfung der endgültigen URL Metadaten im Format { url, suggestedFilename, path } zurück.
• Playwright-basierte Agentenaktionen geben ein downloads-Array mit denselben verwalteten Metadaten zurück, wenn die Aktion unmittelbar einen oder mehrere Downloads startet.
• Ein mitgeliefertes browser-automation-Skill, das Agenten die Wiederherstellungsschleife für Snapshots, stabile Tabs, veraltete Referenzen und manuelle Blockierungen vermittelt, wenn das Browser- Plugin aktiviert ist.
• Optionale Unterstützung mehrerer Profile (openclaw, work, remote, ...).

Dieser Browser ist nicht für Ihre tägliche Nutzung vorgesehen. Er bietet eine sichere, isolierte Oberfläche für die Automatisierung und Verifizierung durch Agenten.

Unter macOS können Sie Cookies explizit aus einem Systemprofil der Chrome-Familie in ein separates verwaltetes Profil kopieren. Der verwaltete Browser verwendet weiterhin sein eigenes Benutzerdatenverzeichnis; nur die ausgewählten Cookies werden kopiert, während lokaler Speicher und IndexedDB zurückbleiben. Informationen zu Importbefehlen und Einschränkungen finden Sie unter Profile oder in der CLI-Referenz zu openclaw browser.

Schnellstart

openclaw browser --browser-profile openclaw doctoropenclaw browser --browser-profile openclaw doctor --deepopenclaw browser --browser-profile openclaw statusopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

„Browser disabled“ bedeutet, dass das Plugin oder browser.enabled deaktiviert ist; siehe Konfiguration und Plugin-Steuerung.

Wenn openclaw browser vollständig fehlt oder der Agent meldet, dass das Browser-Tool nicht verfügbar ist, wechseln Sie zu Fehlender Browserbefehl oder fehlendes Tool.

Plugin-Steuerung

Das standardmäßige browser-Tool ist ein mitgeliefertes Plugin. Deaktivieren Sie es, um es durch ein anderes Plugin zu ersetzen, das denselben Tool-Namen browser registriert:

{  plugins: {    entries: {      browser: {        enabled: false,      },    },  },}

Für die Standardeinstellungen müssen sowohl plugins.entries.browser.enabled als auch browser.enabled=true gesetzt sein. Wenn Sie nur das Plugin deaktivieren, werden die CLI openclaw browser, die Gateway-Methode browser.request, das Agenten-Tool und der Steuerungsdienst gemeinsam entfernt; Ihre browser.*-Konfiguration bleibt für einen Ersatz erhalten.

Änderungen an der Browserkonfiguration erfordern einen Neustart des Gateway, damit das Plugin seinen Dienst erneut registrieren kann.

Hinweise für Agenten

Hinweis zum Tool-Profil: tools.profile: "coding" umfasst web_search und web_fetch, jedoch nicht das vollständige browser-Tool. Damit der Agent oder ein gestarteter Unteragent die Browserautomatisierung verwenden kann, fügen Sie den Browser auf der Profilebene hinzu:

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

Verwenden Sie für einen einzelnen Agenten agents.list[].tools.alsoAllow: ["browser"]. tools.subagents.tools.allow: ["browser"] allein reicht nicht aus, da die Richtlinie für Unteragenten erst nach der Profilfilterung angewendet wird.

Das Browser-Plugin stellt Hinweise für Agenten auf zwei Ebenen bereit:

• Die Beschreibung des browser-Tools enthält den kompakten, stets aktiven Vertrag: das richtige Profil auswählen, Referenzen im selben Tab verwenden, tabId/Bezeichnungen zur Tab-Auswahl nutzen und für mehrstufige Aufgaben das Browser-Skill laden.
• Das mitgelieferte browser-automation-Skill enthält den ausführlicheren Arbeitsablauf: zuerst Status/Tabs prüfen, Aufgaben-Tabs bezeichnen, vor Aktionen einen Snapshot erstellen, nach UI-Änderungen erneut einen Snapshot erstellen, veraltete Referenzen einmal wiederherstellen und Blockierungen durch Anmeldung/2FA/Captcha oder Kamera/Mikrofon als erforderliche manuelle Aktion melden, statt zu raten.

Mit Plugins mitgelieferte Skills werden in den verfügbaren Skills des Agenten aufgeführt, wenn das Plugin aktiviert ist. Die vollständigen Skill-Anweisungen werden bei Bedarf geladen, sodass bei routinemäßigen Durchläufen nicht die vollständigen Token-Kosten anfallen.

Fehlender Browserbefehl 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, liegt die Ursache normalerweise in einer plugins.allow-Liste, die browser nicht enthält, während kein browser-Konfigurationsblock auf der Stammebene vorhanden ist. Fügen Sie ihn hinzu:

{  plugins: {    allow: ["telegram", "browser"],  },}

Ein expliziter browser-Block auf der Stammebene (ein beliebiger Schlüssel unter browser, etwa browser.enabled=true oder browser.profiles.<name>) aktiviert das mitgelieferte Browser-Plugin selbst bei einer restriktiven plugins.allow-Liste, entsprechend dem Verhalten der Konfiguration mitgelieferter Kanäle. plugins.entries.browser.enabled=true und tools.alsoAllow: ["browser"] ersetzen allein nicht die Mitgliedschaft in der Zulassungsliste. Wenn Sie plugins.allow vollständig entfernen, wird ebenfalls der Standard wiederhergestellt.

Profile: openclaw, user, chrome

• openclaw: verwalteter, isolierter Browser (keine Erweiterung erforderlich).
• user: integriertes Chrome-DevTools-MCP-Verbindungsprofil für Ihre tatsächlich angemeldete Chrome-Sitzung. Chrome zeigt beim ersten Verbindungsaufbau durch OpenClaw die blockierende Aufforderung „Allow remote debugging?“ an, sodass sich jemand am Computer befinden muss.
• chrome: integriertes Profil der Chrome-Erweiterung für Ihre tatsächlich angemeldete Chrome-Sitzung. Funktioniert von einem Smartphone aus, auch wenn niemand am Schreibtisch sitzt, da Tabs über die OpenClaw-Browsererweiterung statt über den Remote-Debugging-Port gesteuert werden; daher erscheint keine Aufforderung „Allow remote debugging?“.

Für Aufrufe des Browser-Tools durch Agenten:

• Standard: Verwenden Sie den isolierten Browser openclaw.
• Bevorzugen Sie profile="chrome" (Erweiterung), wenn bestehende angemeldete Sitzungen erforderlich sind und der Benutzer nicht am Computer ist (Telegram, WhatsApp usw.).
• Bevorzugen Sie profile="user" (Chrome MCP), wenn bestehende angemeldete Sitzungen erforderlich sind und der Benutzer am Computer ist, um die Verbindungsaufforderung zu bestätigen.
• profile ist die explizite Überschreibung, wenn Sie einen bestimmten Browsermodus verwenden möchten.

Legen Sie browser.defaultProfile: "openclaw" fest, wenn Sie standardmäßig den verwalteten Modus verwenden möchten.

Konfiguration

Browsereinstellungen befinden sich in ~/.openclaw/openclaw.json.

{  browser: {    enabled: true, // Standard: true    evaluateEnabled: true, // Standard: true; false deaktiviert act:evaluate (beliebiges JS)    ssrfPolicy: {      // dangerouslyAllowPrivateNetwork: true, // nur für vertrauenswürdigen Zugriff auf private Netzwerke aktivieren      // hostnameAllowlist: ["*.example.com", "example.com"],      // allowedHostnames: ["localhost"],    },    // cdpUrl: "http://127.0.0.1:18792", // ältere Überschreibung für ein einzelnes Profil    remoteCdpTimeoutMs: 1500, // Zeitüberschreitung für Remote-CDP-HTTP (ms)    remoteCdpHandshakeTimeoutMs: 3000, // Zeitüberschreitung für Remote-CDP-WebSocket-Handshake (ms)    localLaunchTimeoutMs: 15000, // Zeitüberschreitung für die lokale Erkennung des verwalteten Chrome (ms)    localCdpReadyTimeoutMs: 8000, // Zeitüberschreitung für lokale CDP-Bereitschaft nach dem Start (ms)    actionTimeoutMs: 60000, // standardmäßige Zeitüberschreitung für Browseraktionen (ms)    tabCleanup: {      enabled: true, // Standard: true      idleMinutes: 120, // auf 0 setzen, um die Bereinigung inaktiver Tabs zu deaktivieren      maxTabsPerSession: 8, // auf 0 setzen, um das Limit pro Sitzung zu deaktivieren      sweepMinutes: 5,    },    // snapshotDefaults: { mode: "efficient" }, // standardmäßiger Snapshot-Modus, wenn der Aufrufer keinen angibt    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" },    },  },}

browser.snapshotDefaults.mode: "efficient" ändert den standardmäßigen snapshot- Extraktionsmodus, wenn ein Aufrufer weder ein explizites snapshotFormat noch einen mode übergibt; Optionen für einzelne Snapshot-Aufrufe finden Sie unter Browsersteuerungs-API.

Screenshot-Bilderkennung (Unterstützung für reine Textmodelle)

Wenn das Hauptmodell ausschließlich Text unterstützt (keine Bild-/Multimodal-Unterstützung), geben Browser- Screenshots Bildblöcke zurück, die das Modell nicht lesen kann. Browser-Screenshots verwenden die vorhandene Konfiguration zur Bilderkennung erneut, sodass ein für das Medienverständnis konfiguriertes Bildmodell Screenshots ohne browserspezifische Modelleinstellungen als Text beschreiben kann.

{  tools: {    media: {      image: {        models: [          { provider: "bytedance", model: "doubao-seed-2.0-pro" },          // Fallback-Kandidaten hinzufügen; der erste Erfolg gewinnt          { provider: "openai", model: "gpt-4o" },        ],      },      // Gemeinsam genutzte Medienmodelle funktionieren ebenfalls, wenn sie für Bildunterstützung gekennzeichnet sind.      // models: [{ provider: "openai", model: "gpt-4o", capabilities: ["image"] }],    },  },  agents: {    defaults: {      // Vorhandene Standardeinstellungen für Bildmodelle werden ebenfalls berücksichtigt.      // imageModel: { primary: "openai/gpt-4o" },    },  },}

Funktionsweise:

1. Der Agent ruft browser screenshot auf, und ein Bild wird wie gewohnt auf dem Datenträger gespeichert.
2. Das Browser-Tool fragt die vorhandene Laufzeit zur Bilderkennung, ob sie den Screenshot mithilfe konfigurierter Medienbildmodelle, gemeinsam genutzter Medien- modelle, Bildmodell-Standardeinstellungen oder eines authentifizierungsgestützten Bild-Providers beschreiben kann.
3. Das Bildmodell gibt eine Textbeschreibung zurück, die mit wrapExternalContent (Schutz vor Prompt-Injection) umschlossen und dem Agenten als Textblock statt als Bildblock zurückgegeben wird.
4. Wenn die Bilderkennung nicht verfügbar ist, übersprungen wird oder fehlschlägt, gibt der Browser stattdessen den ursprünglichen Bildblock zurück.

Screenshot-Bildblöcke sind private Tool-Ergebnisse: Der Agent kann sie prüfen, OpenClaw hängt sie jedoch nicht automatisch an Antworten in Kanälen an. Um einen Screenshot zu teilen, weisen Sie den Agenten an, ihn explizit mit dem Nachrichten-Tool zu senden.

Verwenden Sie die vorhandenen Felder tools.media.image / tools.media.models für Modell- Fallbacks, Zeitüberschreitungen, Bytelimits, Profile und Einstellungen für Provider-Anfragen.

Wenn das aktive Hauptmodell bereits Bilder unterstützt und kein explizites Modell zur Bilderkennung konfiguriert ist, behält OpenClaw das normale Bildergebnis bei, sodass das Hauptmodell den Screenshot direkt lesen kann.

Brave oder einen anderen Chromium-basierten Browser verwenden

Wenn Ihr systemweiter Standardbrowser Chromium-basiert ist (Chrome/Brave/Edge/usw.), verwendet OpenClaw ihn automatisch. Legen Sie browser.executablePath fest, um die automatische Erkennung zu überschreiben. Werte für executablePath auf oberster Ebene und pro Profil akzeptieren ~ für das Stammverzeichnis Ihres Betriebssystembenutzers:

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 legen Sie den Wert plattformspezifisch in der Konfiguration fest:

{browser: {executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",},}

{browser: {executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",},}

{browser: {executablePath: "/usr/bin/brave-browser",},}

Das profilbezogene executablePath wirkt sich nur auf lokale verwaltete Profile aus, die OpenClaw startet. existing-session-Profile stellen stattdessen eine Verbindung zu einem bereits ausgeführten Browser her, und Remote-CDP-Profile verwenden den Browser hinter cdpUrl.

Lokale und Remote-Steuerung

• Lokale Steuerung (Standard): Das Gateway startet den Loopback-Steuerungsdienst und kann einen lokalen Browser starten.
• Remote-Steuerung (Node-Host): Führen Sie einen Node-Host auf dem Computer aus, auf dem sich der Browser befindet; das Gateway leitet Browseraktionen als Proxy an ihn weiter.
• Remote-CDP: Legen Sie browser.profiles.<name>.cdpUrl (oder browser.cdpUrl) fest, um eine Verbindung zu einem entfernten Chromium-basierten Browser herzustellen. In diesem Fall startet OpenClaw keinen lokalen Browser.
• Legen Sie für extern verwaltete CDP-Dienste auf der Loopback-Schnittstelle (beispielsweise Browserless in Docker, veröffentlicht unter 127.0.0.1) zusätzlich attachOnly: true fest. Loopback-CDP ohne attachOnly wird als lokales, von OpenClaw verwaltetes Browserprofil behandelt.
• headless wirkt sich nur auf lokale verwaltete Profile aus, die OpenClaw startet. Es startet Browser für bestehende Sitzungen oder Remote-CDP weder neu noch verändert es sie.
• executablePath folgt derselben Regel für lokale verwaltete Profile. Wird der Wert bei einem ausgeführten lokalen verwalteten Profil geändert, wird dieses Profil für einen Neustart/Abgleich markiert, sodass beim nächsten Start die neue Binärdatei verwendet wird.

Das Verhalten beim Beenden unterscheidet sich je nach Profilmodus:

• lokale verwaltete Profile: openclaw browser stop beendet den Browserprozess, den OpenClaw gestartet hat
• reine Verbindungs- und Remote-CDP-Profile: openclaw browser stop schließt die aktive Steuerungssitzung und gibt Playwright-/CDP-Emulationsüberschreibungen frei (Viewport, Farbschema, Gebietsschema, Zeitzone, Offlinemodus und ähnliche Zustände), obwohl kein Browserprozess von OpenClaw gestartet wurde

Remote-CDP-URLs können Authentifizierungsdaten enthalten:

• Abfragetoken (z. B. https://provider.example?token=<token>)
• HTTP-Basisauthentifizierung (z. B. https://user:pass@provider.example)

OpenClaw behält die Authentifizierungsdaten bei Aufrufen von /json/*-Endpunkten und beim Herstellen der Verbindung zum CDP-WebSocket bei. Verwenden Sie für Token vorzugsweise Umgebungsvariablen oder Secret-Manager, anstatt sie in Konfigurationsdateien einzuchecken.

Node-Browser-Proxy (konfigurationsfreier Standard)

Wenn Sie einen Node-Host auf dem Computer ausführen, auf dem sich Ihr Browser befindet, kann OpenClaw Browser-Tool-Aufrufe ohne zusätzliche Browserkonfiguration automatisch an diesen Node weiterleiten. Dies ist der Standardpfad für Remote-Gateways.

Hinweise:

• Der Node-Host stellt seinen lokalen Browser-Steuerungsserver über einen Proxy-Befehl bereit.
• Profile stammen aus der eigenen browser.profiles-Konfiguration des Nodes (wie bei einer lokalen Konfiguration).
• Der Proxy-Befehl erlaubt unabhängig von allowProfiles niemals dauerhafte Profiländerungen (create-profile, delete-profile, reset-profile); nehmen Sie diese Änderungen direkt auf dem Node vor.
• nodeHost.browserProxy.allowProfiles ist optional. Lassen Sie die Option für das bisherige/standardmäßige Verhalten leer: Alle konfigurierten Profile bleiben über den Proxy erreichbar.
• Wenn Sie nodeHost.browserProxy.allowProfiles festlegen, behandelt OpenClaw dies als Least-Privilege-Grenze, die einschränkt, auf welche Profilnamen der Proxy zugreifen darf.
• Deaktivieren Sie die Funktion, wenn Sie sie nicht verwenden möchten:
  • Auf dem Node: nodeHost.browserProxy.enabled=false
  • Auf dem Gateway: gateway.nodes.browser.mode="off" (akzeptiert auch "auto", um einen einzelnen verbundenen Browser-Node auszuwählen, oder "manual", um einen expliziten Node-Parameter zu verlangen)

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 Remote-Browserprofil ist die direkte WebSocket-URL aus der Verbindungsdokumentation von Browserless die einfachste Option.

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 tatsächliches Browserless-Token.
• Wählen Sie den regionalen Endpunkt, der zu Ihrem Browserless-Konto passt (siehe deren Dokumentation).
• Wenn Browserless Ihnen eine HTTPS-Basis-URL bereitstellt, können Sie diese entweder für eine direkte CDP-Verbindung in wss:// umwandeln oder die HTTPS-URL beibehalten und OpenClaw /json/version ermitteln lassen.

Browserless Docker auf demselben Host

Wenn Browserless selbstgehostet in Docker ausgeführt wird und OpenClaw auf dem Host läuft, 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 für den OpenClaw-Prozess erreichbar sein. Browserless muss außerdem einen passenden erreichbaren Endpunkt bekannt geben. Setzen Sie EXTERNAL von Browserless auf dieselbe von OpenClaw erreichbare WebSocket-Basis, beispielsweise ws://127.0.0.1:3000, ws://browserless:3000 oder eine stabile private Docker-Netzwerkadresse. Wenn /json/version eine webSocketDebuggerUrl zurückgibt, die auf eine für OpenClaw nicht erreichbare Adresse verweist, kann CDP HTTP funktionsfähig erscheinen, während das Anhängen über WebSocket dennoch fehlschlägt.

Lassen Sie attachOnly für ein Browserless-Profil mit Loopback-Adresse nicht unbelegt. Ohne attachOnly behandelt OpenClaw den Loopback-Port als lokal verwaltetes Browserprofil und meldet möglicherweise, dass der Port verwendet wird, aber nicht OpenClaw gehört.

Direkte WebSocket-CDP-Provider

Einige gehostete Browserdienste stellen statt der standardmäßigen HTTP-basierten CDP-Ermittlung (/json/version) einen direkten WebSocket-Endpunkt bereit. OpenClaw akzeptiert drei Formen von CDP-URLs und wählt automatisch die richtige Verbindungsstrategie:

• HTTP(S)-Ermittlung – http://host[:port] oder https://host[:port]. OpenClaw ruft /json/version auf, um die WebSocket-Debugger-URL zu ermitteln, und stellt anschließend die Verbindung her. Kein WebSocket-Fallback.
• Direkte WebSocket-Endpunkte – ws://host[:port]/devtools/<kind>/<id> oder wss://... mit einem Pfad vom Typ /devtools/browser|page|worker|shared_worker|service_worker/<id>. OpenClaw stellt die Verbindung direkt über einen WebSocket-Handshake her und überspringt /json/version vollständig.
• Reine WebSocket-Basisadressen – ws://host[:port] oder wss://host[:port] ohne /devtools/...-Pfad (z. B. Browserless, Browserbase). OpenClaw versucht zunächst die HTTP-Ermittlung über /json/version (wobei das Schema zu http/https normalisiert wird). Wenn die Ermittlung eine webSocketDebuggerUrl zurückgibt, wird diese verwendet; andernfalls greift OpenClaw auf einen direkten WebSocket-Handshake an der reinen Basisadresse zurück. Wenn der bekannt gegebene WebSocket-Endpunkt den CDP-Handshake ablehnt, die konfigurierte reine Basisadresse ihn jedoch akzeptiert, greift OpenClaw ebenfalls auf diese Basisadresse zurück. Dadurch kann eine reine ws://-Adresse, die auf ein lokales Chrome verweist, weiterhin eine Verbindung herstellen, da Chrome WebSocket-Upgrades nur auf dem spezifischen zielbezogenen Pfad aus /json/version akzeptiert. Gehostete Provider können zugleich weiterhin ihren WebSocket-Basisendpunkt verwenden, wenn ihr Ermittlungsendpunkt eine kurzlebige URL bekannt gibt, die für Playwright CDP nicht geeignet ist.

openclaw browser doctor verwendet dieselbe Logik aus Ermittlung zuerst und WebSocket-Fallback wie das Anhängen zur Laufzeit. Daher wird eine reine Basis-URL, die erfolgreich eine Verbindung herstellt, von der Diagnose nicht als unerreichbar gemeldet.

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 Overview dashboard.
• Ersetzen Sie <BROWSERBASE_API_KEY> durch Ihren tatsächlichen Browserbase-API-Schlüssel.
• Browserbase erstellt bei der WebSocket-Verbindung automatisch eine Browser-Sitzung, sodass kein manueller Schritt zum Erstellen einer Sitzung erforderlich ist.
• Die aktuellen Limits der kostenlosen Stufe und kostenpflichtigen Tarife finden Sie unter Preise.
• Die vollständige API-Referenz, SDK-Anleitungen und Integrationsbeispiele finden Sie in der Browserbase-Dokumentation.

Notte

Notte ist eine Cloud-Plattform zum Ausführen von Headless-Browsern mit integriertem Stealth-Modus, Residential-Proxys und einem CDP-nativen WebSocket-Gateway.

{  browser: {    enabled: true,    defaultProfile: "notte",    remoteCdpTimeoutMs: 3000,    remoteCdpHandshakeTimeoutMs: 5000,    profiles: {      notte: {        cdpUrl: "wss://us-prod.notte.cc/sessions/connect?token=<NOTTE_API_KEY>",        color: "#7C3AED",      },    },  },}

Hinweise:

• Registrieren Sie sich und kopieren Sie Ihren API Key von der Einstellungsseite der Konsole.
• Ersetzen Sie <NOTTE_API_KEY> durch Ihren tatsächlichen Notte-API-Schlüssel.
• Notte erstellt bei der WebSocket-Verbindung automatisch eine Browser-Sitzung, sodass kein manueller Schritt zum Erstellen einer Sitzung erforderlich ist. Die Sitzung wird beendet, wenn die WebSocket-Verbindung getrennt wird.
• Die aktuellen Limits der kostenlosen Stufe und kostenpflichtigen Tarife finden Sie unter Preise.
• Die vollständige API-Referenz, SDK-Anleitungen und Integrationsbeispiele finden Sie in der Notte-Dokumentation.

Sicherheit

Grundgedanken:

• Die Browsersteuerung ist ausschließlich über Loopback erreichbar; der Zugriff erfolgt über die Authentifizierung des Gateways oder die Node-Kopplung.
• Die eigenständige Loopback-Browser-HTTP-API verwendet ausschließlich Shared-Secret-Authentifizierung: Bearer-Authentifizierung mit dem Gateway-Token, x-openclaw-password oder HTTP-Basic-Authentifizierung mit dem konfigurierten Gateway-Passwort.
• Identitätsheader von Tailscale Serve und gateway.auth.mode: "trusted-proxy" authentifizieren diese eigenständige Loopback-Browser-API nicht.
• Wenn die Browsersteuerung aktiviert und keine Shared-Secret-Authentifizierung konfiguriert ist, erzeugt und speichert OpenClaw beim Start automatisch Zugangsdaten für die Browsersteuerung: ein Token, wenn gateway.auth.mode auf none gesetzt ist, oder ein Passwort, wenn der Wert trusted-proxy ist (über gateway.auth.password gespeichert, damit externe Loopback-Clients es auflösen können). Die automatische Erzeugung wird übersprungen, wenn für diesen Modus bereits explizite Zugangsdaten als Zeichenfolge konfiguriert sind oder wenn gateway.auth.mode auf password gesetzt ist.
• Konfigurieren Sie gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN oder OPENCLAW_GATEWAY_PASSWORD explizit, wenn Sie statt der erzeugten Zugangsdaten ein stabiles, von Ihnen kontrolliertes Geheimnis verwenden möchten.

Tipps für Remote-CDP:

• Bevorzugen Sie nach Möglichkeit verschlüsselte Endpunkte (HTTPS oder WSS) und kurzlebige Token.
• Betten Sie langlebige Token möglichst nicht direkt in Konfigurationsdateien ein.
• Betreiben Sie das Gateway und alle Node-Hosts in einem privaten Netzwerk (Tailscale); vermeiden Sie eine öffentliche Bereitstellung.
• Behandeln Sie Remote-CDP-URLs und -Token als Geheimnisse; bevorzugen Sie Umgebungsvariablen oder einen Secrets-Manager.

Profile (mehrere Browser)

OpenClaw unterstützt mehrere benannte Profile (Routing-Konfigurationen). Profile können folgende Typen haben:

• von OpenClaw verwaltet: eine dedizierte Chromium-basierte Browserinstanz mit eigenem Benutzerdatenverzeichnis und CDP-Port
• remote: eine explizite CDP-URL (Chromium-basierter Browser, der an anderer Stelle ausgeführt wird)
• bestehende Sitzung: Ihr vorhandenes Chrome-Profil über die automatische Verbindung von Chrome DevTools MCP

Standardwerte:

• Das Profil openclaw wird automatisch erstellt, wenn es fehlt.
• Das Profil user ist für das Anhängen an bestehende Sitzungen über Chrome MCP integriert.
• Weitere Profile für bestehende Sitzungen außer user müssen explizit aktiviert werden; erstellen Sie sie mit --driver existing-session.
• Lokale CDP-Ports werden standardmäßig aus dem Bereich 18800-18899 zugewiesen.
• Beim Löschen eines Profils wird dessen lokales Datenverzeichnis in den Papierkorb verschoben.

Alle Steuerungsendpunkte akzeptieren ?profile=<name>; die CLI verwendet --browser-profile.

Bestehende Sitzung über Chrome DevTools MCP

OpenClaw kann sich über den offiziellen Chrome-DevTools-MCP-Server auch an ein laufendes Chromium-basiertes Browserprofil anhängen. Dabei werden die bereits in diesem Browserprofil geöffneten Tabs und der vorhandene Anmeldestatus wiederverwendet.

Offizielle Hintergrundinformationen und Einrichtungsreferenzen:

• Chrome for Developers: Chrome DevTools MCP mit Ihrer Browsersitzung verwenden
• README von Chrome DevTools MCP

Integriertes Profil: user. Erstellen Sie ein eigenes benutzerdefiniertes Profil für bestehende Sitzungen, wenn Sie einen anderen Namen, eine andere Farbe oder ein anderes Browser-Datenverzeichnis verwenden möchten.

Standardmäßig verwendet das integrierte Profil user die automatische Verbindung von Chrome MCP, die auf das lokale Standardprofil von Google Chrome zielt. Verwenden Sie userDataDir für Brave, Edge, Chromium oder ein vom Standard abweichendes Chrome-Profil. ~ wird zu Ihrem Betriebssystem-Home-Verzeichnis erweitert:

{  browser: {    profiles: {      brave: {        driver: "existing-session",        attachOnly: true,        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",        color: "#FB542B",      },    },  },}

Führen Sie anschließend im entsprechenden Browser folgende Schritte aus:

1. Öffnen Sie die Inspektionsseite dieses Browsers für Remote-Debugging.
2. Aktivieren Sie Remote-Debugging.
3. Lassen Sie den Browser geöffnet und bestätigen Sie die Verbindungsaufforderung, wenn OpenClaw sich anhängt.

Gängige Inspektionsseiten:

• Chrome: chrome://inspect/#remote-debugging
• Brave: brave://inspect/#remote-debugging
• Edge: edge://inspect/#remote-debugging

Smoke-Test für das Live-Anhängen:

openclaw browser --browser-profile user startopenclaw browser --browser-profile user statusopenclaw browser --browser-profile user tabsopenclaw browser --browser-profile user snapshot --format ai

So sieht eine erfolgreiche Verbindung 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 Referenzen aus dem ausgewählten Live-Tab zurück

Prüfen Sie Folgendes, wenn das Anhängen nicht funktioniert:

• Der Zielbrowser auf Chromium-Basis hat die Version 144+.
• Remote-Debugging ist auf der Inspektionsseite dieses Browsers aktiviert.
• Der Browser hat die Zustimmungsaufforderung zum Anhängen angezeigt und Sie haben sie bestätigt.
• Wenn Chrome mit einem expliziten --remote-debugging-port gestartet wurde, setzen Sie browser.profiles.<name>.cdpUrl auf diesen DevTools-Endpunkt, statt sich auf die automatische Verbindung von Chrome MCP zu verlassen.
• openclaw doctor migriert alte erweiterungsbasierte Browserkonfigurationen und prüft bei standardmäßigen Profilen mit automatischer Verbindung, ob Chrome lokal installiert ist. Es kann Remote-Debugging im Browser jedoch nicht für Sie aktivieren.

Verwendung durch Agenten:

• Verwenden Sie profile="user", wenn Sie den angemeldeten Browserstatus 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 sitzt, um die Aufforderung zum Verbinden zu bestätigen.
• Der Gateway- oder Node-Host kann npx chrome-devtools-mcp@latest --autoConnect starten.

Hinweise:

• Dieser Pfad birgt ein höheres Risiko als das isolierte Profil openclaw, da er innerhalb Ihrer angemeldeten Browsersitzung agieren kann.
• OpenClaw startet den Browser für diesen Treiber nicht, sondern verbindet sich nur mit ihm.
• OpenClaw verwendet hier den offiziellen Chrome-DevTools-MCP-Ablauf --autoConnect. Wenn userDataDir festgelegt ist, wird es weitergereicht, um dieses Benutzerdatenverzeichnis als Ziel zu verwenden.
• Eine bestehende Sitzung kann auf dem ausgewählten Host oder über eine verbundene Browser-Node eingebunden werden. Wenn Chrome an einem anderen Ort ausgeführt wird und keine Browser-Node verbunden ist, verwenden Sie stattdessen Remote-CDP oder einen Node-Host.
• Chrome-MCP-Ziele und Snapshot-Referenzen sind auf einen MCP-Unterprozess beschränkt. Nachdem dieser Prozess neu gestartet wurde, führen Sie browser tabs erneut aus, wählen Sie vor zielspezifischen Arbeiten ausdrücklich ein neues Ziel aus und erstellen Sie einen neuen Snapshot, bevor Sie Referenzen verwenden. Jede Referenz ist nur für ihr Ziel und den neuesten Snapshot gültig. Alte Aliasse werden nicht auf einen Ersatz-Tab übertragen, selbst wenn dessen URL übereinstimmt.
• Chrome DevTools MCP leitet Seitenwerkzeuge derzeit anhand einer prozesslokalen numerischen Seiten- ID weiter. Prozessgebundene Handles verhindern die Wiederverwendung nach dem Ersetzen eines Unterprozesses, aber ein Austausch des Browserkontexts innerhalb des Prozesses zwischen aufeinanderfolgenden Werkzeugaufrufen kann eine Aktion dennoch auf ein anderes Ziel umleiten. Eine vollständig atomare Weiterleitung erfordert vorgelagerte Unterstützung der Seitenwerkzeuge für stabile Ziel-IDs.

Benutzerdefinierter Chrome-MCP-Start

Überschreiben Sie den gestarteten Chrome-DevTools-MCP-Server pro Profil, wenn der standardmäßige Ablauf npx chrome-devtools-mcp@latest nicht Ihren Anforderungen entspricht (Offline-Hosts, festgelegte Versionen, mitgelieferte Binärdateien):

Wenn cdpUrl in einem Profil für eine bestehende Sitzung festgelegt ist, überspringt OpenClaw --autoConnect und leitet den Endpunkt automatisch an Chrome MCP weiter:

• http(s)://... → --browserUrl <url> (HTTP-Discovery-Endpunkt von DevTools).
• ws(s)://... → --wsEndpoint <url> (direkter CDP-WebSocket).

Endpunkt-Flags und userDataDir können nicht kombiniert werden: Wenn cdpUrl festgelegt ist, wird userDataDir beim Start von Chrome MCP ignoriert, da Chrome MCP eine Verbindung mit dem hinter dem Endpunkt ausgeführten Browser herstellt, statt ein Profilverzeichnis zu öffnen.

Isolationsgarantien

• Dediziertes Benutzerdatenverzeichnis: Berührt niemals Ihr persönliches Browserprofil.
• Dedizierte Ports: Vermeidet 9222, um Kollisionen mit Entwicklungsabläufen zu verhindern.
• Deterministische Tab-Steuerung: tabs gibt zuerst suggestedTargetId zurück, danach stabile tabId-Handles wie t1, optionale Bezeichnungen und die rohe targetId. Agenten 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 Browser:

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 von 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 Loopback erreichbare HTTP- Steuerungs-API sowie eine entsprechende openclaw browser-CLI bereit (Snapshots, Referenzen, erweiterte Wartefunktionen, JSON-Ausgabe, Debugging-Abläufe). Die vollständige Referenz finden Sie unter Browser-Steuerungs-API.

Fehlerbehebung

Linux-spezifische Probleme (insbesondere mit Snap-Chromium) werden unter Fehlerbehebung für Browser behandelt.

Informationen zu Split-Host-Konfigurationen mit WSL2-Gateway und Chrome unter Windows finden Sie unter Fehlerbehebung für WSL2 + Windows + Remote-Chrome-CDP.

CDP-Startfehler gegenüber SSRF-Blockierung bei Navigation

Dies sind unterschiedliche Fehlerklassen, die auf unterschiedliche Codepfade hinweisen.

• CDP-Start- oder Bereitschaftsfehler bedeutet, dass OpenClaw nicht bestätigen kann, dass die Browser-Steuerungsebene funktionsfähig ist.
• SSRF-Blockierung bei Navigation bedeutet, dass die Browser-Steuerungsebene funktionsfähig ist, aber ein Ziel für die Seitennavigation durch eine 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 Loopback-CDP-Dienst ohne attachOnly: true konfiguriert ist
• SSRF-Blockierung bei Navigation:
  • Abläufe mit open, navigate, Snapshot-Erstellung oder Tab-Öffnung schlagen mit einem Browser-/Netzwerkrichtlinienfehler fehl, während start und tabs weiterhin funktionieren

Verwenden Sie diese minimale Abfolge, um die beiden Fälle zu unterscheiden:

openclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw tabsopenclaw 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 nicht funktionsfähig. Behandeln Sie dies als CDP-Erreichbarkeitsproblem, nicht als Problem der Seitennavigation.
• Wenn start und tabs erfolgreich sind, aber open oder navigate fehlschlägt, ist die Browser-Steuerungsebene aktiv und der Fehler liegt in der Navigationsrichtlinie oder bei der Zielseite.
• Wenn start, tabs und open alle erfolgreich sind, ist der grundlegende verwaltete Browser-Steuerungspfad 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 Loopback-Profil openclaw überspringen CDP-Zustandsprüfungen absichtlich die Durchsetzung der Browser-SSRF-Erreichbarkeit für die eigene lokale Steuerungsebene von OpenClaw.
• Der Navigationsschutz ist davon getrennt. Ein erfolgreiches Ergebnis von start oder tabs bedeutet nicht, dass ein späteres Ziel von open oder navigate zulässig ist.

Sicherheitshinweise:

• Lockern Sie die Browser-SSRF-Richtlinie standardmäßig nicht.
• Bevorzugen Sie eng gefasste Host-Ausnahmen wie hostnameAllowlist oder allowedHostnames gegenüber einem umfassenden Zugriff auf private Netzwerke.
• Verwenden Sie dangerouslyAllowPrivateNetwork: true nur in bewusst vertrauenswürdigen Umgebungen, in denen Browserzugriff auf private Netzwerke erforderlich und geprüft ist.

Agentenwerkzeuge und Funktionsweise der Steuerung

Der Agent erhält ein Werkzeug für die Browserautomatisierung:

• browser – doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

Zuordnung:

• browser snapshot gibt einen stabilen UI-Baum zurück (KI oder ARIA).
• browser act verwendet die ref-IDs des Snapshots zum Klicken/Eingeben/Ziehen/Auswählen.
• browser screenshot erfasst Pixel (vollständige Seite, Element oder beschriftete Referenzen).
• browser doctor prüft die Bereitschaft von Gateway, Plugin, Profil, Browser und Tab.
• browser akzeptiert:
  • profile, um ein benanntes Browserprofil auszuwählen (openclaw, chrome oder Remote-CDP).
  • target (sandbox | host | node), um auszuwählen, wo sich der Browser befindet.
  • In Sandbox-Sitzungen erfordert target: "host" die Einstellung agents.defaults.sandbox.browser.allowHostControl=true.
  • Wenn target nicht angegeben ist: Sandbox-Sitzungen verwenden standardmäßig sandbox, Sitzungen ohne Sandbox standardmäßig host.
  • Wenn eine browserfähige Node verbunden ist, kann das Werkzeug Aufrufe automatisch an sie weiterleiten, sofern Sie nicht target="host" oder target="node" festlegen.

Dies sorgt für deterministisches Agentenverhalten und vermeidet fragile Selektoren.

Verwandte Themen

• Werkzeugübersicht – alle verfügbaren Agentenwerkzeuge
• Sandboxing – Browsersteuerung in Sandbox-Umgebungen
• Sicherheit – Risiken und Absicherung der Browsersteuerung