openclaw browser

Verwalten Sie die Browser-Steuerungsoberfläche von OpenClaw und führen Sie Browseraktionen aus: Lebenszyklus, Profile, Tabs, Snapshots, Screenshots, Navigation, Eingabe, Zustandsemulation und Debugging.

Verwandte Informationen: Browser-Tool

Allgemeine Flags

• --url <gatewayWsUrl>: Gateway-WebSocket-URL (standardmäßig aus der Konfiguration).
• --token <token>: Gateway-Token (falls erforderlich).
• --timeout <ms>: Anfrage-Timeout in ms (Standard: 30000).
• --expect-final: Auf eine endgültige Gateway-Antwort warten.
• --browser-profile <name>: Ein Browserprofil auswählen (Standard: openclaw oder browser.defaultProfile).
• --json: Maschinenlesbare Ausgabe (sofern unterstützt). Dies ist eine Option auf Browserebene; platzieren Sie sie daher für eine eindeutige Form vor dem Unterbefehl, beispielsweise openclaw browser --json status. Eine nachgestellte Platzierung wie openclaw browser status --json funktioniert ebenfalls, wenn der ausgewählte untergeordnete Befehl keine eigene Option --json definiert.

Schnellstart (lokal)

openclaw browser profilesopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

Agenten können dieselbe Bereitschaftsprüfung mit browser({ action: "doctor" }) ausführen.

Schnelle Fehlerbehebung

Wenn start mit not reachable after start fehlschlägt, beheben Sie zuerst Probleme mit der CDP-Bereitschaft. Wenn start und tabs erfolgreich sind, aber open oder navigate fehlschlägt, ist die Browser-Steuerungsebene funktionsfähig und der Fehler wird normalerweise durch eine SSRF-Richtlinienblockierung der Navigation verursacht.

Minimale Abfolge:

openclaw browser --browser-profile openclaw doctoropenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw tabsopenclaw browser --browser-profile openclaw open https://example.com

Ausführliche Anleitung: Fehlerbehebung für den Browser

Lebenszyklus

openclaw browser statusopenclaw browser doctoropenclaw browser doctor --deepopenclaw browser startopenclaw browser start --headlessopenclaw browser stopopenclaw browser --browser-profile openclaw reset-profile

• doctor --deep fügt eine Live-Snapshot-Prüfung hinzu: nützlich, wenn die grundlegende CDP-Bereitschaft gegeben ist, Sie aber einen Nachweis benötigen, dass der aktuelle Tab untersucht werden kann.
• Für ein laufendes lokal verwaltetes Profil melden status und doctor zwischengespeicherte Grafikdiagnosen aus Chrome: Hardware-/Softwareklassifizierung, Renderer, Backend, Gerät/Treiber, Funktions- und Deaktivierungsstatusdetails sowie beschleunigte Videofunktionen. openclaw browser --json status gibt die vollständigen strukturierten Nutzdaten zurück. Der passive Status startet Chrome niemals nur zur Erfassung dieser Fakten.
• stop schließt die aktive Steuerungssitzung und entfernt temporäre Emulationsüberschreibungen auch für attachOnly und Remote-CDP-Profile, bei denen OpenClaw den Browserprozess nicht selbst gestartet hat. Bei lokal verwalteten Profilen beendet stop außerdem den gestarteten Browserprozess.
• start --headless gilt nur für diese Startanfrage und nur, wenn OpenClaw einen lokal verwalteten Browser startet. Es schreibt weder browser.headless noch die Profilkonfiguration um und hat bei einem bereits laufenden Browser keine Wirkung.
• Auf Linux-Hosts ohne DISPLAY oder WAYLAND_DISPLAY werden lokal verwaltete Profile automatisch im Headless-Modus ausgeführt, sofern OPENCLAW_BROWSER_HEADLESS=0, browser.headless=false oder browser.profiles.<name>.headless=false nicht ausdrücklich einen sichtbaren Browser anfordert.

Wenn der Befehl fehlt

Wenn openclaw browser ein unbekannter Befehl ist, überprüfen Sie plugins.allow in ~/.openclaw/openclaw.json. Wenn plugins.allow vorhanden ist, führen Sie das gebündelte Browser-Plugin ausdrücklich auf, sofern die Konfiguration nicht bereits einen browser-Block auf der obersten Ebene enthält:

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

Ein ausdrücklicher browser-Block auf der obersten Ebene (beispielsweise browser.enabled=true oder browser.profiles.<name>) aktiviert das gebündelte Browser-Plugin ebenfalls unter einer restriktiven Plugin-Zulassungsliste.

Verwandte Informationen: Browser-Tool

Profile

Profile sind benannte Browser-Routing-Konfigurationen:

• openclaw (Standard): Startet eine dedizierte, von OpenClaw verwaltete Chrome-Instanz oder stellt eine Verbindung zu ihr her (isoliertes Benutzerdatenverzeichnis).
• user: Steuert Ihre vorhandene angemeldete Chrome-Sitzung über Chrome DevTools MCP.
• Benutzerdefinierte CDP-Profile: Verweisen auf einen lokalen oder entfernten CDP-Endpunkt.

openclaw browser profilesopenclaw browser system-profilesopenclaw browser system-profiles --browser braveopenclaw browser import-profile --browser chrome --system Default --into importedopenclaw browser import-profile --system "Profile 1" --into work --domains google.com,youtube.comopenclaw browser create-profile --name work --color "#FF5A36"openclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name remote --cdp-url https://browser-host.example.comopenclaw browser delete-profile --name work

Verwenden Sie bei einem beliebigen Unterbefehl mit --browser-profile <name> ein bestimmtes Profil, beispielsweise openclaw browser --browser-profile work tabs.

Unter macOS listet system-profiles die tatsächlich auf dem Host verfügbaren Chrome-, Brave-, Edge- oder Chromium-Profile auf. import-profile entschlüsselt deren Cookies nach einer einmaligen Zustimmung über den macOS-Schlüsselbund/Touch ID und fügt sie in ein neues, von OpenClaw verwaltetes Profil ein. Dabei werden nur Cookies importiert; lokaler Speicher und IndexedDB bleiben unverändert. Einige Google-Sitzungen verwenden gerätegebundene Sitzungsanmeldedaten (DBSC) und können nach dem Import weiterhin eine erneute Authentifizierung erfordern.

Wenn die macOS-App ein lokales Gateway verwendet, kann sie diesen Import einmalig anbieten und das isolierte importierte Profil als Standard für das Browsen durch Agenten festlegen. Der Import erfordert immer einen ausdrücklichen Klick; ein erfolgreicher Import oder das Schließen der Aufforderung unterdrückt spätere automatische Aufforderungen, und Settings → General → Browser login bleibt für einen erneuten Import verfügbar.

Der Import von Systemprofilen ist standardmäßig aktiviert. Setzen Sie browser.allowSystemProfileImport=false, um sowohl CLI- als auch durch Agenten ausgelöste Importe zu deaktivieren. Der Import erfolgt lokal auf dem Host und kann nicht über den Browser-Node-Proxy ausgeführt werden.

Tabs

openclaw browser tabsopenclaw browser tab new --label docsopenclaw browser tab label t1 docsopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://docs.openclaw.ai --label docsopenclaw browser focus docsopenclaw browser close t1

tabs gibt zuerst suggestedTargetId, dann die stabile tabId (beispielsweise t1), die optionale Bezeichnung und die rohe targetId zurück. Übergeben Sie suggestedTargetId erneut an focus, close, Snapshots und Aktionen. Weisen Sie mit open --label, tab new --label oder tab label eine Bezeichnung zu; Bezeichnungen, Tab-IDs, rohe Ziel-IDs und eindeutige Ziel-ID-Präfixe werden sämtlich akzeptiert. Das Anfragefeld heißt aus Kompatibilitätsgründen weiterhin targetId, akzeptiert jedoch alle diese Tab-Referenzen.

Rohe Ziel-IDs sind flüchtige Diagnosekennungen und kein dauerhafter Agentenspeicher: Wenn Chromium das zugrunde liegende rohe Ziel während einer Navigation oder Formularübermittlung ersetzt, behält OpenClaw die stabile tabId/Bezeichnung am Ersatz-Tab bei, sofern die Übereinstimmung nachgewiesen werden kann. Bevorzugen Sie suggestedTargetId.

Snapshot / Screenshot / Aktionen

Snapshot:

openclaw browser snapshotopenclaw browser snapshot --urls

Screenshot:

openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref e12openclaw browser screenshot --labels

• --full-page ist ausschließlich für Seitenaufnahmen vorgesehen und kann nicht mit --ref oder --element kombiniert werden.
• existing-session- / user-Profile unterstützen Seiten-Screenshots und --ref-Screenshots aus der Snapshot-Ausgabe, jedoch keine CSS---element-Screenshots.
• --labels überlagert den Screenshot mit den aktuellen Snapshot-Referenzen. Bei Playwright-basierten Profilen funktioniert dies mit --full-page (ganzseitige Überlagerung), --ref (Elementausschnitt-Überlagerung anhand einer ARIA-Referenz) und --element (Elementausschnitt-Überlagerung anhand eines CSS-Selektors); in den Elementausschnittmodi werden Bezeichnungen relativ zum Element projiziert. Die Antwort enthält außerdem ein annotations-Array (wird bei Leerstand ausgelassen) mit dem Begrenzungsrahmen jeder Referenz: ref, number, role, optional name und box: {x, y, width, height} im Koordinatenraum des aufgenommenen Bildes (Viewport / ganze Seite / elementrelativ). existing-session-Profile rendern bei Seiten-Screenshots eine chrome-mcp-Überlagerung, verwenden jedoch nicht die Playwright-Projektionshilfe und enthalten nicht annotations; CSS---element-Screenshots werden dort nicht unterstützt. Ohne Playwright oder chrome-mcp sind beschriftete Screenshots nicht verfügbar.
• snapshot --urls hängt erkannte Linkziele an KI-Snapshots an, damit Agenten direkte Navigationsziele auswählen können, anstatt ausschließlich anhand des Linktexts zu raten.

Navigieren/Klicken/Eingeben (referenzbasierte UI-Automatisierung):

openclaw browser navigate https://example.comopenclaw browser click <ref>openclaw browser click-coords 120 340openclaw browser type <ref> "hello"openclaw browser press Enteropenclaw browser hover <ref>openclaw browser scrollintoview <ref>openclaw browser drag <startRef> <endRef>openclaw browser select <ref> OptionA OptionBopenclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'openclaw browser wait --text "Done"openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>openclaw browser evaluate --fn 'const title = document.title; return title;'openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'

evaluate --fn akzeptiert eine Funktionsquelle, einen Ausdruck oder einen Anweisungsrumpf. Anweisungsrümpfe werden als asynchrone Funktionen gekapselt; verwenden Sie daher return für den gewünschten Rückgabewert. Verwenden Sie --timeout-ms, wenn die seitenseitige Funktion möglicherweise länger als der standardmäßige Auswertungs-Timeout benötigt. browser.evaluateEnabled=false (Standard: true) deaktiviert sowohl evaluate als auch wait --fn.

Aktionsantworten geben die aktuelle rohe targetId nach einem durch eine Aktion ausgelösten Seitenaustausch zurück, sofern OpenClaw den Ersatz-Tab nachweisen kann. Skripte sollten für langlebige Workflows weiterhin suggestedTargetId/Bezeichnungen speichern und übergeben.

Hilfsfunktionen für Dateien und Dialogfelder:

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>openclaw browser upload media://inbound/file.pdf --ref <ref>openclaw browser waitfordownloadopenclaw browser download <ref> report.pdfopenclaw browser dialog --acceptopenclaw browser dialog --dismiss --dialog-id d1

Verwaltete Chrome-Profile speichern gewöhnliche, durch Klicks ausgelöste Downloads im OpenClaw-Downloadverzeichnis (standardmäßig /tmp/openclaw/downloads oder im konfigurierten temporären Stammverzeichnis). Verwenden Sie waitfordownload oder download, wenn der Agent auf eine bestimmte Datei warten und deren Pfad zurückgeben muss; diese ausdrücklichen Warteoperationen übernehmen den nächsten Download. Für Uploads werden Dateien aus dem temporären Upload-Stammverzeichnis von OpenClaw und von OpenClaw verwaltete eingehende Medien akzeptiert, einschließlich media://inbound/<id>- und Sandbox-relativer media/inbound/<id>-Referenzen. Verschachtelte Medienreferenzen, Verzeichnisdurchquerung und beliebige lokale Pfade werden abgelehnt.

Wenn eine Aktion ein modales Dialogfeld öffnet, gibt die Aktionsantwort blockedByDialog mit browserState.dialogs.pending zurück; übergeben Sie --dialog-id, um es direkt zu beantworten. Außerhalb von OpenClaw verarbeitete Dialogfelder erscheinen unter browserState.dialogs.recent.

Stapelaktionen:

openclaw browser batch --actions '[{"kind":"wait","timeMs":500},{"kind":"click","ref":"12"},{"kind":"type","ref":"23","text":"hello"}]'openclaw browser batch --actions-file plan.jsonopenclaw browser batch --actions-file - --continue

openclaw browser batch sendet eine kind="batch"-/act-Anfrage mit verschachtelten BrowserActRequest-Aktionen (wait, click, type, evaluate, ...) – nicht open/navigate/snapshot/screenshot, bei denen es sich um CLI-Unterbefehle und nicht um /act-Arten handelt. --continue legt stopOnError=false fest (standardmäßig wird beim ersten Fehler abgebrochen); --target-id beschränkt den gesamten Batch auf einen Tab. Eine fehlgeschlagene verschachtelte Aktion führt dazu, dass der Befehl mit einem von null verschiedenen Statuscode beendet wird; verwenden Sie --json, um die geordnete results-Antwort beizubehalten. Den vollständigen Vertrag (Lebenszyklus von Referenzen, Konflikte bei Ziel-IDs, Fehlerzusammenfassung) finden Sie unter Browser-Batch-CLI. batch wird bei profile="user"- / bestehenden Sitzungsprofilen nicht unterstützt.

Status und Speicher

Viewport und Emulation:

openclaw browser resize 1280 720openclaw browser set viewport 1280 720openclaw browser set offline onopenclaw browser set media darkopenclaw browser set timezone Europe/Londonopenclaw browser set locale en-GBopenclaw browser set geo 51.5074 -0.1278 --accuracy 25openclaw browser set device "iPhone 14"openclaw browser set headers '{"x-test":"1"}'openclaw browser set credentials myuser mypass

Cookies und Speicher:

openclaw browser cookiesopenclaw browser cookies set session abc123 --url https://example.comopenclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set token abc123openclaw browser storage session clear

Fehlerbehebung

openclaw browser console --level erroropenclaw browser pdfopenclaw browser responsebody "**/api"openclaw browser highlight <ref>openclaw browser errors --clearopenclaw browser requests --filter apiopenclaw browser trace startopenclaw browser trace stop --out trace.zip

Vorhandenes Chrome über MCP

Verwenden Sie das integrierte Profil user oder erstellen Sie Ihr eigenes Profil existing-session:

openclaw browser --browser-profile user tabsopenclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"openclaw browser create-profile --name chrome-port --driver existing-session --cdp-url http://127.0.0.1:9222openclaw browser --browser-profile chrome-live tabs

Der Standardpfad für bestehende Sitzungen ist die automatische Verbindung von Chrome MCP ausschließlich auf dem Host. Wenn der Browser bereits mit einem DevTools-Endpunkt ausgeführt wird, übergeben Sie --cdp-url, damit Chrome MCP stattdessen eine Verbindung zu diesem Endpunkt herstellt. Verwenden Sie für Docker, Browserless oder andere Remote-Konfigurationen, bei denen die Semantik von Chrome MCP nicht benötigt wird, stattdessen ein CDP-Profil.

Aktuelle Einschränkungen für bestehende Sitzungen:

• Snapshot-gesteuerte Aktionen verwenden Referenzen, keine CSS-Selektoren.
• Unterstützte act-Anfragen verwenden einen integrierten Standardwert von 60000 ms, wenn Aufrufer timeoutMs auslassen; der aufrufbezogene Wert timeoutMs hat weiterhin Vorrang.
• click unterstützt nur Linksklicks.
• type unterstützt slowly=true nicht.
• press unterstützt delayMs nicht.
• hover, scrollintoview, drag, select und fill lehnen aufrufbezogene Zeitüberschreibungen ab; evaluate akzeptiert --timeout-ms.
• select unterstützt nur einen Wert.
• wait --load networkidle wird nicht unterstützt (funktioniert mit verwalteten und unformatierten/Remote-CDP-Profilen).
• Datei-Uploads erfordern --ref / --input-ref, unterstützen keine CSS---element und jeweils nur eine Datei.
• Dialog-Hooks unterstützen --timeout nicht.
• Screenshots unterstützen Seitenaufnahmen und --ref, jedoch keine CSS---element.
• responsebody, das Abfangen von Downloads, der PDF-Export und Batch-Aktionen erfordern weiterhin einen verwalteten Browser oder ein unformatiertes CDP-Profil.

Remote-Browsersteuerung (Node-Host-Proxy)

Wenn das Gateway auf einem anderen Rechner als der Browser ausgeführt wird, führen Sie auf dem Rechner mit Chrome/Brave/Edge/Chromium einen Node-Host aus. Das Gateway leitet Browseraktionen an diesen Node weiter; ein separater Browsersteuerungsserver ist nicht erforderlich.

Verwenden Sie gateway.nodes.browser.mode, um das automatische Routing zu steuern, und gateway.nodes.browser.node, um einen bestimmten Node festzulegen, wenn mehrere verbunden sind.

Sicherheit und Remote-Einrichtung: Browser-Tool, Remote-Zugriff, Tailscale, Sicherheit

Verwandte Themen

• CLI-Referenz
• Browser