Risoluzione dei problemi

• 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 locale del provider semplice. Selezionalo una volta con il prefisso del provider, per 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 Chat Completions strutturate. Correzione: imposta models.providers.<provider>.models[].compat.requiresStringContent: true.
• incomplete turn detected ... stopReason=stop payloads=0 → il backend ha completato la richiesta Chat Completions ma non ha restituito testo assistente visibile all'utente per quel turno. OpenClaw ritenta una volta i turni vuoti compatibili con OpenAI sicuri da riprodurre; errori persistenti di solito indicano che il backend sta emettendo contenuto vuoto/non testuale o sta sopprimendo il testo della risposta finale.
• piccole richieste dirette riescono, ma le esecuzioni agente OpenClaw falliscono con arresti anomali backend/modello (per esempio Gemma su alcune build inferrs) → il trasporto OpenClaw probabilmente è già corretto; il backend fallisce sulla forma più grande del prompt runtime agente.
• gli errori diminuiscono dopo aver disabilitato gli strumenti ma non scompaiono → gli schemi degli strumenti facevano parte della pressione, ma il problema restante è ancora la capacità del modello/server upstream o un bug del backend.

1. Imposta compat.requiresStringContent: true per backend Chat Completions che accettano solo stringhe.
2. Imposta compat.supportsTools: false per modelli/backend che non riescono a gestire in modo affidabile la superficie degli schemi strumenti di OpenClaw.
3. Riduci la pressione del prompt dove possibile: bootstrap workspace più piccolo, cronologia sessione più breve, modello locale più leggero o un backend con supporto al contesto lungo più solido.
4. Se le piccole richieste dirette continuano a passare mentre i turni agente OpenClaw continuano a causare arresti anomali nel backend, trattalo come una limitazione del server/modello upstream e apri una segnalazione di riproduzione lì con la forma del payload accettata.

• device identity required → contesto non sicuro o auth dispositivo mancante.
• origin not allowed → 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 sta completando il flusso auth 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 retry attendibile con il token dispositivo memorizzato nella cache.
• Quel retry con token in cache riutilizza l'insieme di scope in cache memorizzato con il token dispositivo associato. I chiamanti con deviceToken esplicito / scopes espliciti mantengono invece l'insieme di scope richiesto.
• Al di fuori di quel percorso di retry, la precedenza auth di connessione è prima token condiviso/password espliciti, poi deviceToken esplicito, poi token dispositivo memorizzato, poi token bootstrap.
• Sul percorso asincrono Tailscale Serve Control UI, i tentativi falliti per lo stesso {scope, ip} vengono serializzati prima che il limiter registri l'errore. Due retry 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 browser-origin loopback → errori ripetuti dalla stessa Origin normalizzata vengono bloccati temporaneamente; un'altra origine localhost usa un bucket separato.
• unauthorized ripetuto dopo quel retry → deriva tra token condiviso/token dispositivo; aggiorna la configurazione del token e riapprova/ruota il token dispositivo se necessario.
• gateway connect failed: → host/porta/url target errato.

• 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 riapplicare la configurazione prevista per la modalità locale. Se stai eseguendo 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, o 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 davvero 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à di sistema systemd mentre manca il servizio a livello utente. 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 vincola ancora il vecchio --port. Esegui openclaw doctor --fix o openclaw gateway install --force, quindi riavvia il servizio Gateway.

• La configurazione non è stata validata durante l'avvio, l'hot reload o una scrittura gestita da OpenClaw.
• L'avvio del Gateway fallisce in modo chiuso invece di riscrivere openclaw.json.
• L'hot reload salta le modifiche esterne non valide e mantiene attiva la configurazione di runtime corrente.
• Le scritture gestite da OpenClaw rifiutano payload non validi/distruttivi prima del commit e salvano .rejected.*.
• openclaw doctor --fix gestisce la riparazione. Può rimuovere prefissi non JSON o ripristinare l'ultima copia valida nota preservando il payload rifiutato come .clobbered.*.

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

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

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

• 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 degli orari attivi.
• 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 dell'Heartbeat.
• heartbeat skipped con reason=dm-blocked → la destinazione dell'Heartbeat è stata risolta in una destinazione di tipo DM mentre agents.defaults.heartbeat.directPolicy (o l'override per agente) è impostato su block.

• unknown command "browser" o unknown command 'browser' → il plugin browser in bundle è 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 → il processo del browser non è riuscito ad avviarsi.
• 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 non valida 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 di base delle pagine possono ancora funzionare, ma navigazione, snapshot AI, screenshot di elementi con selettore CSS ed esportazione PDF restano non disponibili.

• 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, tieni aperto il browser, approva la prima richiesta di aggancio, quindi riprova. Se lo stato con accesso effettuato non è necessario, 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 destinazioni raggiungibili, oppure l'endpoint HTTP ha risposto ma non è stato comunque possibile aprire il WebSocket CDP.

• 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 di snapshot, non un --element CSS.
• existing-session file uploads do not support element selectors; use ref/inputRef. → gli hook di caricamento Chrome MCP richiedono riferimenti snapshot, non selettori CSS.
• existing-session file uploads currently support one file at a time. → invia un caricamento per chiamata sui profili Chrome MCP.
• existing-session dialog handling does not support timeoutMs. → gli hook di dialogo sui profili Chrome MCP non supportano override del timeout.
• existing-session type does not support timeoutMs overrides. → ometti timeoutMs per act:type su profili profile="user" / 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 profili profile="user" / 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 grezzo.
• override obsoleti di viewport / modalità scura / locale / offline su profili solo aggancio o CDP remoti → 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.

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 tuo servizio locale funziona correttamente.
• Le chiamate esplicite con --url non ripiegano sulle credenziali salvate.

Firme comuni:

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

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 local loopback (lan, tailnet, custom) richiedono un percorso di autenticazione gateway valido: autenticazione con token/password condivisi, oppure una distribuzione trusted-proxy non local loopback configurata correttamente.
• Le vecchie chiavi come gateway.token non sostituiscono gateway.auth.token.

Firme comuni:

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

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 abbinamento DM in sospeso dopo modifiche di criterio o identità.

Firme comuni:

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