From b3ee18e897fc86ea2a29d7d48d37ca99c2f71245 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 14 Apr 2026 13:06:41 +0000 Subject: [PATCH] chore(i18n): refresh it translations --- docs/it/tools/browser.md | 511 ++++++++++++++++++++++----------------- 1 file changed, 287 insertions(+), 224 deletions(-) diff --git a/docs/it/tools/browser.md b/docs/it/tools/browser.md index 5b0da2789..ee645a3ce 100644 --- a/docs/it/tools/browser.md +++ b/docs/it/tools/browser.md @@ -1,43 +1,43 @@ --- read_when: - - Aggiungere automazione del browser controllata dall'agente - - Debug di perché openclaw interferisce con il tuo Chrome - - Implementare impostazioni + ciclo di vita del browser nell'app macOS -summary: Servizio integrato di controllo del browser + comandi di azione + - Aggiunta dell'automazione del browser controllata dall'agente + - Debug di come openclaw stia interferendo con il tuo Chrome + - Implementazione delle impostazioni del browser + del ciclo di vita nell'app macOS +summary: Servizio di controllo del browser integrato + comandi di azione title: Browser (gestito da OpenClaw) x-i18n: - generated_at: "2026-04-11T02:47:50Z" + generated_at: "2026-04-14T13:04:29Z" model: gpt-5.4 provider: openai - source_hash: da6fed36a6f40a50e825f90e5616778954545bd7e52397f7e088b85251ee024f + source_hash: ae9ef725f544d4236d229f498c7187871c69bd18d31069b30a7e67fac53166a2 source_path: tools/browser.md workflow: 15 --- # Browser (gestito da openclaw) -OpenClaw può eseguire un **profilo dedicato Chrome/Brave/Edge/Chromium** controllato dall'agente. -È isolato dal tuo browser personale ed è gestito tramite un piccolo servizio di -controllo locale all'interno del Gateway (solo loopback). +OpenClaw può eseguire un **profilo Chrome/Brave/Edge/Chromium dedicato** controllato dall'agente. +È isolato dal tuo browser personale ed è gestito tramite un piccolo +servizio di controllo locale all'interno del Gateway (solo loopback). Vista per principianti: - Consideralo come un **browser separato, solo per l'agente**. -- Il profilo `openclaw` **non** tocca il tuo profilo browser personale. -- L'agente può **aprire schede, leggere pagine, fare clic e digitare** in un ambiente sicuro. -- Il profilo integrato `user` si collega alla tua vera sessione Chrome con accesso effettuato tramite Chrome MCP. +- Il profilo `openclaw` **non** tocca il profilo del tuo browser personale. +- L'agente può **aprire schede, leggere pagine, fare clic e digitare** in un percorso sicuro. +- Il profilo `user` integrato si collega alla tua sessione Chrome reale con accesso effettuato tramite Chrome MCP. ## Cosa ottieni - Un profilo browser separato chiamato **openclaw** (accento arancione per impostazione predefinita). - Controllo deterministico delle schede (elenca/apri/metti a fuoco/chiudi). -- Azioni dell'agente (clic/digitazione/trascinamento/selezione), snapshot, screenshot, PDF. +- Azioni dell'agente (clic/digita/trascina/seleziona), snapshot, screenshot, PDF. - Supporto opzionale per più profili (`openclaw`, `work`, `remote`, ...). -Questo browser **non** è il tuo browser quotidiano. È una superficie sicura e isolata per -automazione e verifica dell'agente. +Questo browser **non** è il tuo browser principale per tutti i giorni. È una superficie sicura e isolata per +l'automazione e la verifica da parte dell'agente. -## Guida rapida +## Avvio rapido ```bash openclaw browser --browser-profile openclaw status @@ -52,11 +52,11 @@ Gateway. Se `openclaw browser` manca del tutto, oppure l'agente dice che lo strumento browser non è disponibile, vai a [Comando o strumento browser mancante](/it/tools/browser#missing-browser-command-or-tool). -## Controllo del plugin +## Controllo del Plugin -Lo strumento `browser` predefinito ora è un plugin incluso distribuito abilitato per +Lo strumento `browser` predefinito ora è un Plugin incluso che viene distribuito abilitato per impostazione predefinita. Questo significa che puoi disabilitarlo o sostituirlo senza rimuovere il resto del -sistema di plugin di OpenClaw: +sistema di Plugin di OpenClaw: ```json5 { @@ -70,28 +70,33 @@ sistema di plugin di OpenClaw: } ``` -Disabilita il plugin incluso prima di installare un altro plugin che fornisce lo -stesso nome di strumento `browser`. L'esperienza browser predefinita richiede entrambi: +Disabilita il Plugin incluso prima di installare un altro plugin che fornisce lo +stesso nome strumento `browser`. L'esperienza browser predefinita richiede entrambi: - `plugins.entries.browser.enabled` non disabilitato - `browser.enabled=true` -Se disattivi solo il plugin, la CLI browser inclusa (`openclaw browser`), -il metodo gateway (`browser.request`), lo strumento agente e il servizio predefinito di controllo browser scompaiono tutti insieme. La tua configurazione `browser.*` rimane intatta perché un plugin sostitutivo possa riutilizzarla. +Se disattivi solo il Plugin, la CLI browser inclusa (`openclaw browser`), +il metodo Gateway (`browser.request`), lo strumento agente e il servizio di controllo browser +predefinito scompaiono tutti insieme. La tua configurazione `browser.*` rimane intatta per essere riutilizzata da +un Plugin sostitutivo. -Il plugin browser incluso ora gestisce anche l'implementazione runtime del browser. -Il core mantiene solo helper condivisi del Plugin SDK più re-export di compatibilità per i vecchi percorsi di import interni. In pratica, rimuovere o sostituire il pacchetto plugin browser elimina l'insieme di funzionalità browser invece di lasciare dietro un secondo runtime gestito dal core. +Il Plugin browser incluso ora possiede anche l'implementazione runtime del browser. +Il core mantiene solo gli helper condivisi del Plugin SDK più le riesportazioni di compatibilità per +i vecchi percorsi di importazione interni. In pratica, rimuovere o sostituire il pacchetto del Plugin browser +rimuove l'insieme di funzionalità del browser invece di lasciare dietro un secondo runtime +di proprietà del core. -Le modifiche alla configurazione browser richiedono comunque un riavvio del Gateway affinché il plugin incluso -possa registrare di nuovo il suo servizio browser con le nuove impostazioni. +Le modifiche alla configurazione del browser richiedono comunque un riavvio del Gateway affinché il Plugin incluso +possa registrare nuovamente il suo servizio browser con le nuove impostazioni. ## Comando o strumento browser mancante Se `openclaw browser` diventa improvvisamente un comando sconosciuto dopo un aggiornamento, oppure -l'agente segnala che lo strumento browser manca, la causa più comune è una lista `plugins.allow` +l'agente segnala che manca lo strumento browser, la causa più comune è una lista `plugins.allow` restrittiva che non include `browser`. -Esempio di configurazione errata: +Esempio di configurazione non funzionante: ```json5 { @@ -113,21 +118,21 @@ Correggila aggiungendo `browser` alla allowlist dei plugin: Note importanti: -- `browser.enabled=true` da solo non basta quando `plugins.allow` è impostato. -- Anche `plugins.entries.browser.enabled=true` da solo non basta quando `plugins.allow` è impostato. -- `tools.alsoAllow: ["browser"]` **non** carica il plugin browser incluso. Regola solo la policy dello strumento dopo che il plugin è già stato caricato. -- Se non hai bisogno di una allowlist restrittiva dei plugin, rimuovere `plugins.allow` ripristina anche il comportamento browser incluso predefinito. +- `browser.enabled=true` da solo non è sufficiente quando `plugins.allow` è impostato. +- Anche `plugins.entries.browser.enabled=true` da solo non è sufficiente quando `plugins.allow` è impostato. +- `tools.alsoAllow: ["browser"]` **non** carica il Plugin browser incluso. Regola solo la policy degli strumenti dopo che il Plugin è già stato caricato. +- Se non hai bisogno di una allowlist dei plugin restrittiva, rimuovere `plugins.allow` ripristina anche il comportamento browser incluso predefinito. Sintomi tipici: - `openclaw browser` è un comando sconosciuto. -- `browser.request` manca. +- `browser.request` è mancante. - L'agente segnala che lo strumento browser non è disponibile o manca. ## Profili: `openclaw` vs `user` -- `openclaw`: browser gestito e isolato (nessuna estensione richiesta). -- `user`: profilo integrato di collegamento Chrome MCP per la tua **vera sessione Chrome con accesso effettuato**. +- `openclaw`: browser gestito e isolato (non richiede estensioni). +- `user`: profilo integrato di collegamento Chrome MCP alla tua **vera sessione Chrome con accesso effettuato**. Per le chiamate allo strumento browser dell'agente: @@ -140,21 +145,21 @@ Imposta `browser.defaultProfile: "openclaw"` se vuoi la modalità gestita come p ## Configurazione -Le impostazioni browser si trovano in `~/.openclaw/openclaw.json`. +Le impostazioni del browser si trovano in `~/.openclaw/openclaw.json`. ```json5 { browser: { - enabled: true, // predefinito: true + enabled: true, // default: true ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // attiva solo per accesso fidato a reti private - // allowPrivateNetwork: true, // alias legacy + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, - // cdpUrl: "http://127.0.0.1:18792", // override legacy a profilo singolo - remoteCdpTimeoutMs: 1500, // timeout HTTP CDP remoto (ms) - remoteCdpHandshakeTimeoutMs: 3000, // timeout handshake WebSocket CDP remoto (ms) + // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override + remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms) + remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms) defaultProfile: "openclaw", color: "#FF4500", headless: false, @@ -183,32 +188,32 @@ Le impostazioni browser si trovano in `~/.openclaw/openclaw.json`. Note: -- Il servizio di controllo browser si collega a loopback su una porta derivata da `gateway.port` - (predefinita: `18791`, cioè gateway + 2). -- Se fai override della porta del Gateway (`gateway.port` o `OPENCLAW_GATEWAY_PORT`), - le porte browser derivate si spostano per restare nella stessa “famiglia”. +- Il servizio di controllo browser si associa al loopback su una porta derivata da `gateway.port` + (predefinito: `18791`, cioè gateway + 2). +- Se sovrascrivi la porta del Gateway (`gateway.port` o `OPENCLAW_GATEWAY_PORT`), + le porte browser derivate cambiano per restare nella stessa “famiglia”. - `cdpUrl` usa per impostazione predefinita la porta CDP locale gestita quando non è impostato. -- `remoteCdpTimeoutMs` si applica ai controlli di raggiungibilità CDP remota (non loopback). -- `remoteCdpHandshakeTimeoutMs` si applica ai controlli di raggiungibilità WebSocket CDP remota. +- `remoteCdpTimeoutMs` si applica ai controlli di raggiungibilità CDP remoti (non loopback). +- `remoteCdpHandshakeTimeoutMs` si applica ai controlli di raggiungibilità WebSocket CDP remoti. - La navigazione/apertura scheda del browser è protetta da SSRF prima della navigazione e ricontrollata al meglio sull'URL finale `http(s)` dopo la navigazione. -- In modalità SSRF strict, anche discovery/probe degli endpoint CDP remoti (`cdpUrl`, incluse le ricerche `/json/version`) vengono controllati. +- In modalità SSRF rigorosa, vengono controllati anche individuazione/sonde degli endpoint CDP remoti (`cdpUrl`, incluse le ricerche `/json/version`). - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` è disabilitato per impostazione predefinita. Impostalo su `true` solo quando ti fidi intenzionalmente dell'accesso browser alla rete privata. - `browser.ssrfPolicy.allowPrivateNetwork` resta supportato come alias legacy per compatibilità. -- `attachOnly: true` significa “non avviare mai un browser locale; collegati solo se è già in esecuzione.” +- `attachOnly: true` significa “non avviare mai un browser locale; collegarsi solo se è già in esecuzione.” - `color` + `color` per profilo colorano l'interfaccia del browser così puoi vedere quale profilo è attivo. - Il profilo predefinito è `openclaw` (browser standalone gestito da OpenClaw). Usa `defaultProfile: "user"` per scegliere il browser utente con accesso effettuato. -- Ordine di rilevamento automatico: browser predefinito del sistema se basato su Chromium; altrimenti Chrome → Brave → Edge → Chromium → Chrome Canary. -- I profili locali `openclaw` assegnano automaticamente `cdpPort`/`cdpUrl` — impostali solo per CDP remota. -- `driver: "existing-session"` usa Chrome DevTools MCP invece di CDP raw. Non +- Ordine di rilevamento automatico: browser di sistema predefinito se basato su Chromium; altrimenti Chrome → Brave → Edge → Chromium → Chrome Canary. +- I profili `openclaw` locali assegnano automaticamente `cdpPort`/`cdpUrl` — impostali solo per CDP remoto. +- `driver: "existing-session"` usa Chrome DevTools MCP invece di CDP grezzo. Non impostare `cdpUrl` per quel driver. - Imposta `browser.profiles..userDataDir` quando un profilo existing-session deve collegarsi a un profilo utente Chromium non predefinito come Brave o Edge. ## Usa Brave (o un altro browser basato su Chromium) -Se il tuo browser **predefinito di sistema** è basato su Chromium (Chrome/Brave/Edge/ecc), -OpenClaw lo usa automaticamente. Imposta `browser.executablePath` per fare override del -rilevamento automatico: +Se il tuo browser **di sistema predefinito** è basato su Chromium (Chrome/Brave/Edge/ecc.), +OpenClaw lo usa automaticamente. Imposta `browser.executablePath` per sovrascrivere +il rilevamento automatico: Esempio CLI: @@ -242,7 +247,7 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## Controllo locale vs remoto - **Controllo locale (predefinito):** il Gateway avvia il servizio di controllo loopback e può avviare un browser locale. -- **Controllo remoto (host del nodo):** esegui un host del nodo sulla macchina che ha il browser; il Gateway inoltra a esso le azioni del browser. +- **Controllo remoto (host node):** esegui un host node sulla macchina che ha il browser; il Gateway inoltra a esso le azioni del browser. - **CDP remoto:** imposta `browser.profiles..cdpUrl` (o `browser.cdpUrl`) per collegarti a un browser remoto basato su Chromium. In questo caso, OpenClaw non avvierà un browser locale. @@ -250,34 +255,34 @@ Il comportamento di arresto varia in base alla modalità del profilo: - profili locali gestiti: `openclaw browser stop` arresta il processo browser che OpenClaw ha avviato -- profili solo-attach e CDP remoti: `openclaw browser stop` chiude la sessione di +- profili attach-only e CDP remoti: `openclaw browser stop` chiude la sessione di controllo attiva e rilascia gli override di emulazione Playwright/CDP (viewport, schema colori, impostazioni locali, fuso orario, modalità offline e stato simile), anche se nessun processo browser è stato avviato da OpenClaw -Gli URL CDP remoti possono includere auth: +Gli URL CDP remoti possono includere autenticazione: -- Token di query (ad es. `https://provider.example?token=`) -- Auth HTTP Basic (ad es. `https://user:pass@provider.example`) +- Token di query (ad esempio, `https://provider.example?token=`) +- Autenticazione HTTP Basic (ad esempio, `https://user:pass@provider.example`) -OpenClaw conserva l'auth quando chiama gli endpoint `/json/*` e quando si collega -al WebSocket CDP. Preferisci variabili di ambiente o gestori di secret per i +OpenClaw preserva l'autenticazione quando chiama gli endpoint `/json/*` e quando si connette +al WebSocket CDP. Preferisci variabili d'ambiente o secret manager per i token invece di salvarli nei file di configurazione. -## Proxy browser del nodo (predefinito zero-config) +## Proxy browser node (predefinito a configurazione zero) -Se esegui un **host del nodo** sulla macchina che ha il browser, OpenClaw può -instradare automaticamente le chiamate allo strumento browser verso quel nodo senza configurazione browser aggiuntiva. -Questo è il percorso predefinito per i gateway remoti. +Se esegui un **host node** sulla macchina che ha il tuo browser, OpenClaw può +instradare automaticamente le chiamate allo strumento browser verso quel node senza alcuna configurazione browser aggiuntiva. +Questo è il percorso predefinito per i Gateway remoti. Note: -- L'host del nodo espone il proprio server locale di controllo browser tramite un **comando proxy**. -- I profili provengono dalla configurazione `browser.profiles` del nodo stesso (uguale a quella locale). -- `nodeHost.browserProxy.allowProfiles` è facoltativo. Lascialo vuoto per il comportamento legacy/predefinito: tutti i profili configurati restano raggiungibili tramite il proxy, incluse le route di creazione/eliminazione profilo. -- Se imposti `nodeHost.browserProxy.allowProfiles`, OpenClaw lo tratta come un confine di minimo privilegio: solo i profili nella allowlist possono essere destinati, e le route persistenti di creazione/eliminazione profilo vengono bloccate sulla superficie del proxy. +- L'host node espone il proprio server di controllo browser locale tramite un **comando proxy**. +- I profili provengono dalla configurazione `browser.profiles` del node stesso (uguale a quella locale). +- `nodeHost.browserProxy.allowProfiles` è opzionale. Lascialo vuoto per il comportamento legacy/predefinito: tutti i profili configurati restano raggiungibili tramite il proxy, incluse le route di creazione/eliminazione profilo. +- Se imposti `nodeHost.browserProxy.allowProfiles`, OpenClaw lo tratta come un confine di privilegio minimo: solo i profili nella allowlist possono essere destinati e le route di creazione/eliminazione dei profili persistenti vengono bloccate sulla superficie del proxy. - Disabilitalo se non lo vuoi: - - Sul nodo: `nodeHost.browserProxy.enabled=false` + - Sul node: `nodeHost.browserProxy.enabled=false` - Sul gateway: `gateway.nodes.browser.mode="off"` ## Browserless (CDP remoto ospitato) @@ -308,23 +313,23 @@ Esempio: Note: -- Sostituisci `` con il tuo vero token Browserless. +- Sostituisci `` con il tuo token Browserless reale. - Scegli l'endpoint regionale che corrisponde al tuo account Browserless (vedi la loro documentazione). - Se Browserless ti fornisce un URL base HTTPS, puoi convertirlo in `wss://` per una connessione CDP diretta oppure mantenere l'URL HTTPS e lasciare che OpenClaw - scopra `/json/version`. + individui `/json/version`. -## Provider WebSocket CDP diretti +## Provider CDP WebSocket diretti -Alcuni servizi browser ospitati espongono un endpoint **WebSocket** diretto invece -della discovery CDP standard basata su HTTP (`/json/version`). OpenClaw supporta entrambe le modalità: +Alcuni servizi browser ospitati espongono un endpoint **WebSocket diretto** invece +del rilevamento CDP standard basato su HTTP (`/json/version`). OpenClaw supporta entrambi: -- **Endpoint HTTP(S)** — OpenClaw chiama `/json/version` per individuare l'URL - WebSocket del debugger, quindi si connette. +- **Endpoint HTTP(S)** — OpenClaw chiama `/json/version` per individuare l'URL del debugger + WebSocket, quindi si connette. - **Endpoint WebSocket** (`ws://` / `wss://`) — OpenClaw si connette direttamente, saltando `/json/version`. Usa questa modalità per servizi come [Browserless](https://browserless.io), - [Browserbase](https://www.browserbase.com) o qualsiasi provider che ti fornisce un + [Browserbase](https://www.browserbase.com), o qualsiasi provider che ti fornisca un URL WebSocket. ### Browserbase @@ -354,30 +359,30 @@ Note: - [Registrati](https://www.browserbase.com/sign-up) e copia la tua **API Key** dalla [dashboard Overview](https://www.browserbase.com/overview). -- Sostituisci `` con la tua vera chiave API Browserbase. -- Browserbase crea automaticamente una sessione browser alla connessione WebSocket, quindi non - è necessario alcun passaggio manuale di creazione della sessione. +- Sostituisci `` con la tua vera API key Browserbase. +- Browserbase crea automaticamente una sessione browser alla connessione WebSocket, quindi + non è necessario alcun passaggio manuale di creazione della sessione. - Il piano gratuito consente una sessione concorrente e un'ora di browser al mese. Vedi i [prezzi](https://www.browserbase.com/pricing) per i limiti dei piani a pagamento. -- Vedi la [documentazione Browserbase](https://docs.browserbase.com) per il riferimento completo - dell'API, le guide SDK e gli esempi di integrazione. +- Consulta la [documentazione Browserbase](https://docs.browserbase.com) per il riferimento API + completo, le guide SDK e gli esempi di integrazione. ## Sicurezza Concetti chiave: -- Il controllo del browser è solo loopback; l'accesso passa tramite auth del Gateway o pairing del nodo. -- L'API HTTP browser loopback standalone usa **solo auth con secret condiviso**: - auth bearer con token gateway, `x-openclaw-password`, oppure auth HTTP Basic con la +- Il controllo del browser è solo loopback; l'accesso passa tramite l'autenticazione del Gateway o l'associazione del node. +- L'API HTTP browser standalone su loopback usa **solo autenticazione con segreto condiviso**: + autenticazione bearer con token del gateway, `x-openclaw-password`, oppure autenticazione HTTP Basic con la password del gateway configurata. - Gli header di identità Tailscale Serve e `gateway.auth.mode: "trusted-proxy"` **non** - autenticano questa API browser loopback standalone. -- Se il controllo browser è abilitato e non è configurata alcuna auth con secret condiviso, OpenClaw + autenticano questa API browser standalone su loopback. +- Se il controllo del browser è abilitato e non è configurata alcuna autenticazione con segreto condiviso, OpenClaw genera automaticamente `gateway.auth.token` all'avvio e lo salva nella configurazione. - OpenClaw **non** genera automaticamente quel token quando `gateway.auth.mode` è - già `password`, `none` o `trusted-proxy`. -- Mantieni il Gateway e gli eventuali host del nodo su una rete privata (Tailscale); evita l'esposizione pubblica. -- Tratta come secret gli URL/token CDP remoti; preferisci variabili di ambiente o un secrets manager. + già `password`, `none`, o `trusted-proxy`. +- Mantieni il Gateway e qualsiasi host node su una rete privata (Tailscale); evita l'esposizione pubblica. +- Tratta gli URL/token CDP remoti come segreti; preferisci variabili d'ambiente o un secret manager. Suggerimenti per CDP remoto: @@ -386,25 +391,25 @@ Suggerimenti per CDP remoto: ## Profili (multi-browser) -OpenClaw supporta più profili nominati (configurazioni di instradamento). I profili possono essere: +OpenClaw supporta più profili con nome (configurazioni di instradamento). I profili possono essere: - **gestiti da openclaw**: un'istanza dedicata di browser basato su Chromium con la propria directory dati utente + porta CDP -- **remoti**: un URL CDP esplicito (browser basato su Chromium in esecuzione altrove) -- **sessione esistente**: il tuo profilo Chrome esistente tramite collegamento automatico Chrome DevTools MCP +- **remoto**: un URL CDP esplicito (browser basato su Chromium in esecuzione altrove) +- **sessione esistente**: il tuo profilo Chrome esistente tramite auto-connessione Chrome DevTools MCP -Valori predefiniti: +Predefiniti: - Il profilo `openclaw` viene creato automaticamente se manca. - Il profilo `user` è integrato per il collegamento existing-session di Chrome MCP. -- I profili existing-session oltre a `user` sono opt-in; creali con `--driver existing-session`. +- I profili existing-session sono opzionali oltre a `user`; creali con `--driver existing-session`. - Le porte CDP locali vengono allocate da **18800–18899** per impostazione predefinita. -- Eliminare un profilo sposta la sua directory dati locale nel Cestino. +- L'eliminazione di un profilo sposta la sua directory dati locale nel Cestino. Tutti gli endpoint di controllo accettano `?profile=`; la CLI usa `--browser-profile`. ## Existing-session tramite Chrome DevTools MCP -OpenClaw può anche collegarsi a un profilo browser basato su Chromium già in esecuzione tramite il +OpenClaw può anche collegarsi a un profilo browser basato su Chromium in esecuzione tramite il server ufficiale Chrome DevTools MCP. Questo riutilizza le schede e lo stato di accesso già aperti in quel profilo browser. @@ -417,12 +422,12 @@ Profilo integrato: - `user` -Facoltativo: crea un tuo profilo existing-session personalizzato se vuoi un +Opzionale: crea il tuo profilo existing-session personalizzato se vuoi un nome, colore o directory dati browser diversi. Comportamento predefinito: -- Il profilo integrato `user` usa il collegamento automatico Chrome MCP, che punta al +- Il profilo `user` integrato usa l'auto-connessione Chrome MCP, che punta al profilo locale predefinito di Google Chrome. Usa `userDataDir` per Brave, Edge, Chromium o un profilo Chrome non predefinito: @@ -442,11 +447,11 @@ Usa `userDataDir` per Brave, Edge, Chromium o un profilo Chrome non predefinito: } ``` -Poi, nel browser corrispondente: +Quindi, nel browser corrispondente: 1. Apri la pagina inspect di quel browser per il debug remoto. 2. Abilita il debug remoto. -3. Mantieni il browser in esecuzione e approva il prompt di connessione quando OpenClaw si collega. +3. Lascia il browser in esecuzione e approva il prompt di connessione quando OpenClaw si collega. Pagine inspect comuni: @@ -463,73 +468,74 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -Aspetto di un risultato corretto: +Come appare il successo: - `status` mostra `driver: existing-session` - `status` mostra `transport: chrome-mcp` - `status` mostra `running: true` -- `tabs` elenca le schede browser già aperte +- `tabs` elenca le schede del browser già aperte - `snapshot` restituisce ref dalla scheda live selezionata Cosa controllare se il collegamento non funziona: -- il browser di destinazione basato su Chromium è versione `144+` +- il browser di destinazione basato su Chromium è alla versione `144+` - il debug remoto è abilitato nella pagina inspect di quel browser -- il browser ha mostrato il prompt di consenso al collegamento e tu l'hai accettato +- il browser ha mostrato il prompt di consenso al collegamento e tu lo hai accettato - `openclaw doctor` migra la vecchia configurazione browser basata su estensione e verifica che - Chrome sia installato localmente per i profili predefiniti di collegamento automatico, ma non può - abilitare per te il debug remoto lato browser + Chrome sia installato localmente per i profili predefiniti con auto-connessione, ma non può + abilitare per te il debug remoto dal lato browser Uso da parte dell'agente: -- Usa `profile="user"` quando hai bisogno dello stato del browser utente con accesso effettuato. +- Usa `profile="user"` quando hai bisogno dello stato del browser con accesso effettuato dell'utente. - Se usi un profilo existing-session personalizzato, passa quel nome profilo esplicito. -- Scegli questa modalità solo quando l'utente è al computer per approvare il prompt - di collegamento. -- il Gateway o l'host del nodo possono avviare `npx chrome-devtools-mcp@latest --autoConnect` +- Scegli questa modalità solo quando l'utente è al computer per approvare il + prompt di collegamento. +- il Gateway o l'host node può eseguire `npx chrome-devtools-mcp@latest --autoConnect` Note: -- Questo percorso è a rischio più elevato rispetto al profilo isolato `openclaw` perché può +- Questo percorso è più rischioso del profilo `openclaw` isolato perché può agire all'interno della tua sessione browser con accesso effettuato. - OpenClaw non avvia il browser per questo driver; si collega solo a una sessione esistente. - OpenClaw usa qui il flusso ufficiale Chrome DevTools MCP `--autoConnect`. Se - `userDataDir` è impostato, OpenClaw lo passa per puntare a quella esplicita + `userDataDir` è impostato, OpenClaw lo passa per puntare a quella specifica directory dati utente Chromium. -- Gli screenshot existing-session supportano catture della pagina e catture di elementi `--ref` - da snapshot, ma non selettori CSS `--element`. -- Gli screenshot della pagina existing-session funzionano senza Playwright tramite Chrome MCP. - Anche gli screenshot di elementi basati su ref (`--ref`) funzionano lì, ma `--full-page` +- Gli screenshot existing-session supportano acquisizioni della pagina e acquisizioni di elementi `--ref` + dagli snapshot, ma non i selettori CSS `--element`. +- Gli screenshot di pagina existing-session funzionano senza Playwright tramite Chrome MCP. + Gli screenshot di elementi basati su ref (`--ref`) funzionano anche lì, ma `--full-page` non può essere combinato con `--ref` o `--element`. -- Le azioni existing-session sono ancora più limitate rispetto al percorso browser gestito: - - `click`, `type`, `hover`, `scrollIntoView`, `drag` e `select` richiedono - ref snapshot invece di selettori CSS - - `click` supporta solo il pulsante sinistro (nessun override di pulsante o modificatore) +- Le azioni existing-session sono ancora più limitate rispetto al percorso del browser + gestito: + - `click`, `type`, `hover`, `scrollIntoView`, `drag`, e `select` richiedono + ref snapshot invece dei selettori CSS + - `click` è solo con il pulsante sinistro (nessuna sovrascrittura del pulsante o modificatore) - `type` non supporta `slowly=true`; usa `fill` o `press` - `press` non supporta `delayMs` - - `hover`, `scrollIntoView`, `drag`, `select`, `fill` ed `evaluate` non + - `hover`, `scrollIntoView`, `drag`, `select`, `fill`, e `evaluate` non supportano override di timeout per chiamata - - `select` attualmente supporta un solo valore -- Existing-session `wait --url` supporta pattern esatti, substring e glob + - `select` al momento supporta un solo valore +- Existing-session `wait --url` supporta pattern esatti, sottostringa e glob come gli altri driver browser. `wait --load networkidle` non è ancora supportato. - Gli hook di upload existing-session richiedono `ref` o `inputRef`, supportano un file alla volta e non supportano il targeting CSS `element`. -- Gli hook di dialogo existing-session non supportano override di timeout. -- Alcune funzionalità richiedono ancora il percorso browser gestito, incluse - batch actions, esportazione PDF, intercettazione dei download e `responsebody`. -- Existing-session è locale all'host. Se Chrome si trova su un'altra macchina o in un - namespace di rete diverso, usa invece CDP remoto o un host del nodo. +- Gli hook dialog existing-session non supportano override di timeout. +- Alcune funzionalità richiedono ancora il percorso browser gestito, inclusi + azioni batch, esportazione PDF, intercettazione dei download e `responsebody`. +- Existing-session è locale all'host. Se Chrome si trova su una macchina diversa o in un + namespace di rete diverso, usa invece CDP remoto o un host node. ## Garanzie di isolamento -- **Directory dati utente dedicata**: non tocca mai il tuo profilo browser personale. +- **Directory dati utente dedicata**: non tocca mai il profilo del tuo browser personale. - **Porte dedicate**: evita `9222` per prevenire collisioni con i flussi di lavoro di sviluppo. -- **Controllo deterministico delle schede**: punta alle schede tramite `targetId`, non “ultima scheda”. +- **Controllo deterministico delle schede**: le schede di destinazione vengono identificate tramite `targetId`, non tramite “ultima scheda”. ## Selezione del browser -Quando avvia localmente, OpenClaw sceglie il primo disponibile: +Quando viene avviato localmente, OpenClaw sceglie il primo disponibile: 1. Chrome 2. Brave @@ -537,15 +543,15 @@ Quando avvia localmente, OpenClaw sceglie il primo disponibile: 4. Chromium 5. Chrome Canary -Puoi fare override con `browser.executablePath`. +Puoi sovrascrivere con `browser.executablePath`. Piattaforme: - macOS: controlla `/Applications` e `~/Applications`. - Linux: cerca `google-chrome`, `brave`, `microsoft-edge`, `chromium`, ecc. -- Windows: controlla i percorsi di installazione comuni. +- Windows: controlla le posizioni di installazione comuni. -## API di controllo (facoltativa) +## API di controllo (opzionale) Solo per integrazioni locali, il Gateway espone una piccola API HTTP loopback: @@ -564,71 +570,71 @@ Solo per integrazioni locali, il Gateway espone una piccola API HTTP loopback: Tutti gli endpoint accettano `?profile=`. -Se è configurata l'auth gateway con secret condiviso, anche le route HTTP browser richiedono auth: +Se è configurata l'autenticazione gateway con segreto condiviso, anche le route HTTP browser richiedono autenticazione: - `Authorization: Bearer ` -- `x-openclaw-password: ` oppure auth HTTP Basic con quella password +- `x-openclaw-password: ` oppure autenticazione HTTP Basic con quella password Note: -- Questa API browser loopback standalone **non** usa header di identità trusted-proxy o - Tailscale Serve. -- Se `gateway.auth.mode` è `none` o `trusted-proxy`, queste route browser loopback - non ereditano quelle modalità che trasportano identità; mantienile solo loopback. +- Questa API browser standalone su loopback **non** usa trusted-proxy o + gli header di identità Tailscale Serve. +- Se `gateway.auth.mode` è `none` o `trusted-proxy`, queste route browser su loopback + non ereditano quelle modalità basate su identità; mantienile solo loopback. -### Contratto di errore di `/act` +### Contratto di errore `/act` -`POST /act` usa una risposta di errore strutturata per errori di validazione a livello route e -fallimenti di policy: +`POST /act` usa una risposta di errore strutturata per la validazione a livello di route e +i fallimenti di policy: ```json { "error": "", "code": "ACT_*" } ``` -Valori `code` attuali: +Valori `code` correnti: - `ACT_KIND_REQUIRED` (HTTP 400): `kind` manca o non è riconosciuto. -- `ACT_INVALID_REQUEST` (HTTP 400): il payload dell'azione non ha superato normalizzazione o validazione. +- `ACT_INVALID_REQUEST` (HTTP 400): il payload dell'azione ha fallito normalizzazione o validazione. - `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): è stato usato `selector` 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): `targetId` di primo livello o in batch è in conflitto con il target della richiesta. +- `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` di primo livello o batch è in conflitto con il target della richiesta. - `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): l'azione non è supportata per i profili existing-session. -Altri errori runtime possono ancora restituire `{ "error": "" }` senza un campo -`code`. +Altri errori di runtime possono ancora restituire `{ "error": "" }` senza un +campo `code`. ### Requisito Playwright -Alcune funzionalità (navigate/act/snapshot AI/snapshot role, screenshot di elementi, +Alcune funzionalità (navigate/act/AI snapshot/role snapshot, screenshot di elementi, PDF) richiedono Playwright. Se Playwright non è installato, quegli endpoint restituiscono un chiaro errore 501. -Cosa funziona ancora senza Playwright: +Cosa continua a funzionare senza Playwright: - Snapshot ARIA -- Screenshot di pagina per il browser gestito `openclaw` quando è disponibile un WebSocket +- Screenshot di pagina per il browser `openclaw` gestito quando è disponibile un WebSocket CDP per scheda -- Screenshot di pagina per i profili `existing-session` / Chrome MCP -- Screenshot existing-session basati su `--ref` dall'output snapshot +- Screenshot di pagina per profili `existing-session` / Chrome MCP +- Screenshot existing-session basati su `--ref` dall'output dello snapshot Cosa richiede ancora Playwright: - `navigate` - `act` -- snapshot AI / snapshot role -- screenshot di elementi con selettori CSS (`--element`) -- esportazione PDF completa del browser +- AI snapshot / role snapshot +- Screenshot di elementi con selettore CSS (`--element`) +- Esportazione PDF completa del browser -Gli screenshot di elementi rifiutano anche `--full-page`; la route restituisce `fullPage is +Anche gli screenshot di elementi rifiutano `--full-page`; la route restituisce `fullPage is not supported for element screenshots`. Se vedi `Playwright is not available in this gateway build`, installa il pacchetto -completo Playwright (non `playwright-core`) e riavvia il gateway, oppure reinstalla -OpenClaw con supporto browser. +Playwright completo (non `playwright-core`) e riavvia il gateway, oppure reinstalla +OpenClaw con il supporto browser. #### Installazione di Playwright in Docker -Se il tuo Gateway viene eseguito in Docker, evita `npx playwright` (conflitti con gli override npm). +Se il tuo Gateway è in esecuzione in Docker, evita `npx playwright` (conflitti con gli override npm). Usa invece la CLI inclusa: ```bash @@ -636,29 +642,29 @@ 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 persistente tramite +Per rendere persistenti i download del browser, imposta `PLAYWRIGHT_BROWSERS_PATH` (ad esempio, +`/home/node/.cache/ms-playwright`) e assicurati che `/home/node` sia persistito tramite `OPENCLAW_HOME_VOLUME` o un bind mount. Vedi [Docker](/it/install/docker). -## Come funziona (internamente) +## Come funziona (interno) Flusso di alto livello: - Un piccolo **server di controllo** accetta richieste HTTP. - Si collega ai browser basati su Chromium (Chrome/Brave/Edge/Chromium) tramite **CDP**. -- Per azioni avanzate (clic/digitazione/snapshot/PDF), usa **Playwright** sopra +- Per le azioni avanzate (clic/digitazione/snapshot/PDF), usa **Playwright** sopra CDP. -- Quando Playwright manca, sono disponibili solo le operazioni che non dipendono da Playwright. +- Quando Playwright non è presente, sono disponibili solo le operazioni che non usano Playwright. -Questo design mantiene l'agente su un'interfaccia stabile e deterministica consentendoti -al tempo stesso di cambiare browser e profili locali/remoti. +Questo design mantiene l'agente su un'interfaccia stabile e deterministica, permettendoti al contempo +di cambiare browser e profili locali/remoti. ## Riferimento rapido CLI -Tutti i comandi accettano `--browser-profile ` per puntare a un profilo specifico. -Tutti i comandi accettano anche `--json` per output leggibili da macchina (payload stabili). +Tutti i comandi accettano `--browser-profile ` per indirizzare un profilo specifico. +Tutti i comandi accettano anche `--json` per output leggibile da macchina (payload stabili). -Elementari: +Nozioni di base: - `openclaw browser status` - `openclaw browser start` @@ -689,8 +695,8 @@ Ispezione: Nota sul ciclo di vita: -- Per i profili solo-attach e CDP remoti, `openclaw browser stop` è comunque il - comando corretto di pulizia dopo i test. Chiude la sessione di controllo attiva e +- Per i profili attach-only e CDP remoti, `openclaw browser stop` è comunque il + comando di pulizia corretto dopo i test. Chiude la sessione di controllo attiva e cancella gli override temporanei di emulazione invece di terminare il browser sottostante. - `openclaw browser errors --clear` @@ -743,49 +749,49 @@ Stato: Note: -- `upload` e `dialog` sono chiamate di **arming**; eseguirle prima del clic/pressione - che attiva il file chooser/dialog. -- I percorsi di output di download e trace sono vincolati alle radici temporanee OpenClaw: +- `upload` e `dialog` sono chiamate di **preparazione**; eseguirle prima del clic/della pressione + che attiva il selettore/la finestra di dialogo. +- I percorsi di output di download e trace sono vincolati alle root temporanee di OpenClaw: - trace: `/tmp/openclaw` (fallback: `${os.tmpdir()}/openclaw`) - download: `/tmp/openclaw/downloads` (fallback: `${os.tmpdir()}/openclaw/downloads`) -- I percorsi di upload sono vincolati a una radice temporanea uploads di OpenClaw: +- I percorsi di upload sono vincolati a una root temporanea uploads di OpenClaw: - uploads: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`) - `upload` può anche impostare direttamente input file tramite `--input-ref` o `--element`. - `snapshot`: - `--format ai` (predefinito quando Playwright è installato): restituisce uno snapshot AI con ref numerici (`aria-ref=""`). - - `--format aria`: restituisce l'albero di accessibilità (nessun ref; solo ispezione). - - `--efficient` (o `--mode efficient`): preset compatto di role snapshot (interactive + compact + depth + maxChars inferiore). - - Predefinito di configurazione (solo strumento/CLI): imposta `browser.snapshotDefaults.mode: "efficient"` per usare snapshot efficient quando il chiamante non passa una modalità (vedi [Configurazione Gateway](/it/gateway/configuration-reference#browser)). - - Le opzioni di role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) forzano uno snapshot basato su ruoli con ref come `ref=e12`. - - `--frame "