API di controllo del browser

Per installazione, configurazione e risoluzione dei problemi, consulta Browser. Questa pagina è il riferimento per l'API HTTP di controllo locale, la CLI openclaw browser e i pattern di scripting (snapshot, ref, attese, flussi di debug).

API di controllo (opzionale)

Solo per integrazioni locali, il Gateway espone una piccola API HTTP su local loopback. Questo server autonomo è opt-in: imposta la variabile d'ambiente OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1 nell'ambiente del servizio gateway e riavvia il gateway prima che gli endpoint HTTP diventino disponibili. Senza questa variabile, il runtime di controllo del browser continua a funzionare tramite la CLI e gli strumenti dell'agente, ma nulla resta in ascolto sulla porta di controllo local loopback.

• Stato/avvio/arresto: GET /, POST /start, POST /stop
• Schede: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
• Snapshot/screenshot: GET /snapshot, POST /screenshot
• Azioni: POST /navigate, POST /act
• Hook: POST /hooks/file-chooser, POST /hooks/dialog
• Download: POST /download, POST /wait/download
• Autorizzazioni: POST /permissions/grant
• Debug: GET /console, POST /pdf
• Debug: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
• Rete: POST /response/body
• Stato: GET /cookies, POST /cookies/set, POST /cookies/clear
• Stato: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
• Impostazioni: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

Tutti gli endpoint accettano ?profile=<name>. POST /start?headless=true richiede un avvio headless una tantum per profili locali gestiti senza modificare la configurazione persistente del browser; i profili attach-only, CDP remoti e con sessione esistente rifiutano questa sovrascrittura perché OpenClaw non avvia quei processi del browser.

Per gli endpoint delle schede, targetId è il nome del campo di compatibilità. Preferisci passare suggestedTargetId da GET /tabs o POST /tabs/open; sono accettati anche etichette e handle tabId come t1. Gli ID target CDP grezzi e i prefissi univoci degli ID target grezzi continuano a funzionare, ma sono handle diagnostici volatili.

Se è configurata l'autenticazione gateway con segreto condiviso, anche le route HTTP del browser richiedono autenticazione:

• Authorization: Bearer <gateway token>
• x-openclaw-password: <gateway password> o autenticazione HTTP Basic con quella password

Note:

• Questa API browser local loopback autonoma non consuma intestazioni di identità trusted-proxy o Tailscale Serve.
• Se gateway.auth.mode è none o trusted-proxy, queste route browser local loopback non ereditano tali modalità basate su identità; mantienile solo su local loopback.

Contratto di errore di /act

POST /act usa una risposta di errore strutturata per la validazione a livello di route e gli errori di policy:

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

Valori correnti di code:

• ACT_KIND_REQUIRED (HTTP 400): kind manca o non è riconosciuto.
• ACT_INVALID_REQUEST (HTTP 400): il payload dell'azione non ha superato la normalizzazione o la validazione.
• ACT_SELECTOR_UNSUPPORTED (HTTP 400): selector è stato usato con un tipo di azione non supportato.
• ACT_EVALUATE_DISABLED (HTTP 403): evaluate (o wait --fn) è disabilitato dalla configurazione.
• ACT_TARGET_ID_MISMATCH (HTTP 403): il targetId di primo livello o in batch è in conflitto con il target della richiesta.
• ACT_EXISTING_SESSION_UNSUPPORTED (HTTP 501): l'azione non è supportata per i profili con sessione esistente.

Altri errori di runtime possono comunque restituire { "error": "<message>" } senza un campo code.

Requisito Playwright

Alcune funzionalità (navigate/act/snapshot AI/snapshot dei ruoli, screenshot degli elementi, PDF) richiedono Playwright. Se Playwright non è installato, questi endpoint restituiscono un errore 501 chiaro.

Cosa funziona comunque senza Playwright:

• Snapshot ARIA
• Snapshot di accessibilità in stile ruolo (--interactive, --compact, --depth, --efficient) quando è disponibile un WebSocket CDP per scheda. Questo è un fallback per l'ispezione e la scoperta delle ref; Playwright resta il motore di azione principale.
• Screenshot di pagina per il browser openclaw gestito quando è disponibile un WebSocket CDP per scheda
• Screenshot di pagina per profili existing-session / Chrome MCP
• Screenshot basati su ref existing-session (--ref) dall'output di snapshot

Cosa richiede ancora Playwright:

• navigate
• act
• Snapshot AI che dipendono dal formato snapshot AI nativo di Playwright
• Screenshot di elementi con selettore CSS (--element)
• esportazione PDF completa del browser

Gli screenshot degli elementi rifiutano anche --full-page; la route restituisce fullPage is not supported for element screenshots.

Se vedi Playwright is not available in this gateway build, al Gateway pacchettizzato manca la dipendenza runtime core del browser. Reinstalla o aggiorna OpenClaw, quindi riavvia il gateway. Per Docker, installa anche i binari del browser Chromium come mostrato sotto.

Installazione Docker di Playwright

Se il tuo Gateway viene eseguito in Docker, evita npx playwright (conflitti con override npm). Per immagini personalizzate, integra Chromium nell'immagine:

OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh

Per un'immagine esistente, installa invece tramite la CLI inclusa:

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

Per rendere persistenti i download del browser, imposta PLAYWRIGHT_BROWSERS_PATH (per esempio, /home/node/.cache/ms-playwright) e assicurati che /home/node sia persistito tramite OPENCLAW_HOME_VOLUME o un bind mount. OpenClaw rileva automaticamente il Chromium persistito su Linux. Consulta Docker.

Come funziona (interno)

Un piccolo server di controllo local loopback accetta richieste HTTP e si connette a browser basati su Chromium tramite CDP. Le azioni avanzate (click/type/snapshot/PDF) passano attraverso Playwright sopra CDP; quando Playwright manca, sono disponibili solo le operazioni non Playwright. L'agente vede un'unica interfaccia stabile mentre browser e profili locali/remoti cambiano liberamente al di sotto.

Riferimento rapido CLI

Tutti i comandi accettano --browser-profile <name> per indirizzare un profilo specifico, e --json per output leggibile da macchine.

openclaw browser statusopenclaw browser startopenclaw browser start --headless # one-shot local managed headless launchopenclaw browser stop            # also clears emulation on attach-only/remote CDPopenclaw browser tabsopenclaw browser tab             # shortcut for current 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 12        # or --ref e12openclaw browser screenshot --labelsopenclaw browser snapshotopenclaw browser snapshot --format aria --limit 200openclaw browser snapshot --interactive --compact --depth 6openclaw browser snapshot --efficientopenclaw browser snapshot --labelsopenclaw browser snapshot --urlsopenclaw 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 --double           # or e12 for role refsopenclaw browser click-coords 120 340        # viewport coordinatesopenclaw 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 report.pdfopenclaw browser waitfordownload report.pdfopenclaw browser upload /tmp/openclaw/uploads/file.pdfopenclaw browser upload media://inbound/file.pdfopenclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'openclaw browser dialog --acceptopenclaw browser dialog --dismiss --dialog-id d1openclaw 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 evaluate --fn 'const title = document.title; return title;'openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'openclaw 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 --headers-json '{"X-Debug":"1"}'openclaw browser set credentials user pass            # --clear to removeopenclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"openclaw browser set media darkopenclaw browser set timezone America/New_Yorkopenclaw browser set locale en-USopenclaw browser set device "iPhone 14"

Note:

• upload e dialog sono chiamate di preparazione; eseguile prima del click/pressione che attiva il selettore/la finestra di dialogo. Se un'azione apre un modale, la risposta dell'azione include blockedByDialog e browserState.dialogs.pending; passa quel dialogId per rispondere direttamente. Le finestre di dialogo gestite fuori da OpenClaw appaiono sotto browserState.dialogs.recent.
• click/type/ecc. richiedono una ref da snapshot (numerica 12, ref di ruolo e12, o ref ARIA azionabile ax12). I selettori CSS non sono intenzionalmente supportati per le azioni. Usa click-coords quando la posizione visibile nel viewport è l'unico target affidabile.
• I percorsi di download e trace sono vincolati alle radici temporanee di OpenClaw: /tmp/openclaw{,/downloads} (fallback: ${os.tmpdir()}/openclaw/...).
• upload accetta file dalla radice temporanea degli upload di OpenClaw e media in ingresso gestiti da OpenClaw. I media in ingresso gestiti possono essere referenziati come media://inbound/<id>, media/inbound/<id> relativo alla sandbox, o un percorso risolto all'interno della directory dei media in ingresso gestiti. Ref media annidate, traversal, symlink, hardlink e percorsi locali arbitrari sono comunque rifiutati.
• upload può anche impostare direttamente gli input file tramite --input-ref o --element.

Gli ID scheda stabili e le etichette sopravvivono alla sostituzione raw-target di Chromium quando OpenClaw può dimostrare la scheda sostitutiva, ad esempio stesso URL o una singola vecchia scheda che diventa una singola nuova scheda dopo l'invio di un modulo. Gli ID target grezzi sono comunque volatili; preferisci suggestedTargetId da tabs negli script.

Panoramica rapida dei flag di snapshot:

• --format ai (predefinito con Playwright): snapshot AI con riferimenti numerici (aria-ref="<n>").
• --format aria: albero di accessibilità con riferimenti axN. Quando Playwright è disponibile, OpenClaw associa i riferimenti alla pagina live con gli ID DOM del backend, così le azioni successive possono usarli; altrimenti considera l'output solo per l'ispezione.
• --efficient (o --mode efficient): preset compatto dello snapshot dei ruoli. Imposta browser.snapshotDefaults.mode: "efficient" per renderlo il predefinito (vedi configurazione del Gateway).
• --interactive, --compact, --depth, --selector forzano uno snapshot dei ruoli con riferimenti ref=e12. --frame "<iframe>" limita gli snapshot dei ruoli a un iframe.
• Con Playwright, --labels aggiunge uno screenshot con etichette dei riferimenti sovrapposte (stampa MEDIA:<path>) più un array annotations con il riquadro di delimitazione di ogni riferimento. Su screenshot, le etichette basate su Playwright funzionano con --full-page, --ref e --element; su snapshot, lo screenshot di accompagnamento resta solo viewport. I profili existing-session/chrome-mcp renderizzano le etichette sovrapposte sugli screenshot della pagina ma non restituiscono annotations né usano l'helper di proiezione full-page/ref/element di Playwright. Senza Playwright o chrome-mcp, gli screenshot etichettati non sono disponibili.
• --urls aggiunge le destinazioni dei link rilevati agli snapshot AI.

Snapshot e riferimenti

OpenClaw supporta due stili di "snapshot":

• Snapshot AI (riferimenti numerici): openclaw browser snapshot (predefinito; --format ai)

  • Output: uno snapshot testuale che include riferimenti numerici.
  • Azioni: openclaw browser click 12, openclaw browser type 23 "hello".
  • Internamente, il riferimento viene risolto tramite aria-ref di Playwright.

• Snapshot dei ruoli (riferimenti di ruolo come e12): openclaw browser snapshot --interactive (o --compact, --depth, --selector, --frame)

  • Output: un elenco/albero basato sui ruoli con [ref=e12] (e [nth=1] opzionale).
  • Azioni: openclaw browser click e12, openclaw browser highlight e12.
  • Internamente, il riferimento viene risolto tramite getByRole(...) (più nth() per i duplicati).
  • Aggiungi --labels per includere uno screenshot con etichette e12 sovrapposte. Sui profili basati su Playwright questo restituisce anche metadati del riquadro di delimitazione per riferimento (annotations[]).
  • Aggiungi --urls quando il testo del link è ambiguo e l'agente ha bisogno di destinazioni di navigazione concrete.

• Snapshot ARIA (riferimenti ARIA come ax12): openclaw browser snapshot --format aria

  • Output: l'albero di accessibilità come nodi strutturati.
  • Azioni: openclaw browser click ax12 funziona quando il percorso dello snapshot può associare il riferimento tramite Playwright e gli ID DOM del backend Chrome.

• Se Playwright non è disponibile, gli snapshot ARIA possono comunque essere utili per l'ispezione, ma i riferimenti potrebbero non essere utilizzabili per azioni. Esegui di nuovo lo snapshot con --format ai o --interactive quando hai bisogno di riferimenti azionabili.

• Prova Docker per il percorso di fallback raw-CDP: pnpm test:docker:browser-cdp-snapshot avvia Chromium con CDP, esegue browser doctor --deep e verifica che gli snapshot dei ruoli includano URL dei link, elementi cliccabili promossi dal cursore e metadati iframe.

Comportamento dei riferimenti:

• I riferimenti non sono stabili tra navigazioni; se qualcosa fallisce, riesegui snapshot e usa un riferimento nuovo.
• /act restituisce l'attuale targetId grezzo dopo una sostituzione attivata da un'azione quando può provare la scheda sostitutiva. Continua a usare ID/etichette di schede stabili per i comandi successivi.
• Se lo snapshot dei ruoli è stato acquisito con --frame, i riferimenti di ruolo sono limitati a quell'iframe fino allo snapshot dei ruoli successivo.
• I riferimenti axN sconosciuti o obsoleti falliscono subito invece di ricadere nel selettore aria-ref di Playwright. Esegui uno snapshot nuovo sulla stessa scheda quando succede.

Potenziamenti dell'attesa

Puoi attendere più di semplice tempo/testo:

• Attendi l'URL (glob supportati da Playwright):
  • openclaw browser wait --url "**/dash"
• Attendi lo stato di caricamento:
  • openclaw browser wait --load networkidle
  • Supportato sui profili gestiti openclaw e raw/remote CDP. I profili user ed existing-session rifiutano networkidle; lì usa attese --url, --text, un selettore o --fn.
• Attendi un predicato JS:
  • openclaw browser wait --fn "window.ready===true"
• Attendi che un selettore diventi visibile:
  • openclaw browser wait "#main"

Questi possono essere combinati:

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

Flussi di debug

Quando un'azione fallisce (ad es. "not visible", "strict mode violation", "covered"):

1. openclaw browser snapshot --interactive
2. Usa click <ref> / type <ref> (preferisci i riferimenti di ruolo in modalità interattiva)
3. Se fallisce ancora: openclaw browser highlight <ref> per vedere cosa sta prendendo di mira Playwright
4. Se la pagina si comporta in modo anomalo:
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. Per un debug approfondito: registra una traccia:
   • openclaw browser trace start
   • riproduci il problema
   • openclaw browser trace stop (stampa TRACE:<path>)

Output JSON

--json è per scripting e strumenti strutturati.

Esempi:

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

Gli snapshot dei ruoli in JSON includono refs più un piccolo blocco stats (lines/chars/refs/interactive) così gli strumenti possono ragionare su dimensione e densità del payload.

Stato e opzioni dell'ambiente

Sono utili per flussi "fai comportare il sito come X":

• Cookie: cookies, cookies set, cookies clear
• Storage: storage local|session get|set|clear
• Offline: set offline on|off
• Header: set headers --headers-json '{"X-Debug":"1"}' (il legacy set headers --json '{"X-Debug":"1"}' resta supportato)
• Autenticazione HTTP basic: set credentials user pass (o --clear)
• Geolocalizzazione: set geo <lat> <lon> --origin "https://example.com" (o --clear)
• Media: set media dark|light|no-preference|none
• Fuso orario / locale: set timezone ..., set locale ...
• Dispositivo / viewport:
  • set device "iPhone 14" (preset dispositivo Playwright)
  • set viewport 1280 720

Sicurezza e privacy

• Il profilo browser openclaw può contenere sessioni autenticate; trattalo come sensibile.
• browser act kind=evaluate / openclaw browser evaluate e wait --fn eseguono JavaScript arbitrario nel contesto della pagina. La prompt injection può orientarlo. Disabilitalo con browser.evaluateEnabled=false se non ne hai bisogno.
• openclaw browser evaluate --fn accetta il sorgente di una funzione, un'espressione o il corpo di un'istruzione. I corpi delle istruzioni vengono racchiusi come funzioni async, quindi usa return per il valore che vuoi ottenere. Usa --timeout-ms <ms> quando la funzione lato pagina può richiedere più tempo del timeout evaluate predefinito.
• Per accessi e note anti-bot (X/Twitter, ecc.), vedi Accesso browser + pubblicazione su X/Twitter.
• Mantieni privato l'host Gateway/node (loopback o solo tailnet).
• Gli endpoint remote CDP sono potenti; crea tunnel e proteggili.

Esempio di strict-mode (blocca destinazioni private/interne per impostazione predefinita):

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

Correlati

• Browser - panoramica, configurazione, profili, sicurezza
• Accesso browser - accesso ai siti
• Risoluzione dei problemi del browser su Linux
• Risoluzione dei problemi Browser WSL2