Skip to main content
Porta d’ingresso per il triage. 2 minuti per una diagnosi, quindi passa alla pagina di approfondimento.

​
Primi 60 secondi

Esegui questa sequenza nell’ordine indicato:
Output corretto, una riga per ciascun comando:
  • openclaw status mostra i canali configurati, senza errori di autenticazione.
  • openclaw status --all produce un rapporto completo e condivisibile.
  • openclaw gateway probe mostra Reachable: yes. Capability: ... è il livello di autenticazione verificato dalla sonda; Read probe: limited - missing scope: operator.read indica una diagnostica limitata, non un errore di connessione.
  • openclaw gateway status mostra Runtime: running, Connectivity probe: ok e un valore plausibile per Capability: .... Aggiungi --require-rpc per richiedere anche la verifica RPC dell’ambito di lettura.
  • openclaw doctor non segnala errori bloccanti di configurazione o del servizio.
  • openclaw channels status --probe restituisce lo stato attuale del trasporto per ciascun account (works / audit ok) quando il Gateway è raggiungibile; in caso contrario, usa riepiloghi basati soltanto sulla configurazione.
  • openclaw logs --follow mostra attività regolare, senza errori irreversibili ricorrenti.

​
L’assistente sembra limitato o privo di strumenti

Controlla il profilo degli strumenti effettivo:
Cause comuni:
  • tools.profile: "minimal" consente soltanto session_status.
  • tools.profile: "messaging" è ristretto ed è destinato agli agenti che gestiscono soltanto chat.
  • tools.profile: "coding" è il valore predefinito per le nuove configurazioni locali (attività su repository, file, shell e runtime).
  • tools.profile: "full" rimuove le restrizioni del profilo; riservalo agli agenti attendibili controllati dall’operatore.
  • Il valore agents.list[].tools per singolo agente restringe o amplia il profilo radice per uno specifico agente.
Modifica il profilo, riavvia o ricarica il Gateway, quindi ricontrolla con openclaw status --all. Tabella completa dei profili e dei gruppi: Profili degli strumenti.

​
Errore 429 di Anthropic con contesto lungo

HTTP 429: rate_limit_error: Extra usage is required for long context requests → Errore 429 di Anthropic: utilizzo aggiuntivo richiesto per il contesto lungo.

​
Il backend locale compatibile con OpenAI funziona direttamente ma non in OpenClaw

Il backend /v1 locale o self-hosted risponde alle sonde dirette /v1/chat/completions, ma non funziona con openclaw infer model run o durante i normali turni dell’agente:
  1. Se l’errore indica che messages[].content deve essere una stringa, imposta models.providers.<provider>.models[].compat.requiresStringContent: true.
  2. Se continua a non funzionare soltanto durante i turni dell’agente OpenClaw, imposta models.providers.<provider>.models[].compat.supportsTools: false e riprova.
  3. Se le piccole chiamate dirette funzionano, ma prompt OpenClaw più grandi causano l’arresto anomalo del backend, si tratta di un limite del modello o del server a monte, non di un errore di OpenClaw. Prosegui in Il backend locale compatibile con OpenAI supera le sonde dirette, ma le esecuzioni dell’agente non riescono.

​
L’installazione del Plugin non riesce perché mancano le estensioni OpenClaw

package.json missing openclaw.extensions significa che il pacchetto del Plugin usa una struttura non più accettata da OpenClaw. Correzione nel pacchetto del Plugin:
  1. Aggiungi openclaw.extensions a package.json, facendolo puntare ai file di runtime compilati, in genere ./dist/index.js.
  2. Pubblica nuovamente il pacchetto, quindi esegui di nuovo openclaw plugins install <package>.
Riferimento: Architettura dei Plugin

​
Il criterio di installazione blocca installazioni o aggiornamenti dei Plugin

L’aggiornamento termina, ma i Plugin non sono aggiornati, sono disabilitati oppure mostrano blocked by install policy, install policy failed closed o Disabled "<plugin>" after plugin update failure: controlla security.installPolicy. Il criterio di installazione viene applicato durante l’installazione e l’aggiornamento dei Plugin. Le versioni dei Plugin @openclaw/* normalmente avanzano con la versione di OpenClaw, quindi un aggiornamento di OpenClaw può richiedere un aggiornamento corrispondente dei Plugin durante la sincronizzazione successiva. Evita queste forme di criterio, a meno che tu non gestisca anche la regola di aggiornamento corrispondente:
  • Bloccare i Plugin di proprietà di OpenClaw a una singola versione precedente esatta, ad esempio soltanto @openclaw/*@2026.5.3.
  • Bloccare esclusivamente in base al tipo di origine, ossia ogni richiesta npm, di rete o request.mode: "update".
  • Considerare facoltativo il comando del criterio: quando security.installPolicy è abilitato, un eseguibile del criterio mancante, lento, illeggibile o bloccato dai permessi causa un errore in modalità chiusa.
  • Approvare le versioni senza confrontare il valore openclawVersion della richiesta con i metadati del Plugin candidato.
Preferisci regole che consentano gli aggiornamenti attendibili di @openclaw/* compatibili con l’host attuale, invece di bloccare per sempre una singola versione. Se blocchi npm per impostazione predefinita, aggiungi un’eccezione circoscritta per gli ID dei Plugin che utilizzi e applica la stessa regola di attendibilità a request.mode: "update" e alle installazioni. Ripristino:
Se il criterio è intenzionalmente rigido, rendilo meno restrittivo durante la finestra di aggiornamento attendibile, esegui nuovamente openclaw plugins update --all, quindi ripristina la regola più rigida. Se un aggiornamento non riuscito ha disabilitato un Plugin, esaminalo prima di riabilitarlo:
Riferimento: Criterio di installazione dell’operatore

​
Plugin presente ma bloccato per proprietà sospetta

openclaw doctor, la configurazione iniziale o gli avvisi di avvio mostrano:
I file del Plugin appartengono a un utente Unix diverso da quello del processo che li carica. Non rimuovere la configurazione del Plugin; correggi la proprietà dei file oppure esegui OpenClaw come l’utente proprietario della directory di stato. Le installazioni Docker vengono eseguite come node (uid 1000). Correggi i bind mount dell’host:
Se esegui intenzionalmente OpenClaw come root, correggi invece la directory radice gestita dei Plugin:
Documentazione di approfondimento: Proprietà del percorso del Plugin bloccata, Docker: permessi ed EACCES

​
Albero decisionale

Output corretto:
  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable o admin-capable
  • Il canale mostra il trasporto connesso e, dove supportato, works o audit ok in channels status --probe
  • Il mittente è approvato oppure il criterio dei messaggi diretti è aperto o basato su un elenco di elementi consentiti
Firme nei registri:
  • drop guild message (mention required → il controllo delle menzioni di Discord ha bloccato il messaggio.
  • pairing request → il mittente non è approvato ed è in attesa dell’approvazione dell’associazione tramite messaggio diretto.
  • blocked / allowlist nei registri del canale → il mittente, la stanza o il gruppo è stato filtrato.
Pagine di approfondimento: Nessuna risposta, Risoluzione dei problemi dei canali, Associazione
Output corretto:
  • Dashboard: http://... mostrato in openclaw gateway status
  • Connectivity probe: ok
  • Capability: read-only, write-capable o admin-capable
  • Nessun ciclo di autenticazione nei registri
Firme nei registri:
  • device identity required → il contesto HTTP/non sicuro non può completare l’autenticazione del dispositivo.
  • origin not allowed → l’Origin del browser non è consentita per la destinazione del Gateway della Control UI.
  • AUTH_TOKEN_MISMATCH con canRetryWithDeviceToken=true → può essere eseguito automaticamente un singolo nuovo tentativo con un token del dispositivo attendibile, riutilizzando gli ambiti memorizzati nella cache del token associato.
  • unauthorized ripetuto dopo tale tentativo → token o password errati, modalità di autenticazione non corrispondente oppure token obsoleto del dispositivo associato.
  • too many failed authentication attempts (retry later) → i tentativi ripetuti non riusciti provenienti da quell’Origin del browser vengono temporaneamente bloccati; le altre origini localhost usano contenitori separati. Consulta Connettività della Dashboard/Control UI per i dettagli sui tentativi simultanei con Tailscale Serve.
  • gateway connect failed: → l’interfaccia utente punta all’URL o alla porta errati oppure il Gateway non è raggiungibile.
Pagine di approfondimento: Connettività della Dashboard/Control UI, Control UI, Autenticazione
Output corretto:
  • Service: ... (loaded)
  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable o admin-capable
Firme nei registri:
  • Gateway start blocked: set gateway.mode=local o existing config is missing gateway.mode → la modalità del Gateway è remota oppure nella configurazione manca l’indicazione della modalità locale ed è necessaria una correzione.
  • refusing to bind gateway ... without auth → associazione a un indirizzo diverso da local loopback senza un percorso di autenticazione valido, tramite token/password o proxy attendibile se configurato.
  • another gateway instance is already listening o EADDRINUSE → la porta è già occupata.
Pagine di approfondimento: Servizio Gateway non in esecuzione, Processo in background, Configurazione
Output corretto:
  • Trasporto del canale connesso.
  • Controlli di associazione e dell’elenco di elementi consentiti superati.
  • Menzioni rilevate dove richieste.
Firme nei registri:
  • mention required → il controllo delle menzioni di gruppo ha bloccato l’elaborazione.
  • pairing / pending → il mittente del messaggio diretto non è ancora approvato.
  • not_in_channel, missing_scope, Forbidden, 401/403 → problema con il token dei permessi del canale.
Pagine di approfondimento: Canale connesso, ma i messaggi non vengono trasmessi, Risoluzione dei problemi dei canali
Output corretto:
  • cron status mostra il pianificatore abilitato e la prossima riattivazione.
  • cron runs mostra voci ok recenti.
  • Heartbeat è abilitato e rientra nell’orario di attività.
Firme nei registri:
  • cron: scheduler disabled; jobs will not run automatically → Cron è disabilitato.
  • heartbeat skipped motivo quiet-hours → al di fuori degli orari di attività configurati.
  • heartbeat skipped motivo empty-heartbeat-file → HEARTBEAT.md esiste, ma contiene solo righe vuote, commenti, intestazioni, delimitatori di blocchi di codice o una struttura vuota di elenco di controllo.
  • heartbeat skipped motivo no-tasks-due → la modalità attività è attiva, ma non è ancora scaduto alcun intervallo delle attività.
  • heartbeat skipped motivo alerts-disabled → showOk, showAlerts e useIndicator sono tutti disattivati.
  • requests-in-flight → corsia principale occupata; riattivazione di Heartbeat rinviata.
  • unknown accountId → l’account di destinazione per la consegna di Heartbeat non esiste.
Pagine di approfondimento: Consegna di Cron e Heartbeat, Attività pianificate: risoluzione dei problemi, Heartbeat
Output corretto:
  • Node indicato come connesso e associato per il ruolo node.
  • La funzionalità necessaria per il comando invocato è disponibile.
  • L’autorizzazione per lo strumento è concessa.
Indicazioni nei log:
  • NODE_BACKGROUND_UNAVAILABLE → porta l’app del Node in primo piano.
  • *_PERMISSION_REQUIRED → autorizzazione del sistema operativo negata o mancante.
  • SYSTEM_RUN_DENIED: approval required → l’approvazione dell’esecuzione è in sospeso.
  • SYSTEM_RUN_DENIED: allowlist miss → il comando non è incluso nell’elenco consentito per l’esecuzione.
Pagine di approfondimento: Node associato, strumento non funzionante, Risoluzione dei problemi del Node, Approvazioni dell’esecuzione
Modifiche intervenute:
  • Se tools.exec.host non è impostato, il valore predefinito è auto, che viene risolto in sandbox quando è attivo un runtime sandbox e in gateway negli altri casi.
  • host=auto determina solo l’instradamento; il comportamento senza richiesta di conferma deriva da security=full insieme a ask=off sul Gateway/Node.
  • Se tools.exec.security non è impostato, il valore predefinito è full su gateway/node.
  • Se tools.exec.ask non è impostato, il valore predefinito è off.
  • Se vengono richieste approvazioni, una policy locale dell’host o specifica della sessione ha reso l’esecuzione più restrittiva rispetto a questi valori predefiniti.
Ripristina i valori predefiniti correnti senza approvazione:
Alternative più sicure:
  • Imposta solo tools.exec.host=gateway per un instradamento stabile verso l’host.
  • Usa security=allowlist con ask=on-miss per l’esecuzione sull’host con revisione quando il comando non è incluso nell’elenco consentito.
  • Abilita la modalità sandbox affinché host=auto venga nuovamente risolto in sandbox.
Indicazioni nei log:
  • Approval required. → il comando è in attesa di /approve ....
  • SYSTEM_RUN_DENIED: approval required → l’approvazione dell’esecuzione sull’host Node è in sospeso.
  • exec host=sandbox requires a sandbox runtime for this session → selezione implicita o esplicita della sandbox, ma la modalità sandbox è disattivata.
Pagine di approfondimento: Esecuzione, Approvazioni dell’esecuzione, Sicurezza: controlli eseguiti dall’audit
Output corretto:
  • Lo stato del browser mostra running: true e un browser/profilo selezionato.
  • Il profilo openclaw si avvia oppure il profilo user rileva le schede locali di Chrome.
Indicazioni nei log:
  • unknown command "browser" → plugins.allow è impostato ed esclude browser.
  • Failed to start Chrome CDP on port → avvio del browser locale non riuscito.
  • browser.executablePath not found → il percorso configurato del file binario è errato.
  • browser.cdpUrl must be http(s) or ws(s) → l’URL CDP configurato usa uno schema non supportato.
  • browser.cdpUrl has invalid port → l’URL CDP configurato contiene una porta non valida o fuori intervallo.
  • No Chrome tabs found for profile="user" → il profilo di collegamento MCP di Chrome non ha schede locali di Chrome aperte.
  • Remote CDP for profile "<name>" is not reachable → l’endpoint CDP remoto configurato non è raggiungibile da questo host.
  • Browser attachOnly is enabled ... not reachable → il profilo di solo collegamento non dispone di una destinazione CDP attiva.
  • Sostituzioni obsolete di viewport/modalità scura/locale/modalità offline nei profili di solo collegamento o CDP remoto → esegui openclaw browser stop --browser-profile <name> per chiudere la sessione di controllo e rilasciare lo stato di emulazione senza riavviare il Gateway.
Pagine di approfondimento: Lo strumento browser non funziona, Comando o strumento browser mancante, Browser: risoluzione dei problemi su Linux, Browser: risoluzione dei problemi del CDP remoto su WSL2/Windows

​
Argomenti correlati