openclaw update

Aggiorna OpenClaw e passa tra i canali stable/extended-stable/beta/dev.

Se l'installazione è stata eseguita tramite npm/pnpm/bun (installazione globale, senza metadati git), gli aggiornamenti seguono il flusso del gestore di pacchetti descritto in Aggiornamento.

Utilizzo

openclaw updateopenclaw update statusopenclaw update repairopenclaw update wizardopenclaw update --channel extended-stableopenclaw update --channel betaopenclaw update --channel devopenclaw update --tag betaopenclaw update --tag mainopenclaw update --dry-runopenclaw update --no-restartopenclaw update --yesopenclaw update --acknowledge-clawhub-riskopenclaw update --jsonopenclaw --update

openclaw --update viene riscritto come openclaw update (utile per shell e script di avvio).

Opzioni

Non esiste alcun flag --verbose. Utilizzare --dry-run per visualizzare in anteprima le azioni pianificate, --json per ottenere risultati leggibili dalla macchina e openclaw update status --json solo per il canale e la disponibilità. Il livello di dettaglio della console del Gateway (--verbose) e il livello di log dei file (logging.level: "debug"/"trace") sono controlli indipendenti; consultare Log del Gateway.

update status

Mostra il canale di aggiornamento attivo, il tag/ramo/SHA git (solo per i checkout del codice sorgente) e la disponibilità degli aggiornamenti.

openclaw update statusopenclaw update status --jsonopenclaw update status --timeout 10

Per le installazioni di pacchetti extended-stable, lo stato esegue lo stesso selettore pubblico e la stessa verifica esatta del pacchetto dell'aggiornamento in primo piano. Può segnalare ahead of extended-stable quando la versione installata è più recente. Gli errori JSON includono registry.reason (selector_missing, selector_query_failed, exact_package_mismatch o unsupported_git_channel).

update repair

Esegue nuovamente la finalizzazione dell'aggiornamento dopo che il pacchetto core è già stato modificato, ma le successive operazioni di riparazione non sono state completate correttamente. Questo è il percorso di ripristino supportato quando openclaw update ha installato il nuovo pacchetto core, ma la sincronizzazione dei plugin successiva all'aggiornamento del core, i metadati dei plugin npm gestiti, l'aggiornamento del registro o la riparazione tramite Doctor non sono giunti a convergenza.

openclaw update repairopenclaw update repair --channel betaopenclaw update repair --acknowledge-clawhub-riskopenclaw update repair --json

update repair esegue openclaw doctor --fix, ricarica la configurazione riparata e i record di installazione, sincronizza i plugin monitorati per il canale di aggiornamento attivo, aggiorna le installazioni dei plugin npm gestiti, ripara i payload mancanti dei plugin configurati, aggiorna il registro dei plugin e scrive i metadati convergenti dei record di installazione. Non installa un nuovo pacchetto core e non riavvia il Gateway.

update wizard

Flusso interattivo per scegliere un canale di aggiornamento e confermare se riavviare successivamente il Gateway (l'impostazione predefinita prevede il riavvio). Se si seleziona dev senza un checkout git, viene proposta la creazione di un checkout.

Funzionamento

Il passaggio esplicito da un canale all'altro (--channel ...) mantiene inoltre allineato il metodo di installazione:

• dev -> assicura la presenza di un checkout git (valore predefinito ~/openclaw o $OPENCLAW_HOME/openclaw quando è impostato OPENCLAW_HOME; sostituibile con OPENCLAW_GIT_DIR), lo aggiorna e installa la CLI globale da tale checkout.
• stable -> esegue l'installazione da npm utilizzando latest.
• extended-stable -> risolve il selettore npm pubblico extended-stable, verifica il pacchetto esatto selezionato e installa quella versione esatta. Non utilizza un altro selettore come fallback e viene rifiutato per i checkout Git.
• beta -> preferisce il dist-tag npm beta, utilizzando come fallback latest quando la versione beta è assente o precedente alla versione stable corrente.

Passaggio di consegne per il riavvio

Il programma di aggiornamento automatico del core del Gateway (quando abilitato tramite configurazione) avvia il percorso di aggiornamento della CLI al di fuori del gestore delle richieste del Gateway attivo. Gli aggiornamenti tramite gestore di pacchetti update.run del piano di controllo e gli aggiornamenti supervisionati dei checkout git utilizzano lo stesso passaggio di consegne del servizio gestito, anziché sostituire l'albero dei pacchetti o ricompilare dist/ all'interno del processo Gateway attivo: il Gateway avvia un processo ausiliario separato e termina, quindi tale processo esegue openclaw update --yes --json all'esterno dell'albero dei processi del Gateway. Se il passaggio di consegne non è disponibile, update.run restituisce una risposta strutturata contenente il comando shell sicuro da eseguire manualmente.

Le selezioni extended-stable memorizzate ricevono suggerimenti di avvio in sola lettura e di aggiornamento ogni 24 ore quando update.checkOnStart è abilitato. Questi controlli non applicano mai un aggiornamento, non avviano un passaggio di consegne, non riavviano il Gateway, non usano il ritardo/jitter di stable né la cadenza di polling di beta. Restano supportati gli aggiornamenti espliciti in primo piano, gli aggiornamenti in primo piano senza argomenti con update.channel: "extended-stable" memorizzato, lo stato su richiesta e il relativo passaggio di consegne gestito del Gateway.

Quando è installato un servizio Gateway gestito locale e il riavvio è abilitato, gli aggiornamenti tramite gestore di pacchetti e checkout Git arrestano il servizio in esecuzione prima di sostituire l'albero dei pacchetti o modificare l'output del checkout/della build. Il programma di aggiornamento aggiorna quindi i metadati del servizio, riavvia il servizio e verifica il Gateway riavviato prima di segnalare Gateway: restarted and verified.. Gli aggiornamenti tramite gestore di pacchetti verificano inoltre che il Gateway riavviato segnali la versione del pacchetto prevista; gli aggiornamenti del checkout Git verificano l'integrità del gateway e la disponibilità del servizio dopo la nuova build.

Gli aggiornamenti tramite gestore di pacchetti normalmente continuano a usare il binario Node registrato nel servizio gestito. Se quel Node non può eseguire la release di destinazione, ma il Node della CLI corrente può farlo e viene dimostrato che il servizio appartiene al pacchetto in corso di aggiornamento, un aggiornamento con riavvio abilitato usa il Node corrente per la finalizzazione e riscrive i metadati del servizio affinché usino tale runtime. --no-restart non può riparare i metadati del servizio, pertanto la stessa incompatibilità del runtime causa l'arresto prima della modifica del pacchetto.

Su macOS, il controllo successivo all'aggiornamento verifica inoltre che LaunchAgent sia caricato/in esecuzione per il profilo attivo e che la porta di loopback configurata sia operativa. Se il plist è installato ma launchd non lo supervisiona, OpenClaw riesegue automaticamente il bootstrap di LaunchAgent e ripete i controlli di integrità/versione/ disponibilità del canale (un nuovo bootstrap carica direttamente il job RunAtLoad, quindi il ripristino non esegue immediatamente kickstart -k sul Gateway appena avviato). Se il Gateway continua a non diventare operativo, il comando termina con un codice diverso da zero e stampa il percorso del log di riavvio, oltre alle istruzioni per il riavvio, la reinstallazione e il rollback del pacchetto.

Se il riavvio non può essere eseguito, il comando stampa Gateway: restart skipped (...) o Gateway: restart failed: ... con un suggerimento per eseguire manualmente openclaw gateway restart. Con --no-restart, la sostituzione del pacchetto o la nuova build Git viene comunque eseguita, ma il servizio gestito non viene arrestato né riavviato, quindi il Gateway in esecuzione continua a usare il vecchio codice finché non viene riavviato manualmente.

Struttura della risposta del piano di controllo

Quando update.run viene eseguito tramite il piano di controllo del Gateway in un'installazione tramite gestore di pacchetti o in un checkout Git supervisionato, il gestore segnala l'avvio del passaggio di consegne separatamente dall'aggiornamento della CLI che continua dopo l'uscita del Gateway:

• ok: true, result.status: "skipped", result.reason: "managed-service-handoff-started" e handoff.status: "started": il Gateway ha creato il passaggio di consegne del servizio gestito e ha pianificato il proprio riavvio, in modo che l'helper separato possa eseguire openclaw update --yes --json al di fuori del processo del servizio attivo.
• ok: false, result.reason: "managed-service-handoff-unavailable" e handoff.status: "unavailable": OpenClaw non ha potuto trovare un confine di servizio supervisionato e un'identità persistente del servizio per un passaggio di consegne sicuro (ad esempio, il passaggio di consegne di systemd richiede l'identità dell'unità OPENCLAW_SYSTEMD_UNIT, non soltanto indicatori ambientali dei processi systemd). La risposta include handoff.command, il comando della shell da eseguire dall'esterno del Gateway.
• ok: false, result.reason: "managed-service-handoff-failed": il Gateway ha tentato di creare il passaggio di consegne, ma non è riuscito ad avviare l'helper separato.

Il payload sentinel viene scritto prima dell'uscita del Gateway e il passaggio di consegne della CLI aggiorna lo stesso sentinel di riavvio al termine dei controlli di integrità successivi al riavvio del servizio gestito. Durante il passaggio di consegne, il sentinel può contenere stats.reason: "restart-health-pending" senza alcuna continuazione in caso di successo; il Gateway riavviato lo interroga ed esegue la continuazione soltanto dopo che la CLI ha verificato l'integrità del servizio e riscritto il sentinel con il risultato finale ok. openclaw status e openclaw status --all mostrano una riga Update restart mentre tale sentinel è in sospeso o non è riuscito, mentre update.status aggiorna e restituisce il sentinel più recente.

Flusso del checkout Git

Selezione del canale

• stable: esegue il checkout del tag non beta più recente, quindi esegue la build e doctor.
• beta: preferisce il tag -beta più recente, ripiegando sul tag stable più recente quando beta è assente o meno recente.
• dev: esegue il checkout di main, quindi esegue il fetch e il rebase.
• extended-stable: non supportato per i checkout Git; non viene eseguita alcuna modifica del checkout.

Passaggi dell'aggiornamento

Dettagli della sincronizzazione dei plugin

Sul canale beta, le installazioni dei plugin npm e ClawHub monitorate che seguono la linea predefinita/latest provano prima una release @beta del plugin. Se il plugin non dispone di una release beta, OpenClaw ripiega sulla specifica predefinita/latest registrata e segnala un avviso. Per i plugin npm, OpenClaw ripiega inoltre quando il pacchetto beta esiste ma non supera la convalida dell'installazione. Questi avvisi di fallback non causano il fallimento dell'aggiornamento principale. Le versioni esatte e i tag espliciti non vengono mai riscritti.

Dopo il completamento di un aggiornamento extended-stable del core, l'integrità e la convergenza dei plugin successive al core hanno come destinazione i plugin npm ufficiali idonei nella versione esatta del core installato. Per l'intento predefinito/latest, OpenClaw non interroga @extended-stable del plugin né ripiega su latest di npm; ricava la versione del pacchetto dal core installato. Le versioni associate esplicitamente, i tag espliciti diversi da latest, i pacchetti di terze parti e le origini diverse da npm mantengono l'intento esistente.

Per le installazioni tramite gestore di pacchetti, openclaw update risolve la versione del pacchetto di destinazione prima di invocare il gestore di pacchetti. Le installazioni globali npm usano un'installazione preliminare: OpenClaw installa il nuovo pacchetto in un prefisso npm temporaneo, consente al pacchetto candidato di convalidare la versione Node dell'host durante preinstall e verifica lì l'inventario dist incluso nel pacchetto. Una protezione di completamento inclusa nel pacchetto rimane fuori da tale inventario finché preinstall non riesce, in modo che anche i gestori di pacchetti che ignorano gli script del ciclo di vita si arrestino prima dell'attivazione. Su npm 12 e versioni successive, il programma di aggiornamento approva soltanto il ciclo di vita del pacchetto OpenClaw candidato; gli script delle dipendenze transitive rimangono bloccati. OpenClaw scambia quindi l'albero dei pacchetti pulito nel prefisso globale reale. Se la verifica non riesce, doctor successivo all'aggiornamento, la sincronizzazione dei plugin e il riavvio non vengono eseguiti dall'albero sospetto. Anche quando la versione installata corrisponde già alla destinazione, il comando aggiorna l'installazione globale del pacchetto, quindi esegue la sincronizzazione dei plugin, un aggiornamento del completamento dei comandi principali e il riavvio. Ciò mantiene i componenti ausiliari inclusi nel pacchetto e i record dei plugin appartenenti al canale allineati con la build OpenClaw installata, lasciando le ricostruzioni complete del completamento dei comandi dei plugin alle esecuzioni esplicite di openclaw completion --write-state.

Correlati

• openclaw doctor (propone di eseguire prima l'aggiornamento nei checkout Git)
• Canali di sviluppo
• Aggiornamento
• Riferimento della CLI