OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Start here

Risoluzione generale dei problemi

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:

bash
openclaw statusopenclaw status --allopenclaw gateway probeopenclaw gateway statusopenclaw doctoropenclaw channels status --probeopenclaw logs --follow

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:

bash
openclaw statusopenclaw status --allopenclaw doctor

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>.
json
{  "name": "@openclaw/my-plugin",  "version": "1.2.3",  "openclaw": {    "extensions": ["./dist/index.js"]  }}

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:

bash
openclaw doctor --deepopenclaw plugins update --allopenclaw status --all

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:

bash
openclaw plugins inspect <plugin-id> --runtime --jsonopenclaw plugins enable <plugin-id>

Riferimento: Criterio di installazione dell’operatore

Plugin presente ma bloccato per proprietà sospetta

openclaw doctor, la configurazione iniziale o gli avvisi di avvio mostrano:

text
blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)plugin present but blocked

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:

bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspaceopenclaw doctor --fix

Se esegui intenzionalmente OpenClaw come root, correggi invece la directory radice gestita dei Plugin:

bash
sudo chown -R root:root /path/to/openclaw-config/npmopenclaw doctor --fix

Documentazione di approfondimento: Proprietà del percorso del Plugin bloccata, Docker: permessi ed EACCES

Albero decisionale

flowchart TD
  A[OpenClaw is not working] --> B{What breaks first}
  B --> C[No replies]
  B --> D[Dashboard or Control UI will not connect]
  B --> E[Gateway will not start or service not running]
  B --> F[Channel connects but messages do not flow]
  B --> G[Cron or heartbeat did not fire or did not deliver]
  B --> H[Node is paired but camera canvas screen exec fails]
  B --> I[Browser tool fails]

  C --> C1[/No replies section/]
  D --> D1[/Control UI section/]
  E --> E1[/Gateway section/]
  F --> F1[/Channel flow section/]
  G --> G1[/Automation section/]
  H --> H1[/Node tools section/]
  I --> I1[/Browser section/]
No replies
bash
openclaw statusopenclaw gateway statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --follow

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

Dashboard or Control UI will not connect
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

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

Gateway will not start or service installed but not running
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

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

Channel connects but messages do not flow
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

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

Cron or heartbeat did not fire or did not deliver
bash
openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw logs --follow

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

Node is paired but tool fails camera canvas screen exec
bash
openclaw statusopenclaw gateway statusopenclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw logs --follow

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

Exec suddenly asks for approval
bash
openclaw config get tools.exec.hostopenclaw config get tools.exec.securityopenclaw config get tools.exec.askopenclaw gateway restart

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:

bash
openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

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

Browser tool fails
bash
openclaw statusopenclaw gateway statusopenclaw browser statusopenclaw logs --followopenclaw doctor

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

Was this useful?
On this page

On this page