Risoluzione dei problemi

​

Sequenza di comandi

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

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

​

Dopo un aggiornamento

openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart

• Update restart in openclaw status / openclaw status --all. I passaggi di consegna in sospeso o non riusciti includono il comando successivo da eseguire.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix nella sezione Canali: la configurazione del canale esiste ancora, ma la registrazione del Plugin non è riuscita prima che il canale potesse essere caricato.
• Errori 401 del provider dopo una nuova autenticazione: openclaw doctor --fix verifica la presenza di copie obsolete delle credenziali OAuth per singolo agente e le rimuove, affinché tutti gli agenti risolvano il profilo condiviso corrente.

​

Installazioni disallineate e protezione dalle configurazioni più recenti

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

openclaw gateway install --force
openclaw gateway restart

​

Mancata corrispondenza del protocollo dopo un rollback

openclaw --version
which -a openclaw
openclaw gateway status --deep
openclaw doctor --deep
openclaw logs --follow

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> nei log del Gateway.
• Established clients: in openclaw gateway status --deep oppure Gateway clients in openclaw doctor --deep: client TCP attivi connessi alla porta del Gateway, con PID e righe di comando quando consentito dal sistema operativo.
• Un processo client la cui riga di comando punta all’installazione o al wrapper OpenClaw più recente da cui è stato eseguito il rollback.

1. Arrestare o riavviare il processo client OpenClaw obsoleto mostrato da gateway status --deep.
2. Riavviare le applicazioni o i wrapper che incorporano OpenClaw: dashboard locali, editor, helper del server applicativo o shell openclaw logs --follow di lunga durata.
3. Eseguire nuovamente openclaw gateway status --deep o openclaw doctor --deep e verificare che il PID del client obsoleto non sia più presente.

​

Collegamento simbolico di una Skill ignorato perché esce dal percorso

Percorso della Skill ignorato perché esce dalla relativa radice configurata: ... reason=symlink-escape

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

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

• Configurazione delle Skills
• Esempi di configurazione

​

Utilizzo aggiuntivo richiesto da Anthropic 429 per il contesto esteso

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

• Il modello Anthropic selezionato è un modello Claude 4.x da 1M con disponibilità generale (Opus 4.6/4.7/4.8, Sonnet 4.6), oppure la configurazione del modello contiene ancora il valore obsoleto params.context1m: true.
• Le credenziali Anthropic correnti non sono idonee all’utilizzo del contesto esteso.
• Le richieste non riescono solo durante sessioni o esecuzioni del modello prolungate che richiedono il percorso di contesto da 1M.

• Anthropic
• Utilizzo dei token e costi
• Perché viene visualizzato HTTP 429 da Anthropic?

​

Risposte 403 bloccate a monte

openclaw status
openclaw gateway status
openclaw logs --follow

• Più modelli dello stesso provider non riescono nello stesso modo.
• Viene restituito HTML o testo generico relativo alla sicurezza anziché un normale errore dell’API del provider.
• Sono presenti eventi di sicurezza sul lato del provider relativi allo stesso momento della richiesta.
• Una piccola richiesta di verifica diretta curl riesce, mentre le normali richieste con la struttura dell’SDK non riescono.

• Endpoint compatibili con OpenAI
• Configurazione dei provider
• Log

​

Il backend locale compatibile con OpenAI supera le verifiche dirette, ma le esecuzioni dell’agente non riescono

• curl ... /v1/models funziona.
• Le piccole chiamate dirette /v1/chat/completions funzionano.
• Le esecuzioni dei modelli OpenClaw non riescono solo durante i normali turni dell’agente.

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

• Le piccole chiamate dirette riescono, ma le esecuzioni di OpenClaw non riescono solo con prompt più grandi.
• Si verificano errori model_not_found o 404, anche se una richiesta diretta /v1/chat/completions funziona con lo stesso ID di modello senza prefisso.
• Il backend segnala errori perché messages[].content richiede una stringa.
• Si verificano avvisi intermittenti incomplete turn detected ... stopReason=stop payloads=0 con un backend locale compatibile con OpenAI.
• Il backend si arresta in modo anomalo solo con un numero maggiore di token del prompt o con i prompt completi del runtime dell’agente.

• Configurazione
• Modelli locali
• Endpoint compatibili con OpenAI

​

Nessuna risposta

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

• Associazione in sospeso per i mittenti dei messaggi diretti.
• Limitazione basata sulle menzioni nei gruppi (requireMention, mentionPatterns).
• Mancate corrispondenze nelle liste consentite di canali/gruppi.

• drop guild message (mention required → messaggio di gruppo ignorato fino a una menzione.
• pairing request → il mittente deve essere approvato.
• blocked / allowlist → il mittente/canale è stato filtrato dai criteri.

• Risoluzione dei problemi dei canali
• Gruppi
• Associazione

​

Connettività dell’interfaccia di controllo della dashboard

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

• URL di verifica e URL della dashboard corretti.
• Mancata corrispondenza della modalità di autenticazione/del token tra client e Gateway.
• Utilizzo di HTTP quando è richiesta l’identità del dispositivo.

openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789

​

Mappa rapida dei codici di dettaglio dell’autenticazione

openclaw --version
openclaw doctor
openclaw gateway status

• Le sessioni con token di un dispositivo associato possono gestire soltanto il proprio dispositivo, a meno che il chiamante non disponga anche di operator.admin.
• openclaw devices rotate --scope ... può richiedere soltanto ambiti operatore già posseduti dalla sessione del chiamante.

• Configurazione (modalità di autenticazione del Gateway)
• Interfaccia di controllo
• Dispositivi
• Accesso remoto
• Autenticazione tramite proxy attendibile

​

Servizio Gateway non in esecuzione

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # analizza anche i servizi a livello di sistema

• Runtime: stopped con indicazioni sull’uscita.
• Mancata corrispondenza della configurazione del servizio (Config (cli) rispetto a Config (service)).
• Conflitti di porta/listener.
• Installazioni aggiuntive di launchd/systemd/schtasks quando viene utilizzato --deep.
• Indicazioni per la pulizia di Other gateway-like services detected (best effort).

• Esecuzione in background e strumento dei processi
• Configurazione
• Doctor

​

Il Gateway su macOS smette silenziosamente di rispondere e riprende quando si interagisce con la dashboard

ls ~/.openclaw/logs/stability/ | tail -5
openclaw gateway stability --bundle latest
pmset -g log | grep -iE "sleep|wake|maintenance" | tail -50
launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

• Uno o più bundle *-uncaught_exception.json in ~/.openclaw/logs/stability/ con error.code impostato su un codice di rete transitorio come ENETDOWN, ENETUNREACH, EHOSTUNREACH o ECONNREFUSED.
• Righe pmset -g log come Entering Sleep state due to 'Maintenance Sleep' o en0 driver is slow (msg: WillChangeState to 0) in corrispondenza dei timestamp degli arresti anomali. Power Nap / Maintenance Sleep porta brevemente il driver Wi-Fi nello stato 0; qualsiasi connect() in uscita che si verifichi in quell’intervallo può non riuscire con ENETDOWN, anche su un host che dispone altrimenti di connettività di rete completa.
• Output di launchctl print che mostra state = not running con più runs recenti e un codice di uscita, soprattutto quando l’intervallo tra l’arresto anomalo e l’avvio successivo è nell’ordine di un’ora anziché di pochi secondi. Dopo una serie di arresti anomali, launchd di macOS applica un meccanismo di protezione dal riavvio non documentato che può smettere di rispettare KeepAlive=true finché un evento esterno, come un accesso interattivo, una connessione alla dashboard o launchctl kickstart, non lo riattiva.

• Un bundle di stabilità il cui error.code è ENETDOWN o un codice correlato, con lo stack di chiamate che punta a Node net lookupAndConnect / Socket.connect. OpenClaw 2026.5.26 e versioni successive classificano questi eventi come errori di rete transitori innocui, impedendo che si propaghino al gestore di primo livello delle eccezioni non intercettate; se si utilizza una versione precedente, eseguire prima l’aggiornamento.
• Lunghi periodi di inattività che terminano nell’istante in cui ci si connette alla Control UI o si accede all’host tramite SSH: è l’attività visibile all’utente a riattivare il meccanismo di riavvio di launchd, non un’azione della dashboard sul Gateway.
• Il conteggio runs aumenta nel corso della giornata senza una riga received SIG*; shutting down corrispondente in ~/Library/Logs/openclaw/gateway.log: gli arresti regolari registrano un segnale, mentre gli arresti anomali transitori no.

1. Aggiornare il Gateway se si utilizza una versione precedente a 2026.5.26. Dopo l’aggiornamento, i futuri errori ENETDOWN vengono registrati come avvisi anziché terminare il processo.
2. Ridurre l’attività di sospensione per manutenzione sugli host Mac mini / desktop destinati a funzionare come server sempre attivi:
   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0
   
   Questa operazione riduce significativamente, ma non elimina del tutto, l’instabilità del driver sottostante. Il sistema può comunque eseguire alcune sospensioni per manutenzione per mantenere attivi TCP keepalive e mDNS, indipendentemente da questi flag.
3. Aggiungere un watchdog di operatività affinché un’eventuale futura serie di arresti anomali bloccata da launchd venga rilevata rapidamente:
   # Esempio di controllo dell'operatività compatibile con launchd, adatto a un Cron o LaunchAgent eseguito ogni 5 minuti
   state=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')
   if [ "$state" != "running" ]; then
     launchctl kickstart -k gui/$UID/ai.openclaw.gateway
   fi
   
   Lo scopo è riattivare esternamente il meccanismo di riavvio; dopo una serie di arresti anomali su macOS, il solo KeepAlive=true non è sufficiente.

• Note sulla piattaforma macOS
• Registrazione
• Doctor

​

Ciclo del supervisore launchd di macOS con LaunchAgent duplicati per Gateway/Node

for i in 1 2 3 4; do
  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
  sleep 10
done

openclaw gateway status --deep
openclaw node status
launchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'
tail -n 80 ~/Library/Logs/openclaw/gateway.log

• Più di un PID del Gateway nel campione di 30 secondi anziché un unico processo stabile.
• EADDRINUSE, another gateway instance is already listening o ripetute righe di riavvio/delega in gateway.log.
• Sia ~/Library/LaunchAgents/ai.openclaw.gateway.plist sia ~/Library/LaunchAgents/ai.openclaw.node.plist caricati contemporaneamente su un host che dovrebbe eseguire un solo servizio Gateway gestito.

1. Se questo host deve eseguire soltanto il servizio Gateway, rimuovere tramite OpenClaw il servizio Node gestito. Saltare questo passaggio se si utilizza attivamente il servizio Node per le funzionalità dei Node remoti; la disinstallazione interrompe tali funzionalità su questo host:
   openclaw node uninstall
   
2. Installare un wrapper permanente per il Gateway che elimini i marcatori launchd ereditati prima di avviare OpenClaw. Utilizzare l’opzione --wrapper supportata; non modificare il file generato in ~/.openclaw/service-env/, perché la reinstallazione del servizio, l’aggiornamento e la riparazione tramite Doctor rigenerano tale file:
   mkdir -p ~/.local/bin
   cat >~/.local/bin/openclaw-launchd-workaround <<'EOF'
   #!/bin/sh
   set -eu
   unset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || true
   exec openclaw "$@"
   EOF
   chmod 700 ~/.local/bin/openclaw-launchd-workaround
   
   openclaw gateway install \
     --wrapper ~/.local/bin/openclaw-launchd-workaround \
     --force
   
   gateway install mantiene il percorso del wrapper durante le reinstallazioni forzate, gli aggiornamenti e le riparazioni tramite Doctor.
3. Verificare che il Gateway sia stabile e gestisca RPC, anziché limitarsi ad ascoltare:
   openclaw gateway status --deep --require-rpc
   
   for i in 1 2 3 4; do
     ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
     sleep 10
   done
   
   Il campione di PID dovrebbe mostrare un unico processo stabile anziché un insieme variabile di PID e l’inoltro dei canali in entrata dovrebbe riprendere.
4. Dopo l’aggiornamento a una versione in cui il ciclo sottostante dei due LaunchAgent è stato corretto, rimuovere la soluzione alternativa e reinstallare il normale servizio gestito:
   OPENCLAW_WRAPPER= openclaw gateway install --force
   rm ~/.local/bin/openclaw-launchd-workaround
   

• Note sulla piattaforma macOS
• Doctor
• CLI del Gateway

​

Chiusura del Gateway durante un utilizzo elevato della memoria

openclaw gateway status --deep
openclaw logs --follow
openclaw gateway stability --bundle latest
openclaw gateway diagnostics export

• Reason: diagnostic.memory.pressure.critical nel bundle di stabilità più recente.
• Memory pressure: con critical/rss_threshold, critical/heap_threshold o critical/rss_growth.
• Valori V8 heap: prossimi al limite dell’heap.
• Voci Largest session files: come agents/<agent>/sessions/<session>.jsonl o sessions/<session>.jsonl.
• Contatori della memoria cgroup di Linux quando il Gateway viene eseguito in un container o in un servizio con memoria limitata.

• critical memory pressure bundle written compare poco prima del riavvio → OpenClaw ha acquisito un bundle di stabilità precedente all’esaurimento della memoria. Esaminarlo con openclaw gateway stability --bundle latest.
• memory pressure: level=critical ... memoryPressureSnapshot=disabled compare nei log del Gateway → OpenClaw ha rilevato una pressione critica sulla memoria, ma l’acquisizione di stabilità precedente all’esaurimento della memoria è disattivata.
• Largest session files: indica un percorso molto grande di una trascrizione oscurata → ridurre la cronologia delle sessioni conservata, esaminare la crescita delle sessioni o spostare le vecchie trascrizioni fuori dall’archivio attivo prima del riavvio.
• I byte utilizzati in V8 heap: sono prossimi al limite dell’heap → ridurre il carico di prompt/sessioni, diminuire il lavoro simultaneo oppure aumentare il limite dell’heap di Node solo dopo aver confermato che il carico di lavoro è previsto.
• Memory pressure: critical/rss_growth → la memoria è aumentata rapidamente durante un singolo intervallo di campionamento. Controllare nei log più recenti la presenza di un’importazione di grandi dimensioni, un output incontrollato degli strumenti, tentativi ripetuti o un gruppo di attività dell’agente in coda.
• Nei log compare una pressione critica sulla memoria, ma non esiste alcun bundle → questo è il comportamento predefinito. Impostare diagnostics.memoryPressureSnapshot: true per acquisire il bundle di stabilità precedente all’esaurimento della memoria in occasione di futuri eventi di pressione critica sulla memoria.

• Integrità del Gateway
• Esportazione della diagnostica
• Sessioni

​

Il Gateway ha rifiutato una configurazione non valida

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

• 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.
• OpenClaw conserva i 32 file .clobbered.* più recenti per ogni percorso di configurazione ed elimina progressivamente quelli meno recenti.

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

• Configurazione
• Configurazione: ricaricamento a caldo
• Configurazione: convalida rigorosa
• Doctor

​

Avvisi del probe del Gateway

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

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

• SSH tunnel failed to start; falling back to direct probes. → la configurazione SSH non è riuscita, ma il comando ha comunque tentato di usare le destinazioni dirette configurate o di loopback.
• multiple reachable gateway identities detected → hanno risposto gateway distinti oppure OpenClaw non ha potuto dimostrare che le destinazioni raggiungibili fossero lo stesso gateway. Un tunnel SSH, un URL proxy o un URL remoto configurato per lo stesso gateway viene considerato un singolo gateway con più trasporti, anche quando le porte dei trasporti sono diverse.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → la connessione è riuscita, ma l’RPC dei dettagli è limitata dall’ambito; associare l’identità del dispositivo o utilizzare credenziali con operator.read.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → la connessione è riuscita, ma il set completo di RPC diagnostiche è scaduto o non è riuscito. Considerarlo un Gateway raggiungibile con diagnostica degradata; confrontare connect.ok e connect.rpcOk nell’output di --json.
• Capability: pairing-pending o gateway closed (1008): pairing required → il gateway ha risposto, ma questo client richiede ancora l’associazione o l’approvazione prima del normale accesso da parte dell’operatore.
• Testo di avviso SecretRef gateway.auth.* / gateway.remote.* non risolto → il materiale di autenticazione non era disponibile in questo percorso del comando per la destinazione non riuscita.

• Gateway
• Più gateway sullo stesso host
• Accesso remoto

​

Canale connesso, ma i messaggi non vengono trasmessi

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

• Criterio per i messaggi diretti (pairing, allowlist, open, disabled).
• Elenco consentito del gruppo e requisiti per le menzioni.
• Autorizzazioni o ambiti API del canale mancanti.

• mention required → messaggio ignorato dai criteri per le menzioni del gruppo.
• pairing / tracce di approvazione in sospeso → il mittente non è approvato.
• missing_scope, not_in_channel, Forbidden, 401/403 → problema di autenticazione o autorizzazioni del canale.

• Risoluzione dei problemi dei canali
• Discord
• Telegram
• WhatsApp

​

Recapito di Cron e Heartbeat

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

• Cron abilitato e prossima attivazione presente.
• Stato della cronologia delle esecuzioni del processo (ok, skipped, error).
• Motivi per cui Heartbeat è stato ignorato (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due).

• Heartbeat
• Attività pianificate
• Attività pianificate: risoluzione dei problemi

​

Node associato, strumento non riuscito

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

• Node online con le funzionalità previste.
• Autorizzazioni del sistema operativo concesse per fotocamera, microfono, posizione e schermo.
• Stato delle approvazioni di esecuzione e dell’elenco consentito.

• NODE_BACKGROUND_UNAVAILABLE → l’app del Node deve essere in primo piano.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → autorizzazione del sistema operativo mancante.
• SYSTEM_RUN_DENIED: approval required → approvazione dell’esecuzione in sospeso.
• SYSTEM_RUN_DENIED: allowlist miss → comando bloccato dall’elenco consentito.

• Approvazioni dell’esecuzione
• Risoluzione dei problemi dei Node
• Node

​

Strumento browser non riuscito

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

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

• Browser (gestito da OpenClaw)
• Risoluzione dei problemi del browser

​

Se dopo un aggiornamento qualcosa ha improvvisamente smesso di funzionare

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

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

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

openclaw gateway install --force
openclaw gateway restart

• Autenticazione
• Esecuzione in background e strumento di gestione dei processi
• Associazione dei nodi

​

Argomenti correlati

• Doctor
• Domande frequenti
• Runbook del Gateway