openclaw browser

Verwalten Sie die Browser-Kontrollfläche von OpenClaw und führen Sie Browser-Aktionen aus (Lebenszyklus, Profile, Tabs, Snapshots, Screenshots, Navigation, Eingabe, Zustandsemulation und Debugging).

Verwandt:

• Browser-Tool + API: Browser-Tool

Allgemeine Flags

• --url <gatewayWsUrl>: Gateway-WebSocket-URL (Standardwert aus der Konfiguration).
• --token <token>: Gateway-Token (falls erforderlich).
• --timeout <ms>: Anfrage-Timeout (ms).
• --expect-final: auf eine finale Gateway-Antwort warten.
• --browser-profile <name>: ein Browser-Profil auswählen (Standardwert aus der Konfiguration).
• --json: maschinenlesbare Ausgabe (wo unterstützt).

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 die CDP-Bereitschaft. Wenn start und tabs erfolgreich sind, aber open oder navigate fehlschlägt, ist die Browser-Kontrollebene funktionsfähig, und der Fehler liegt normalerweise an der Navigations-SSRF-Richtlinie.

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: Browser-Fehlerbehebung

Lebenszyklus

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

Hinweise:

• doctor --deep fügt eine Live-Snapshot-Prüfung hinzu. Das ist nützlich, wenn die grundlegende CDP-Bereitschaft grün ist, Sie aber einen Nachweis möchten, dass der aktuelle Tab inspiziert werden kann.
• Für attachOnly- und Remote-CDP-Profile schließt openclaw browser stop die aktive Kontrollsitzung und löscht temporäre Emulationsüberschreibungen, auch wenn OpenClaw den Browser-Prozess nicht selbst gestartet hat.
• Für lokal verwaltete Profile stoppt openclaw browser stop den erzeugten Browser-Prozess.
• openclaw browser 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 headless ausgeführt, sofern nicht OPENCLAW_BROWSER_HEADLESS=0, browser.headless=false oder browser.profiles.<name>.headless=false ausdrücklich einen sichtbaren Browser anfordert.

Wenn der Befehl fehlt

Wenn openclaw browser ein unbekannter Befehl ist, prüfen Sie plugins.allow in ~/.openclaw/openclaw.json.

Wenn plugins.allow vorhanden ist, listen Sie das gebündelte Browser-Plugin ausdrücklich auf, sofern die Konfiguration nicht bereits einen browser-Block auf Root-Ebene enthält:

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

Ein ausdrücklicher browser-Block auf Root-Ebene, zum Beispiel browser.enabled=true oder browser.profiles.<name>, aktiviert das gebündelte Browser-Plugin ebenfalls unter einer restriktiven Plugin-Zulassungsliste.

Verwandt: Browser-Tool

Profile

Profile sind benannte Routing-Konfigurationen für Browser. In der Praxis:

• openclaw: startet eine dedizierte, von OpenClaw verwaltete Chrome-Instanz oder verbindet sich damit (isoliertes Benutzerdatenverzeichnis).
• user: steuert Ihre bestehende angemeldete Chrome-Sitzung über Chrome DevTools MCP.
• benutzerdefinierte CDP-Profile: verweisen auf einen lokalen oder Remote-CDP-Endpunkt.

openclaw browser profilesopenclaw 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

Ein bestimmtes Profil verwenden:

openclaw browser --browser-profile work tabs

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 zurück, dann die stabile tabId wie t1, das optionale Label und die rohe targetId. Agenten sollten suggestedTargetId wieder an focus, close, Snapshots und Aktionen übergeben. Sie können ein Label mit open --label, tab new --label oder tab label zuweisen; Labels, Tab-IDs, rohe Target-IDs und eindeutige Target-ID-Präfixe werden alle akzeptiert. Das Anfragefeld heißt aus Kompatibilitätsgründen weiterhin targetId, akzeptiert aber diese Tab-Referenzen. Behandeln Sie rohe Target-IDs als Diagnose-Handles, nicht als dauerhafte Agentenspeicher. Wenn Chromium das zugrunde liegende rohe Target während einer Navigation oder Formularübermittlung ersetzt, hält OpenClaw die stabile tabId/das Label am Ersatz-Tab fest, wenn es die Übereinstimmung nachweisen kann. Rohe Target-IDs bleiben flüchtig; 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

Hinweise:

• --full-page ist nur für Seitenerfassungen vorgesehen; es kann nicht mit --ref oder --element kombiniert werden.
• existing-session- / user-Profile unterstützen Seiten-Screenshots und --ref-Screenshots aus der Snapshot-Ausgabe, aber keine CSS---element-Screenshots.
• --labels blendet aktuelle Snapshot-Refs auf dem Screenshot ein. Bei Playwright-gestützten Profilen funktioniert es mit --full-page (Label-Overlay für vollständige Seiten), --ref (Label-Overlay für Elementausschnitt nach ARIA-Ref) und --element (Label-Overlay für Elementausschnitt nach CSS-Selektor); in Elementausschnitt-Modi werden Labels relativ zum Element projiziert. Die Antwort enthält außerdem ein annotations-Array mit der Begrenzungsbox jeder Ref. Jedes Element hat ref, number, role, optional name und box: {x, y, width, height}; Koordinaten befinden sich im Raum des erfassten Bildes (Viewport / vollständige Seite / elementrelativ). Das Feld wird ausgelassen, wenn es leer ist. existing-session-Profile rendern ein chrome-mcp-Overlay auf Seiten-Screenshots, verwenden aber nicht den Playwright-Projektionshelfer und enthalten keine annotations; CSS---element-Screenshots werden dort nicht unterstützt. Ohne Playwright oder chrome-mcp sind beschriftete Screenshots nicht verfügbar. Frühere Releases haben --full-page, --ref und --element bei beschrifteten Playwright-Screenshots ignoriert und immer eine Viewport-Erfassung zurückgegeben; beschriftete Screenshots berücksichtigen diese Bereiche jetzt.
• snapshot --urls hängt entdeckte Linkziele an KI-Snapshots an, sodass Agenten direkte Navigationsziele auswählen können, statt nur aus dem Linktext zu raten.

Navigieren/Klicken/Tippen (Ref-basierte 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 Anweisungskörper. Anweisungskörper werden als Async-Funktionen umschlossen; verwenden Sie daher return für den Wert, den Sie zurückhaben möchten. Verwenden Sie evaluate --timeout-ms <ms>, wenn die seitenseitige Funktion länger als den standardmäßigen Evaluate-Timeout benötigen kann.

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

Datei- und Dialoghelfer:

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 (/tmp/openclaw/downloads standardmäßig oder im konfigurierten temporären Root). Verwenden Sie waitfordownload oder download, wenn der Agent auf eine bestimmte Datei warten und ihren Pfad zurückgeben muss; diese expliziten Wartemechanismen besitzen den nächsten Download. Uploads akzeptieren Dateien aus dem temporären Upload-Root von OpenClaw und von OpenClaw verwaltete eingehende Medien, einschließlich media://inbound/<id>- und sandboxrelativer media/inbound/<id>-Referenzen. Verschachtelte Medien-Refs, Pfadtraversierung und beliebige lokale Pfade bleiben abgelehnt. Wenn eine Aktion einen modalen Dialog öffnet, gibt die Aktionsantwort blockedByDialog mit browserState.dialogs.pending zurück; übergeben Sie --dialog-id, um direkt darauf zu antworten. Außerhalb von OpenClaw behandelte Dialoge erscheinen unter browserState.dialogs.recent.

Zustand und Speicher

Viewport + 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 + 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

Debugging

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

Bestehendes Chrome über MCP

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

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 standardmäßige existing-session-Pfad ist eine host-only automatische Chrome-MCP-Verbindung. Wenn der Browser bereits mit einem DevTools-Endpunkt ausgeführt wird, übergeben Sie --cdp-url, damit Chrome MCP stattdessen an diesen Endpunkt anschließt. Verwenden Sie für Docker, Browserless oder andere Remote-Setups, bei denen Chrome-MCP-Semantik nicht erforderlich ist, ein CDP-Profil.

Aktuelle existing-session-Einschränkungen:

• Snapshot-gesteuerte Aktionen verwenden Refs, keine CSS-Selektoren
• browser.actionTimeoutMs setzt unterstützte act-Anfragen standardmäßig auf 60000 ms, wenn Aufrufer timeoutMs weglassen; timeoutMs pro Aufruf hat weiterhin Vorrang.
• click ist nur ein Linksklick
• type unterstützt slowly=true nicht
• press unterstützt delayMs nicht
• hover, scrollintoview, drag, select, fill und evaluate lehnen Timeout-Überschreibungen pro Aufruf ab
• select unterstützt nur einen Wert
• wait --load networkidle wird bei Profilen mit bestehender Sitzung nicht unterstützt (funktioniert mit verwalteten und Raw-/Remote-CDP-Profilen)
• Datei-Uploads erfordern --ref / --input-ref, unterstützen kein CSS --element und unterstützen derzeit jeweils nur eine Datei
• Dialog-Hooks unterstützen --timeout nicht
• Screenshots unterstützen Seitenaufnahmen und --ref, aber kein CSS---element
• responsebody, Download-Abfangen, PDF-Export und Batch-Aktionen erfordern weiterhin einen verwalteten Browser oder ein Raw-CDP-Profil

Remote-Browser-Steuerung (Node-Host-Proxy)

Wenn der Gateway auf einem anderen Rechner als der Browser läuft, führen Sie einen Node-Host auf dem Rechner aus, auf dem Chrome/Brave/Edge/Chromium installiert ist. Der Gateway leitet Browser-Aktionen per Proxy an diesen Node weiter (kein separater Browser-Steuerungsserver erforderlich).

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

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

Verwandte Themen

• CLI-Referenz
• Browser