Browser (door openclaw beheerd)
OpenClaw kan een toegewijd Chrome/Brave/Edge/Chromium-profiel draaien dat door de agent wordt bestuurd. Het is geïsoleerd van je persoonlijke browser en wordt beheerd via een kleine lokale control service binnen de Gateway (alleen loopback). Beginnerweergave:- Zie het als een aparte, agent-only browser.
- Het
openclaw-profiel raakt je persoonlijke browserprofiel niet aan. - De agent kan tabbladen openen, pagina’s lezen, klikken en typen in een veilige omgeving.
- Het standaard
chrome-profiel gebruikt de systeemstandaard Chromium-browser via de extension relay; schakel naaropenclawvoor de geïsoleerde beheerde browser.
Wat je krijgt
- Een apart browserprofiel met de naam openclaw (standaard met oranje accent).
- Deterministische tabbladbesturing (lijst/openen/focussen/sluiten).
- Agentacties (klikken/typen/slepen/selecteren), snapshots, screenshots, PDF’s.
- Optionele ondersteuning voor meerdere profielen (
openclaw,work,remote, …).
Snelle start
Profielen: openclaw vs chrome
openclaw: beheerde, geïsoleerde browser (geen extensie vereist).chrome: extension relay naar je systeembrowser (vereist dat de OpenClaw- extensie aan een tabblad is gekoppeld).
browser.defaultProfile: "openclaw" in als je de beheerde modus standaard wilt gebruiken.
Configuratie
Browserinstellingen staan in~/.openclaw/openclaw.json.
- De browser control service bindt aan loopback op een poort afgeleid van
gateway.port(standaard:18791, wat gateway + 2 is). De relay gebruikt de volgende poort (18792). - Als je de Gateway-poort overschrijft (
gateway.portofOPENCLAW_GATEWAY_PORT), verschuiven de afgeleide browserpoorten om in dezelfde “familie” te blijven. cdpUrlgebruikt standaard de relaypoort wanneer niet ingesteld.remoteCdpTimeoutMsgeldt voor remote (niet-loopback) CDP-bereikbaarheidschecks.remoteCdpHandshakeTimeoutMsgeldt voor remote CDP WebSocket-bereikbaarheidschecks.attachOnly: truebetekent “start nooit een lokale browser; alleen koppelen als deze al draait.”color+ per-profielcolorkleuren de browser-UI zodat je ziet welk profiel actief is.- Het standaardprofiel is
chrome(extension relay). GebruikdefaultProfile: "openclaw"voor de beheerde browser. - Auto-detectievolgorde: systeembrowser als die op Chromium is gebaseerd; anders Chrome → Brave → Edge → Chromium → Chrome Canary.
- Lokale
openclaw-profielen wijzen automatischcdpPort/cdpUrltoe — stel die alleen in voor remote CDP.
Brave gebruiken (of een andere Chromium-browser)
Als je systeemstandaard browser op Chromium is gebaseerd (Chrome/Brave/Edge/etc), gebruikt OpenClaw die automatisch. Stelbrowser.executablePath in om
auto-detectie te overschrijven:
CLI-voorbeeld:
Lokale vs. remote besturing
- Lokale besturing (standaard): de Gateway start de loopback control service en kan een lokale browser starten.
- Remote besturing (node-host): draai een node-host op de machine met de browser; de Gateway proxyt browseracties daarheen.
- Remote CDP: stel
browser.profiles.<name>.cdpUrl(ofbrowser.cdpUrl) in om aan een remote Chromium-browser te koppelen. In dit geval start OpenClaw geen lokale browser.
- Querytokens (bijv.
https://provider.example?token=<token>) - HTTP Basic auth (bijv.
https://user:[email protected])
/json/*-endpoints en bij het verbinden
met de CDP WebSocket. Gebruik bij voorkeur omgevingsvariabelen of secrets managers voor
tokens in plaats van ze in configbestanden vast te leggen.
Node browser proxy (zero-config standaard)
Als je een node-host draait op de machine met je browser, kan OpenClaw browser-toolcalls automatisch naar die node routeren zonder extra browserconfig. Dit is het standaardpad voor remote gateways. Notities:- De node-host stelt zijn lokale browser control server beschikbaar via een proxy-opdracht.
- Profielen komen uit de eigen
browser.profiles-config van de node (hetzelfde als lokaal). - Uitschakelen als je dit niet wilt:
- Op de node:
nodeHost.browserProxy.enabled=false - Op de gateway:
gateway.nodes.browser.mode="off"
- Op de node:
Browserless (gehoste remote CDP)
Browserless is een gehoste Chromium-service die CDP-endpoints via HTTPS aanbiedt. Je kunt een OpenClaw-browserprofiel naar een Browserless-regio-endpoint laten wijzen en authenticeren met je API-sleutel. Voorbeeld:- Vervang
<BROWSERLESS_API_KEY>door je echte Browserless-token. - Kies het regio-endpoint dat past bij je Browserless-account (zie hun documentatie).
Beveiliging
Sleutel ideeën:- Browserbesturing is alleen loopback; toegang loopt via de Gateway-authenticatie of node-koppeling.
- Als browserbesturing is ingeschakeld en er geen authenticatie is geconfigureerd, genereert OpenClaw automatisch
gateway.auth.tokenbij het opstarten en slaat dit op in de configuratie. - Houd de Gateway en eventuele node-hosts op een privénetwerk (Tailscale); vermijd publieke blootstelling.
- Behandel remote CDP-URL’s/tokens als geheimen; gebruik bij voorkeur env vars of een secrets manager.
- Geef waar mogelijk de voorkeur aan HTTPS-endpoints en kortlevende tokens.
- Vermijd het direct insluiten van langlevende tokens in configbestanden.
Profielen (meerdere browsers)
OpenClaw ondersteunt meerdere benoemde profielen (routeringsconfiguraties). Profielen kunnen zijn:- openclaw-managed: een toegewijde Chromium-browserinstantie met eigen user data directory + CDP-poort
- remote: een expliciete CDP-URL (Chromium-browser die elders draait)
- extension relay: je bestaande Chrome-tabbladen via de lokale relay + Chrome-extensie
- Het
openclaw-profiel wordt automatisch aangemaakt als het ontbreekt. - Het
chrome-profiel is ingebouwd voor de Chrome extension relay (wijst standaard naarhttp://127.0.0.1:18792). - Lokale CDP-poorten worden standaard toegewezen uit 18800–18899.
- Het verwijderen van een profiel verplaatst de lokale datadirectory naar de prullenmand.
?profile=<name>; de CLI gebruikt --browser-profile.
Chrome extension relay (gebruik je bestaande Chrome)
OpenClaw kan ook je bestaande Chrome-tabbladen aansturen (geen aparte “openclaw” Chrome-instantie) via een lokale CDP relay + een Chrome-extensie. Volledige gids: Chrome extension Stroom:- De Gateway draait lokaal (dezelfde machine) of een node-host draait op de browsermachine.
- Een lokale relayserver luistert op een loopback
cdpUrl(standaard:http://127.0.0.1:18792). - Je klikt op het extensiepictogram OpenClaw Browser Relay op een tabblad om te koppelen (het koppelt niet automatisch).
- De agent bestuurt dat tabblad via de normale
browser-tool, door het juiste profiel te selecteren.
Gesandboxte sessies
Als de agentsessie gesandboxed is, kan debrowser-tool standaard naar target="sandbox" (sandboxbrowser) gaan.
Overname via de Chrome extension relay vereist hostbrowserbesturing, dus:
- draai de sessie ongesandboxed, of
- stel
agents.defaults.sandbox.browser.allowHostControl: truein en gebruiktarget="host"bij het aanroepen van de tool.
Installatie
- Laad de extensie (dev/unpacked):
- Chrome →
chrome://extensions→ schakel “Developer mode” in - “Load unpacked” → selecteer de directory die door
openclaw browser extension pathwordt weergegeven - Pin de extensie en klik erop op het tabblad dat je wilt besturen (badge toont
ON).
- Gebruik het:
- CLI:
openclaw browser --browser-profile chrome tabs - Agenttool:
browsermetprofile="chrome"
- Deze modus vertrouwt voor de meeste bewerkingen op Playwright-on-CDP (screenshots/snapshots/acties).
- Ontkoppelen doe je door opnieuw op het extensiepictogram te klikken.
Isolatiegaranties
- Toegewijde user data dir: raakt je persoonlijke browserprofiel nooit aan.
- Toegewijde poorten: vermijdt
9222om botsingen met dev-workflows te voorkomen. - Deterministische tabbladbesturing: richt tabbladen op
targetId, niet op “laatste tabblad”.
Browserselectie
Bij lokaal starten kiest OpenClaw de eerste beschikbare:- Chrome
- Brave
- Edge
- Chromium
- Chrome Canary
browser.executablePath.
Platformen:
- macOS: controleert
/Applicationsen~/Applications. - Linux: zoekt naar
google-chrome,brave,microsoft-edge,chromium, enz. - Windows: controleert veelvoorkomende installatielocaties.
Control API (optioneel)
Alleen voor lokale integraties stelt de Gateway een kleine loopback HTTP-API beschikbaar:- Status/start/stop:
GET /,POST /start,POST /stop - Tabbladen:
GET /tabs,POST /tabs/open,POST /tabs/focus,DELETE /tabs/:targetId - Snapshot/screenshot:
GET /snapshot,POST /screenshot - Acties:
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 - Netwerk:
POST /response/body - Status:
GET /cookies,POST /cookies/set,POST /cookies/clear - Status:
GET /storage/:kind,POST /storage/:kind/set,POST /storage/:kind/clear - Instellingen:
POST /set/offline,POST /set/headers,POST /set/credentials,POST /set/geolocation,POST /set/media,POST /set/timezone,POST /set/locale,POST /set/device
?profile=<name>.
Als gateway-authenticatie is geconfigureerd, vereisen browser-HTTP-routes ook authenticatie:
Authorization: Bearer <gateway token>x-openclaw-password: <gateway password>of HTTP Basic-authenticatie met dat wachtwoord
Playwright-vereiste
Sommige functies (navigeren/acteren/AI-snapshot/rolesnapshot, elementscreenshots, PDF) vereisen Playwright. Als Playwright niet is geïnstalleerd, geven die endpoints een duidelijke 501-fout. ARIA-snapshots en basis-screenshots werken nog steeds voor door openclaw beheerde Chrome. Voor de Chrome extension relay-driver vereisen ARIA-snapshots en screenshots Playwright. Als jePlaywright is not available in this gateway build ziet, installeer het volledige
Playwright-pakket (niet playwright-core) en herstart de gateway, of installeer
OpenClaw opnieuw met browserondersteuning.
Docker Playwright-installatie
Als je Gateway in Docker draait, vermijdnpx playwright (npm override-conflicten).
Gebruik in plaats daarvan de gebundelde CLI:
PLAYWRIGHT_BROWSERS_PATH in (bijvoorbeeld
/home/node/.cache/ms-playwright) en zorg dat /home/node wordt behouden via
OPENCLAW_HOME_VOLUME of een bind mount. Zie Docker.
Hoe het werkt (intern)
Stroom op hoog niveau:- Een kleine control server accepteert HTTP-verzoeken.
- Deze verbindt met Chromium-browsers (Chrome/Brave/Edge/Chromium) via CDP.
- Voor geavanceerde acties (klikken/typen/snapshot/PDF) gebruikt hij Playwright bovenop CDP.
- Wanneer Playwright ontbreekt, zijn alleen niet-Playwright-bewerkingen beschikbaar.
CLI snelle referentie
Alle opdrachten accepteren--browser-profile <name> om een specifiek profiel te targeten.
Alle opdrachten accepteren ook --json voor machineleesbare uitvoer (stabiele payloads).
Basis:
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
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
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
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"
uploadendialogzijn arming-aanroepen; voer ze uit vóór de klik/toets die de chooser/dialog triggert.- Download- en trace-uitvoerpaden zijn beperkt tot OpenClaw temp-roots:
- Stroom:
- downloads:
/tmp/openclaw/downloads(fallback:${os.tmpdir()}/openclaw/downloads)
- Uploadpaden zijn beperkt tot een OpenClaw temp-uploads-root:
- uploads:
/tmp/openclaw/uploads(fallback:${os.tmpdir()}/openclaw/uploads)
- uploads:
uploadkan bestandsinputs ook direct instellen via--input-refof--element.snapshot:--format ai(standaard wanneer Playwright is geïnstalleerd): retourneert een AI-snapshot met numerieke refs (aria-ref="<n>").--format aria: retourneert de accessibility tree (geen refs; alleen inspectie).--efficient(of--mode efficient): compact rolesnapshot-voorinstelling (interactief + compact + diepte + lagere maxChars).- Config-standaard (alleen tool/CLI): stel
browser.snapshotDefaults.mode: "efficient"in om efficiënte snapshots te gebruiken wanneer de aanroeper geen modus meegeeft (zie Gateway-configuratie). - Rolesnapshot-opties (
--interactive,--compact,--depth,--selector) forceren een role-based snapshot met refs zoalsref=e12. --frame "<iframe selector>"beperkt rolesnapshots tot een iframe (combineert met rolrefs zoalse12).--interactivegeeft een platte, gemakkelijk te kiezen lijst van interactieve elementen (het beste voor het aansturen van acties).--labelsvoegt een screenshot toe dat alleen de viewport toont met overlappende reflabels (printMEDIA:<path>).
click/type/etc vereisen eenrefuitsnapshot(ofwel numeriek12of rolrefe12). CSS-selectors worden opzettelijk niet ondersteund voor acties.
Snapshots en refs
OpenClaw ondersteunt twee “snapshot”-stijlen:-
AI-snapshot (numerieke refs):
openclaw browser snapshot(standaard;--format ai)- Uitvoer: een tekstsnapshot met numerieke refs.
- Acties:
openclaw browser click 12,openclaw browser type 23 "hello". - Intern wordt de ref opgelost via Playwrights
aria-ref.
-
Rolesnapshot (rolrefs zoals
e12):openclaw browser snapshot --interactive(of--compact,--depth,--selector,--frame)- Uitvoer: een rolgebaseerde lijst/boom met
[ref=e12](en optioneel[nth=1]). - Acties:
openclaw browser click e12,openclaw browser highlight e12. - Intern wordt de ref opgelost via
getByRole(...)(plusnth()voor duplicaten). - Voeg
--labelstoe om een viewport-screenshot met overlappendee12-labels op te nemen.
- Uitvoer: een rolgebaseerde lijst/boom met
- Refs zijn niet stabiel over navigaties heen; als iets faalt, voer
snapshotopnieuw uit en gebruik een verse ref. - Als de rolesnapshot is genomen met
--frame, zijn rolrefs beperkt tot dat iframe tot de volgende rolesnapshot.
Wacht-power-ups
Je kunt op meer wachten dan alleen tijd/tekst:- Wachten op URL (globs ondersteund door Playwright):
openclaw browser wait --url "**/dash"
- Wachten op laadstatus:
openclaw browser wait --load networkidle
- Wachten op een JS-predicaat:
openclaw browser wait --fn "window.ready===true"
- Wachten tot een selector zichtbaar wordt:
openclaw browser wait "#main"
Debug-workflows
Wanneer een actie faalt (bijv. “not visible”, “strict mode violation”, “covered”):openclaw browser snapshot --interactive- Gebruik
click <ref>/type <ref>(gebruik bij voorkeur rolrefs in interactieve modus) - Als het nog steeds faalt:
openclaw browser highlight <ref>om te zien waarop Playwright richt - Als de pagina zich vreemd gedraagt:
openclaw browser errors --clearopenclaw browser requests --filter api --clear
- Voor diepgaande debugging: neem een trace op:
openclaw browser trace start- reproduceer het probleem
openclaw browser trace stop(printTRACE:<path>)
JSON-uitvoer
--json is bedoeld voor scripting en gestructureerde tooling.
Voorbeelden:
refs plus een klein stats-blok (regels/tekens/refs/interactief) zodat tools kunnen redeneren over payloadgrootte en -dichtheid.
Status- en omgevingsknoppen
Deze zijn handig voor workflows zoals “laat de site zich gedragen als X”:- Cookies:
cookies,cookies set,cookies clear - Opslag:
storage local|session get|set|clear - Offline:
set offline on|off - Headers:
set headers --json '{"X-Debug":"1"}'(of--clear) - HTTP basic auth:
set credentials user pass(of--clear) - Geolocatie:
set geo <lat> <lon> --origin "https://example.com"(of--clear) - Media:
set media dark|light|no-preference|none - Tijdzone / locale:
set timezone ...,set locale ... - Apparaat / viewport:
set device "iPhone 14"(Playwright-apparaatvoorinstellingen)set viewport 1280 720
Beveiliging & privacy
- Het openclaw-browserprofiel kan ingelogde sessies bevatten; behandel dit als gevoelig.
browser act kind=evaluate/openclaw browser evaluateenwait --fnvoeren willekeurige JavaScript uit in de paginacontext. Prompt injection kan dit sturen. Schakel dit uit metbrowser.evaluateEnabled=falseals je het niet nodig hebt.- Voor logins en anti-botnotities (X/Twitter, enz.), zie Browser login + X/Twitter posting.
- Houd de Gateway/node-host privé (loopback of alleen tailnet).
- Remote CDP-endpoints zijn krachtig; tunnel en bescherm ze.
Problemen oplossen
Voor Linux-specifieke problemen (vooral snap Chromium), zie Browser troubleshooting.Agenttools + hoe besturing werkt
De agent krijgt één tool voor browserautomatisering:browser— status/start/stop/tabbladen/openen/focussen/sluiten/snapshot/screenshot/navigeren/acteren
browser snapshotretourneert een stabiele UI-boom (AI of ARIA).browser actgebruikt de snapshot-ref-ID’s om te klikken/typen/slepen/selecteren.browser screenshotlegt pixels vast (volledige pagina of element).browseraccepteert:profileom een benoemd browserprofiel te kiezen (openclaw, chrome of remote CDP).target(sandbox|host|node) om te selecteren waar de browser draait.- In gesandboxte sessies vereist
target: "host"agents.defaults.sandbox.browser.allowHostControl=true. - Als
targetwordt weggelaten: gesandboxte sessies gebruiken standaardsandbox, niet-gesandboxte sessies standaardhost. - Als een browser-capabele node is verbonden, kan de tool automatisch daarnaar routeren tenzij je
target="host"oftarget="node"vastzet.