Risoluzione dei problemi

Questo è il runbook approfondito. Per prima cosa, iniziare da /help/risoluzione-dei-problemi per il flusso di triage rapido.

Sequenza di comandi

Eseguire nell'ordine seguente:

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Segnali di funzionamento corretto:

• 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

Utilizzare questa procedura quando un aggiornamento è terminato, ma il Gateway non è attivo, i canali sono vuoti oppure le chiamate ai modelli non riescono con errori 401.

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

Verificare quanto segue:

• 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

Utilizzare questa procedura quando un servizio Gateway si arresta inaspettatamente dopo un aggiornamento oppure i log mostrano che un file binario openclaw è precedente alla versione che ha scritto per ultima openclaw.json.

OpenClaw contrassegna le scritture della configurazione con meta.lastTouchedVersion. I comandi di sola lettura possono esaminare una configurazione scritta da una versione più recente di OpenClaw, ma le operazioni che modificano processi e servizi non possono essere eseguite da un file binario precedente. Azioni bloccate: avvio, arresto, riavvio e disinstallazione del servizio Gateway; reinstallazione forzata del servizio; avvio del Gateway in modalità servizio; pulizia della porta gateway --force.

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

Mancata corrispondenza del protocollo dopo un rollback

Utilizzare questa procedura quando i log continuano a mostrare protocol mismatch dopo un downgrade o un rollback. È in esecuzione un Gateway precedente, ma un processo client locale più recente continua a riconnettersi con un intervallo di versioni del protocollo non supportato dal Gateway precedente.

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

Verificare quanto segue:

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

Correzione:

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.

Non fare in modo che un Gateway precedente accetti un protocollo più recente e incompatibile. Gli incrementi di versione del protocollo proteggono il contratto di comunicazione; il ripristino dopo un rollback richiede la pulizia dei processi e delle versioni.

Collegamento simbolico di una Skill ignorato perché esce dal percorso

Utilizzare questa procedura quando i log includono:

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

Ogni radice delle Skill costituisce un limite di contenimento. Un collegamento simbolico in ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills o ~/.openclaw/skills viene ignorato quando la sua destinazione reale viene risolta al di fuori di tale radice, a meno che la destinazione non sia esplicitamente considerata attendibile.

Esaminare il collegamento:

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

Se la destinazione è intenzionale, configurare sia la radice diretta delle Skill sia la destinazione consentita del collegamento simbolico:

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

Avviare quindi una nuova sessione oppure attendere che il monitoraggio delle Skill esegua l'aggiornamento. Riavviare il Gateway se il processo in esecuzione è precedente alla modifica della configurazione.

Non utilizzare destinazioni generiche come ~, / o un'intera cartella di progetto sincronizzata. Limitare allowSymlinkTargets alla radice reale delle Skill che contiene directory SKILL.md attendibili.

Se l'applicazione di Skill Workshop deve anche scrivere attraverso tali percorsi attendibili delle Skill nell'area di lavoro collegati simbolicamente, abilitare skills.workshop.allowSymlinkTargetWrites. Mantenerlo disabilitato per le radici condivise delle Skill in sola lettura.

Correlati:

• Configurazione delle Skills
• Esempi di configurazione

Utilizzo aggiuntivo richiesto da Anthropic 429 per il contesto esteso

Utilizzare questa procedura quando i log o gli errori includono: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

Verificare quanto segue:

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

Opzioni di correzione:

Correlati:

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

Risposte 403 bloccate a monte

Utilizzare questa procedura quando un provider LLM a monte restituisce un errore generico 403, ad esempio Your request was blocked.

Non presupporre che si tratti sempre di un problema di configurazione di OpenClaw. La risposta può provenire da un livello di sicurezza a monte, ad esempio una CDN, un WAF, una regola di gestione dei bot o un proxy inverso posto davanti a un endpoint compatibile con OpenAI.

openclaw statusopenclaw gateway statusopenclaw logs --follow

Verificare quanto segue:

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

Quando le evidenze indicano un blocco WAF/CDN, correggere prima il filtraggio sul lato del provider. Preferire una regola di autorizzazione o esclusione strettamente limitata al percorso API utilizzato da OpenClaw ed evitare di disabilitare la protezione per l'intero sito.

Correlati:

• 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

Utilizzare questa procedura quando:

• 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/modelscurl 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" --jsonopenclaw logs --follow

Verificare quanto segue:

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

Correlati:

• Configurazione
• Modelli locali
• Endpoint compatibili con OpenAI

Nessuna risposta

Se i canali sono attivi ma non arriva alcuna risposta, controllare l'instradamento e i criteri prima di riconnettere qualsiasi elemento.

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

Verificare la presenza di:

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

Segnali comuni:

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

Argomenti correlati:

• Risoluzione dei problemi dei canali
• Gruppi
• Associazione

Connettività dell'interfaccia di controllo della dashboard

Quando la dashboard/interfaccia di controllo non riesce a connettersi, verificare l'URL, la modalità di autenticazione e le condizioni relative al contesto sicuro.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

Verificare la presenza di:

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

Se un browser locale non riesce a connettersi a 127.0.0.1:18789 dopo un aggiornamento, ripristinare innanzitutto il servizio Gateway locale e verificare che stia rendendo disponibile la dashboard:

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

Se curl restituisce l'HTML di OpenClaw, il Gateway funziona e il problema restante è probabilmente dovuto alla cache del browser, a un vecchio collegamento diretto o allo stato obsoleto di una scheda. Aprire direttamente http://127.0.0.1:18789 e navigare dalla dashboard. Se dopo il riavvio il servizio non rimane in esecuzione, eseguire openclaw gateway start e ricontrollare openclaw gateway status.

Mappa rapida dei codici di dettaglio dell'autenticazione

Utilizzare error.details.code dalla risposta connect non riuscita per scegliere l'azione successiva:

Verifica della migrazione all'autenticazione del dispositivo v2:

openclaw --versionopenclaw doctoropenclaw gateway status

Se i log mostrano errori di nonce/firma, aggiornare il client che si connette e verificarlo:

Se openclaw devices rotate / revoke / remove viene negato inaspettatamente:

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

Argomenti correlati:

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

Servizio Gateway non in esecuzione

Utilizzare questa sezione quando il servizio è installato, ma il processo non rimane attivo.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # analizza anche i servizi a livello di sistema

Verificare la presenza di:

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

Argomenti correlati:

• 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

Da utilizzare quando i canali (Telegram, WhatsApp, ecc.) su un host macOS smettono di rispondere per periodi che vanno da alcuni minuti ad alcune ore e il Gateway sembra riattivarsi non appena si apre la Control UI, si accede tramite SSH o si interagisce in altro modo con l'host. Di solito non è presente alcun sintomo evidente in openclaw status, perché quando lo si controlla il Gateway è già di nuovo attivo.

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

Cercare:

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

Segnali comuni:

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

Cosa fare:

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 minutistate=$(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.gatewayfi

   Lo scopo è riattivare esternamente il meccanismo di riavvio; dopo una serie di arresti anomali su macOS, il solo KeepAlive=true non è sufficiente.

Correlati:

• Note sulla piattaforma macOS
• Registrazione
• Doctor

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

Da utilizzare quando un'installazione macOS continua a riavviarsi ogni pochi secondi, i controlli di integrità openclaw oscillano tra disponibile e non disponibile e l'inoltro dei canali si blocca, anche se il servizio sembra essere in esecuzione.

Questo comportamento è stato osservato nelle installazioni meno recenti in cui sia ai.openclaw.gateway sia ai.openclaw.node erano LaunchAgent attivi e ciascuno inseriva OPENCLAW_LAUNCHD_LABEL. In questo stato OpenClaw può rilevare la supervisione di launchd, tentare di delegare nuovamente il riavvio a launchd e finire in un rapido ciclo di EADDRINUSE/riavvio anziché mantenere un unico processo Gateway stabile.

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

Cercare:

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

Cosa fare:

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/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 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 10done

   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 --forcerm ~/.local/bin/openclaw-launchd-workaround

Correlati:

• Note sulla piattaforma macOS
• Doctor
• CLI del Gateway

Chiusura del Gateway durante un utilizzo elevato della memoria

Da utilizzare quando il Gateway scompare sotto carico, il supervisore segnala un riavvio dovuto all'esaurimento della memoria oppure i log menzionano critical memory pressure bundle written.

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

Cercare:

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

Segnali comuni:

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

Il bundle di stabilità non contiene payload. Include dati operativi relativi alla memoria e percorsi di file relativi oscurati, ma non testo dei messaggi, corpi dei Webhook, credenziali, token, cookie o ID di sessione non elaborati. Allegare l'esportazione della diagnostica alle segnalazioni di bug anziché copiare i log non elaborati.

Correlati:

• Integrità del Gateway
• Esportazione della diagnostica
• Sessioni

Il Gateway ha rifiutato una configurazione non valida

Da utilizzare quando l'avvio del Gateway non riesce con Invalid config o i log del ricaricamento a caldo indicano che una modifica non valida è stata ignorata.

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

Cercare:

• 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 | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor

Contenuti correlati:

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

Avvisi del probe del Gateway

Utilizzare quando openclaw gateway probe raggiunge una destinazione, ma visualizza comunque un blocco di avviso.

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

Verificare:

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

Indicatori comuni:

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

Contenuti correlati:

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

Canale connesso, ma i messaggi non vengono trasmessi

Se lo stato del canale risulta connesso ma il flusso dei messaggi è interrotto, concentrarsi sui criteri, sulle autorizzazioni e sulle regole di recapito specifiche del canale.

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

Verificare:

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

Indicatori comuni:

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

Contenuti correlati:

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

Recapito di Cron e Heartbeat

Se Cron o Heartbeat non è stato eseguito o non ha effettuato il recapito, verificare prima lo stato dell'utilità di pianificazione, quindi la destinazione di recapito.

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

Verificare:

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

Contenuti correlati:

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

Node associato, strumento non riuscito

Se un Node è associato ma gli strumenti non funzionano, isolare lo stato di primo piano, delle autorizzazioni e dell'approvazione.

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

Verificare:

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

Indicatori comuni:

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

Contenuti correlati:

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

Strumento browser non riuscito

Utilizzare quando le azioni dello strumento browser non riescono anche se il gateway è integro.

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

Verificare:

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

Contenuti correlati:

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

Se dopo un aggiornamento qualcosa ha improvvisamente smesso di funzionare

La maggior parte dei problemi successivi a un aggiornamento è dovuta a una divergenza della configurazione o all'applicazione di impostazioni predefinite ora più rigorose.

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

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

Se la configurazione del servizio e il runtime continuano a non corrispondere dopo le verifiche, reinstallare i metadati del servizio dalla stessa directory di profilo/stato:

openclaw gateway install --forceopenclaw gateway restart

Argomenti correlati:

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

Argomenti correlati

• Doctor
• Domande frequenti
• Runbook del Gateway