Browser (gestito da OpenClaw)

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.

• 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 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.
• Una skill browser-automation inclusa che insegna agli agenti il ciclo di recupero snapshot, scheda stabile, riferimento obsoleto e blocco manuale quando il Plugin browser è abilitato.
• Supporto opzionale per più profili (openclaw, work, remote, …).

​

Avvio rapido

openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw doctor --deep
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

​

Controllo del Plugin

{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

​

Guida per l’agente

{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

• La descrizione dello strumento browser contiene il contratto compatto sempre attivo: scegliere il profilo corretto, mantenere i riferimenti sulla stessa scheda, usare tabId/etichette per il targeting delle schede e caricare la skill browser per il lavoro in più passaggi.
• La skill browser-automation inclusa contiene il ciclo operativo più esteso: controllare prima stato/schede, etichettare le schede dell’attività, acquisire uno snapshot prima di agire, acquisire un nuovo snapshot dopo modifiche dell’interfaccia, recuperare una volta i riferimenti obsoleti e segnalare login/2FA/captcha o blocchi di fotocamera/microfono come azione manuale invece di tirare a indovinare.

​

Comando o strumento browser mancante

{
  plugins: {
    allow: ["telegram", "browser"],
  },
}

​

Profili: openclaw vs user

• openclaw: browser gestito e isolato (non richiede estensioni).
• user: profilo di collegamento Chrome MCP integrato per la tua sessione Chrome reale con accesso effettuato.

• Predefinito: usa il browser isolato openclaw.
• Preferisci profile="user" quando le sessioni con accesso già effettuato sono importanti e l’utente è al computer per fare clic/approvare eventuali richieste di collegamento.
• profile è l’override esplicito quando vuoi una modalità browser specifica.

​

Configurazione

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      // 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", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms)
    localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms)
    actionTimeoutMs: 60000, // default browser act timeout (ms)
    tabCleanup: {
      enabled: true, // default: true
      idleMinutes: 120, // set 0 to disable idle cleanup
      maxTabsPerSession: 8, // set 0 to disable the per-session cap
      sweepMinutes: 5,
    },
    defaultProfile: "openclaw",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: {
        cdpPort: 18801,
        color: "#0066CC",
        headless: true,
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

​

Usare Brave o un altro browser basato su Chromium

openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
  },
}

{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
  },
}

{
  browser: {
    executablePath: "/usr/bin/brave-browser",
  },
}

​

Controllo locale e remoto

• Controllo locale (predefinito): il Gateway avvia il servizio di controllo loopback e può avviare un browser locale.
• Controllo remoto (host nodo): esegui un host nodo sulla macchina che ha il browser; il Gateway inoltra le azioni del browser a esso.
• CDP remoto: imposta browser.profiles.<name>.cdpUrl (o browser.cdpUrl) per collegarti a un browser remoto basato su Chromium. In questo caso, OpenClaw non avvierà un browser locale.
• Per i servizi CDP gestiti esternamente su loopback (per esempio Browserless in Docker pubblicato su 127.0.0.1), imposta anche attachOnly: true. Il CDP loopback senza attachOnly viene trattato come un profilo browser locale gestito da OpenClaw.
• headless influisce solo sui profili locali gestiti che OpenClaw avvia. Non riavvia né modifica i browser con sessione esistente o CDP remoti.
• executablePath segue la stessa regola dei profili locali gestiti. Modificarlo su un profilo locale gestito in esecuzione contrassegna quel profilo per il riavvio/la riconciliazione, così il prossimo avvio usa il nuovo binario.

• profili locali gestiti: openclaw browser stop arresta il processo browser che OpenClaw ha avviato
• profili solo collegamento e CDP remoti: openclaw browser stop chiude la sessione di controllo attiva e rilascia le sostituzioni di emulazione Playwright/CDP (viewport, schema colore, locale, fuso orario, modalità offline e stato simile), anche se nessun processo browser è stato avviato da OpenClaw

• Token di query (ad es. https://provider.example?token=<token>)
• Autenticazione HTTP Basic (ad es. https://user:pass@provider.example)

​

Proxy browser Node (predefinito zero-config)

• L’host nodo espone il proprio server locale di controllo browser tramite un comando proxy.
• I profili provengono dalla configurazione browser.profiles propria del nodo (come in 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 limite di privilegio minimo: possono essere presi di mira solo i profili nella allowlist, e le route persistenti di creazione/eliminazione profilo sono bloccate sulla superficie proxy.
• Disabilitalo se non lo vuoi:
  • Sul nodo: nodeHost.browserProxy.enabled=false
  • Sul gateway: gateway.nodes.browser.mode="off"

​

Browserless (CDP remoto ospitato)

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

• Sostituisci <BROWSERLESS_API_KEY> con il tuo vero token Browserless.
• Scegli l’endpoint di regione 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.

​

Browserless Docker sullo stesso host

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "ws://127.0.0.1:3000",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}

​

Provider CDP WebSocket diretti

• Rilevamento HTTP(S) - http://host[:port] o https://host[:port]. OpenClaw chiama /json/version per scoprire l’URL debugger WebSocket, poi si connette. Nessun fallback WebSocket.
• Endpoint WebSocket diretti - ws://host[:port]/devtools/<kind>/<id> o wss://... con un percorso /devtools/browser|page|worker|shared_worker|service_worker/<id>. OpenClaw si connette direttamente tramite un handshake WebSocket e salta completamente /json/version.
• Root WebSocket nudi - ws://host[:port] o wss://host[:port] senza percorso /devtools/... (ad es. Browserless, Browserbase). OpenClaw prova prima il rilevamento HTTP /json/version (normalizzando lo schema a http/https); se il rilevamento restituisce un webSocketDebuggerUrl, viene usato, altrimenti OpenClaw ricorre a un handshake WebSocket diretto alla root nuda. Se l’endpoint WebSocket pubblicizzato rifiuta l’handshake CDP ma la root nuda configurata lo accetta, OpenClaw ricorre anche a quella root. Questo consente a un ws:// nudo puntato a un Chrome locale di connettersi comunque, poiché Chrome accetta upgrade WebSocket solo sul percorso specifico per target da /json/version, mentre i provider ospitati possono continuare a usare il loro endpoint WebSocket root quando il loro endpoint di rilevamento pubblicizza un URL di breve durata non adatto a Playwright CDP.

​

Browserbase

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

• Registrati e copia la tua API Key dalla dashboard Overview.
• Sostituisci <BROWSERBASE_API_KEY> con la tua vera chiave API Browserbase.
• Browserbase crea automaticamente una sessione browser alla connessione WebSocket, quindi non è necessario alcun passaggio manuale di creazione sessione.
• Il piano gratuito consente una sessione concorrente e un’ora browser al mese. Vedi i prezzi per i limiti dei piani a pagamento.
• Vedi la documentazione Browserbase per il riferimento API completo, le guide SDK e gli esempi di integrazione.

​

Sicurezza

• Il controllo del browser è solo loopback; l’accesso passa attraverso l’autenticazione del Gateway o l’associazione del nodo.
• L’API HTTP autonoma del browser loopback usa solo l’autenticazione con segreto condiviso: autenticazione bearer con token del Gateway, x-openclaw-password o autenticazione HTTP Basic con la password del Gateway configurata.
• Gli header di identità di Tailscale Serve e gateway.auth.mode: "trusted-proxy" non autenticano questa API autonoma del browser loopback.
• Se il controllo del browser è abilitato e non è configurata alcuna autenticazione con segreto condiviso, OpenClaw genera un token del Gateway solo runtime per quell’avvio. Configura gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN o OPENCLAW_GATEWAY_PASSWORD in modo esplicito se i client hanno bisogno di un segreto stabile tra i riavvii.
• OpenClaw non genera automaticamente quel token quando gateway.auth.mode è già password, none o trusted-proxy.
• Mantieni il Gateway e tutti gli host nodo su una rete privata (Tailscale); evita l’esposizione pubblica.
• Tratta gli URL/token CDP remoti come segreti; preferisci variabili env o un gestore di segreti.

• Preferisci endpoint cifrati (HTTPS o WSS) e token a breve durata quando possibile.
• Evita di incorporare token a lunga durata direttamente nei file di configurazione.

​

Profili (multi-browser)

• gestiti da openclaw: un’istanza dedicata di browser basato su Chromium con la propria directory dei dati utente + porta CDP
• remoti: un URL CDP esplicito (browser basato su Chromium in esecuzione altrove)
• sessione esistente: il tuo profilo Chrome esistente tramite connessione automatica Chrome DevTools MCP

• Il profilo openclaw viene creato automaticamente se manca.
• Il profilo user è integrato per il collegamento a una sessione esistente Chrome MCP.
• I profili di sessione esistente oltre a user sono opt-in; creali con --driver existing-session.
• Le porte CDP locali vengono allocate da 18800-18899 per impostazione predefinita.
• L’eliminazione di un profilo sposta la sua directory dati locale nel Cestino.

​

Sessione esistente tramite Chrome DevTools MCP

• Chrome for Developers: Use Chrome DevTools MCP with your browser session
• Chrome DevTools MCP README

• user

• Il profilo integrato user usa la connessione automatica Chrome MCP, che ha come target il profilo locale predefinito di Google Chrome.

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

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 la richiesta di connessione quando OpenClaw si collega.

• Chrome: chrome://inspect/#remote-debugging
• Brave: brave://inspect/#remote-debugging
• Edge: edge://inspect/#remote-debugging

openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai

• status mostra driver: existing-session
• status mostra transport: chrome-mcp
• status mostra running: true
• tabs elenca le schede del browser già aperte
• snapshot restituisce riferimenti dalla scheda live selezionata

• il browser target basato su Chromium è alla versione 144+
• il debug remoto è abilitato nella pagina inspect di quel browser
• il browser ha mostrato la richiesta di consenso al collegamento e l’hai accettata
• openclaw doctor migra la vecchia configurazione browser basata su estensione e verifica che Chrome sia installato localmente per i profili predefiniti con connessione automatica, ma non può abilitare per te il debug remoto lato browser

• Usa profile="user" quando hai bisogno dello stato autenticato del browser dell’utente.
• Se usi un profilo personalizzato di sessione esistente, passa quel nome di profilo esplicito.
• Scegli questa modalità solo quando l’utente è al computer per approvare la richiesta di collegamento.
• il Gateway o l’host nodo può avviare npx chrome-devtools-mcp@latest --autoConnect

• Questo percorso è più rischioso del profilo isolato openclaw perché può agire all’interno della tua sessione browser autenticata.
• OpenClaw non avvia il browser per questo driver; si collega soltanto.
• OpenClaw usa qui il flusso ufficiale Chrome DevTools MCP --autoConnect. Se userDataDir è impostato, viene inoltrato per puntare a quella directory dei dati utente.
• La sessione esistente può collegarsi sull’host selezionato o tramite un nodo browser connesso. Se Chrome si trova altrove e nessun nodo browser è connesso, usa CDP remoto o un host nodo.

​

Avvio Chrome MCP personalizzato

• http(s)://... → --browserUrl <url> (endpoint di discovery HTTP DevTools).
• ws(s)://... → --wsEndpoint <url> (WebSocket CDP diretto).

​

Garanzie di isolamento

• Directory dati utente dedicata: non tocca mai il tuo profilo browser personale.
• Porte dedicate: evita 9222 per prevenire collisioni con i flussi di sviluppo.
• Controllo deterministico delle schede: tabs restituisce prima suggestedTargetId, poi handle tabId stabili come t1, etichette opzionali e il targetId grezzo. Gli agenti dovrebbero riutilizzare suggestedTargetId; gli id grezzi restano disponibili per debug e compatibilità.

​

Selezione del browser

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

• macOS: controlla /Applications e ~/Applications.
• Linux: controlla le posizioni comuni di Chrome/Brave/Edge/Chromium sotto /usr/bin, /snap/bin, /opt/google, /opt/brave.com, /usr/lib/chromium e /usr/lib/chromium-browser, più Chromium gestito da Playwright sotto PLAYWRIGHT_BROWSERS_PATH o ~/.cache/ms-playwright.
• Windows: controlla le posizioni di installazione comuni.

​

API di controllo (facoltativa)

​

Risoluzione dei problemi

​

Errore di avvio CDP rispetto a blocco SSRF di navigazione

• Errore di avvio o di prontezza CDP significa che OpenClaw non può confermare che il piano di controllo del browser sia integro.
• Blocco SSRF di navigazione significa che il piano di controllo del browser è integro, ma un target di navigazione pagina viene rifiutato dalla policy.

• Errore di avvio o di prontezza CDP:
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
  • Port <port> is in use for profile "<name>" but not by openclaw quando è configurato un servizio CDP esterno loopback senza attachOnly: true
• Blocco SSRF di navigazione:
  • i flussi open, navigate, snapshot o di apertura scheda falliscono con un errore di policy browser/rete mentre start e tabs continuano a funzionare

openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com

• Se start fallisce con not reachable after start, risolvi prima la prontezza CDP.
• Se start riesce ma tabs fallisce, il piano di controllo non è ancora integro. Trattalo come un problema di raggiungibilità CDP, non come un problema di navigazione pagina.
• Se start e tabs riescono ma open o navigate fallisce, il piano di controllo del browser è attivo e l’errore è nella policy di navigazione o nella pagina target.
• Se start, tabs e open riescono tutti, il percorso di controllo di base del browser gestito è integro.

• La configurazione del browser usa per impostazione predefinita un oggetto policy SSRF fail-closed anche quando non configuri browser.ssrfPolicy.
• Per il profilo gestito locale loopback openclaw, i controlli di integrità CDP saltano intenzionalmente l’applicazione della raggiungibilità SSRF del browser per il piano di controllo locale di OpenClaw.
• La protezione della navigazione è separata. Un risultato start o tabs riuscito non significa che un target successivo di open o navigate sia consentito.

• Non allentare per impostazione predefinita il criterio SSRF del browser.
• Preferisci eccezioni di host ristrette come hostnameAllowlist o allowedHostnames rispetto a un accesso ampio alla rete privata.
• Usa dangerouslyAllowPrivateNetwork: true solo in ambienti intenzionalmente attendibili in cui l’accesso del browser alla rete privata è richiesto e revisionato.

​

Strumenti dell’agente + funzionamento del controllo

• browser - doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

• browser snapshot restituisce un albero dell’interfaccia utente stabile (IA o ARIA).
• browser act usa gli ID ref dello snapshot per fare clic/digitare/trascinare/selezionare.
• browser screenshot cattura i pixel (pagina intera, elemento o riferimenti etichettati).
• browser doctor controlla la preparazione di Gateway, Plugin, profilo, browser e scheda.
• browser accetta:
  • profile per scegliere un profilo browser denominato (openclaw, chrome o CDP remoto).
  • target (sandbox | host | node) per selezionare dove risiede il browser.
  • Nelle sessioni in sandbox, target: "host" richiede agents.defaults.sandbox.browser.allowHostControl=true.
  • Se target è omesso: le sessioni in sandbox usano per impostazione predefinita sandbox, le sessioni non in sandbox usano per impostazione predefinita host.
  • Se è connesso un nodo in grado di usare il browser, lo strumento può instradare automaticamente verso di esso a meno che tu non fissi target="host" o target="node".

​

Correlati

• Panoramica degli strumenti - tutti gli strumenti disponibili per l’agente
• Sandboxing - controllo del browser in ambienti in sandbox
• Sicurezza - rischi del controllo del browser e hardening