Tools

API voor browserbesturing

Voor installatie, configuratie en probleemoplossing, zie Browser. Deze pagina is de referentie voor de lokale HTTP-API voor bediening, de openclaw browser CLI en scriptpatronen (snapshots, refs, waits, debugflows).

Bedienings-API (optioneel)

Alleen voor lokale integraties stelt de Gateway een kleine HTTP-API via loopback 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
Machtigingen: POST /permissions/grant
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

Alle endpoints accepteren ?profile=<name>. POST /start?headless=true vraagt een eenmalige headless-start aan voor lokaal beheerde profielen zonder de persistente browserconfiguratie te wijzigen; attach-only-, externe CDP- en bestaande-sessieprofielen weigeren die overschrijving omdat OpenClaw die browserprocessen niet start.

Als Gateway-authenticatie met een gedeeld geheim is geconfigureerd, vereisen browser-HTTP-routes ook authenticatie:

Authorization: Bearer <gateway token>
x-openclaw-password: <gateway password> of HTTP Basic-authenticatie met dat wachtwoord

Opmerkingen:

Deze zelfstandige browser-API via loopback gebruikt geen trusted-proxy- of Tailscale Serve-identiteitsheaders.
Als gateway.auth.mode none of trusted-proxy is, erven deze browserroutes via loopback die identiteitsdragende modi niet; houd ze uitsluitend beschikbaar via loopback.

Foutcontract van `/act`

POST /act gebruikt een gestructureerde foutrespons voor validatie op routeniveau en beleidsfouten:

{ "error": "<message>", "code": "ACT_*" }

Huidige code-waarden:

ACT_KIND_REQUIRED (HTTP 400): kind ontbreekt of wordt niet herkend.
ACT_INVALID_REQUEST (HTTP 400): de actiepayload is niet door normalisatie of validatie gekomen.
ACT_SELECTOR_UNSUPPORTED (HTTP 400): selector is gebruikt met een niet-ondersteunde actiesoort.
ACT_EVALUATE_DISABLED (HTTP 403): evaluate (of wait --fn) is uitgeschakeld via configuratie.
ACT_TARGET_ID_MISMATCH (HTTP 403): targetId op topniveau of in een batch conflicteert met het doel van de aanvraag.
ACT_EXISTING_SESSION_UNSUPPORTED (HTTP 501): de actie wordt niet ondersteund voor bestaande-sessieprofielen.

Andere runtimefouten kunnen nog steeds { "error": "<message>" } retourneren zonder een code-veld.

Playwright-vereiste

Sommige functies (navigate/act/AI-snapshot/rolsnapshot, elementscreenshots, PDF) vereisen Playwright. Als Playwright niet is geinstalleerd, retourneren die endpoints een duidelijke 501-fout.

Wat nog werkt zonder Playwright:

ARIA-snapshots
Rolachtige toegankelijkheidssnapshots (--interactive, --compact, --depth, --efficient) wanneer een CDP-WebSocket per tabblad beschikbaar is. Dit is een fallback voor inspectie en ref-detectie; Playwright blijft de primaire actie-engine.
Paginascreenshots voor de beheerde openclaw-browser wanneer een CDP- WebSocket per tabblad beschikbaar is
Paginascreenshots voor existing-session- / Chrome MCP-profielen
Op refs gebaseerde screenshots van existing-session (--ref) vanuit snapshotuitvoer

Wat nog steeds Playwright nodig heeft:

navigate
act
AI-snapshots die afhankelijk zijn van Playwrights native AI-snapshotformaat
Elementscreenshots met CSS-selector (--element)
volledige browserexport naar PDF

Elementscreenshots weigeren ook --full-page; de route retourneert fullPage is not supported for element screenshots.

Als je Playwright is not available in this gateway build ziet, mist de verpakte Gateway de kernruntime-afhankelijkheid voor de browser. Installeer OpenClaw opnieuw of werk het bij en herstart daarna de Gateway. Installeer voor Docker ook de Chromium- browserbinaries zoals hieronder getoond.

Playwright installeren in Docker

Als je Gateway in Docker draait, vermijd dan npx playwright (conflicten met npm-overschrijvingen). Gebruik in plaats daarvan de meegeleverde CLI:

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

Stel PLAYWRIGHT_BROWSERS_PATH in om browserdownloads te bewaren (bijvoorbeeld /home/node/.cache/ms-playwright) en zorg dat /home/node persistent is via OPENCLAW_HOME_VOLUME of een bind mount. Zie Docker.

Hoe het werkt (intern)

Een kleine bedieningsserver via loopback accepteert HTTP-aanvragen en verbindt met Chromium-gebaseerde browsers via CDP. Geavanceerde acties (click/type/snapshot/PDF) lopen via Playwright bovenop CDP; wanneer Playwright ontbreekt, zijn alleen niet-Playwright-bewerkingen beschikbaar. De agent ziet een stabiele interface terwijl lokale/externe browsers en profielen eronder vrij worden gewisseld.

Snelle CLI-referentie

Alle commando's accepteren --browser-profile <name> om een specifiek profiel te targeten, en --json voor machineleesbare uitvoer.

Basis: status, tabbladen, openen/focussen/sluiten

openclaw browser status
openclaw browser start
openclaw browser start --headless # one-shot local managed headless launch
openclaw browser stop            # also clears emulation on attach-only/remote CDP
openclaw browser tabs
openclaw browser tab             # shortcut for current 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

Inspectie: screenshot, snapshot, console, fouten, aanvragen

openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref 12        # or --ref e12
openclaw browser screenshot --labels
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 --urls
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

Acties: navigeren, klikken, typen, slepen, wachten, evalueren

openclaw browser navigate https://example.com
openclaw browser resize 1280 720
openclaw browser click 12 --double           # or e12 for role refs
openclaw browser click-coords 120 340        # viewport coordinates
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: cookies, opslag, offline, headers, geo, apparaat

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            # --clear to remove
openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
openclaw browser set media dark
openclaw browser set timezone America/New_York
openclaw browser set locale en-US
openclaw browser set device "iPhone 14"

Opmerkingen:

upload en dialog zijn bewapeningsaanroepen; voer ze uit vóór de click/press die de kiezer/dialoog activeert.
click/type/enz. vereisen een ref uit snapshot (numeriek 12, rol-ref e12 of uitvoerbare ARIA-ref ax12). CSS-selectors worden bewust niet ondersteund voor acties. Gebruik click-coords wanneer de zichtbare viewportpositie het enige betrouwbare doel is.
Download-, trace- en uploadpaden zijn beperkt tot tijdelijke OpenClaw-roots: /tmp/openclaw{,/downloads,/uploads} (fallback: ${os.tmpdir()}/openclaw/...).
upload kan ook bestandsinvoer direct instellen via --input-ref of --element.

Stabiele tabblad-id's en labels blijven behouden bij vervanging van raw Chromium-targets wanneer OpenClaw het vervangende tabblad kan bewijzen, zoals dezelfde URL of een enkel oud tabblad dat een enkel nieuw tabblad wordt na formulierverzending. Raw target-id's blijven vluchtig; geef in scripts de voorkeur aan suggestedTargetId uit tabs.

Snapshotvlaggen in het kort:

--format ai (standaard met Playwright): AI-snapshot met numerieke refs (aria-ref="<n>").
--format aria: toegankelijkheidsboom met axN-refs. Wanneer Playwright beschikbaar is, bindt OpenClaw refs met backend-DOM-id's aan de live pagina zodat vervolgacties ze kunnen gebruiken; behandel de uitvoer anders als alleen voor inspectie.
--efficient (of --mode efficient): compacte rol-snapshotpreset. Stel browser.snapshotDefaults.mode: "efficient" in om dit de standaard te maken (zie Gateway-configuratie).
--interactive, --compact, --depth, --selector forceren een rolsnapshot met ref=e12-refs. --frame "<iframe>" beperkt rolsnapshots tot een iframe.
--labels voegt een viewport-only screenshot toe met overlappende ref-labels (print MEDIA:<path>).
--urls voegt gevonden linkbestemmingen toe aan AI-snapshots.

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.
Rolsnapshot (rol-refs 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(...) (plus nth() voor duplicaten).
- Voeg --labels toe om een viewportscreenshot met overlappende e12-labels op te nemen.
- Voeg --urls toe wanneer linktekst dubbelzinnig is en de agent concrete navigatiedoelen nodig heeft.
ARIA-snapshot (ARIA-refs zoals ax12): openclaw browser snapshot --format aria
- Uitvoer: de toegankelijkheidsboom als gestructureerde knooppunten.
- Acties: openclaw browser click ax12 werkt wanneer het snapshotpad de ref kan binden via Playwright en Chrome-backend-DOM-id's.
Als Playwright niet beschikbaar is, kunnen ARIA-snapshots nog steeds nuttig zijn voor inspectie, maar refs zijn mogelijk niet uitvoerbaar. Maak opnieuw een snapshot met --format ai of --interactive wanneer je actierefs nodig hebt.
Docker-bewijs voor het raw-CDP-fallbackpad: pnpm test:docker:browser-cdp-snapshot start Chromium met CDP, voert browser doctor --deep uit en verifieert dat rolsnapshots link-URL's, naar cursor gepromoveerde klikbare elementen en iframe-metadata bevatten.

Ref-gedrag:

Verwijzingen zijn niet stabiel tussen navigaties; als iets mislukt, voer snapshot opnieuw uit en gebruik een verse verwijzing.
/act retourneert de huidige ruwe targetId na door een actie getriggerde vervanging wanneer het de vervangende tab kan bewijzen. Blijf stabiele tab-id's/-labels gebruiken voor vervolgcommando's.
Als de rolsnapshot is gemaakt met --frame, zijn rolverwijzingen beperkt tot dat iframe tot de volgende rolsnapshot.
Onbekende of verouderde axN-verwijzingen falen snel in plaats van door te vallen naar Playwrights aria-ref-selector. Maak een verse snapshot op dezelfde tab wanneer dat gebeurt.

Wachtuitbreidingen

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"

Deze kunnen worden gecombineerd:

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

Debugworkflows

Wanneer een actie mislukt (bijv. "not visible", "strict mode violation", "covered"):

openclaw browser snapshot --interactive
Gebruik click <ref> / type <ref> (geef in interactieve modus de voorkeur aan rolverwijzingen)
Als het nog steeds mislukt: openclaw browser highlight <ref> om te zien waarop Playwright mikt
Als de pagina zich vreemd gedraagt:
- openclaw browser errors --clear
- openclaw browser requests --filter api --clear
Voor diepgaand debuggen: neem een trace op:
- openclaw browser trace start
- reproduceer het probleem
- openclaw browser trace stop (print TRACE:<path>)

JSON-uitvoer

--json is bedoeld voor scripting en gestructureerde tooling.

Voorbeelden:

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

Rolsnapshots in JSON bevatten refs plus een klein stats-blok (regels/tekens/verwijzingen/interactief), zodat tools kunnen redeneren over payloadgrootte en dichtheid.

Status- en omgevingsknoppen

Deze zijn nuttig 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 --headers-json '{"X-Debug":"1"}' (legacy set headers --json '{"X-Debug":"1"}' blijft ondersteund)
HTTP-basisverificatie: 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-apparaatpresets)
- set viewport 1280 720

Beveiliging en privacy

Het openclaw-browserprofiel kan ingelogde sessies bevatten; behandel het als gevoelig.
browser act kind=evaluate / openclaw browser evaluate en wait --fn voeren willekeurige JavaScript uit in de paginacontext. Promptinjectie kan dit sturen. Schakel het uit met browser.evaluateEnabled=false als je het niet nodig hebt.
Zie voor logins en anti-botnotities (X/Twitter, enz.) Browserlogin + posten op X/Twitter.
Houd de Gateway-/Node-host privé (local loopback of alleen tailnet).
Externe CDP-eindpunten zijn krachtig; tunnel en bescherm ze.

Strict-mode-voorbeeld (blokkeer standaard privé/interne bestemmingen):

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // optional exact allow
    },
  },
}

Gerelateerd

Browser - overzicht, configuratie, profielen, beveiliging
Browserlogin - inloggen op sites
Browser Linux-probleemoplossing
Browser WSL2-probleemoplossing

# Bedienings-API (optioneel)

# Foutcontract van /act

# Playwright-vereiste

# Playwright installeren in Docker

# Hoe het werkt (intern)

# Snelle CLI-referentie

# Snapshots en refs

# Wachtuitbreidingen

# Debugworkflows

# JSON-uitvoer

# Status- en omgevingsknoppen

# Beveiliging en privacy

# Gerelateerd