Browser (clawd-verwaltet)

Browser-Tool: Clawd kann Chrome/Brave steuern. So richtest du es ein. OpenClaw kann ein dediziertes Chrome/Brave/Edge/Chromium-Profil betreiben, das der Agent steuert. Es ist von deinem persönlichen Browser getrennt und wird über einen kleinen lokalen Steuerungs-Service im Gateway verwaltet (nur Loopback). Kurzüberblick:

Als separaten, nur für den Agenten gedachten Browser verstehen.
Das Profil clawd berührt nicht dein persönliches Browser-Profil.
Der Agent kann Tabs öffnen, Seiten lesen, klicken und tippen in einer sicheren Spur.
Das Standard-Profil chrome nutzt den System-Standard-Chromium-Browser über den Extension-Relay; für den isolierten verwalteten Browser auf clawd wechseln.

Was du bekommst

Ein separates Browser-Profil clawd (standardmäßig orange Akzent).
Deterministische Tab-Steuerung (list/open/focus/close).
Agent-Aktionen (click/type/drag/select), Snapshots, Screenshots, PDFs.
Optionale Multi-Profil-Unterstützung (clawd, work, remote, …).

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

Schnellstart


openclaw browser --browser-profile clawd status
openclaw browser --browser-profile clawd start
openclaw browser --browser-profile clawd open https://example.com
openclaw browser --browser-profile clawd snapshot

Bei „Browser disabled“ in der Config aktivieren (siehe unten) und Gateway neu starten.

Profile: `clawd` vs `chrome`

clawd: verwalteter, isolierter Browser (keine Extension nötig).
chrome: Extension-Relay zu deinem System-Browser (OpenClaw-Extension muss an einen Tab angehängt sein).

browser.defaultProfile: "clawd" setzen für verwalteten Modus standardmäßig.

Konfiguration

Browser-Einstellungen stehen in ~/.clawdbot/openclaw.json.


{
  browser: {
    enabled: true,                    // default: true
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500,         // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    defaultProfile: "chrome",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      clawd: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" }
    }
  }
}

Hinweise:

Der Browser-Steuerungs-Service bindet an Loopback auf einem von gateway.port abgeleiteten Port (Standard: 18791, also Gateway + 2). Der Relay nutzt den nächsten Port (18792).
Bei Überschreibung des Gateway-Ports (gateway.port oder CLAWDBOT_GATEWAY_PORT) verschieben sich die abgeleiteten Browser-Ports in derselben „Familie“.
cdpUrl standardmäßig Relay-Port, wenn ungesetzt.
remoteCdpTimeoutMs gilt für Remote- (nicht-Loopback-) CDP-Erreichbarkeitsprüfungen.
remoteCdpHandshakeTimeoutMs gilt für Remote-CDP-WebSocket-Erreichbarkeitsprüfungen.
attachOnly: true heißt „niemals lokalen Browser starten; nur anhängen, wenn bereits laufend“.
color + pro-Profil-color färben die Browser-UI, damit du siehst, welches Profil aktiv ist.
Standard-Profil ist chrome (Extension-Relay). Für den verwalteten Browser defaultProfile: "clawd" nutzen.
Auto-Erkennung: System-Standard-Browser wenn Chromium-basiert; sonst Chrome → Brave → Edge → Chromium → Chrome Canary.
Lokale clawd-Profile vergeben cdpPort/cdpUrl automatisch — nur bei Remote-CDP setzen.

Brave (oder anderen Chromium-Browser) nutzen

Ist dein System-Standard-Browser Chromium-basiert (Chrome/Brave/Edge usw.), nutzt OpenClaw ihn automatisch. browser.executablePath setzen, 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-Steuerungs-Service und kann einen lokalen Browser starten.
Remote-Steuerung (Node-Host): Einen Node-Host auf der Maschine mit dem Browser betreiben; das Gateway proxied Browser-Aktionen dorthin.
Remote-CDP: browser.profiles.<name>.cdpUrl (oder browser.cdpUrl) setzen, um sich an einen Remote-Chromium-Browser anzuhängen. In dem 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:pass@provider.example)

OpenClaw bewahrt die Auth beim Aufruf von /json/*-Endpunkten und bei der CDP-WebSocket-Verbindung. Tokens bevorzugt über Umgebungsvariablen oder Secrets-Manager statt in Config-Dateien.

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

Läuft ein Node-Host auf der Maschine mit deinem Browser, kann OpenClaw Browser-Tool-Aufrufe ohne zusätzliche Browser-Config automatisch an diesen Node routen. Das ist der Standardweg für Remote-Gateways. Hinweise:

Der Node-Host exponiert seinen lokalen Browser-Steuerungs-Server über einen Proxy-Befehl.
Profile kommen aus der eigenen browser.profiles-Config des Nodes (wie lokal).
Deaktivieren, wenn unerwünscht:
- Auf dem Node: nodeHost.browserProxy.enabled=false
- Auf dem Gateway: gateway.nodes.browser.mode="off"

Browserless (gehosteter Remote-CDP)

Browserless ist ein gehosteter Chromium-Dienst, der CDP-Endpunkte über HTTPS exponiert. Du kannst ein OpenClaw-Browser-Profil auf einen Browserless-Region-Endpoint zeigen und 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:

<BROWSERLESS_API_KEY> durch deinen echten Browserless-Token ersetzen.
Den Region-Endpoint wählen, der zu deinem Browserless-Account passt (siehe deren Docs).

Sicherheit

Kernpunkte:

Browser-Steuerung nur über Loopback; Zugriff läuft über Gateway-Auth oder Node-Pairing.
Gateway und Node-Hosts in einem privaten Netz (Tailscale) halten; keine öffentliche Exposition.
Remote-CDP-URLs/Tokens als Secrets behandeln; Env-Vars oder Secrets-Manager bevorzugen.

Remote-CDP-Tipps:

HTTPS-Endpoints und kurzlebige Tokens bevorzugen, wo möglich.
Langlebige Tokens nicht direkt in Config-Dateien einbetten.

Profile (Multi-Browser)

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

clawd-verwaltet: dedizierte Chromium-basierte Browser-Instanz mit eigenem User-Data-Verzeichnis + CDP-Port
remote: explizite CDP-URL (Chromium-Browser läuft woanders)
Extension-Relay: deine bestehenden Chrome-Tab(s) über lokalen Relay + Chrome-Extension

Defaults:

Das Profil clawd wird bei Fehlen automatisch angelegt.
Das Profil chrome ist eingebaut für den Chrome-Extension-Relay (zeigt standardmäßig auf http://127.0.0.1:18792).
Lokale CDP-Ports werden standardmäßig aus 18800–18899 vergeben.
Beim Löschen eines Profils wird sein lokales Data-Verzeichnis in den Papierkorb verschoben.

Alle Steuerungs-Endpoints akzeptieren ?profile=<name>; die CLI nutzt --browser-profile.

Chrome-Extension-Relay (bestehenden Chrome nutzen)

OpenClaw kann auch deine bestehenden Chrome-Tabs steuern (ohne separate „clawd“-Chrome-Instanz) über einen lokalen CDP-Relay + Chrome-Extension. Vollständige Anleitung: Chrome Extension. Ablauf:

Das Gateway läuft lokal (gleiche Maschine) oder ein Node-Host läuft auf der Browser-Maschine.
Ein lokaler Relay-Server lauscht auf Loopback-cdpUrl (Standard: http://127.0.0.1:18792).
Du klickst auf das OpenClaw Browser Relay-Extension-Icon auf einem Tab zum Anhängen (es hängt nicht automatisch an).
Der Agent steuert diesen Tab über das normale browser-Tool durch Wahl des richtigen Profils.

Läuft das Gateway woanders, einen Node-Host auf der Browser-Maschine betreiben, damit das Gateway Browser-Aktionen proxen kann.

Sandboxed-Sitzungen

Ist die Agent-Sitzung sandboxed, nutzt das browser-Tool standardmäßig target="sandbox" (Sandbox-Browser). Chrome-Extension-Relay-Übernahme erfordert Host-Browser-Steuerung, also entweder:

Sitzung unsandboxed laufen lassen, oder
agents.defaults.sandbox.browser.allowHostControl: true setzen und beim Tool-Aufruf target="host" nutzen.

Setup

Extension laden (Dev/Unpacked):


openclaw browser extension install

Chrome → chrome://extensions → „Entwicklermodus“ aktivieren
„Entpackte Erweiterung laden“ → Verzeichnis wählen, das openclaw browser extension path ausgibt
Extension anheften, dann auf dem zu steuernden Tab klicken (Badge zeigt ON).

Nutzen:

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

Optional: Für anderen Namen oder Relay-Port eigenes Profil anlegen:


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

Hinweise:

Dieser Modus nutzt Playwright-on-CDP für die meisten Operationen (Screenshots/Snapshots/Actions).
Abhängen durch erneutes Klicken auf das Extension-Icon.

Isolations-Garantien

Eigenes User-Data-Verzeichnis: berührt nie dein persönliches Browser-Profil.
Eigene Ports: vermeidet 9222, um Kollisionen mit Dev-Workflows zu verhindern.
Deterministische Tab-Steuerung: Tabs per targetId ansprechen, nicht „letzter Tab“.

Browser-Auswahl

Beim lokalen Start wählt OpenClaw die erste verfügbare:

Chrome
Brave
Edge
Chromium
Chrome Canary

Überschreiben mit browser.executablePath. Plattformen:

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

Control-API (optional)

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

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
Actions: POST /navigate, POST /act
Hooks: POST /hooks/file-chooser, POST /hooks/dialog
Downloads: POST /download, POST /wait/download
Debug: GET /console, POST /pdf
Debug: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
Network: POST /response/body
State: GET /cookies, POST /cookies/set, POST /cookies/clear
State: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
Settings: 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 Endpoints akzeptieren ?profile=<name>.

Playwright-Anforderung

Einige Features (navigate/act/AI-Snapshot/Role-Snapshot, Element-Screenshots, PDF) benötigen Playwright. Ist Playwright nicht installiert, geben diese Endpoints einen klaren 501-Fehler zurück. ARIA-Snapshots und einfache Screenshots funktionieren weiterhin für clawd-verwaltetes Chrome. Beim Chrome-Extension-Relay-Treiber benötigen ARIA-Snapshots und Screenshots Playwright. Bei Playwright is not available in this gateway build: volles Playwright-Paket (nicht playwright-core) installieren und Gateway neu starten, oder OpenClaw mit Browser-Support neu installieren.

So funktioniert es (intern)

Ablauf auf hoher Ebene:

Ein kleiner Steuerungs-Server nimmt HTTP-Anfragen entgegen.
Er verbindet sich über CDP mit Chromium-Browsern (Chrome/Brave/Edge/Chromium).
Für erweiterte Aktionen (click/type/snapshot/PDF) nutzt er Playwright auf CDP.
Fehlt Playwright, sind nur Operationen ohne Playwright verfügbar.

So bleibt die Agent-Schnittstelle stabil und deterministisch, während du lokale/remote Browser und Profile tauschen kannst.

CLI-Kurzreferenz

Alle Befehle akzeptieren --browser-profile <name> für ein bestimmtes Profil. 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 /tmp/report.pdf
openclaw browser waitfordownload /tmp/report.pdf
openclaw browser upload /tmp/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

State:

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 --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 Arming-Aufrufe; vor dem Klick/Tastendruck ausführen, der den Chooser/Dialog auslöst.
upload kann Datei-Inputs auch direkt per --input-ref oder --element setzen.
snapshot:
- --format ai (Standard bei installiertem Playwright): AI-Snapshot mit numerischen Refs (aria-ref="<n>").
- --format aria: Accessibility-Tree (ohne Refs; nur Inspektion).
- --efficient (oder --mode efficient): kompaktes Role-Snapshot-Preset (interactive + compact + depth + niedrigeres maxChars).
- Config-Default (nur Tool/CLI): browser.snapshotDefaults.mode: "efficient" setzen für effiziente Snapshots, wenn der Aufrufer keinen Modus übergibt (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 ein iframe (zusammen mit Role-Refs wie e12).
- --interactive liefert eine flache, leicht wählbare Liste interaktiver Elemente (gut für Aktionen).
- --labels fügt einen Viewport-Screenshot mit überlagerten Ref-Labels hinzu (gibt MEDIA:<path> aus).
click/type/usw. benötigen einen ref aus snapshot (numerisch 12 oder Role-Ref e12). CSS-Selektoren werden für Aktionen bewusst nicht unterstützt.

Snapshots und Refs

OpenClaw unterstützt zwei „Snapshot“-Stile:

AI-Snapshot (numerische Refs): openclaw browser snapshot (Standard; --format ai) — Ausgabe: 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: rollenbasierte Liste/Struktur mit [ref=e12] (und optional [nth=1]). Aktionen: openclaw browser click e12, openclaw browser highlight e12. Intern wird der Ref über getByRole(...) (plus nth() bei Duplikaten) aufgelöst. --labels für Viewport-Screenshot mit überlagerten e12-Labels.

Ref-Verhalten:

Refs sind nicht stabil über Navigationen; bei Fehlern snapshot erneut ausführen und einen frischen Ref nutzen.
Wurde der Role-Snapshot mit --frame erstellt, gelten Role-Refs bis zum nächsten Role-Snapshot nur für dieses iframe.

Wait-Power-Ups

Du kannst auf mehr warten als nur Zeit/Text:

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

Kombinierbar:


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> nutzen (Role-Refs im interaktiven Modus bevorzugen)
Schlägt es weiter fehl: openclaw browser highlight <ref>, um zu sehen, was Playwright anspricht
Verhält sich die Seite seltsam: openclaw browser errors --clear, openclaw browser requests --filter api --clear
Für tiefes Debugging: Trace aufnehmen: openclaw browser trace start, Problem reproduzieren, openclaw browser trace stop (gibt TRACE:<path> aus)

JSON-Ausgabe

--json für Skripte und strukturierte Tools. Beispiele:


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

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

State- und Umgebungs-Stellschrauben

Nützlich für „Lass die Seite 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 --json '{"X-Debug":"1"}' (oder --clear)
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
Timezone/Locale: set timezone ..., set locale ...
Device/Viewport: set device "iPhone 14" (Playwright-Device-Presets), set viewport 1280 720

Sicherheit & Datenschutz

Das clawd-Browser-Profil kann eingeloggte Sitzungen enthalten; als sensibel behandeln.
browser act kind=evaluate / openclaw browser evaluate und wait --fn führen beliebiges JavaScript im Seitenkontext aus. Prompt-Injection kann das steuern. Mit browser.evaluateEnabled=false deaktivieren, wenn nicht benötigt.
Für Logins und Anti-Bot-Hinweise (X/Twitter usw.): Browser-Login + X/Twitter-Posts.
Gateway/Node-Host privat halten (Loopback oder nur Tailnet).
Remote-CDP-Endpoints sind mächtig; tunneln und schützen.

Fehlerbehebung

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

Agent-Tools + wie die Steuerung funktioniert

Der Agent erhält ein Tool für Browser-Automatisierung:

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

Zuordnung:

browser snapshot liefert einen stabilen UI-Baum (AI oder ARIA).
browser act nutzt die Snapshot-ref-IDs zum Klicken/Tippen/Ziehen/Auswählen.
browser screenshot erfasst Pixel (ganze Seite oder Element).
browser akzeptiert:
- profile für ein benanntes Browser-Profil (clawd, chrome oder Remote-CDP).
- target (sandbox | host | node) für den Ort des Browsers.
- Bei sandboxed Sitzungen erfordert target: "host" agents.defaults.sandbox.browser.allowHostControl=true.
- Ohne target: sandboxed Sitzungen standardmäßig sandbox, nicht-sandbox Sitzungen standardmäßig host.
- Ist ein browser-fähiger Node verbunden, kann das Tool automatisch dorthin routen, außer du setzt target="host" oder target="node".

So bleibt der Agent deterministisch und vermeidet fragile Selektoren.

Browser (clawd-verwaltet)

Was du bekommst

Schnellstart

Profile: clawd vs chrome

Konfiguration

Brave (oder anderen Chromium-Browser) nutzen

Lokale vs. Remote-Steuerung

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

Browserless (gehosteter Remote-CDP)

Sicherheit

Profile (Multi-Browser)

Chrome-Extension-Relay (bestehenden Chrome nutzen)

Sandboxed-Sitzungen

Setup

Isolations-Garantien

Browser-Auswahl

Control-API (optional)

Playwright-Anforderung

So funktioniert es (intern)

CLI-Kurzreferenz

Snapshots und Refs

Wait-Power-Ups

Debug-Workflows

JSON-Ausgabe

State- und Umgebungs-Stellschrauben

Sicherheit & Datenschutz

Fehlerbehebung

Agent-Tools + wie die Steuerung funktioniert

Profile: `clawd` vs `chrome`