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 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.

1. Imposta compat.requiresStringContent: true per backend Chat Completions che accettano solo stringhe.
2. Imposta compat.strictMessageKeys: true per backend Chat Completions rigorosi che accettano solo role e content in ogni messaggio.
3. Imposta compat.supportsTools: false per modelli/backend che non riescono a gestire in modo affidabile la superficie degli schemi strumenti di OpenClaw.
4. 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.
5. 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.

• 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.

• 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.

• 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.*.

• .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 ***.

1. Esegui openclaw doctor --fix per lasciare che doctor ripari una configurazione con prefissi/clobbered o ripristini l'ultima versione 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 l'intera configurazione JSON5, 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 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.

• 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.

• 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.

• 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.

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw 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.

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw 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.

openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw 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.