Risoluzione dei problemi del gateway OpenClaw

Quando la pagina di triage rapido non basta, la documentazione ti manda al runbook approfondito del gateway. È un indice più che un muro di correzioni: una scala di comandi, i segnali che mostra un gateway in salute e sei pagine per area di sintomo con ancore stabili. La sezione più utile è il breve elenco di ciò che si rompe subito dopo un aggiornamento. Ecco la mappa.

La scala e le sei pagine

• Esegui in quest’ordine i comandi status, gateway status, log follow, doctor e channel probe; se tutto è in salute, gateway status mostra un runtime in esecuzione, una sonda di connettività ok e una riga delle capacità, doctor non segnala problemi bloccanti di configurazione o di servizio, e la sonda mostra lo stato del trasporto in tempo reale per ciascun account, con un indicatore works o audit ok dove supportato.
• La pagina su aggiornamenti e rollback copre un gateway rimasto fermo o disallineato dopo un aggiornamento, un downgrade o un’installazione split-brain: dopo un aggiornamento, il timeout di pubblicazione del runtime del modello preparato, la protezione contro le configurazioni più recenti, la correzione del percorso di ricerca, la reinstallazione del servizio, la rimozione dei wrapper obsoleti e un disallineamento di protocollo dopo un rollback. Quella su skill e provider di modelli copre una radice di skill saltata, l’errore di rate limit per il contesto lungo con le sue correzioni (finestra standard, credenziale idonea e modello di fallback), le risposte bloccate a monte e un backend locale compatibile con OpenAI che supera le sonde ma fallisce nelle esecuzioni dell’agente.
• La pagina sulle risposte dell’agente e l’interfaccia di controllo copre un’esecuzione che fallisce con un errore di storage, una risposta che non arriva, la connettività della dashboard, le firme di connessione e autenticazione con una mappa rapida dei codici di dettaglio dell’autenticazione, e i passaggi di challenge di connessione, firma del payload e nonce del dispositivo. Quella su servizio e processo del gateway copre un servizio che non parte o non resta attivo, un gateway su macOS che si ferma in silenzio finché non si tocca la dashboard, un loop del supervisore con launch agent duplicati e un’uscita con un uso elevato della memoria.
• La pagina su validazione della configurazione e sonde copre una configurazione non valida rifiutata: cosa è successo, ispezione e riparazione, le sue firme comuni e le opzioni di correzione, più gli avvisi della sonda del gateway. Quella su consegna sui canali e strumenti copre un canale connesso in cui i messaggi non passano, la consegna pianificata e degli heartbeat, un nodo abbinato il cui strumento fallisce, gli errori dello strumento browser, le firme di plugin ed eseguibili, le firme delle sessioni del browser e quelle di elementi, screenshot e upload; ogni vecchia ancora della pagina unica rimanda ancora alla sua nuova collocazione.

La maggior parte dei guasti dopo un aggiornamento è una deriva della configurazione o valori predefiniti più rigidi che ora vengono applicati.

Se hai aggiornato e qualcosa si è rotto

L’indice riporta direttamente tre controlli. Primo, il comportamento di autenticazione e override dell’URL: leggi la modalità del gateway, l’URL remoto e la modalità di autenticazione, perché con la modalità impostata su remote la riga di comando potrebbe puntare a un gateway remoto mentre il servizio locale funziona, e le chiamate con URL esplicito non ripiegano sulle credenziali salvate; una firma connect-failed indica il bersaglio URL sbagliato e una firma unauthorized indica che l’endpoint è raggiungibile ma con l’autenticazione sbagliata. Secondo, le protezioni di bind e autenticazione sono più rigide: i bind non loopback richiedono un percorso di autenticazione valido, cioè un token condiviso o una password oppure un trusted proxy non loopback configurato correttamente, e la vecchia chiave del token non sostituisce la chiave attuale del token di autenticazione; le firme sono il rifiuto di fare il bind senza autenticazione e una sonda di connettività fallita con il runtime in esecuzione. Terzo, lo stato dell’abbinamento e dell’identità dei dispositivi: elenca i dispositivi e gli abbinamenti dei canali e cerca approvazioni di dispositivi in sospeso per la dashboard o i nodi e approvazioni in sospeso dopo un cambio di policy o di identità; le firme sono device identity required e pairing required. Se la configurazione del servizio e il runtime continuano a non coincidere, reinstalla i metadati del servizio dallo stesso profilo e dalla stessa directory di stato e riavvia.

Leggere i segnali

• Un runtime in esecuzione con una sonda di connettività fallita è in assoluto la combinazione più eloquente: il processo è vivo, ma la riga di comando non riesce a raggiungerlo con l’URL e l’autenticazione attuali, quindi la correzione va fatta nella modalità, nell’URL o nel token, non nel servizio.
• Una firma device identity required dopo un aggiornamento non è un bug del client; l’autenticazione dei dispositivi ora viene applicata e la dashboard o il nodo ha bisogno della sua approvazione in sospeso, che compare negli elenchi dei dispositivi e degli abbinamenti.
• La sonda lavora per account: un canale con due account può mostrare un trasporto funzionante e uno in errore, cosa che la sola riga di stato non rivela.

La risoluzione dei problemi dei canali OpenClaw è il complemento a livello di canale per il caso in cui il trasporto si connette ma il comportamento è sbagliato, e la guida a OpenClaw doctor spiega il comando di riparazione su cui si basa la scala.

Perché un indice

Dividere il runbook per area di sintomo mantiene ogni pagina abbastanza breve da poterla leggere mentre qualcosa è fermo, e le ancore conservate fanno sì che i link da vecchi thread e issue arrivino ancora alla sezione giusta. Anche l’ordine della scala è voluto: va dal segnale più ampio al più ristretto, e doctor viene prima della sonda perché ripara le configurazioni errate che altrimenti la sonda segnalerebbe come errori. La guida all’abbinamento in OpenClaw copre le approvazioni che cerca il terzo controllo e la guida alla configurazione di OpenClaw descrive le chiavi che leggono i primi due.

Su Diali

Su Diali la configurazione del runtime viene generata dalla dashboard e sostituita a ogni rilascio, il che elimina gran parte della deriva descritta nella sezione sugli aggiornamenti, e la stessa scala funziona sul runtime ospitato. La pagina sull’hosting OpenClaw di Diali descrive l’assistente ospitato e la pagina sulla sicurezza di Diali il confine che lo circonda.

• Cinque comandi in ordine; runtime in esecuzione più sonda ok: sistema in salute.
• Sei pagine per sintomo; ogni vecchia ancora funziona ancora.
• Dopo un aggiornamento: modalità e URL, bind e autenticazione, stato dell’abbinamento.