Browser (OpenClaw-verwaltet)

OpenClaw kann ein dediziertes Chrome/Brave/Edge/Chromium-Profil betreiben, das der Agent steuert. Es ist von deinem persönlichen Browser isoliert und wird über einen kleinen lokalen Steuerungsdienst innerhalb des Gateways verwaltet (nur Loopback).

Einsteiger-Perspektive:

Stell dir das als einen separaten, agenten-exklusiven Browser vor.
Das openclaw-Profil berührt nicht dein persönliches Browserprofil.
Der Agent kann Tabs öffnen, Seiten lesen, klicken und tippen in einem sicheren Bereich.
Das Standard-chrome-Profil verwendet den System-Standard-Chromium-Browser über das Extension Relay; wechsle zu openclaw für den isolierten verwalteten Browser.

Was du bekommst

Ein separates Browserprofil namens openclaw (standardmäßig orangefarbener Akzent).
Deterministische Tab-Steuerung (auflisten/öffnen/fokussieren/schließen).
Agent-Aktionen (klicken/tippen/ziehen/auswählen), Snapshots, Screenshots, PDFs.
Optionale Multi-Profil-Unterstützung (openclaw, work, remote, …).

Dieser Browser ist nicht dein Alltagsbrowser. Er ist eine sichere, isolierte Oberfläche für Agent-Automatisierung und Verifikation.

Schnellstart

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 du „Browser disabled” erhältst, aktiviere ihn in der Konfiguration (siehe unten) und starte das Gateway neu.

Profile: `openclaw` vs `chrome`

openclaw: verwalteter, isolierter Browser (keine Extension erforderlich).
chrome: Extension Relay zu deinem System-Browser (erfordert, dass die OpenClaw- Extension an einen Tab angehängt ist).
existing-session: Offizieller Chrome-MCP-Attach-Flow für ein laufendes Chrome- Profil.

Setze browser.defaultProfile: "openclaw", wenn du den verwalteten Modus standardmäßig möchtest.

Konfiguration

Browser-Einstellungen befinden sich in ~/.openclaw/openclaw.json.

{
  browser: {
    enabled: true, // Standard: true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // Standard-Trusted-Network-Modus
      // allowPrivateNetwork: true, // Legacy-Alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // Legacy-Einzelprofil-Überschreibung
    remoteCdpTimeoutMs: 1500, // Remote CDP HTTP-Timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // Remote CDP WebSocket-Handshake-Timeout (ms)
    defaultProfile: "chrome",
    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" },
      chromeLive: {
        cdpPort: 18802,
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

Hinweise:

Der Browser-Steuerungsdienst bindet sich an Loopback auf einem Port, der von gateway.port abgeleitet wird (Standard: 18791, das ist Gateway + 2). Das Relay verwendet den nächsten Port (18792).
Wenn du den Gateway-Port überschreibst (gateway.port oder OPENCLAW_GATEWAY_PORT), verschieben sich die abgeleiteten Browser-Ports, um in der gleichen „Familie” zu bleiben.
cdpUrl fällt standardmäßig auf den Relay-Port zurück, wenn nicht gesetzt.
remoteCdpTimeoutMs gilt für Remote-(Nicht-Loopback-)CDP-Erreichbarkeitsprüfungen.
remoteCdpHandshakeTimeoutMs gilt für Remote-CDP-WebSocket-Erreichbarkeitsprüfungen.
Browser-Navigation/Tab-Öffnen ist SSRF-geschützt vor der Navigation und wird best-effort nach der Navigation bei finaler http(s)-URL erneut geprüft.
browser.ssrfPolicy.dangerouslyAllowPrivateNetwork ist standardmäßig true (Trusted-Network-Modell). Setze es auf false für striktes Public-only-Browsing.
browser.ssrfPolicy.allowPrivateNetwork bleibt als Legacy-Alias für Kompatibilität unterstützt.
attachOnly: true bedeutet „niemals einen lokalen Browser starten; nur anhängen, wenn er bereits läuft.”
color + pro-Profil color färben die Browser-UI ein, damit du siehst, welches Profil aktiv ist.
Standardprofil ist openclaw (OpenClaw-verwalteter eigenständiger Browser). Verwende defaultProfile: "chrome", um das Chrome Extension Relay zu nutzen.
Auto-Erkennungsreihenfolge: System-Standard-Browser wenn Chromium-basiert; sonst Chrome → Brave → Edge → Chromium → Chrome Canary.
Lokale openclaw-Profile weisen cdpPort/cdpUrl automatisch zu — setze diese nur für Remote-CDP.
driver: "existing-session" verwendet Chrome DevTools MCP statt Raw CDP. Setze cdpUrl nicht für diesen Treiber.

Brave (oder einen anderen Chromium-basierten Browser) verwenden

Wenn dein System-Standard-Browser Chromium-basiert ist (Chrome/Brave/Edge/etc.), verwendet OpenClaw ihn automatisch. Setze browser.executablePath, um die Auto-Erkennung zu überschreiben:

CLI-Beispiel:

openclaw config set browser.executablePath "/usr/bin/google-chrome"

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

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

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

Lokale vs. Remote-Steuerung

Lokale Steuerung (Standard): Das Gateway startet den Loopback-Steuerungsdienst und kann einen lokalen Browser starten.
Remote-Steuerung (Node Host): Führe einen Node Host auf dem Rechner aus, der den Browser hat; das Gateway leitet Browser-Aktionen dorthin weiter.
Remote CDP: Setze browser.profiles.<name>.cdpUrl (oder browser.cdpUrl), um sich an einen entfernten Chromium-basierten Browser anzuhängen. In diesem Fall startet OpenClaw keinen lokalen Browser.

Remote-CDP-URLs können Auth enthalten:

Query-Tokens (z.B. https://provider.example?token=<token>)
HTTP Basic Auth (z.B. https://user:[email protected])

OpenClaw behält die Auth bei, wenn es /json/*-Endpunkte aufruft und sich mit dem CDP-WebSocket verbindet. Bevorzuge Umgebungsvariablen oder Secrets-Manager für Tokens, statt sie in Konfigurationsdateien zu committen.

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

Wenn du einen Node Host auf dem Rechner betreibst, der deinen Browser hat, kann OpenClaw Browser-Tool-Aufrufe automatisch an diesen Node routen, ohne zusätzliche Browser-Konfiguration. Das ist der Standardpfad für Remote-Gateways.

Hinweise:

Der Node Host stellt seinen lokalen Browser-Steuerungsdienst über einen Proxy-Befehl bereit.
Profile stammen aus der eigenen browser.profiles-Konfiguration des Nodes (wie bei lokal).
Deaktivieren, wenn nicht gewünscht:
- Auf dem Node: nodeHost.browserProxy.enabled=false
- Auf dem Gateway: gateway.nodes.browser.mode="off"

Browserless (gehostetes Remote CDP)

Browserless ist ein gehosteter Chromium-Service, der CDP-Endpunkte über HTTPS bereitstellt. Du kannst ein OpenClaw-Browserprofil auf einen Browserless-Region-Endpunkt richten und dich mit deinem API-Key authentifizieren.

Beispiel:

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "https://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

Hinweise:

Ersetze <BROWSERLESS_API_KEY> durch deinen echten Browserless-Token.
Wähle den Region-Endpunkt, der zu deinem Browserless-Konto passt (siehe deren Dokumentation).

Direkte WebSocket-CDP-Anbieter

Einige gehostete Browser-Dienste stellen einen direkten WebSocket-Endpunkt bereit, anstatt der standardmäßigen HTTP-basierten CDP-Discovery (/json/version). OpenClaw unterstützt beides:

HTTP(S)-Endpunkte (z.B. Browserless) — OpenClaw ruft /json/version auf, um die WebSocket-Debugger-URL zu ermitteln, und verbindet sich dann.
WebSocket-Endpunkte (ws:// / wss://) — OpenClaw verbindet sich direkt, überspringt /json/version. Verwende dies für Dienste wie Browserbase oder andere Anbieter, die dir eine WebSocket-URL geben.

Browserbase

Browserbase ist eine Cloud-Plattform für den Betrieb headless Browser mit integriertem CAPTCHA-Löser, Stealth-Modus und Residential Proxies.

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

Hinweise:

Registriere dich und kopiere deinen API-Key vom Overview-Dashboard.
Ersetze <BROWSERBASE_API_KEY> durch deinen echten Browserbase-API-Key.
Browserbase erstellt automatisch eine Browser-Sitzung bei WebSocket-Verbindung, es ist also kein manueller Sitzungserstellungsschritt nötig.
Der kostenlose Tarif erlaubt eine gleichzeitige Sitzung und eine Browser-Stunde pro Monat. Siehe Preise für bezahlte Tarif-Limits.
Siehe die Browserbase-Dokumentation für die vollständige API- Referenz, SDK-Leitfäden und Integrationsbeispiele.

Sicherheit

Kernideen:

Browsersteuerung ist Loopback-only; Zugriff fließt über die Auth des Gateways oder Node-Pairing.
Wenn Browsersteuerung aktiviert und keine Auth konfiguriert ist, generiert OpenClaw beim Start automatisch gateway.auth.token und speichert es in der Konfiguration.
Gateway und Node Hosts in einem privaten Netzwerk halten (Tailscale); öffentliche Exposition vermeiden.
Remote-CDP-URLs/Tokens als Geheimnisse behandeln; Umgebungsvariablen oder einen Secrets-Manager bevorzugen.

Remote-CDP-Tipps:

Verschlüsselte Endpunkte (HTTPS oder WSS) und kurzlebige Tokens bevorzugen, wenn möglich.
Langlebige Tokens nicht direkt in Konfigurationsdateien einbetten.

Profile (Multi-Browser)

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

OpenClaw-verwaltet: eine dedizierte Chromium-basierte Browser-Instanz mit eigenem User-Data-Verzeichnis + CDP-Port
Remote: eine explizite CDP-URL (Chromium-basierter Browser, der woanders läuft)
Extension Relay: deine bestehenden Chrome-Tabs über das lokale Relay + Chrome-Extension
Existing Session: dein bestehendes Chrome-Profil über Chrome DevTools MCP Auto-Connect

Standardwerte:

Das openclaw-Profil wird automatisch erstellt, wenn es fehlt.
Das chrome-Profil ist eingebaut für das Chrome Extension Relay (zeigt standardmäßig auf http://127.0.0.1:18792).
Existing-Session-Profile sind Opt-in; erstelle sie mit --driver existing-session.
Lokale CDP-Ports werden standardmäßig ab 18800–18899 vergeben.
Das Löschen eines Profils verschiebt sein lokales Datenverzeichnis in den Papierkorb.

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

Chrome Extension Relay (bestehenden Chrome verwenden)

OpenClaw kann auch deine bestehenden Chrome-Tabs steuern (keine separate „openclaw”-Chrome-Instanz) über ein lokales CDP-Relay + eine Chrome-Extension.

Vollständiger Leitfaden: Chrome Extension

Ablauf:

Das Gateway läuft lokal (gleicher Rechner) oder ein Node Host läuft auf dem Browser-Rechner.
Ein lokaler Relay-Server lauscht auf einer Loopback-cdpUrl (Standard: http://127.0.0.1:18792).
Du klickst das OpenClaw Browser Relay-Extension-Symbol auf einem Tab, um es anzuhängen (es hängt sich nicht automatisch an).
Der Agent steuert diesen Tab über das normale browser-Tool, indem er das richtige Profil auswählt.

Wenn das Gateway woanders läuft, betreibe einen Node Host auf dem Browser-Rechner, damit das Gateway Browser-Aktionen dorthin weiterleiten kann.

Gesandboxte Sitzungen

Wenn die Agent-Sitzung gesandboxt ist, verwendet das browser-Tool möglicherweise standardmäßig target="sandbox" (Sandbox-Browser). Chrome Extension Relay-Übernahme erfordert Host-Browsersteuerung, daher entweder:

die Sitzung unsandboxt ausführen, oder
agents.defaults.sandbox.browser.allowHostControl: true setzen und target="host" beim Tool-Aufruf verwenden.

Einrichtung

Extension laden (Dev/entpackt):

openclaw browser extension install

Chrome → chrome://extensions → „Entwicklermodus” aktivieren
„Entpackte Erweiterung laden” → das von openclaw browser extension path ausgegebene Verzeichnis auswählen
Extension anpinnen, dann auf dem Tab klicken, den du steuern möchtest (Badge zeigt ON).

Verwenden:

CLI: openclaw browser --browser-profile chrome tabs
Agent-Tool: browser mit profile="chrome"

Optional: wenn du einen anderen Namen oder Relay-Port möchtest, erstelle dein eigenes Profil:

openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

Hinweise:

Dieser Modus basiert auf Playwright-on-CDP für die meisten Operationen (Screenshots/Snapshots/Aktionen).
Durch erneutes Klicken des Extension-Symbols trennen.

Chrome Existing-Session über MCP

OpenClaw kann sich auch über den offiziellen Chrome DevTools MCP Server an ein laufendes Chrome-Profil anhängen. Dies nutzt die Tabs und den Login-Status, die bereits in diesem Chrome-Profil offen sind.

Offizielle Hintergrundinfos und Setup-Referenzen:

Profil erstellen:

openclaw browser create-profile \
  --name chrome-live \
  --driver existing-session \
  --color "#00AA00"

Dann in Chrome:

chrome://inspect/#remote-debugging öffnen
Remote Debugging aktivieren
Chrome laufen lassen und die Verbindungsanfrage genehmigen, wenn OpenClaw sich anhängt

Live-Attach-Smoke-Test:

openclaw browser --browser-profile chrome-live start
openclaw browser --browser-profile chrome-live status
openclaw browser --browser-profile chrome-live tabs
openclaw browser --browser-profile chrome-live snapshot --format ai

Was Erfolg aussieht:

status zeigt driver: existing-session
status zeigt running: true
tabs listet deine bereits offenen Chrome-Tabs auf
snapshot gibt Refs vom ausgewählten Live-Tab zurück

Was du prüfen solltest, wenn Attach nicht funktioniert:

Chrome ist Version 144+
Remote Debugging ist unter chrome://inspect/#remote-debugging aktiviert
Chrome hat die Attach-Zustimmungsaufforderung angezeigt und du hast sie akzeptiert
Das Gateway oder der Node Host kann npx chrome-devtools-mcp@latest --autoConnect starten

Hinweise:

Dieser Pfad ist riskanter als das isolierte openclaw-Profil, weil er innerhalb deiner angemeldeten Browser-Sitzung agieren kann.
OpenClaw startet Chrome für diesen Treiber nicht; es hängt sich nur an eine bestehende Sitzung an.
OpenClaw verwendet hier den offiziellen Chrome DevTools MCP --autoConnect-Flow, nicht den Legacy-Standard-Profil-Remote-Debugging-Port-Workflow.
Existing-Session-Screenshots unterstützen Seitenaufnahmen und --ref-Element- Aufnahmen aus Snapshots, aber keine CSS --element-Selektoren.
Existing-Session wait --url unterstützt exakte, Teilstring- und Glob-Muster wie andere Browser-Treiber. wait --load networkidle wird noch nicht unterstützt.
Einige Features erfordern noch den Extension Relay- oder verwalteten Browser-Pfad, wie PDF-Export und Download-Abfangen.
Das Relay standardmäßig auf Loopback lassen. Wenn das Relay von einem anderen Netzwerk-Namespace erreichbar sein muss (zum Beispiel Gateway in WSL2, Chrome auf Windows), setze browser.relayBindHost auf eine explizite Bind-Adresse wie 0.0.0.0, während du das umgebende Netzwerk privat und authentifiziert hältst.

WSL2 / Cross-Namespace-Beispiel:

{
  browser: {
    enabled: true,
    relayBindHost: "0.0.0.0",
    defaultProfile: "chrome",
  },
}

Isolationsgarantien

Dediziertes User-Data-Verzeichnis: berührt niemals dein persönliches Browserprofil.
Dedizierte Ports: vermeidet 9222, um Konflikte mit Entwickler-Workflows zu verhindern.
Deterministische Tab-Steuerung: Tabs nach targetId ansprechen, nicht „letzter Tab”.

Browser-Auswahl

Beim lokalen Start wählt OpenClaw den ersten verfügbaren:

Chrome
Brave
Edge
Chromium
Chrome Canary

Überschreibe mit browser.executablePath.

Plattformen:

macOS: prüft /Applications und ~/Applications.
Linux: sucht nach google-chrome, brave, microsoft-edge, chromium, etc.
Windows: prüft gängige Installationsorte.

Steuerungs-API (optional)

Nur für lokale Integrationen stellt das Gateway eine kleine Loopback-HTTP-API bereit:

Status/Start/Stop: GET /, POST /start, POST /stop
Tabs: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
Snapshot/Screenshot: GET /snapshot, POST /screenshot
Aktionen: POST /navigate, POST /act
Hooks: POST /hooks/file-chooser, POST /hooks/dialog
Downloads: POST /download, POST /wait/download
Debugging: GET /console, POST /pdf
Debugging: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
Netzwerk: POST /response/body
Status: GET /cookies, POST /cookies/set, POST /cookies/clear
Status: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
Einstellungen: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

Alle Endpunkte akzeptieren ?profile=<name>.

Wenn Gateway-Auth konfiguriert ist, erfordern Browser-HTTP-Routen ebenfalls Auth:

Authorization: Bearer <gateway token>
x-openclaw-password: <gateway password> oder HTTP Basic Auth mit diesem Passwort

Playwright-Anforderung

Einige Features (navigate/act/AI snapshot/Role snapshot, Element-Screenshots, PDF) erfordern Playwright. Wenn Playwright nicht installiert ist, geben diese Endpunkte einen klaren 501- Fehler zurück. ARIA-Snapshots und einfache Screenshots funktionieren weiterhin für OpenClaw-verwaltetes Chrome. Für den Chrome Extension Relay-Treiber erfordern ARIA-Snapshots und Screenshots Playwright.

Wenn du Playwright is not available in this gateway build siehst, installiere das vollständige Playwright-Paket (nicht playwright-core) und starte das Gateway neu, oder installiere OpenClaw mit Browser-Unterstützung neu.

Docker Playwright-Installation

Wenn dein Gateway in Docker läuft, vermeide npx playwright (npm-Override-Konflikte). Verwende stattdessen die mitgelieferte CLI:

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

Um Browser-Downloads zu persistieren, setze PLAYWRIGHT_BROWSERS_PATH (zum Beispiel /home/node/.cache/ms-playwright) und stelle sicher, dass /home/node über OPENCLAW_HOME_VOLUME oder einen Bind-Mount persistiert wird. Siehe Docker.

Funktionsweise (intern)

Grober Ablauf:

Ein kleiner Steuerungsserver nimmt HTTP-Anfragen entgegen.
Er verbindet sich mit Chromium-basierten Browsern (Chrome/Brave/Edge/Chromium) über CDP.
Für erweiterte Aktionen (klicken/tippen/snapshot/PDF) verwendet er Playwright auf CDP-Basis.
Wenn Playwright fehlt, sind nur Nicht-Playwright-Operationen verfügbar.

Dieses Design hält den Agenten auf einer stabilen, deterministischen Schnittstelle, während du lokale/remote Browser und Profile austauschen kannst.

CLI-Kurzreferenz

Alle Befehle akzeptieren --browser-profile <name>, um ein bestimmtes Profil anzusprechen. Alle Befehle akzeptieren auch --json für maschinenlesbare Ausgabe (stabile Payloads).

Grundlagen:

openclaw browser status
openclaw browser start
openclaw browser stop
openclaw browser tabs
openclaw browser tab
openclaw browser tab new
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://example.com
openclaw browser focus abcd1234
openclaw browser close abcd1234

Inspektion:

openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref 12
openclaw browser screenshot --ref e12
openclaw browser snapshot
openclaw browser snapshot --format aria --limit 200
openclaw browser snapshot --interactive --compact --depth 6
openclaw browser snapshot --efficient
openclaw browser snapshot --labels
openclaw browser snapshot --selector "#main" --interactive
openclaw browser snapshot --frame "iframe#main" --interactive
openclaw browser console --level error
openclaw browser errors --clear
openclaw browser requests --filter api --clear
openclaw browser pdf
openclaw browser responsebody "**/api" --max-chars 5000

Aktionen:

openclaw browser navigate https://example.com
openclaw browser resize 1280 720
openclaw browser click 12 --double
openclaw browser click e12 --double
openclaw browser type 23 "hello" --submit
openclaw browser press Enter
openclaw browser hover 44
openclaw browser scrollintoview e12
openclaw browser drag 10 11
openclaw browser select 9 OptionA OptionB
openclaw browser download e12 report.pdf
openclaw browser waitfordownload report.pdf
openclaw browser upload /tmp/openclaw/uploads/file.pdf
openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
openclaw browser dialog --accept
openclaw browser wait --text "Done"
openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
openclaw browser highlight e12
openclaw browser trace start
openclaw browser trace stop

Status:

openclaw browser cookies
openclaw browser cookies set session abc123 --url "https://example.com"
openclaw browser cookies clear
openclaw browser storage local get
openclaw browser storage local set theme dark
openclaw browser storage session clear
openclaw browser set offline on
openclaw browser set headers --headers-json '{"X-Debug":"1"}'
openclaw browser set credentials user pass
openclaw browser set credentials --clear
openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
openclaw browser set geo --clear
openclaw browser set media dark
openclaw browser set timezone America/New_York
openclaw browser set locale en-US
openclaw browser set device "iPhone 14"

Hinweise:

upload und dialog sind Vorbereitungsaufrufe; führe sie vor dem Klick/Tastendruck aus, der den Chooser/Dialog auslöst.
Download- und Trace-Ausgabepfade sind auf OpenClaw-Temp-Roots beschränkt:
- Traces: /tmp/openclaw (Fallback: ${os.tmpdir()}/openclaw)
- Downloads: /tmp/openclaw/downloads (Fallback: ${os.tmpdir()}/openclaw/downloads)
Upload-Pfade sind auf ein OpenClaw-Temp-Uploads-Root beschränkt:
- Uploads: /tmp/openclaw/uploads (Fallback: ${os.tmpdir()}/openclaw/uploads)
upload kann auch Datei-Inputs direkt über --input-ref oder --element setzen.
snapshot:
- --format ai (Standard wenn Playwright installiert): gibt einen AI-Snapshot mit numerischen Refs zurück (aria-ref="<n>").
- --format aria: gibt den Accessibility-Tree zurück (keine Refs; nur Inspektion).
- --efficient (oder --mode efficient): kompaktes Role-Snapshot-Preset (interactive + compact + depth + niedrigere maxChars).
- Konfigurations-Standard (nur Tool/CLI): setze browser.snapshotDefaults.mode: "efficient", um effiziente Snapshots zu verwenden, wenn der Aufrufer keinen Modus angibt (siehe Gateway-Konfiguration).
- Role-Snapshot-Optionen (--interactive, --compact, --depth, --selector) erzwingen einen rollenbasierten Snapshot mit Refs wie ref=e12.
- --frame "<iframe selector>" begrenzt Role-Snapshots auf einen iframe (paart mit Role-Refs wie e12).
- --interactive gibt eine flache, leicht auswählbare Liste interaktiver Elemente aus (am besten für Aktionssteuerung).
- --labels fügt einen Viewport-only-Screenshot mit überlagerten Ref-Labels hinzu (gibt MEDIA:<path> aus).
click/type/etc. erfordern einen ref aus snapshot (entweder numerisch 12 oder Role-Ref e12). CSS-Selektoren werden absichtlich nicht für Aktionen unterstützt.

Snapshots und Refs

OpenClaw unterstützt zwei „Snapshot”-Stile:

AI-Snapshot (numerische Refs): openclaw browser snapshot (Standard; --format ai)
- Ausgabe: ein Text-Snapshot mit numerischen Refs.
- Aktionen: openclaw browser click 12, openclaw browser type 23 "hello".
- Intern wird der Ref über Playwrights aria-ref aufgelöst.
Role-Snapshot (Role-Refs wie e12): openclaw browser snapshot --interactive (oder --compact, --depth, --selector, --frame)
- Ausgabe: eine rollenbasierte Liste/Baum mit [ref=e12] (und optionalem [nth=1]).
- Aktionen: openclaw browser click e12, openclaw browser highlight e12.
- Intern wird der Ref über getByRole(...) (plus nth() für Duplikate) aufgelöst.
- Füge --labels hinzu, um einen Viewport-Screenshot mit überlagerten e12-Labels einzuschließen.

Ref-Verhalten:

Refs sind nicht stabil über Navigationen hinweg; wenn etwas fehlschlägt, führe snapshot erneut aus und verwende einen frischen Ref.
Wenn der Role-Snapshot mit --frame erstellt wurde, sind Role-Refs bis zum nächsten Role-Snapshot auf diesen iframe begrenzt.

Wait-Erweiterungen

Du kannst auf mehr als nur Zeit/Text warten:

Auf URL warten (Globs von Playwright unterstützt):
- openclaw browser wait --url "**/dash"
Auf Ladezustand warten:
- openclaw browser wait --load networkidle
Auf ein JS-Prädikat warten:
- openclaw browser wait --fn "window.ready===true"
Auf Sichtbarkeit eines Selektors warten:
- openclaw browser wait "#main"

Diese können kombiniert werden:

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

Debug-Workflows

Wenn eine Aktion fehlschlägt (z.B. „not visible”, „strict mode violation”, „covered”):

openclaw browser snapshot --interactive
click <ref> / type <ref> verwenden (Role-Refs im interaktiven Modus bevorzugen)
Wenn es immer noch fehlschlägt: openclaw browser highlight <ref>, um zu sehen, was Playwright anspricht
Wenn sich die Seite seltsam verhält:
- openclaw browser errors --clear
- openclaw browser requests --filter api --clear
Für tiefes Debugging: einen Trace aufzeichnen:
- openclaw browser trace start
- das Problem reproduzieren
- openclaw browser trace stop (gibt TRACE:<path> aus)

JSON-Ausgabe

--json ist für Scripting und strukturiertes Tooling.

Beispiele:

openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

Role-Snapshots im JSON enthalten refs plus einen kleinen stats-Block (lines/chars/refs/interactive), damit Tools über Payload-Größe und -Dichte urteilen können.

Status- und Umgebungsregler

Nützlich für „lass die Website sich wie X verhalten”-Workflows:

Cookies: cookies, cookies set, cookies clear
Storage: storage local|session get|set|clear
Offline: set offline on|off
Headers: set headers --headers-json '{"X-Debug":"1"}' (Legacy set headers --json '{"X-Debug":"1"}' bleibt unterstützt)
HTTP Basic Auth: set credentials user pass (oder --clear)
Geolocation: set geo <lat> <lon> --origin "https://example.com" (oder --clear)
Media: set media dark|light|no-preference|none
Zeitzone / Locale: set timezone ..., set locale ...
Gerät / Viewport:
- set device "iPhone 14" (Playwright-Gerätepresets)
- set viewport 1280 720

Sicherheit & Datenschutz

Das OpenClaw-Browserprofil kann angemeldete Sitzungen enthalten; behandle es als sensibel.
browser act kind=evaluate / openclaw browser evaluate und wait --fn führen beliebiges JavaScript im Seitenkontext aus. Prompt-Injection kann dies steuern. Deaktiviere es mit browser.evaluateEnabled=false, wenn du es nicht brauchst.
Für Logins und Anti-Bot-Hinweise (X/Twitter, etc.), siehe Browser-Login + X/Twitter-Posting.
Gateway/Node Host privat halten (Loopback oder Tailnet-only).
Remote-CDP-Endpunkte sind mächtig; tunnel und schütze sie.

Strict-Mode-Beispiel (private/interne Ziele standardmäßig blockieren):

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // optionales exaktes Allow
    },
  },
}

Fehlerbehebung

Für Linux-spezifische Probleme (besonders Snap-Chromium), siehe Browser-Fehlerbehebung.

Für WSL2-Gateway + Windows Chrome Split-Host-Setups, siehe WSL2 + Windows + Remote Chrome CDP Fehlerbehebung.

Agent-Tools + wie Steuerung funktioniert

Der Agent bekommt ein Tool für Browser-Automatisierung:

browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

Wie es abbildet:

browser snapshot gibt einen stabilen UI-Tree zurück (AI oder ARIA).
browser act verwendet die Snapshot-ref-IDs zum Klicken/Tippen/Ziehen/Auswählen.
browser screenshot nimmt Pixel auf (ganze Seite oder Element).
browser akzeptiert:
- profile, um ein benanntes Browserprofil zu wählen (openclaw, chrome oder Remote CDP).
- target (sandbox | host | node), um auszuwählen, wo der Browser lebt.
- In gesandboxten Sitzungen erfordert target: "host" agents.defaults.sandbox.browser.allowHostControl=true.
- Wenn target weggelassen wird: gesandboxte Sitzungen verwenden standardmäßig sandbox, nicht-gesandboxte Sitzungen standardmäßig host.
- Wenn ein browser-fähiger Node verbunden ist, kann das Tool automatisch dorthin routen, es sei denn, du pinnst target="host" oder target="node".

Das hält den Agenten deterministisch und vermeidet fragile Selektoren.

Browser (OpenClaw-verwaltet)

Was du bekommst

Schnellstart

Profile: openclaw vs chrome

Konfiguration

Brave (oder einen anderen Chromium-basierten Browser) verwenden

Lokale vs. Remote-Steuerung

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

Browserless (gehostetes Remote CDP)

Direkte WebSocket-CDP-Anbieter

Browserbase

Sicherheit

Profile (Multi-Browser)

Chrome Extension Relay (bestehenden Chrome verwenden)

Gesandboxte Sitzungen

Einrichtung

Chrome Existing-Session über MCP

Isolationsgarantien

Browser-Auswahl

Steuerungs-API (optional)

Playwright-Anforderung

Docker Playwright-Installation

Funktionsweise (intern)

CLI-Kurzreferenz

Snapshots und Refs

Wait-Erweiterungen

Debug-Workflows

JSON-Ausgabe

Status- und Umgebungsregler

Sicherheit & Datenschutz

Fehlerbehebung

Agent-Tools + wie Steuerung funktioniert

Profile: `openclaw` vs `chrome`