# openclaw update

Aggiorna OpenClaw in modo sicuro e passa tra i canali stable/beta/dev.

Se hai installato tramite npm/pnpm/bun (installazione globale, senza metadati git), gli aggiornamenti avvengono tramite il flusso del package manager in Aggiornamento.

# Utilizzo

openclaw update
openclaw update status
openclaw update wizard
openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag beta
openclaw update --tag main
openclaw update --dry-run
openclaw update --no-restart
openclaw update --yes
openclaw update --json
openclaw --update

# Opzioni

• --no-restart: salta il riavvio del servizio Gateway dopo un aggiornamento riuscito. Gli aggiornamenti tramite package manager che riavviano il Gateway verificano che il servizio riavviato riporti la versione aggiornata prevista prima che il comando abbia esito positivo.
• --channel <stable|beta|dev>: imposta il canale di aggiornamento (git + npm; persistito nella configurazione).
• --tag <dist-tag|version|spec>: sostituisce la destinazione del pacchetto solo per questo aggiornamento. Per le installazioni da pacchetto, main corrisponde a github:openclaw/openclaw#main.
• --dry-run: mostra in anteprima le azioni di aggiornamento pianificate (flusso canale/tag/destinazione/riavvio) senza scrivere la configurazione, installare, sincronizzare plugin o riavviare.
• --json: stampa JSON UpdateRunResult leggibile da macchina, inclusi postUpdate.plugins.warnings quando plugin gestiti corrotti o non caricabili richiedono riparazione dopo il successo dell'aggiornamento del core, e postUpdate.plugins.integrityDrifts quando viene rilevata una deriva dell'artefatto del plugin npm durante la sincronizzazione dei plugin post-aggiornamento.
• --timeout <seconds>: timeout per passaggio (il valore predefinito è 1800s).
• --yes: salta le richieste di conferma (ad esempio la conferma di downgrade).

openclaw update non ha un flag --verbose. Usa --dry-run per visualizzare in anteprima le azioni pianificate di canale/tag/installazione/riavvio, --json per risultati leggibili da macchina e openclaw update status --json quando ti servono solo i dettagli su canale e disponibilità. Se stai eseguendo il debug dei log del Gateway durante un aggiornamento, la verbosità della console e il livello dei log su file sono separati: Gateway --verbose influisce sull'output terminale/WebSocket, mentre i log su file richiedono logging.level: "debug" o "trace" nella configurazione. Vedi Logging del Gateway.

# update status

Mostra il canale di aggiornamento attivo + tag/branch/SHA git (per checkout da sorgente), oltre alla disponibilità di aggiornamenti.

openclaw update status
openclaw update status --json
openclaw update status --timeout 10

Opzioni:

• --json: stampa JSON di stato leggibile da macchina.
• --timeout <seconds>: timeout per i controlli (il valore predefinito è 3s).

# update wizard

Flusso interattivo per scegliere un canale di aggiornamento e confermare se riavviare il Gateway dopo l'aggiornamento (l'impostazione predefinita è riavviare). Se selezioni dev senza un checkout git, propone di crearne uno.

Opzioni:

• --timeout <seconds>: timeout per ogni passaggio di aggiornamento (predefinito 1800)

# Cosa fa

Quando cambi canale in modo esplicito (--channel ...), OpenClaw mantiene anche allineato il metodo di installazione:

• dev → assicura un checkout git (predefinito: ~/openclaw, sostituibile con OPENCLAW_GIT_DIR), lo aggiorna e installa la CLI globale da quel checkout.
• stable → installa da npm usando latest.
• beta → preferisce il dist-tag npm beta, ma ripiega su latest quando beta è assente o più vecchio della release stable corrente.

OpenClaw non ha ancora un canale di supporto LTS o mensile. Stiamo lavorando verso linee di supporto mensili, ma --channel attualmente accetta solo stable, beta e dev. Usa --tag <version-or-dist-tag> per una destinazione una tantum quando ti serve uno specifico artefatto di pacchetto.

L'auto-updater del core Gateway (quando abilitato tramite configurazione) avvia il percorso di aggiornamento CLI fuori dall'handler della richiesta Gateway attiva. Gli aggiornamenti tramite package manager update.run del control plane forzano un riavvio di aggiornamento non differito e senza cooldown dopo lo scambio del pacchetto, perché il vecchio processo Gateway potrebbe avere ancora in memoria chunk che puntano a file rimossi dal nuovo pacchetto.

Per le installazioni tramite package manager, openclaw update risolve la versione del pacchetto di destinazione prima di invocare il package manager. Le installazioni globali npm usano un'installazione staged: OpenClaw installa il nuovo pacchetto in un prefisso npm temporaneo, verifica l'inventario dist del pacchetto lì, poi scambia quel package tree pulito nel prefisso globale reale. Se la verifica fallisce, doctor post-aggiornamento, sincronizzazione plugin e riavvio non vengono eseguiti dal tree sospetto. Anche quando la versione installata corrisponde già alla destinazione, il comando aggiorna l'installazione globale del pacchetto, poi esegue la sincronizzazione plugin, un refresh del completamento dei comandi core e il riavvio. Questo mantiene i sidecar pacchettizzati e i record dei plugin posseduti dal canale allineati con la build OpenClaw installata, lasciando le ricostruzioni complete del completamento dei comandi plugin alle esecuzioni esplicite di openclaw completion --write-state.

Quando è installato un servizio Gateway gestito locale e il riavvio è abilitato, gli aggiornamenti tramite package manager arrestano il servizio in esecuzione prima di sostituire il package tree, poi aggiornano i metadati del servizio dall'installazione aggiornata, riavviano il servizio e verificano che il Gateway riavviato riporti la versione prevista prima di segnalare il successo. Su macOS, il controllo post-aggiornamento verifica anche che il LaunchAgent sia caricato/in esecuzione per il profilo attivo e che la porta loopback configurata sia integra. Se il plist è installato ma launchd non lo sta supervisionando, OpenClaw ri-esegue automaticamente il bootstrap del LaunchAgent, poi riesegue i controlli di prontezza salute/versione/canale. Un bootstrap fresco carica direttamente il job RunAtLoad, quindi il ripristino dell'aggiornamento non esegue immediatamente kickstart -k sul Gateway appena avviato. Se il Gateway continua a non diventare integro, il comando esce con codice diverso da zero e stampa il percorso del log di riavvio più istruzioni esplicite per riavvio, reinstallazione e rollback del pacchetto. Con --no-restart, la sostituzione del pacchetto viene comunque eseguita ma il servizio gestito non viene arrestato o riavviato, quindi il Gateway in esecuzione potrebbe mantenere il vecchio codice finché non lo riavvii manualmente.

# Flusso di checkout git

# Selezione del canale

• stable: esegue il checkout del tag non beta più recente, poi build e doctor.
• beta: preferisce il tag -beta più recente, ma ripiega sul tag stable più recente quando beta è assente o più vecchio.
• dev: esegue il checkout di main, poi fetch e rebase.

# Passaggi di aggiornamento

Sul canale di aggiornamento beta, le installazioni plugin npm e ClawHub tracciate che seguono la linea default/latest provano prima una release plugin @beta. Se il plugin non ha release beta, OpenClaw ripiega sulla spec default/latest registrata. Per i plugin npm, OpenClaw ripiega anche quando il pacchetto beta esiste ma fallisce la validazione dell'installazione. Versioni esatte e tag espliciti non vengono riscritti.

# Abbreviazione --update

openclaw --update viene riscritto in openclaw update (utile per shell e script launcher).

# Correlati

• openclaw doctor (propone di eseguire prima update sui checkout git)
• Canali di sviluppo
• Aggiornamento
• Riferimento CLI