​

Browser (openclaw-verwaltet)

• Betrachten Sie es als einen separaten, agentenexklusiven Browser.
• Das Profil openclaw greift nicht auf Ihr persönliches Browserprofil zu.
• Der Agent kann Tabs öffnen, Seiten lesen, klicken und tippen – in einer sicheren Spur.
• Das Standardprofil chrome verwendet den systemweiten Standard-Chromium-Browser über das Extension-Relay; wechseln Sie zu openclaw für den isolierten, verwalteten Browser.

​

Was Sie erhalten

• Ein separates Browserprofil namens openclaw (standardmäßig mit orangefarbenem Akzent).
• Deterministische Tab-Steuerung (auflisten/öffnen/fokussieren/schließen).
• Agentenaktionen (klicken/tippen/ziehen/auswählen), Snapshots, Screenshots, PDFs.
• Optionale Unterstützung mehrerer Profile (openclaw, work, remote, …).

​

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

​

Profile: openclaw vs chrome

• openclaw: verwalteter, isolierter Browser (keine Erweiterung erforderlich).
• chrome: Extension-Relay zu Ihrem Systembrowser (erfordert, dass die OpenClaw- Erweiterung an einen Tab angeheftet ist).

​

Konfiguration

{
  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" },
    },
  },
}

• Der Browsersteuerungsdienst bindet an Loopback auf einem Port, der von gateway.port abgeleitet ist (Standard: 18791, also Gateway + 2). Das Relay verwendet den nächsten Port (18792).
• Wenn Sie den Gateway-Port überschreiben (gateway.port oder OPENCLAW_GATEWAY_PORT), verschieben sich die abgeleiteten Browser-Ports, um in derselben „Familie“ zu bleiben.
• cdpUrl verwendet standardmäßig den Relay-Port, wenn er nicht gesetzt ist.
• remoteCdpTimeoutMs gilt für Remote-CDP-Erreichbarkeitsprüfungen (nicht Loopback).
• remoteCdpHandshakeTimeoutMs gilt für Remote-CDP-WebSocket-Erreichbarkeitsprüfungen.
• attachOnly: true bedeutet „nie einen lokalen Browser starten; nur anhängen, wenn er bereits läuft“.
• color + profilbezogenes color färben die Browser-UI, damit Sie sehen, welches Profil aktiv ist.
• Standardprofil ist chrome (Extension-Relay). Verwenden Sie defaultProfile: "openclaw" für den verwalteten Browser.
• Auto-Erkennungsreihenfolge: systemweiter Standardbrowser, falls Chromium-basiert; andernfalls Chrome → Brave → Edge → Chromium → Chrome Canary.
• Lokale openclaw-Profile weisen cdpPort/cdpUrl automatisch zu — setzen Sie diese nur für Remote-CDP.

​

Brave (oder einen anderen Chromium-basierten Browser) verwenden

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ühren Sie einen Node-Host auf der Maschine aus, auf der sich der Browser befindet; das Gateway leitet Browseraktionen dorthin weiter.
• Remote CDP: Setzen Sie 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.

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

​

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

• Der Node-Host stellt seinen lokalen Browsersteuerungsserver über einen Proxy-Befehl bereit.
• Profile stammen aus der eigenen browser.profiles-Konfiguration des Nodes (wie lokal).
• Deaktivieren, wenn Sie dies nicht möchten:
  • Auf dem Node: nodeHost.browserProxy.enabled=false
  • Auf dem Gateway: gateway.nodes.browser.mode="off"

​

Browserless (gehostetes Remote-CDP)

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

• Ersetzen Sie <BROWSERLESS_API_KEY> durch Ihr echtes Browserless-Token.
• Wählen Sie den Regionsendpunkt, der zu Ihrem Browserless-Konto passt (siehe deren Dokumentation).

​

Sicherheit

• Die Browsersteuerung ist ausschließlich Loopback; der Zugriff erfolgt über die Authentifizierung des Gateway oder die Node-Paarung.
• Wenn die Browsersteuerung aktiviert ist und keine Authentifizierung konfiguriert wurde, generiert OpenClaw beim Start automatisch gateway.auth.token und speichert es in der Konfiguration.
• Halten Sie das Gateway und alle Node-Hosts in einem privaten Netzwerk (Tailscale); vermeiden Sie öffentliche Exposition.
• Behandeln Sie Remote-CDP-URLs/Token als Geheimnisse; bevorzugen Sie Umgebungsvariablen oder einen Secrets-Manager.

• Bevorzugen Sie HTTPS-Endpunkte und kurzlebige Token, wo möglich.
• Vermeiden Sie das direkte Einbetten langlebiger Token in Konfigurationsdateien.

​

Profile (Multi-Browser)

• openclaw-managed: eine dedizierte Chromium-basierte Browserinstanz mit eigenem User-Data-Verzeichnis + CDP-Port
• remote: eine explizite CDP-URL (Chromium-basierter Browser läuft anderswo)
• extension relay: Ihre bestehenden Chrome-Tabs über das lokale Relay + Chrome-Erweiterung

• Das Profil openclaw wird automatisch erstellt, falls es fehlt.
• Das Profil chrome ist integriert für das Chrome-Extension-Relay (zeigt standardmäßig auf http://127.0.0.1:18792).
• Lokale CDP-Ports werden standardmäßig aus 18800–18899 vergeben.
• Das Löschen eines Profils verschiebt dessen lokales Datenverzeichnis in den Papierkorb.

​

Chrome-Extension-Relay (Ihren bestehenden Chrome verwenden)

• Das Gateway läuft lokal (gleiche Maschine) oder ein Node-Host läuft auf der Browser-Maschine.
• Ein lokaler Relay-Server lauscht auf einem Loopback-cdpUrl (Standard: http://127.0.0.1:18792).
• Sie klicken auf das OpenClaw Browser Relay-Erweiterungssymbol in einem Tab, um anzuhängen (keine automatische Anheftung).
• Der Agent steuert diesen Tab über das normale browser-Werkzeug, indem das richtige Profil ausgewählt wird.

​

Sandboxed-Sitzungen

• die Sitzung unsandboxed ausführen oder
• agents.defaults.sandbox.browser.allowHostControl: true setzen und target="host" beim Aufruf des Werkzeugs verwenden.

​

Einrichtung

1. Erweiterung laden (Dev/Unpacked):

openclaw browser extension install

• Chrome → chrome://extensions → „Developer mode“ aktivieren
• „Load unpacked“ → das von openclaw browser extension path ausgegebene Verzeichnis auswählen
• Erweiterung anheften und dann im gewünschten Tab anklicken (Badge zeigt ON).

2. Verwenden:

• CLI: openclaw browser --browser-profile chrome tabs
• Agentenwerkzeug: browser mit profile="chrome"

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

• Dieser Modus stützt sich für die meisten Operationen (Screenshots/Snapshots/Aktionen) auf Playwright-on-CDP.
• Trennen durch erneutes Klicken auf das Erweiterungssymbol.

​

Isolationsgarantien

• Dediziertes User-Data-Verzeichnis: greift niemals auf Ihr persönliches Browserprofil zu.
• Dedizierte Ports: vermeidet 9222, um Kollisionen mit Entwicklungs-Workflows zu verhindern.
• Deterministische Tab-Steuerung: Zielauswahl nach targetId, nicht nach „letztem Tab“.

​

Browserauswahl

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

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

​

Control API (optional)

• Status/Start/Stopp: 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
• Zustand: GET /cookies, POST /cookies/set, POST /cookies/clear
• Zustand: 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

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

​

Playwright-Anforderung

​

Docker-Playwright-Installation

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

​

Funktionsweise (intern)

• Ein kleiner Steuerungsserver akzeptiert HTTP-Anfragen.
• Er verbindet sich mit Chromium-basierten Browsern (Chrome/Brave/Edge/Chromium) über CDP.
• Für erweiterte Aktionen (klicken/tippen/snapshot/PDF) nutzt er Playwright auf CDP.
• Fehlt Playwright, stehen nur Nicht-Playwright-Operationen zur Verfügung.

​

CLI-Schnellreferenz

• 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

• 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

• 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

• 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"

• upload und dialog sind Arming-Aufrufe; führen Sie sie vor dem Klick/Tastendruck aus, der den Auswahldialog auslöst.
• Download- und Trace-Ausgabepfade sind auf OpenClaw-Temp-Root-Verzeichnisse 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-Verzeichnis beschränkt:
  • uploads: /tmp/openclaw/uploads (Fallback: ${os.tmpdir()}/openclaw/uploads)
• upload kann Dateieingaben auch direkt über --input-ref oder --element setzen.
• snapshot:
  • --format ai (Standard, wenn Playwright installiert ist): gibt einen AI-Snapshot mit numerischen Referenzen (aria-ref="<n>") zurück.
  • --format aria: gibt den Accessibility-Baum zurück (keine Referenzen; nur Inspektion).
  • --efficient (oder --mode efficient): kompaktes Rollen-Snapshot-Preset (interaktiv + kompakt + Tiefe + niedrigere maxChars).
  • Konfigurationsstandard (nur Werkzeug/CLI): Setzen Sie browser.snapshotDefaults.mode: "efficient", um effiziente Snapshots zu verwenden, wenn der Aufrufer keinen Modus übergibt (siehe Gateway-Konfiguration).
  • Optionen für Rollen-Snapshots (--interactive, --compact, --depth, --selector) erzwingen ein rollenbasiertes Snapshot mit Referenzen wie ref=e12.
  • --frame "<iframe selector>" begrenzt Rollen-Snapshots auf ein iframe (in Kombination mit Rollen-Referenzen wie e12).
  • --interactive gibt eine flache, leicht auswählbare Liste interaktiver Elemente aus (am besten zum Steuern von Aktionen).
  • --labels fügt einen Screenshot nur des Viewports mit überlagerten Referenzlabels hinzu (gibt MEDIA:<path> aus).
• click/type/etc. erfordern eine ref aus snapshot (entweder numerische 12 oder Rollen-Referenz e12). CSS-Selektoren werden für Aktionen bewusst nicht unterstützt.

​

Snapshots und Referenzen

• AI-Snapshot (numerische Referenzen): openclaw browser snapshot (Standard; --format ai)
  • Ausgabe: ein Text-Snapshot mit numerischen Referenzen.
  • Aktionen: openclaw browser click 12, openclaw browser type 23 "hello".
  • Intern wird die Referenz über Playwrights aria-ref aufgelöst.
• Rollen-Snapshot (Rollen-Referenzen wie e12): openclaw browser snapshot --interactive (oder --compact, --depth, --selector, --frame)
  • Ausgabe: eine rollenbasierte Liste/Baum mit [ref=e12] (und optional [nth=1]).
  • Aktionen: openclaw browser click e12, openclaw browser highlight e12.
  • Intern wird die Referenz über getByRole(...) aufgelöst (zzgl. nth() bei Duplikaten).
  • Fügen Sie --labels hinzu, um einen Viewport-Screenshot mit überlagerten e12-Labels einzuschließen.

• Referenzen sind nicht stabil über Navigationswechsel hinweg; wenn etwas fehlschlägt, führen Sie snapshot erneut aus und verwenden Sie eine frische Referenz.
• Wenn der Rollen-Snapshot mit --frame erstellt wurde, sind Rollen-Referenzen bis zum nächsten Rollen-Snapshot auf dieses iframe beschränkt.

​

Wait-Power-ups

• Auf URL warten (Globs werden 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 einen Selektor warten, bis er sichtbar wird:
  • openclaw browser wait "#main"

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

​

Debug-Workflows

1. openclaw browser snapshot --interactive
2. Verwenden Sie click <ref> / type <ref> (bevorzugen Sie Rollen-Referenzen im interaktiven Modus)
3. Falls es weiterhin fehlschlägt: openclaw browser highlight <ref>, um zu sehen, worauf Playwright zielt
4. Wenn sich die Seite merkwürdig verhält:
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. Für tiefgehendes Debugging: einen Trace aufzeichnen:
   • openclaw browser trace start
   • das Problem reproduzieren
   • openclaw browser trace stop (gibt TRACE:<path> aus)

​

JSON-Ausgabe

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

​

Zustands- und Umgebungsregler

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

​

Sicherheit & Datenschutz

• Das openclaw-Browserprofil kann eingeloggte Sitzungen enthalten; behandeln Sie 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. Deaktivieren Sie es mit browser.evaluateEnabled=false, wenn Sie es nicht benötigen.
• Hinweise zu Logins und Anti-Bot-Themen (X/Twitter usw.) finden Sie unter Browser login + X/Twitter posting.
• Halten Sie Gateway/Node-Host privat (Loopback oder nur Tailnet).
• Remote-CDP-Endpunkte sind mächtig; tunneln und schützen Sie sie.

​

Fehlerbehebung

​

Agentenwerkzeuge + Funktionsweise der Steuerung

• browser — Status/Start/Stopp/Tabs/Öffnen/Fokussieren/Schließen/Snapshot/Screenshot/Navigation/Aktion

• browser snapshot gibt eine stabile UI-Struktur zurück (AI oder ARIA).
• browser act verwendet die Snapshot-ref-IDs zum Klicken/Tippen/Ziehen/Auswählen.
• browser screenshot erfasst Pixel (ganze Seite oder Element).
• browser akzeptiert:
  • profile, um ein benanntes Browserprofil auszuwählen (openclaw, chrome oder Remote-CDP).
  • target (sandbox | host | node), um auszuwählen, wo der Browser läuft.
  • In sandboxed Sitzungen erfordert target: "host" agents.defaults.sandbox.browser.allowHostControl=true.
  • Wenn target weggelassen wird: sandboxed Sitzungen verwenden standardmäßig sandbox, nicht-sandboxed Sitzungen standardmäßig host.
  • Wenn ein browserfähiger Node verbunden ist, kann das Werkzeug automatisch dorthin routen, sofern Sie target="host" oder target="node" nicht anheften.