Aggiornamento

OpenClaw si muove velocemente (pre “1.0”). Tratta gli aggiornamenti come il deploy dell’infrastruttura: aggiorna → esegui i controlli → riavvia (o usa openclaw update, che riavvia) → verifica.

Consigliato: riesegui l’installer dal sito web (aggiornamento in-place)

Il percorso di aggiornamento preferito e rieseguire l’installer dal sito web. Rileva le installazioni esistenti, aggiorna in-place ed esegue openclaw doctor quando necessario.

curl -fsSL https://openclaw.ai/install.sh | bash

Note:

• Aggiungi --no-onboard se non vuoi che il wizard di onboarding venga rieseguito.

• Per installazioni dal sorgente, usa:

  curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard

  L’installer fara git pull --rebase solo se il repo e pulito.

• Per installazioni globali, lo script usa npm install -g openclaw@latest internamente.

Prima di aggiornare

• Sappi come hai installato: globale (npm/pnpm) vs dal sorgente (git clone).
• Sappi come gira il tuo Gateway: terminale in primo piano vs servizio supervisionato (launchd/systemd).
• Fai uno snapshot della tua personalizzazione:
  • Config: ~/.openclaw/openclaw.json
  • Credenziali: ~/.openclaw/credentials/
  • Workspace: ~/.openclaw/workspace

Aggiornamento (installazione globale)

Installazione globale (scegli uno):

npm i -g openclaw@latest

pnpm add -g openclaw@latest

Non consigliamo Bun per il runtime del Gateway (bug WhatsApp/Telegram).

Per cambiare canale di aggiornamento (installazioni git + npm):

openclaw update --channel beta
openclaw update --channel dev
openclaw update --channel stable

Usa --tag <dist-tag|version> per un tag/versione una tantum.

Vedi Canali di sviluppo per la semantica dei canali e le note di rilascio.

Auto-updater core (opzionale)

L’auto-updater e disattivato di default ed e una funzionalita core del Gateway (non un plugin).

{
  "update": {
    "channel": "stable",
    "auto": {
      "enabled": true,
      "stableDelayHours": 6,
      "stableJitterHours": 12,
      "betaCheckIntervalHours": 1
    }
  }
}

Comportamento:

• stable: quando viene vista una nuova versione, OpenClaw attende stableDelayHours e poi applica un jitter deterministico per installazione in stableJitterHours (rollout distribuito).
• beta: controlla con cadenza betaCheckIntervalHours (default: oraria) e applica quando un aggiornamento e disponibile.
• dev: nessuna applicazione automatica; usa openclaw update manuale.

Poi:

openclaw doctor
openclaw gateway restart
openclaw health

Note:

• Se il tuo Gateway gira come servizio, openclaw gateway restart e preferito rispetto a terminare i PID.
• Se sei ancorato a una versione specifica, vedi “Rollback / pinning” sotto.

Aggiornamento (openclaw update)

Per installazioni dal sorgente (checkout git), preferisci:

openclaw update

Esegue un flusso di aggiornamento ragionevolmente sicuro:

• Richiede un worktree pulito.
• Passa al canale selezionato (tag o branch).
• Recupera + rebase rispetto all’upstream configurato (canale dev).
• Installa le dipendenze, compila, costruisce la Control UI, ed esegue openclaw doctor.
• Riavvia il gateway di default (usa --no-restart per saltare).

Se hai installato via npm/pnpm (senza metadati git), openclaw update provera ad aggiornare tramite il tuo package manager. Se non riesce a rilevare l’installazione, usa “Aggiornamento (installazione globale)”.

Aggiornamento (dal sorgente)

Dal checkout del repo:

Preferito:

openclaw update

Manuale (equivalente):

git pull
pnpm install
pnpm build
pnpm ui:build # installa automaticamente le dipendenze UI alla prima esecuzione
openclaw doctor
openclaw health

Note:

• pnpm build e importante quando esegui il binario pacchettizzato openclaw (openclaw.mjs) o usi Node per eseguire dist/.
• Se esegui da un checkout del repo senza installazione globale, usa pnpm openclaw ... per i comandi CLI.
• Se esegui direttamente da TypeScript (pnpm openclaw ...), una ricompilazione di solito non e necessaria, ma le migrazioni della configurazione si applicano comunque → esegui doctor.

Esegui sempre: openclaw doctor

Doctor e il comando di “aggiornamento sicuro”. E intenzionalmente noioso: ripara + migra + avvisa.

Nota: se sei su un’installazione dal sorgente (checkout git), openclaw doctor offrira di eseguire openclaw update prima.

Cose tipiche che fa:

• Migra chiavi di configurazione deprecate / posizioni legacy dei file di configurazione.
• Controlla le policy DM e avvisa su impostazioni “open” rischiose.
• Controlla la salute del Gateway e puo offrire di riavviare.
• Rileva e migra servizi gateway piu vecchi (launchd/systemd; legacy schtasks) ai servizi OpenClaw attuali.
• Su Linux, assicura il lingering systemd dell’utente (cosi il Gateway sopravvive al logout).

Dettagli: Doctor

Avvia / ferma / riavvia il Gateway

CLI (funziona indipendentemente dal sistema operativo):

openclaw gateway status
openclaw gateway stop
openclaw gateway restart
openclaw gateway --port 18789
openclaw logs --follow

Se usi un supervisore:

• macOS launchd (LaunchAgent dall’app): launchctl kickstart -k gui/$UID/ai.openclaw.gateway (usa ai.openclaw.<profile>; il legacy com.openclaw.* funziona ancora)
• Linux servizio utente systemd: systemctl --user restart openclaw-gateway[-<profile>].service
• Windows (WSL2): systemctl --user restart openclaw-gateway[-<profile>].service
  • launchctl/systemctl funzionano solo se il servizio e installato; altrimenti esegui openclaw gateway install.

Runbook + etichette di servizio esatte: Runbook del gateway

Rollback / pinning (quando qualcosa si rompe)

Pin (installazione globale)

Installa una versione nota funzionante (sostituisci <version> con l’ultima funzionante):

npm i -g openclaw@<version>

pnpm add -g openclaw@<version>

Suggerimento: per vedere la versione attualmente pubblicata, esegui npm view openclaw version.

Poi riavvia + riesegui doctor:

openclaw doctor
openclaw gateway restart

Pin (sorgente) per data

Scegli un commit da una data (esempio: “stato di main al 2026-01-01”):

git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"

Poi reinstalla le dipendenze + riavvia:

pnpm install
pnpm build
openclaw gateway restart

Se vuoi tornare all’ultimo piu tardi:

git checkout main
git pull

Se sei bloccato

• Esegui openclaw doctor di nuovo e leggi l’output attentamente (spesso ti dice la soluzione).
• Controlla: Risoluzione problemi
• Chiedi su Discord: https://discord.gg/clawd