Risoluzione dei problemi del browser

# Problema: "Failed to start Chrome CDP on port 18800"

Il server di controllo del browser di OpenClaw non riesce ad avviare Chrome/Brave/Edge/Chromium con l'errore:

{"error":"Error: Failed to start Chrome CDP on port 18800 for profile \"openclaw\"."}

# Causa principale

Su Ubuntu (e molte distribuzioni Linux), l'installazione predefinita di Chromium è un pacchetto snap. Il confinamento AppArmor di Snap interferisce con il modo in cui OpenClaw genera e monitora il processo del browser.

Il comando apt install chromium installa un pacchetto stub che reindirizza a snap:

Note, selecting 'chromium-browser' instead of 'chromium'
chromium-browser is already the newest version (2:1snap1-0ubuntu2).

Questo NON è un vero browser: è solo un wrapper.

Altri errori comuni di avvio su Linux:

• The profile appears to be in use by another Chromium process significa che Chrome ha trovato file di blocco Singleton* obsoleti nella directory del profilo gestito. OpenClaw rimuove quei blocchi e riprova una volta quando il blocco punta a un processo terminato o su un host diverso.
• Missing X server or $DISPLAY significa che è stato richiesto esplicitamente un browser visibile su un host senza una sessione desktop. Per impostazione predefinita, i profili gestiti locali ora passano alla modalità headless su Linux quando DISPLAY e WAYLAND_DISPLAY sono entrambi non impostati. Se imposti OPENCLAW_BROWSER_HEADLESS=0, browser.headless: false o browser.profiles.<name>.headless: false, rimuovi tale override con interfaccia grafica, imposta OPENCLAW_BROWSER_HEADLESS=1, avvia Xvfb, esegui openclaw browser start --headless per un avvio gestito singolo, oppure esegui OpenClaw in una vera sessione desktop.

# Soluzione 1: installare Google Chrome (consigliato)

Installa il pacchetto ufficiale Google Chrome .deb, che non è isolato da snap:

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt --fix-broken install -y  # if there are dependency errors

Poi aggiorna la configurazione di OpenClaw (~/.openclaw/openclaw.json):

{
  "browser": {
    "enabled": true,
    "executablePath": "/usr/bin/google-chrome-stable",
    "headless": true,
    "noSandbox": true
  }
}

# Soluzione 2: usare Chromium Snap in modalità solo collegamento

Se devi usare Chromium snap, configura OpenClaw per collegarsi a un browser avviato manualmente:

1. Aggiorna la configurazione:

{
  "browser": {
    "enabled": true,
    "attachOnly": true,
    "headless": true,
    "noSandbox": true
  }
}

2. Avvia Chromium manualmente:

chromium-browser --headless --no-sandbox --disable-gpu \
  --remote-debugging-port=18800 \
  --user-data-dir=$HOME/.openclaw/browser/openclaw/user-data \
  about:blank &

3. Facoltativamente, crea un servizio utente systemd per avviare automaticamente Chrome:

# ~/.config/systemd/user/openclaw-browser.service
[Unit]
Description=OpenClaw Browser (Chrome CDP)
After=network.target

[Service]
ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.openclaw/browser/openclaw/user-data about:blank
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Abilita con: systemctl --user enable --now openclaw-browser.service

# Verificare che il browser funzioni

Controlla lo stato:

curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'

Testa la navigazione:

curl -s -X POST http://127.0.0.1:18791/start
curl -s http://127.0.0.1:18791/tabs

# Riferimento di configurazione

Opzione	Descrizione	Predefinito
browser.enabled	Abilita il controllo del browser	true
browser.executablePath	Percorso di un binario browser basato su Chromium (Chrome/Brave/Edge/Chromium)	rilevato automaticamente (preferisce il browser predefinito se basato su Chromium)
browser.headless	Esegui senza GUI	false
OPENCLAW_BROWSER_HEADLESS	Override per processo della modalità headless del browser gestito locale	non impostato
browser.noSandbox	Aggiungi il flag --no-sandbox (necessario per alcune configurazioni Linux)	false
browser.attachOnly	Non avviare il browser, collegati solo a quello esistente	false
browser.cdpPort	Porta Chrome DevTools Protocol	18800
browser.localLaunchTimeoutMs	Timeout di rilevamento di Chrome gestito locale	15000
browser.localCdpReadyTimeoutMs	Timeout di prontezza CDP dopo l'avvio gestito locale	8000

Su Raspberry Pi, host VPS meno recenti o archiviazione lenta, aumenta browser.localLaunchTimeoutMs quando Chrome ha bisogno di più tempo per esporre il suo endpoint HTTP CDP. Aumenta browser.localCdpReadyTimeoutMs quando l'avvio riesce ma openclaw browser start segnala ancora not reachable after start. I valori devono essere interi positivi fino a 120000 ms; i valori di configurazione non validi vengono rifiutati.

# Problema: "No Chrome tabs found for profile="user""

Stai usando un profilo existing-session / Chrome MCP. OpenClaw riesce a vedere Chrome locale, ma non ci sono schede aperte disponibili a cui collegarsi.

Opzioni di correzione:

1. Usa il browser gestito: openclaw browser start --browser-profile openclaw (oppure imposta browser.defaultProfile: "openclaw").
2. Usa Chrome MCP: assicurati che Chrome locale sia in esecuzione con almeno una scheda aperta, poi riprova con --browser-profile user.

Note:

• user è solo per l'host. Per server Linux, container o host remoti, preferisci i profili CDP.
• I profili user / altri profili existing-session mantengono gli attuali limiti di Chrome MCP: azioni basate su ref, hook di caricamento di un singolo file, nessun override del timeout delle finestre di dialogo, nessun wait --load networkidle e nessun responsebody, esportazione PDF, intercettazione dei download o azioni batch.
• I profili locali openclaw assegnano automaticamente cdpPort/cdpUrl; impostali solo per CDP remoto.
• I profili CDP remoti accettano http://, https://, ws:// e wss://. Usa HTTP(S) per il rilevamento /json/version, oppure WS(S) quando il tuo servizio browser fornisce un URL socket DevTools diretto.

# Correlati

• Browser
• Accesso al browser
• Risoluzione dei problemi Browser WSL2