Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
openclaw browser

Gestisci la superficie di controllo del browser di OpenClaw ed esegui azioni del browser (ciclo di vita, profili, schede, snapshot, screenshot, navigazione, input, emulazione dello stato e debug). Correlati:

​
Flag comuni

  • --url <gatewayWsUrl>: URL WebSocket del Gateway (predefinito dalla configurazione).
  • --token <token>: token del Gateway (se richiesto).
  • --timeout <ms>: timeout della richiesta (ms).
  • --expect-final: attende una risposta finale del Gateway.
  • --browser-profile <name>: sceglie un profilo del browser (predefinito dalla configurazione).
  • --json: output leggibile da macchina (dove supportato).

​
Avvio rapido (locale)

openclaw browser profiles
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
Gli agenti possono eseguire lo stesso controllo di prontezza con browser({ action: "doctor" }).

​
Risoluzione rapida dei problemi

Se start fallisce con not reachable after start, diagnostica prima la prontezza CDP. Se start e tabs riescono ma open o navigate fallisce, il piano di controllo del browser è integro e l’errore è di solito dovuto alla policy SSRF di navigazione. Sequenza minima: 
openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com
Indicazioni dettagliate: Risoluzione dei problemi del browser

​
Ciclo di vita

openclaw browser status
openclaw browser doctor
openclaw browser doctor --deep
openclaw browser start
openclaw browser start --headless
openclaw browser stop
openclaw browser --browser-profile openclaw reset-profile
Note:
  • doctor --deep aggiunge una prova snapshot live. È utile quando la prontezza CDP di base è verde ma vuoi una prova che la scheda corrente possa essere ispezionata.
  • Per profili attachOnly e CDP remoti, openclaw browser stop chiude la sessione di controllo attiva e cancella gli override temporanei di emulazione anche quando OpenClaw non ha avviato direttamente il processo del browser.
  • Per i profili locali gestiti, openclaw browser stop arresta il processo del browser generato.
  • openclaw browser start --headless si applica solo a quella richiesta di avvio e solo quando OpenClaw avvia un browser locale gestito. Non riscrive browser.headless o la configurazione del profilo, ed è un no-op per un browser già in esecuzione.
  • Sugli host Linux senza DISPLAY o WAYLAND_DISPLAY, i profili locali gestiti vengono eseguiti automaticamente in modalità headless a meno che OPENCLAW_BROWSER_HEADLESS=0, browser.headless=false o browser.profiles.<name>.headless=false richieda esplicitamente un browser visibile.

​
Se il comando manca

Se openclaw browser è un comando sconosciuto, controlla plugins.allow in ~/.openclaw/openclaw.json. Quando plugins.allow è presente, elenca esplicitamente il Plugin browser incluso a meno che la configurazione non abbia già un blocco radice browser: 
{
  plugins: {
    allow: ["telegram", "browser"],
  },
}
Un blocco radice browser esplicito, per esempio browser.enabled=true o browser.profiles.<name>, attiva anche il Plugin browser incluso sotto una allowlist restrittiva dei Plugin. Correlato: Strumento browser

​
Profili

I profili sono configurazioni denominate di instradamento del browser. In pratica:
  • openclaw: avvia o si collega a un’istanza Chrome dedicata gestita da OpenClaw (directory dati utente isolata).
  • user: controlla la tua sessione Chrome esistente con accesso già effettuato tramite Chrome DevTools MCP.
  • profili CDP personalizzati: puntano a un endpoint CDP locale o remoto.
openclaw browser profiles
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
openclaw browser delete-profile --name work
Usa un profilo specifico: 
openclaw browser --browser-profile work tabs

​
Schede

openclaw browser tabs
openclaw browser tab new --label docs
openclaw browser tab label t1 docs
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://docs.openclaw.ai --label docs
openclaw browser focus docs
openclaw browser close t1
tabs restituisce prima suggestedTargetId, poi il tabId stabile come t1, l’etichetta opzionale e il targetId grezzo. Gli agenti devono passare suggestedTargetId di nuovo a focus, close, snapshot e azioni. Puoi assegnare un’etichetta con open --label, tab new --label o tab label; etichette, ID scheda, ID target grezzi e prefissi univoci degli ID target sono tutti accettati. Quando Chromium sostituisce il target grezzo sottostante durante una navigazione o l’invio di un modulo, OpenClaw mantiene il tabId/l’etichetta stabile collegati alla scheda sostitutiva quando può dimostrare la corrispondenza. Gli ID target grezzi restano volatili; preferisci suggestedTargetId.

​
Snapshot / screenshot / azioni

Snapshot: 
openclaw browser snapshot
openclaw browser snapshot --urls
Screenshot: 
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
openclaw browser screenshot --labels
Note:
  • --full-page è solo per acquisizioni di pagina; non può essere combinato con --ref o --element.
  • I profili existing-session / user supportano screenshot di pagina e screenshot --ref dall’output snapshot, ma non screenshot CSS --element.
  • --labels sovrappone i riferimenti snapshot correnti allo screenshot.
  • snapshot --urls aggiunge le destinazioni dei link rilevate agli snapshot AI così che gli agenti possano scegliere target di navigazione diretti invece di dedurli dal solo testo del link.
Naviga/fai clic/digita (automazione UI basata su ref): 
openclaw browser navigate https://example.com
openclaw browser click <ref>
openclaw browser click-coords 120 340
openclaw browser type <ref> "hello"
openclaw browser press Enter
openclaw browser hover <ref>
openclaw browser scrollintoview <ref>
openclaw browser drag <startRef> <endRef>
openclaw browser select <ref> OptionA OptionB
openclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'
openclaw browser wait --text "Done"
openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>
Le risposte delle azioni restituiscono il targetId grezzo corrente dopo la sostituzione della pagina innescata dall’azione quando OpenClaw può dimostrare la scheda sostitutiva. Gli script devono comunque memorizzare e passare suggestedTargetId/etichette per workflow di lunga durata. Helper per file e finestre di dialogo: 
openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
openclaw browser waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
I profili Chrome gestiti salvano i download ordinari attivati da clic nella directory dei download di OpenClaw (/tmp/openclaw/downloads per impostazione predefinita, o la radice temporanea configurata). Usa waitfordownload o download quando l’agente deve attendere un file specifico e restituirne il percorso; questi waiter espliciti possiedono il download successivo.

​
Stato e archiviazione

Viewport + emulazione: 
openclaw browser resize 1280 720
openclaw browser set viewport 1280 720
openclaw browser set offline on
openclaw browser set media dark
openclaw browser set timezone Europe/London
openclaw browser set locale en-GB
openclaw browser set geo 51.5074 -0.1278 --accuracy 25
openclaw browser set device "iPhone 14"
openclaw browser set headers '{"x-test":"1"}'
openclaw browser set credentials myuser mypass
Cookie + archiviazione: 
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 token abc123
openclaw browser storage session clear

​
Debug

openclaw browser console --level error
openclaw browser pdf
openclaw browser responsebody "**/api"
openclaw browser highlight <ref>
openclaw browser errors --clear
openclaw browser requests --filter api
openclaw browser trace start
openclaw browser trace stop --out trace.zip

​
Chrome esistente tramite MCP

Usa il profilo user integrato, oppure crea un tuo profilo existing-session: 
openclaw browser --browser-profile user tabs
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
openclaw browser --browser-profile chrome-live tabs
Questo percorso è solo host. Per Docker, server headless, Browserless o altre configurazioni remote, usa invece un profilo CDP. Limiti attuali di existing-session:
  • le azioni guidate da snapshot usano ref, non selettori CSS
  • browser.actionTimeoutMs imposta per impostazione predefinita le richieste act supportate a 60000 ms quando i chiamanti omettono timeoutMs; timeoutMs per chiamata ha comunque la precedenza.
  • click è solo clic sinistro
  • type non supporta slowly=true
  • press non supporta delayMs
  • hover, scrollintoview, drag, select, fill e evaluate rifiutano override di timeout per chiamata
  • select supporta un solo valore
  • wait --load networkidle non è supportato
  • i caricamenti di file richiedono --ref / --input-ref, non supportano CSS --element e attualmente supportano un file alla volta
  • gli hook delle finestre di dialogo non supportano --timeout
  • gli screenshot supportano acquisizioni di pagina e --ref, ma non CSS --element
  • responsebody, l’intercettazione dei download, l’esportazione PDF e le azioni batch richiedono ancora un browser gestito o un profilo CDP grezzo

​
Controllo browser remoto (proxy host del node)

Se il Gateway viene eseguito su una macchina diversa dal browser, esegui un host node sulla macchina che ha Chrome/Brave/Edge/Chromium. Il Gateway inoltrerà le azioni del browser a quel node (non è richiesto un server di controllo browser separato). Usa gateway.nodes.browser.mode per controllare l’instradamento automatico e gateway.nodes.browser.node per fissare un node specifico se ne sono connessi più di uno. Sicurezza + configurazione remota: Strumento browser, Accesso remoto, Tailscale, Sicurezza

​
Correlati