Browser (openclaw-managed)
OpenClaw kann ein dediziertes Chrome/Brave/Edge/Chromium-Profil ausführen, das der Agent steuert. Es ist von deinem persönlichen Browser isoliert und wird über einen kleinen lokalen Steuerungsdienst innerhalb des Gateway verwaltet (nur Loopback).
Einsteigeransicht:
- Stell es dir als separaten, nur für den Agent bestimmten Browser vor.
- Das
openclaw-Profil berührt nicht dein persönliches Browser-Profil. - Der Agent kann Tabs öffnen, Seiten lesen, klicken und tippen in einer sicheren Umgebung.
- Das Standard-
chrome-Profil nutzt den Standard-Chromium-Browser des Systems über das Extension-Relay; wechsle zuopenclawfür den isolierten verwalteten Browser.
Was du bekommst
- Ein separates Browser-Profil namens openclaw (standardmäßig mit orangem Akzent).
- Deterministische Tab-Steuerung (list/open/focus/close).
- Agent-Aktionen (click/type/drag/select), Snapshots, Screenshots, PDFs.
- Optionale Multi-Profil-Unterstützung (
openclaw,work,remote, …).
Dieser Browser ist nicht dein täglicher Browser. Er ist eine sichere, isolierte Oberfläche für Agent-Automatisierung und Verifikation.
Quick start
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 die OpenClaw Extension, die an einen Tab angehängt ist).
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, // 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: {
openclaw: { cdpPort: 18800, color: "#FF4500" },
work: { cdpPort: 18801, color: "#0066CC" },
remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
},
},
}
Hinweise:
- Der Browser-Steuerungsdienst bindet sich an Loopback auf einem Port, der von
gateway.portabgeleitet wird (Standard:18791, also Gateway + 2). Das Relay nutzt den nächsten Port (18792). - Wenn du den Gateway-Port überschreibst (
gateway.portoderOPENCLAW_GATEWAY_PORT), verschieben sich die abgeleiteten Browser-Ports, um in derselben “Familie” zu bleiben. cdpUrlverwendet standardmäßig den Relay-Port, wenn nicht gesetzt.remoteCdpTimeoutMsgilt für Remote-CDP-Erreichbarkeitsprüfungen (nicht Loopback).remoteCdpHandshakeTimeoutMsgilt für Remote-CDP-WebSocket-Erreichbarkeitsprüfungen.attachOnly: truebedeutet “niemals einen lokalen Browser starten; nur anhängen, wenn er bereits läuft.”color+ profilspezifischecolorfärben die Browser-UI, damit du siehst, welches Profil aktiv ist.- Standardprofil ist
chrome(Extension-Relay). NutzedefaultProfile: "openclaw"für den verwalteten Browser. - Auto-Erkennungsreihenfolge: Standard-Browser des Systems, falls Chromium-basiert; ansonsten Chrome → Brave → Edge → Chromium → Chrome Canary.
- Lokale
openclaw-Profile weisen automatischcdpPort/cdpUrlzu — setze diese nur für Remote-CDP.
Brave nutzen (oder einen anderen Chromium-basierten Browser)
Wenn dein Standard-Browser des Systems Chromium-basiert ist (Chrome/Brave/Edge/etc),
nutzt 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 der Maschine aus, die den Browser hat; das Gateway leitet Browser-Aktionen dorthin weiter.
- Remote-CDP: setze
browser.profiles.<name>.cdpUrl(oderbrowser.cdpUrl), um dich an einen Remote-Chromium-basierten Browser anzuhängen. In diesem Fall startet OpenClaw keinen lokalen Browser.
Remote-CDP-URLs können Authentifizierung enthalten:
- Query-Tokens (z.B.
https://provider.example?token=<token>) - HTTP Basic Auth (z.B.
https://user:[email protected])
OpenClaw bewahrt die Authentifizierung beim Aufruf von /json/*-Endpoints und beim Verbinden
mit dem CDP-WebSocket. Bevorzuge Umgebungsvariablen oder Secrets-Manager für
Tokens, anstatt sie in Konfigurationsdateien zu committen.
Node-Browser-Proxy (Zero-Config-Standard)
Wenn du einen Node-Host auf der Maschine ausführst, die deinen Browser hat, kann OpenClaw Browser-Tool-Aufrufe automatisch an diesen Node weiterleiten, ohne zusätzliche Browser-Konfiguration. Das 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 lokal). - Deaktiviere es, wenn du es nicht möchtest:
- Auf dem Node:
nodeHost.browserProxy.enabled=false - Auf dem Gateway:
gateway.nodes.browser.mode="off"
- Auf dem Node:
Browserless (gehostetes Remote-CDP)
Browserless ist ein gehosteter Chromium-Dienst, der CDP-Endpoints über HTTPS bereitstellt. Du kannst ein OpenClaw-Browser-Profil auf einen Browserless-Region-Endpoint zeigen lassen 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-Endpoint, der zu deinem Browserless-Account passt (siehe deren Dokumentation).
Sicherheit
Wichtige Punkte:
- Browser-Steuerung ist nur über Loopback; Zugriff erfolgt über die Gateway-Authentifizierung oder Node-Pairing.
- Halte das Gateway und alle Node-Hosts in einem privaten Netzwerk (Tailscale); vermeide öffentliche Exposition.
- Behandle Remote-CDP-URLs/Tokens als Secrets; bevorzuge Umgebungsvariablen oder einen Secrets-Manager.
Remote-CDP-Tipps:
- Bevorzuge HTTPS-Endpoints und kurzlebige Tokens, wo möglich.
- Vermeide es, langlebige Tokens direkt in Konfigurationsdateien einzubetten.
Profile (Multi-Browser)
OpenClaw unterstützt mehrere benannte Profile (Routing-Konfigurationen). Profile können sein:
- openclaw-managed: 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
Standardwerte:
- Das
openclaw-Profil wird automatisch erstellt, falls es fehlt. - Das
chrome-Profil ist eingebaut für das Chrome-Extension-Relay (zeigt standardmäßig aufhttp://127.0.0.1:18792). - Lokale CDP-Ports werden standardmäßig aus 18800–18899 zugewiesen.
- Das Löschen eines Profils verschiebt dessen lokales Datenverzeichnis in den Papierkorb.
Alle Steuerungs-Endpoints akzeptieren ?profile=<name>; die CLI nutzt --browser-profile.
Chrome-Extension-Relay (nutze deinen bestehenden Chrome)
OpenClaw kann auch deine bestehenden Chrome-Tabs steuern (keine separate “openclaw”-Chrome-Instanz) über ein lokales CDP-Relay + eine 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 einer Loopback-
cdpUrl(Standard:http://127.0.0.1:18792). - Du klickst auf das OpenClaw Browser Relay-Extension-Icon auf einem Tab, um ihn 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, führe einen Node-Host auf der Browser-Maschine aus, damit das Gateway Browser-Aktionen weiterleiten kann.
Sandboxed Sessions
Wenn die Agent-Session sandboxed ist, verwendet das browser-Tool möglicherweise standardmäßig target="sandbox" (Sandbox-Browser).
Chrome-Extension-Relay-Übernahme erfordert Host-Browser-Steuerung, also entweder:
- führe die Session unsandboxed aus, oder
- setze
agents.defaults.sandbox.browser.allowHostControl: trueund nutzetarget="host"beim Aufruf des Tools.
Setup
- Lade die Extension (dev/unpacked):
openclaw browser extension install
- Chrome →
chrome://extensions→ aktiviere “Entwicklermodus” - “Entpackte Erweiterung laden” → wähle das Verzeichnis aus, das von
openclaw browser extension pathausgegeben wird - Pinne die Extension, dann klicke darauf auf dem Tab, den du steuern möchtest (Badge zeigt
ON).
- Nutze sie:
- CLI:
openclaw browser --browser-profile chrome tabs - Agent-Tool:
browsermitprofile="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/Actions).
- Trenne die Verbindung, indem du erneut auf das Extension-Icon klickst.
Isolationsgarantien
- Dediziertes User-Data-Verzeichnis: berührt niemals dein persönliches Browser-Profil.
- Dedizierte Ports: vermeidet
9222, um Kollisionen mit Dev-Workflows zu verhindern. - Deterministische Tab-Steuerung: zielt auf Tabs über
targetId, nicht “letzter Tab”.
Browser-Auswahl
Beim lokalen Start wählt OpenClaw den ersten verfügbaren:
- Chrome
- Brave
- Edge
- Chromium
- Chrome Canary
Du kannst dies mit browser.executablePath überschreiben.
Plattformen:
- macOS: prüft
/Applicationsund~/Applications. - Linux: sucht nach
google-chrome,brave,microsoft-edge,chromium, etc. - Windows: prüft gängige Installationsorte.
Control-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 - Actions:
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 - 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) erfordern Playwright. Wenn Playwright nicht installiert ist, geben diese Endpoints einen klaren 501-Fehler zurück. ARIA-Snapshots und einfache Screenshots funktionieren weiterhin für openclaw-managed 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.
Wie es funktioniert (intern)
High-Level-Ablauf:
- Ein kleiner Control-Server akzeptiert HTTP-Requests.
- Er verbindet sich mit Chromium-basierten Browsern (Chrome/Brave/Edge/Chromium) über CDP.
- Für erweiterte Aktionen (click/type/snapshot/PDF) nutzt er Playwright auf CDP.
- Wenn Playwright fehlt, sind nur Nicht-Playwright-Operationen verfügbar.
Dieses Design hält den Agent auf einem stabilen, deterministischen Interface, 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).
Basics:
openclaw browser statusopenclaw browser startopenclaw browser stopopenclaw browser tabsopenclaw browser tabopenclaw browser tab newopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://example.comopenclaw browser focus abcd1234openclaw browser close abcd1234
Inspektion:
openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref 12openclaw browser screenshot --ref e12openclaw browser snapshotopenclaw browser snapshot --format aria --limit 200openclaw browser snapshot --interactive --compact --depth 6openclaw browser snapshot --efficientopenclaw browser snapshot --labelsopenclaw browser snapshot --selector "#main" --interactiveopenclaw browser snapshot --frame "iframe#main" --interactiveopenclaw browser console --level erroropenclaw browser errors --clearopenclaw browser requests --filter api --clearopenclaw browser pdfopenclaw browser responsebody "**/api" --max-chars 5000
Actions:
openclaw browser navigate https://example.comopenclaw browser resize 1280 720openclaw browser click 12 --doubleopenclaw browser click e12 --doubleopenclaw browser type 23 "hello" --submitopenclaw browser press Enteropenclaw browser hover 44openclaw browser scrollintoview e12openclaw browser drag 10 11openclaw browser select 9 OptionA OptionBopenclaw browser download e12 /tmp/report.pdfopenclaw browser waitfordownload /tmp/report.pdfopenclaw browser upload /tmp/file.pdfopenclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'openclaw browser dialog --acceptopenclaw browser wait --text "Done"openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"openclaw browser evaluate --fn '(el) => el.textContent' --ref 7openclaw browser highlight e12openclaw browser trace startopenclaw browser trace stop
State:
openclaw browser cookiesopenclaw browser cookies set session abc123 --url "https://example.com"openclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set theme darkopenclaw browser storage session clearopenclaw browser set offline onopenclaw browser set headers --json '{"X-Debug":"1"}'openclaw browser set credentials user passopenclaw browser set credentials --clearopenclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"openclaw browser set geo --clearopenclaw browser set media darkopenclaw browser set timezone America/New_Yorkopenclaw browser set locale en-USopenclaw browser set device "iPhone 14"
Hinweise:
uploadunddialogsind Arming-Aufrufe; führe sie vor dem click/press aus, der den Chooser/Dialog auslöst.uploadkann auch Datei-Inputs direkt über--input-refoder--elementsetzen.snapshot:--format ai(Standard, wenn Playwright installiert ist): gibt einen AI-Snapshot mit numerischen Refs (aria-ref="<n>") zurück.--format aria: gibt den Accessibility-Tree zurück (keine Refs; nur zur Inspektion).--efficient(oder--mode efficient): kompaktes Role-Snapshot-Preset (interactive + compact + depth + niedrigere maxChars).- Config-Standard (nur Tool/CLI): setze
browser.snapshotDefaults.mode: "efficient", um effiziente Snapshots zu nutzen, wenn der Aufrufer keinen Modus übergibt (siehe Gateway-Konfiguration). - Role-Snapshot-Optionen (
--interactive,--compact,--depth,--selector) erzwingen einen rollenbasierten Snapshot mit Refs wieref=e12. --frame "<iframe selector>"beschränkt Role-Snapshots auf ein iframe (passt zu Role-Refs wiee12).--interactivegibt eine flache, leicht auswählbare Liste interaktiver Elemente aus (am besten für Aktionen).--labelsfügt einen Viewport-only-Screenshot mit überlagerten Ref-Labels hinzu (gibtMEDIA:<path>aus).
click/type/etc erfordern einerefaussnapshot(entweder numerisch12oder Role-Refe12). CSS-Selektoren werden für Aktionen absichtlich nicht unterstützt.
Snapshots und Refs
OpenClaw unterstützt zwei “Snapshot”-Stile:
-
AI-Snapshot (numerische Refs):
openclaw browser snapshot(Standard;--format ai)- Output: ein Text-Snapshot, der numerische Refs enthält.
- Actions:
openclaw browser click 12,openclaw browser type 23 "hello". - Intern wird die Ref über Playwrights
aria-refaufgelöst.
-
Role-Snapshot (Role-Refs wie
e12):openclaw browser snapshot --interactive(oder--compact,--depth,--selector,--frame)- Output: eine rollenbasierte Liste/Baum mit
[ref=e12](und optional[nth=1]). - Actions:
openclaw browser click e12,openclaw browser highlight e12. - Intern wird die Ref über
getByRole(...)aufgelöst (plusnth()für Duplikate). - Füge
--labelshinzu, um einen Viewport-Screenshot mit überlagertene12-Labels zu erhalten.
- Output: eine rollenbasierte Liste/Baum mit
Ref-Verhalten:
- Refs sind nicht stabil über Navigationen hinweg; wenn etwas fehlschlägt, führe
snapshoterneut aus und nutze eine frische Ref. - Wenn der Role-Snapshot mit
--frameerstellt wurde, sind Role-Refs auf dieses iframe beschränkt, bis zum nächsten Role-Snapshot.
Wait-Power-Ups
Du kannst auf mehr als nur Zeit/Text warten:
- Warte auf URL (Globs werden von Playwright unterstützt):
openclaw browser wait --url "**/dash"
- Warte auf Load-State:
openclaw browser wait --load networkidle
- Warte auf ein JS-Prädikat:
openclaw browser wait --fn "window.ready===true"
- Warte darauf, dass ein Selektor sichtbar wird:
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- Nutze
click <ref>/type <ref>(bevorzuge Role-Refs im interaktiven Modus) - Wenn es immer noch fehlschlägt:
openclaw browser highlight <ref>, um zu sehen, was Playwright anvisiert - Wenn sich die Seite seltsam verhält:
openclaw browser errors --clearopenclaw browser requests --filter api --clear
- Für tiefes Debugging: zeichne einen Trace auf:
openclaw browser trace start- reproduziere das Problem
openclaw browser trace stop(gibtTRACE:<path>aus)
JSON-Output
--json ist für Scripting 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 über Payload-Größe und -Dichte nachdenken können.
State- und Environment-Knöpfe
Diese sind 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 openclaw-Browser-Profil kann eingeloggte Sessions enthalten; behandle es als sensibel.
browser act kind=evaluate/openclaw browser evaluateundwait --fnführen beliebiges JavaScript im Seitenkontext aus. Prompt-Injection kann dies steuern. Deaktiviere es mitbrowser.evaluateEnabled=false, wenn du es nicht brauchst.- Für Logins und Anti-Bot-Hinweise (X/Twitter, etc.), siehe Browser-Login + X/Twitter-Posting.
- Halte das Gateway/den Node-Host privat (Loopback oder nur Tailnet).
- Remote-CDP-Endpoints sind mächtig; tunnel und schütze sie.
Troubleshooting
Für Linux-spezifische Probleme (besonders Snap-Chromium), siehe Browser-Troubleshooting.
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
Wie es zugeordnet wird:
browser snapshotgibt einen stabilen UI-Tree zurück (AI oder ARIA).browser actnutzt die Snapshot-ref-IDs zum click/type/drag/select.browser screenshoterfasst Pixel (ganze Seite oder Element).browserakzeptiert:profile, um ein benanntes Browser-Profil auszuwählen (openclaw, chrome oder Remote-CDP).target(sandbox|host|node), um auszuwählen, wo der Browser lebt.- In sandboxed Sessions erfordert
target: "host"agents.defaults.sandbox.browser.allowHostControl=true. - Wenn
targetweggelassen wird: sandboxed Sessions verwenden standardmäßigsandbox, Nicht-Sandbox-Sessions verwenden standardmäßighost. - Wenn ein browserfähiger Node verbunden ist, kann das Tool automatisch dorthin routen, es sei denn, du pinnst
target="host"odertarget="node".
Das hält den Agent deterministisch und vermeidet fragile Selektoren.