> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Browserbesturings-API

Zie [Browser](/nl/tools/browser) voor installatie, configuratie en probleemoplossing.
Deze pagina is de referentie voor de lokale HTTP-API voor besturing, de `openclaw browser`
CLI en scriptpatronen (snapshots, refs, waits, debugflows).

## Besturings-API (optioneel)

Alleen voor lokale integraties stelt de Gateway een kleine loopback-HTTP-API beschikbaar.
Deze zelfstandige server is opt-in: stel de omgevingsvariabele
`OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1` in de gateway-serviceomgeving in
en herstart de Gateway voordat de HTTP-eindpunten beschikbaar worden. Zonder
deze variabele werkt de browserbesturingsruntime nog steeds via de CLI en
agenttools, maar luistert er niets op de loopback-besturingspoort.

* Status/start/stop: `GET /`, `POST /start`, `POST /stop`
* Tabbladen: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
* Snapshot/schermafbeelding: `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`
* Debuggen: `GET /console`, `POST /pdf`
* Debuggen: `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 eindpunten accepteren `?profile=<name>`. `POST /start?headless=true` vraagt een
eenmalige headless-start aan voor lokale beheerde profielen zonder opgeslagen
browserconfiguratie te wijzigen; attach-only-, externe CDP- en bestaande-sessieprofielen weigeren
die override omdat OpenClaw die browserprocessen niet start.

Voor tabbladeindpunten is `targetId` de compatibiliteitsveldnaam. Geef bij voorkeur
`suggestedTargetId` door uit `GET /tabs` of `POST /tabs/open`; labels en `tabId`-
handles zoals `t1` worden ook geaccepteerd. Ruwe CDP-doel-ID's en unieke ruwe
doel-ID-prefixen werken nog steeds, maar het zijn vluchtige diagnostische handles.

Als Gateway-authenticatie met 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 loopback-browser-API gebruikt **geen** trusted-proxy- of
  Tailscale Serve-identiteitsheaders.
* Als `gateway.auth.mode` `none` of `trusted-proxy` is, erven deze loopback-browserroutes
  die identiteitsdragende modi niet; houd ze uitsluitend loopback.

### `/act`-foutcontract

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{ "error": "<message>", "code": "ACT_*" }
```

Huidige `code`-waarden:

* `ACT_KIND_REQUIRED` (HTTP 400): `kind` ontbreekt of wordt niet herkend.
* `ACT_INVALID_REQUEST` (HTTP 400): normalisatie of validatie van de actielading is mislukt.
* `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` is gebruikt met een niet-ondersteund actietype.
* `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (of `wait --fn`) is uitgeschakeld door configuratie.
* `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` op topniveau of in batches conflicteert met het aanvraagdoel.
* `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): actie wordt niet ondersteund voor bestaande-sessieprofielen.

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

### Playwright-vereiste

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

Wat nog werkt zonder Playwright:

* ARIA-snapshots
* Toegankelijkheidssnapshots in rolstijl (`--interactive`, `--compact`,
  `--depth`, `--efficient`) wanneer een per-tabblad CDP-WebSocket beschikbaar is. Dit is
  een fallback voor inspectie en ref-ontdekking; Playwright blijft de primaire
  actie-engine.
* Paginaschermafbeeldingen voor de beheerde `openclaw`-browser wanneer een per-tabblad CDP-
  WebSocket beschikbaar is
* Paginaschermafbeeldingen voor `existing-session`- / Chrome MCP-profielen
* Op refs gebaseerde `existing-session`-schermafbeeldingen (`--ref`) uit snapshotuitvoer

Wat nog steeds Playwright nodig heeft:

* `navigate`
* `act`
* AI-snapshots die afhankelijk zijn van Playwrights native AI-snapshotindeling
* Element-schermafbeeldingen met CSS-selector (`--element`)
* volledige browser-PDF-export

Element-schermafbeeldingen 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 browsers. Installeer OpenClaw opnieuw of werk
OpenClaw bij en herstart daarna de Gateway. Installeer voor Docker ook de Chromium-
browserbinaries zoals hieronder weergegeven.

#### Docker Playwright-installatie

Als je Gateway in Docker draait, vermijd dan `npx playwright` (npm-overrideconflicten).
Voor aangepaste images bak je Chromium in de image:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh
```

Voor een bestaande image installeer je in plaats daarvan via de meegeleverde CLI:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium
```

Om browserdownloads te behouden, stel je `PLAYWRIGHT_BROWSERS_PATH` in (bijvoorbeeld
`/home/node/.cache/ms-playwright`) en zorg je dat `/home/node` behouden blijft via
`OPENCLAW_HOME_VOLUME` of een bind mount. OpenClaw detecteert de behouden
Chromium automatisch op Linux. Zie [Docker](/nl/install/docker).

## Hoe het werkt (intern)

Een kleine loopback-besturingsserver accepteert HTTP-aanvragen en maakt via CDP verbinding met Chromium-gebaseerde browsers. Geavanceerde acties (click/type/snapshot/PDF) lopen via Playwright boven op 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 verwisseld.

## CLI-snelreferentie

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

<AccordionGroup>
  <Accordion title="Basics: status, tabs, open/focus/close">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    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
    ```
  </Accordion>

  <Accordion title="Inspection: screenshot, snapshot, console, errors, requests">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    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
    ```
  </Accordion>

  <Accordion title="Actions: navigate, click, type, drag, wait, evaluate">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    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 upload media://inbound/file.pdf
    openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
    openclaw browser dialog --accept
    openclaw browser dialog --dismiss --dialog-id d1
    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 evaluate --fn 'const title = document.title; return title;'
    openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'
    openclaw browser highlight e12
    openclaw browser trace start
    openclaw browser trace stop
    ```
  </Accordion>

  <Accordion title="State: cookies, storage, offline, headers, geo, device">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    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"
    ```
  </Accordion>
</AccordionGroup>

Opmerkingen:

* `upload` en `dialog` zijn **bewapenings**-aanroepen; voer ze uit voor de click/press die de kiezer/dialoog activeert. Als een actie een modaal venster opent, bevat de actierespons `blockedByDialog` en `browserState.dialogs.pending`; geef die `dialogId` door om direct te reageren. Dialogen die buiten OpenClaw worden afgehandeld, verschijnen onder `browserState.dialogs.recent`.
* `click`/`type`/enzovoort vereisen een `ref` uit `snapshot` (numeriek `12`, rolref `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- en tracepaden zijn beperkt tot tijdelijke OpenClaw-roots: `/tmp/openclaw{,/downloads}` (fallback: `${os.tmpdir()}/openclaw/...`).
* `upload` accepteert bestanden uit de tijdelijke uploads-root van OpenClaw en
  door OpenClaw beheerde inkomende media. Beheerde inkomende media kunnen worden verwezen als
  `media://inbound/<id>`, sandbox-relatief `media/inbound/<id>`, of een opgelost
  pad binnen de beheerde directory voor inkomende media. Geneste mediarefs,
  traversal, symlinks, hardlinks en willekeurige lokale paden worden nog steeds geweigerd.
* `upload` kan ook bestandsinvoervelden direct instellen via `--input-ref` of `--element`.

Stabiele tabblad-ID's en labels overleven vervanging van Chromium-raw-target wanneer OpenClaw
de vervangende tab kan bewijzen, zoals dezelfde URL of een enkel oud tabblad dat na
formulierinzending een enkel nieuw tabblad wordt. Ruwe target-ID's blijven vluchtig; gebruik bij voorkeur
`suggestedTargetId` uit `tabs` in scripts.

Snapshotvlaggen in een oogopslag:

* `--format ai` (standaard met Playwright): AI-snapshot met numerieke refs (`aria-ref="<n>"`).
* `--format aria`: toegankelijkheidsstructuur met `axN`-refs. Wanneer Playwright beschikbaar is, koppelt OpenClaw refs met backend-DOM-id's aan de live pagina zodat vervolgacties ze kunnen gebruiken; behandel de uitvoer anders alleen als inspectie.
* `--efficient` (of `--mode efficient`): compacte voorinstelling voor rolesnapshot. Stel `browser.snapshotDefaults.mode: "efficient"` in om dit de standaard te maken (zie [Gateway-configuratie](/nl/gateway/configuration-reference#browser)).
* `--interactive`, `--compact`, `--depth`, `--selector` forceren een rolesnapshot met `ref=e12`-refs. `--frame "<iframe>"` beperkt rolesnapshots tot een iframe.
* Met Playwright voegt `--labels` een screenshot met overlappende ref-labels toe
  (print `MEDIA:<path>`) plus een `annotations`-array met de begrenzingsbox
  van elke ref. Bij `screenshot` werken door Playwright ondersteunde labels met
  `--full-page`, `--ref` en `--element`; bij `snapshot` blijft de bijbehorende
  screenshot beperkt tot de viewport. Bestaande-sessie-/chrome-mcp-profielen renderen overlaylabels op
  paginascreenshots, maar retourneren geen `annotations` en gebruiken de Playwright
  full-page/ref/element-projectiehelper niet. Zonder Playwright of chrome-mcp
  zijn gelabelde screenshots niet beschikbaar.
* `--urls` voegt ontdekte 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`.

* **Rolesnapshot (rolrefs zoals `e12`)**: `openclaw browser snapshot --interactive` (of `--compact`, `--depth`, `--selector`, `--frame`)
  * Uitvoer: een op rollen gebaseerde lijst/structuur 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 screenshot met overlappende `e12`-labels op te nemen. Op
    door Playwright ondersteunde profielen retourneert dit ook begrenzingsboxmetadata
    per ref (`annotations[]`).
  * 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 toegankelijkheidsstructuur als gestructureerde knooppunten.
  * Acties: `openclaw browser click ax12` werkt wanneer het snapshotpad de ref kan koppelen
    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 bruikbaar voor acties. Maak opnieuw een snapshot met `--format ai`
  of `--interactive` wanneer je actierefs nodig hebt.

* Docker-bewijs voor het raw-CDP-terugvalpad: `pnpm test:docker:browser-cdp-snapshot`
  start Chromium met CDP, voert `browser doctor --deep` uit en verifieert dat rolesnapshots
  link-URL's, cursor-gepromoveerde aanklikbare elementen en iframe-metadata bevatten.

Ref-gedrag:

* Refs zijn **niet stabiel over navigaties heen**; als iets mislukt, voer `snapshot` opnieuw uit en gebruik een nieuwe ref.
* `/act` retourneert de huidige ruwe `targetId` na door actie getriggerde vervanging
  wanneer het de vervangende tab kan bewijzen. Blijf stabiele tab-id's/labels gebruiken voor
  vervolgopdrachten.
* Als de rolesnapshot met `--frame` is gemaakt, zijn rolrefs beperkt tot dat iframe tot de volgende rolesnapshot.
* Onbekende of verouderde `axN`-refs falen snel in plaats van terug te vallen op
  Playwrights `aria-ref`-selector. Voer een nieuwe snapshot uit 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`
  * Ondersteund op beheerde `openclaw`- en raw/remote CDP-profielen. De profielen `user` en `existing-session` weigeren `networkidle`; gebruik daar `--url`, `--text`, een selector of `--fn`-wachters.
* 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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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"):

1. `openclaw browser snapshot --interactive`
2. Gebruik `click <ref>` / `type <ref>` (geef de voorkeur aan rolrefs in interactieve modus)
3. Als het nog steeds mislukt: `openclaw browser highlight <ref>` om te zien waarop Playwright zich richt
4. Als de pagina zich vreemd gedraagt:
   * `openclaw browser errors --clear`
   * `openclaw browser requests --filter api --clear`
5. Voor diepgaande debugging: neem een trace op:
   * `openclaw browser trace start`
   * reproduceer het probleem
   * `openclaw browser trace stop` (print `TRACE:<path>`)

## JSON-uitvoer

`--json` is bedoeld voor scripts en gestructureerde tooling.

Voorbeelden:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json
```

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

## Status- en omgevingsknoppen

Deze zijn nuttig voor workflows van het type "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-apparaatvoorinstellingen)
  * `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 dit uit met `browser.evaluateEnabled=false` als je het niet nodig hebt.
* `openclaw browser evaluate --fn` accepteert een functiebron, een expressie of
  een statement-body. Statement-body's worden verpakt als async functies, dus gebruik
  `return` voor de waarde die je terug wilt krijgen. Gebruik `--timeout-ms <ms>` wanneer de
  functie aan paginazijde langer nodig kan hebben dan de standaard-evaluatietime-out.
* Voor logins en anti-botnotities (X/Twitter, enz.), zie [Browserlogin + posten op X/Twitter](/nl/tools/browser-login).
* Houd de Gateway/Node-host privé (local loopback of alleen tailnet).
* Remote CDP-eindpunten zijn krachtig; tunnel en bescherm ze.

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // optional exact allow
    },
  },
}
```

## Gerelateerd

* [Browser](/nl/tools/browser) - overzicht, configuratie, profielen, beveiliging
* [Browserlogin](/nl/tools/browser-login) - inloggen op sites
* [Browser Linux-probleemoplossing](/nl/tools/browser-linux-troubleshooting)
* [Browser WSL2-probleemoplossing](/nl/tools/browser-wsl2-windows-remote-cdp-troubleshooting)