Risoluzione dei problemi

Questa pagina è il runbook approfondito. Inizia da /help/troubleshooting se vuoi prima il flusso di triage rapido.

Scala dei comandi

Esegui prima questi, in questo ordine:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Segnali attesi di stato sano:

openclaw gateway status mostra Runtime: running, Connectivity probe: ok e una riga Capability: ....
openclaw doctor non segnala problemi bloccanti di configurazione/servizio.
openclaw channels status --probe mostra lo stato live del trasporto per account e, dove supportato, risultati di probe/audit come works o audit ok.

Installazioni split brain e guardia per configurazioni più nuove

Usa questa se un servizio Gateway si arresta inaspettatamente dopo un aggiornamento, oppure se i log mostrano che un binario openclaw è più vecchio della versione che ha scritto per ultima openclaw.json. OpenClaw contrassegna le scritture di configurazione con meta.lastTouchedVersion. I comandi in sola lettura possono ancora ispezionare una configurazione scritta da un OpenClaw più nuovo, ma le mutazioni di processo e servizio rifiutano di continuare da un binario più vecchio. Le azioni bloccate includono avvio, arresto, riavvio e disinstallazione del servizio Gateway, reinstallazione forzata del servizio, avvio del Gateway in modalità servizio e pulizia della porta con gateway --force.

which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion

Correggi PATH

Correggi PATH in modo che openclaw punti all’installazione più nuova, poi riesegui l’azione.

Reinstalla il servizio Gateway

Reinstalla il servizio Gateway previsto dall’installazione più nuova:

openclaw gateway install --force
openclaw gateway restart

Rimuovi wrapper obsoleti

Rimuovi il pacchetto di sistema obsoleto o le vecchie voci wrapper che puntano ancora a un vecchio binario openclaw.

Solo per downgrade intenzionale o ripristino di emergenza, imposta OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1 per il singolo comando. Lascialo non impostato per il funzionamento normale.

Symlink Skills ignorato come escape di percorso

Usa questa quando i log includono:

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

OpenClaw tratta ogni radice di Skills come un perimetro di contenimento. Un symlink sotto ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills o ~/.openclaw/skills viene ignorato quando il suo target reale si risolve fuori da quella radice, a meno che il target non sia esplicitamente considerato attendibile. Ispeziona il link:

ls -l ~/.agents/skills/<name>
realpath ~/.agents/skills/<name>
openclaw config get skills.load

Se il target è intenzionale, configura sia la radice Skills diretta sia il target symlink consentito:

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

Poi avvia una nuova sessione o attendi che il watcher delle Skills si aggiorni. Riavvia il Gateway se il processo in esecuzione precede la modifica della configurazione. Non usare target ampi come ~, / o un’intera cartella di progetto sincronizzata. Mantieni allowSymlinkTargets limitato alla radice Skills reale che contiene directory SKILL.md attendibili. Correlati:

Anthropic 429: utilizzo extra richiesto per contesto lungo

Usa questa quando log/errori includono: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

Cerca:

Il modello Anthropic Opus/Sonnet selezionato ha params.context1m: true.
La credenziale Anthropic corrente non è idonea all’uso del contesto lungo.
Le richieste falliscono solo su sessioni/esecuzioni di modelli lunghe che richiedono il percorso beta 1M.

Opzioni di correzione:

Disabilita context1m

Disabilita context1m per quel modello per tornare alla finestra di contesto normale.

Usa una credenziale idonea

Usa una credenziale Anthropic idonea alle richieste con contesto lungo, oppure passa a una chiave API Anthropic.

Configura modelli di fallback

Configura modelli di fallback in modo che le esecuzioni continuino quando le richieste Anthropic con contesto lungo vengono rifiutate.

Correlati:

Il backend locale compatibile con OpenAI supera i probe diretti ma le esecuzioni agent falliscono

Usa questa quando:

curl ... /v1/models funziona
le piccole chiamate dirette a /v1/chat/completions funzionano
le esecuzioni di modelli OpenClaw falliscono solo nei turni agent normali

curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow

Cerca:

le piccole chiamate dirette riescono, ma le esecuzioni OpenClaw falliscono solo con prompt più grandi
errori model_not_found o 404 anche se /v1/chat/completions diretto funziona con lo stesso id modello semplice
errori del backend su messages[].content che si aspetta una stringa
avvisi intermittenti incomplete turn detected ... stopReason=stop payloads=0 con un backend locale compatibile con OpenAI
crash del backend che compaiono solo con conteggi di prompt-token più grandi o prompt completi del runtime agent

Firme comuni

model_not_found con un server locale in stile MLX/vLLM → verifica che baseUrl includa /v1, che api sia "openai-completions" per backend /v1/chat/completions e che models.providers.<provider>.models[].id sia l’id semplice locale del provider. Selezionalo una volta con il prefisso del provider, ad esempio mlx/mlx-community/Qwen3-30B-A3B-6bit; mantieni la voce di catalogo come mlx-community/Qwen3-30B-A3B-6bit.
messages[...].content: invalid type: sequence, expected a string → il backend rifiuta parti di contenuto strutturato di Chat Completions. Correzione: imposta models.providers.<provider>.models[].compat.requiresStringContent: true.
validation.keys o chiavi di messaggio consentite come ["role","content"] → il backend rifiuta metadati di replay in stile OpenAI sui messaggi Chat Completions. Correzione: imposta models.providers.<provider>.models[].compat.strictMessageKeys: true.
incomplete turn detected ... stopReason=stop payloads=0 → il backend ha completato la richiesta Chat Completions ma non ha restituito testo dell’assistente visibile all’utente per quel turno. OpenClaw ritenta una volta i turni vuoti compatibili con OpenAI e sicuri per il replay; i fallimenti persistenti di solito indicano che il backend sta emettendo contenuto vuoto/non testuale o sopprimendo il testo della risposta finale.
le piccole richieste dirette riescono, ma le esecuzioni agent OpenClaw falliscono con crash del backend/modello (per esempio Gemma su alcune build inferrs) → il trasporto OpenClaw è probabilmente già corretto; il backend sta fallendo sulla forma più grande del prompt di runtime agent.
i fallimenti si riducono dopo aver disabilitato gli strumenti ma non scompaiono → gli schemi degli strumenti erano parte della pressione, ma il problema restante è ancora la capacità del modello/server a monte o un bug del backend.

Opzioni di correzione

Imposta compat.requiresStringContent: true per backend Chat Completions che accettano solo stringhe.
Imposta compat.strictMessageKeys: true per backend Chat Completions rigorosi che accettano solo role e content in ogni messaggio.
Imposta compat.supportsTools: false per modelli/backend che non riescono a gestire in modo affidabile la superficie degli schemi strumenti di OpenClaw.
Riduci la pressione del prompt dove possibile: bootstrap del workspace più piccolo, cronologia sessione più breve, modello locale più leggero o un backend con supporto più robusto per contesti lunghi.
Se le piccole richieste dirette continuano a riuscire mentre i turni agent OpenClaw continuano a crashare dentro il backend, trattalo come una limitazione del server/modello a monte e apri lì una riproduzione con la forma del payload accettato.

Correlati:

Nessuna risposta

Se i canali sono attivi ma nulla risponde, controlla routing e policy prima di riconnettere qualsiasi cosa.

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

Cerca:

Pairing in sospeso per i mittenti DM.
Gating delle menzioni nei gruppi (requireMention, mentionPatterns).
Disallineamenti dell’allowlist di canale/gruppo.

Firme comuni:

drop guild message (mention required → messaggio di gruppo ignorato fino alla menzione.
pairing request → il mittente richiede approvazione.
blocked / allowlist → il mittente/canale è stato filtrato dalla policy.

Correlati:

Connettività dell’UI di controllo della dashboard

Quando la dashboard/UI di controllo non si connette, valida URL, modalità di autenticazione e presupposti di contesto sicuro.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

Cerca:

URL di probe e URL della dashboard corretti.
Disallineamento modalità/token di autenticazione tra client e Gateway.
Uso di HTTP dove è richiesta l’identità del dispositivo.

Firme di connessione / autenticazione

device identity required → contesto non sicuro o autenticazione dispositivo mancante.
origin not allowed → l’Origin del browser non è in gateway.controlUi.allowedOrigins (oppure ti stai connettendo da un’origine browser non loopback senza un’allowlist esplicita).
device nonce required / device nonce mismatch → il client non completa il flusso di autenticazione dispositivo basato su challenge (connect.challenge + device.nonce).
device signature invalid / device signature expired → il client ha firmato il payload sbagliato (o un timestamp obsoleto) per l’handshake corrente.
AUTH_TOKEN_MISMATCH con canRetryWithDeviceToken=true → il client può eseguire un solo tentativo attendibile con token dispositivo in cache.
Quel ritentativo con token in cache riutilizza l’insieme di ambiti in cache memorizzato con il token dispositivo associato. I chiamanti con deviceToken esplicito / scopes espliciti mantengono invece il proprio insieme di ambiti richiesto.
AUTH_SCOPE_MISMATCH → il token dispositivo è stato riconosciuto, ma i suoi ambiti approvati non coprono questa richiesta di connessione; riassocia o approva il contratto di ambiti richiesto invece di ruotare un token Gateway condiviso.
Fuori da quel percorso di ritentativo, la precedenza dell’autenticazione di connessione è prima token/password condivisi espliciti, poi deviceToken esplicito, poi token dispositivo memorizzato, poi token bootstrap.
Nel percorso async della UI di controllo Tailscale Serve, i tentativi falliti per lo stesso {scope, ip} vengono serializzati prima che il limiter registri il fallimento. Due ritentativi concorrenti errati dallo stesso client possono quindi mostrare retry later al secondo tentativo invece di due semplici mismatch.
too many failed authentication attempts (retry later) da un client loopback con origine browser → fallimenti ripetuti dalla stessa Origin normalizzata vengono bloccati temporaneamente; un’altra origine localhost usa un bucket separato.
unauthorized ripetuto dopo quel ritentativo → deriva tra token condiviso/token dispositivo; aggiorna la configurazione del token e riapprova/ruota il token dispositivo se necessario.
gateway connect failed: → target host/porta/url errato.

Mappa rapida dei codici di dettaglio autenticazione

Usa error.details.code dalla risposta connect fallita per scegliere l’azione successiva:

Codice dettaglio	Significato	Azione consigliata
`AUTH_TOKEN_MISSING`	Il client non ha inviato un token condiviso richiesto.	Incolla/imposta il token nel client e riprova. Per i percorsi della dashboard: `openclaw config get gateway.auth.token`, quindi incollalo nelle impostazioni della Control UI.
`AUTH_TOKEN_MISMATCH`	Il token condiviso non corrispondeva al token di autenticazione del gateway.	Se `canRetryWithDeviceToken=true`, consenti un solo nuovo tentativo attendibile. I tentativi con token in cache riutilizzano gli ambiti approvati memorizzati; i chiamanti espliciti `deviceToken` / `scopes` mantengono gli ambiti richiesti. Se l’errore persiste, esegui la checklist di recupero della deriva del token.
`AUTH_DEVICE_TOKEN_MISMATCH`	Il token per dispositivo memorizzato nella cache è obsoleto o revocato.	Ruota/riapprova il token del dispositivo usando la CLI dei dispositivi, quindi riconnettiti.
`AUTH_SCOPE_MISMATCH`	Il token del dispositivo è valido, ma il suo ruolo/i suoi ambiti approvati non coprono questa richiesta di connessione.	Associa nuovamente il dispositivo o approva il contratto di ambito richiesto; non trattarlo come deriva del token condiviso.
`PAIRING_REQUIRED`	L’identità del dispositivo richiede approvazione. Controlla `error.details.reason` per `not-paired`, `scope-upgrade`, `role-upgrade` o `metadata-upgrade`, e usa `requestId` / `remediationHint` quando presenti.	Approva la richiesta in sospeso: `openclaw devices list`, quindi `openclaw devices approve <requestId>`. Gli upgrade di ambito/ruolo usano lo stesso flusso dopo aver esaminato l’accesso richiesto.

Gli RPC backend loopback diretti autenticati con il token/password condiviso del gateway non dovrebbero dipendere dalla baseline degli ambiti dei dispositivi associati della CLI. Se subagent o altre chiamate interne continuano a fallire con scope-upgrade, verifica che il chiamante usi client.id: "gateway-client" e client.mode: "backend" e che non forzi un deviceIdentity esplicito o un token dispositivo.

Controllo della migrazione dell’autenticazione dispositivo v2:

openclaw --version
openclaw doctor
openclaw gateway status

Se i log mostrano errori di nonce/firma, aggiorna il client di connessione e verificalo:

Attendi connect.challenge

Il client attende il connect.challenge emesso dal gateway.

Firma il payload

Il client firma il payload vincolato alla challenge.

Invia il nonce del dispositivo

Il client invia connect.params.device.nonce con lo stesso nonce della challenge.

Se openclaw devices rotate / revoke / remove viene negato inaspettatamente:

le sessioni con token di dispositivo associato possono gestire solo il proprio dispositivo, a meno che il chiamante non abbia anche operator.admin
openclaw devices rotate --scope ... può richiedere solo ambiti operatore già posseduti dalla sessione chiamante

Correlati:

Configurazione (modalità di autenticazione del gateway)
Control UI
Dispositivi
Accesso remoto
Autenticazione proxy attendibile

Servizio Gateway non in esecuzione

Usa questa se il servizio è installato ma il processo non rimane attivo.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # also scan system-level services

Cerca:

Runtime: stopped con suggerimenti di uscita.
Mancata corrispondenza della configurazione del servizio (Config (cli) rispetto a Config (service)).
Conflitti di porta/listener.
Installazioni launchd/systemd/schtasks extra quando viene usato --deep.
Suggerimenti di pulizia Other gateway-like services detected (best effort).

Firme comuni

Gateway start blocked: set gateway.mode=local o existing config is missing gateway.mode → la modalità gateway locale non è abilitata, oppure il file di configurazione è stato sovrascritto e ha perso gateway.mode. Correzione: imposta gateway.mode="local" nella configurazione, oppure riesegui openclaw onboard --mode local / openclaw setup per ristampare la configurazione prevista in modalità locale. Se esegui OpenClaw tramite Podman, il percorso di configurazione predefinito è ~/.openclaw/openclaw.json.
refusing to bind gateway ... without auth → bind non-loopback senza un percorso di autenticazione gateway valido (token/password, oppure trusted-proxy dove configurato).
another gateway instance is already listening / EADDRINUSE → conflitto di porta.
Other gateway-like services detected (best effort) → esistono unità launchd/systemd/schtasks obsolete o parallele. La maggior parte delle configurazioni dovrebbe mantenere un solo gateway per macchina; se ne serve più di uno, isola porte + configurazione/stato/workspace. Vedi /gateway#multiple-gateways-same-host.
System-level OpenClaw gateway service detected da doctor → esiste un’unità systemd di sistema mentre il servizio a livello utente manca. Rimuovi o disabilita il duplicato prima di consentire a doctor di installare un servizio utente, oppure imposta OPENCLAW_SERVICE_REPAIR_POLICY=external se l’unità di sistema è il supervisore previsto.
Gateway service port does not match current gateway config → il supervisore installato impone ancora il vecchio --port. Esegui openclaw doctor --fix o openclaw gateway install --force, quindi riavvia il servizio gateway.

Correlati:

Gateway ha rifiutato una configurazione non valida

Usa questa se l’avvio del Gateway fallisce con Invalid config o i log del ricaricamento a caldo indicano che ha ignorato una modifica non valida.

openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor

Cerca:

Invalid config at ...
config reload skipped (invalid config): ...
Config write rejected: ...
Un file openclaw.json.rejected.* con timestamp accanto alla configurazione attiva
Un file openclaw.json.clobbered.* con timestamp se doctor --fix ha riparato una modifica diretta non valida

Cosa è successo

La configurazione non è stata convalidata durante l’avvio, il ricaricamento a caldo o una scrittura di proprietà di OpenClaw.
L’avvio del Gateway fallisce in modo chiuso invece di riscrivere openclaw.json.
Il ricaricamento a caldo ignora le modifiche esterne non valide e mantiene attiva la configurazione runtime corrente.
Le scritture di proprietà di OpenClaw rifiutano payload non validi/distruttivi prima del commit e salvano .rejected.*.
openclaw doctor --fix è responsabile della riparazione. Può rimuovere prefissi non JSON o ripristinare l’ultima copia valida nota, preservando il payload rifiutato come .clobbered.*.

Ispeziona e ripara

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

Firme comuni

.clobbered.* esiste → doctor ha preservato una modifica esterna non valida mentre riparava la configurazione attiva.
.rejected.* esiste → una scrittura di configurazione di proprietà di OpenClaw ha fallito i controlli di schema o clobber prima del commit.
Config write rejected: → la scrittura ha tentato di rimuovere la forma richiesta, ridurre drasticamente il file o persistere una configurazione non valida.
config reload skipped (invalid config): → una modifica diretta ha fallito la validazione ed è stata ignorata dal Gateway in esecuzione.
Invalid config at ... → l’avvio è fallito prima che i servizi Gateway si avviassero.
missing-meta-vs-last-good, gateway-mode-missing-vs-last-good o size-drop-vs-last-good:* → una scrittura di proprietà di OpenClaw è stata rifiutata perché ha perso campi o dimensione rispetto al backup dell’ultima versione valida nota.
Config last-known-good promotion skipped → il candidato conteneva segnaposto di segreti redatti, come ***.

Opzioni di correzione

Esegui openclaw doctor --fix per lasciare che doctor ripari una configurazione con prefissi/clobbered o ripristini l’ultima versione valida nota.
Copia solo le chiavi previste da .clobbered.* o .rejected.*, quindi applicale con openclaw config set o config.patch.
Esegui openclaw config validate prima di riavviare.
Se modifichi a mano, mantieni l’intera configurazione JSON5, non solo l’oggetto parziale che volevi cambiare.

Correlati:

Avvisi del probe Gateway

Usa questa se openclaw gateway probe raggiunge qualcosa, ma stampa comunque un blocco di avviso.

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

Cerca:

warnings[].code e primaryTargetId nell’output JSON.
Se l’avviso riguarda fallback SSH, gateway multipli, ambiti mancanti o riferimenti di autenticazione non risolti.

Firme comuni:

SSH tunnel failed to start; falling back to direct probes. → configurazione SSH non riuscita, ma il comando ha comunque provato i target diretti configurati/loopback.
multiple reachable gateways detected → ha risposto più di un target. Di solito significa una configurazione multi-gateway intenzionale o listener obsoleti/duplicati.
Read-probe diagnostics are limited by gateway scopes (missing operator.read) → la connessione ha funzionato, ma l’RPC di dettaglio è limitato dagli ambiti; associa l’identità del dispositivo o usa credenziali con operator.read.
Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → la connessione ha funzionato, ma l’intero set di RPC diagnostici è scaduto o non è riuscito. Trattalo come un Gateway raggiungibile con diagnostica degradata; confronta connect.ok e connect.rpcOk nell’output --json.
Capability: pairing-pending o gateway closed (1008): pairing required → il gateway ha risposto, ma questo client richiede ancora associazione/approvazione prima del normale accesso operatore.
testo di avviso SecretRef gateway.auth.* / gateway.remote.* non risolto → il materiale di autenticazione non era disponibile in questo percorso di comando per il target non riuscito.

Correlati:

Canale connesso, messaggi non in transito

Se lo stato del canale è connesso ma il flusso dei messaggi è fermo, concentrati su criteri, autorizzazioni e regole di recapito specifiche del canale.

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

Verifica:

Criterio DM (pairing, allowlist, open, disabled).
Allowlist dei gruppi e requisiti di menzione.
Autorizzazioni/scope API del canale mancanti.

Indicatori comuni:

mention required → messaggio ignorato dal criterio di menzione del gruppo.
pairing / tracce di approvazione in sospeso → il mittente non è approvato.
missing_scope, not_in_channel, Forbidden, 401/403 → problema di autenticazione/autorizzazioni del canale.

Correlati:

Recapito di Cron e Heartbeat

Se Cron o Heartbeat non è stato eseguito o non ha recapitato, verifica prima lo stato dello scheduler, poi la destinazione di recapito.

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

Verifica:

Cron abilitato e prossima riattivazione presente.
Stato della cronologia di esecuzione del job (ok, skipped, error).
Motivi di salto di Heartbeat (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due).

Indicatori comuni

cron: scheduler disabled; jobs will not run automatically → Cron disabilitato.
cron: timer tick failed → tick dello scheduler non riuscito; controlla errori di file/log/runtime.
heartbeat skipped con reason=quiet-hours → fuori dalla finestra di ore attive.
heartbeat skipped con reason=empty-heartbeat-file → HEARTBEAT.md esiste ma contiene solo righe vuote / intestazioni markdown, quindi OpenClaw salta la chiamata al modello.
heartbeat skipped con reason=no-tasks-due → HEARTBEAT.md contiene un blocco tasks:, ma nessuna attività è in scadenza in questo tick.
heartbeat: unknown accountId → ID account non valido per la destinazione di recapito di Heartbeat.
heartbeat skipped con reason=dm-blocked → la destinazione Heartbeat risolta è di tipo DM mentre agents.defaults.heartbeat.directPolicy (o l’override per agente) è impostato su block.

Correlati:

Node associato, strumento non riuscito

Se un Node è associato ma gli strumenti non funzionano, isola foreground, autorizzazioni e stato di approvazione.

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

Verifica:

Node online con le capacità previste.
Concessioni di autorizzazioni del sistema operativo per fotocamera/microfono/posizione/schermo.
Approvazioni exec e stato dell’allowlist.

Indicatori comuni:

NODE_BACKGROUND_UNAVAILABLE → l’app del Node deve essere in foreground.
*_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → autorizzazione del sistema operativo mancante.
SYSTEM_RUN_DENIED: approval required → approvazione exec in sospeso.
SYSTEM_RUN_DENIED: allowlist miss → comando bloccato dall’allowlist.

Correlati:

Strumento browser non riuscito

Usa questa se le azioni dello strumento browser falliscono anche se il Gateway stesso è integro.

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

Verifica:

Se plugins.allow è impostato e include browser.
Percorso valido dell’eseguibile del browser.
Raggiungibilità del profilo CDP.
Disponibilità di Chrome locale per i profili existing-session / user.

Indicatori di Plugin / eseguibile

unknown command "browser" o unknown command 'browser' → il Plugin browser incluso è escluso da plugins.allow.
strumento browser mancante / non disponibile mentre browser.enabled=true → plugins.allow esclude browser, quindi il Plugin non è mai stato caricato.
Failed to start Chrome CDP on port → avvio del processo browser non riuscito.
browser.executablePath not found → il percorso configurato non è valido.
browser.cdpUrl must be http(s) or ws(s) → l’URL CDP configurato usa uno schema non supportato come file: o ftp:.
browser.cdpUrl has invalid port → l’URL CDP configurato ha una porta errata o fuori intervallo.
Playwright is not available in this gateway build; '<feature>' is unsupported. → l’installazione corrente del Gateway non include la dipendenza runtime core del browser; reinstalla o aggiorna OpenClaw, quindi riavvia il Gateway. Gli snapshot ARIA e gli screenshot base delle pagine possono comunque funzionare, ma navigazione, snapshot AI, screenshot di elementi con selettore CSS ed esportazione PDF restano non disponibili.

Indicatori Chrome MCP / existing-session

Could not find DevToolsActivePort for chrome → Chrome MCP existing-session non è ancora riuscito ad agganciarsi alla directory dati del browser selezionata. Apri la pagina di ispezione del browser, abilita il debug remoto, mantieni il browser aperto, approva il primo prompt di aggancio, quindi riprova. Se lo stato di accesso non è richiesto, preferisci il profilo gestito openclaw.
No Chrome tabs found for profile="user" → il profilo di aggancio Chrome MCP non ha schede Chrome locali aperte.
Remote CDP for profile "<name>" is not reachable → l’endpoint CDP remoto configurato non è raggiungibile dall’host del Gateway.
Browser attachOnly is enabled ... not reachable o Browser attachOnly is enabled and CDP websocket ... is not reachable → il profilo solo aggancio non ha target raggiungibili, oppure l’endpoint HTTP ha risposto ma il WebSocket CDP non ha comunque potuto essere aperto.

Indicatori di elemento / screenshot / upload

fullPage is not supported for element screenshots → la richiesta di screenshot ha combinato --full-page con --ref o --element.
element screenshots are not supported for existing-session profiles; use ref from snapshot. → le chiamate screenshot Chrome MCP / existing-session devono usare la cattura della pagina o un --ref da snapshot, non CSS --element.
existing-session file uploads do not support element selectors; use ref/inputRef. → gli hook di upload Chrome MCP richiedono riferimenti snapshot, non selettori CSS.
existing-session file uploads currently support one file at a time. → invia un upload per chiamata sui profili Chrome MCP.
existing-session dialog handling does not support timeoutMs. → gli hook dialog sui profili Chrome MCP non supportano override del timeout.
existing-session type does not support timeoutMs overrides. → ometti timeoutMs per act:type su profile="user" / profili Chrome MCP existing-session, oppure usa un profilo browser gestito/CDP quando è richiesto un timeout personalizzato.
existing-session evaluate does not support timeoutMs overrides. → ometti timeoutMs per act:evaluate su profile="user" / profili Chrome MCP existing-session, oppure usa un profilo browser gestito/CDP quando è richiesto un timeout personalizzato.
response body is not supported for existing-session profiles yet. → responsebody richiede ancora un browser gestito o un profilo CDP raw.
override obsoleti di viewport / modalità scura / locale / offline sui profili solo aggancio o CDP remoto → esegui openclaw browser stop --browser-profile <name> per chiudere la sessione di controllo attiva e rilasciare lo stato di emulazione Playwright/CDP senza riavviare l’intero Gateway.

Correlati:

Se hai aggiornato e qualcosa si è rotto all’improvviso

La maggior parte dei guasti successivi a un aggiornamento è dovuta a deriva della configurazione o a default più rigorosi ora applicati.

1. Il comportamento di autenticazione e override URL è cambiato

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

Cosa controllare:

Se gateway.mode=remote, le chiamate CLI potrebbero puntare al remoto mentre il servizio locale è a posto.
Le chiamate esplicite --url non ricadono sulle credenziali memorizzate.

Indicatori comuni:

gateway connect failed: → destinazione URL errata.
unauthorized → endpoint raggiungibile ma autenticazione errata.

2. Le protezioni di bind e autenticazione sono più rigorose

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

Cosa controllare:

I bind non-loopback (lan, tailnet, custom) richiedono un percorso di autenticazione Gateway valido: autenticazione con token/password condivisi, oppure una distribuzione trusted-proxy non-loopback configurata correttamente.
Vecchie chiavi come gateway.token non sostituiscono gateway.auth.token.

Indicatori comuni:

refusing to bind gateway ... without auth → bind non-loopback senza un percorso di autenticazione Gateway valido.
Connectivity probe: failed mentre il runtime è in esecuzione → Gateway attivo ma inaccessibile con autenticazione/URL correnti.

3. Lo stato di associazione e identità dispositivo è cambiato

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

Cosa controllare:

Approvazioni dispositivo in sospeso per dashboard/Node.
Approvazioni di associazione DM in sospeso dopo modifiche di criterio o identità.

Indicatori comuni:

device identity required → autenticazione dispositivo non soddisfatta.
pairing required → mittente/dispositivo deve essere approvato.

Se la configurazione del servizio e il runtime sono ancora in disaccordo dopo i controlli, reinstalla i metadati del servizio dalla stessa directory di profilo/stato:

openclaw gateway install --force
openclaw gateway restart

Correlati:

Gateway

Remote access

Security

Nodes and media

Web interfaces

Risoluzione dei problemi

Scala dei comandi

Installazioni split brain e guardia per configurazioni più nuove

Symlink Skills ignorato come escape di percorso

Anthropic 429: utilizzo extra richiesto per contesto lungo

Il backend locale compatibile con OpenAI supera i probe diretti ma le esecuzioni agent falliscono

Nessuna risposta

Connettività dell’UI di controllo della dashboard

Mappa rapida dei codici di dettaglio autenticazione

Servizio Gateway non in esecuzione

Gateway ha rifiutato una configurazione non valida

Avvisi del probe Gateway

Canale connesso, messaggi non in transito

Recapito di Cron e Heartbeat

Node associato, strumento non riuscito

Strumento browser non riuscito

Se hai aggiornato e qualcosa si è rotto all’improvviso

Correlati

Gateway

Remote access

Security

Nodes and media

Web interfaces

Documentation Index

​Scala dei comandi

​Installazioni split brain e guardia per configurazioni più nuove

​Symlink Skills ignorato come escape di percorso

​Anthropic 429: utilizzo extra richiesto per contesto lungo

​Il backend locale compatibile con OpenAI supera i probe diretti ma le esecuzioni agent falliscono

​Nessuna risposta

​Connettività dell’UI di controllo della dashboard

​Mappa rapida dei codici di dettaglio autenticazione

​Servizio Gateway non in esecuzione

​Gateway ha rifiutato una configurazione non valida

​Avvisi del probe Gateway

​Canale connesso, messaggi non in transito

​Recapito di Cron e Heartbeat

​Node associato, strumento non riuscito

​Strumento browser non riuscito

​Se hai aggiornato e qualcosa si è rotto all’improvviso

​Correlati

Scala dei comandi

Installazioni split brain e guardia per configurazioni più nuove

Symlink Skills ignorato come escape di percorso

Anthropic 429: utilizzo extra richiesto per contesto lungo

Il backend locale compatibile con OpenAI supera i probe diretti ma le esecuzioni agent falliscono

Nessuna risposta

Connettività dell’UI di controllo della dashboard

Mappa rapida dei codici di dettaglio autenticazione

Servizio Gateway non in esecuzione

Gateway ha rifiutato una configurazione non valida

Avvisi del probe Gateway

Canale connesso, messaggi non in transito

Recapito di Cron e Heartbeat

Node associato, strumento non riuscito

Strumento browser non riuscito

Se hai aggiornato e qualcosa si è rotto all’improvviso

Correlati