Mise à jour

openclaw update

Mettre à jour OpenClaw en toute sécurité et basculer entre les canaux stable/beta/dev.

Si vous avez installé via npm/pnpm/bun (installation globale, sans métadonnées git), les mises à jour se font via le flux du gestionnaire de paquets dans Mise à jour.

Utilisation

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

Options

• --no-restart : ignorer le redémarrage du service Gateway après une mise à jour réussie. Les mises à jour du gestionnaire de paquets qui redémarrent le Gateway vérifient que le service redémarré signale la version mise à jour attendue avant que la commande ne réussisse.
• --channel <stable|beta|dev> : définir le canal de mise à jour (git + npm ; persisté dans la configuration).
• --tag <dist-tag|version|spec> : remplace la cible du paquet pour cette mise à jour uniquement. Pour les installations de paquets, main correspond à github:openclaw/openclaw#main ; les spécifications de source GitHub/git sont empaquetées dans une archive tar temporaire avant l’installation globale npm intermédiaire.
• --dry-run : prévisualiser les actions de mise à jour prévues (canal/tag/cible/flux de redémarrage) sans écrire la configuration, installer, synchroniser les plugins ou redémarrer.
• --json : imprime du JSON UpdateRunResult lisible par la machine, y compris postUpdate.plugins.warnings lorsque des plugins gérés corrompus ou non chargeables nécessitent une réparation après la réussite de la mise à jour du cœur, les détails de repli du plugin du channel bêta lorsqu’un plugin n’a pas de version bêta, et postUpdate.plugins.integrityDrifts lorsqu’une dérive d’artefact de plugin npm est détectée lors de la synchronisation des plugins post-mise à jour.
• --timeout <seconds> : délai d’attente par étape (par défaut 1800s).
• --yes : ignorer les invites de confirmation (par exemple confirmation de rétrogradation).

openclaw update n’a pas d’option --verbose. Utilisez --dry-run pour prévisualiser les actions planifiées de channel/tag/install/restart, --json pour des résultats lisibles par machine, et openclaw update status --json lorsque vous avez uniquement besoin des détails de canal et de disponibilité. Si vous déboguez les journaux Gateway lors d’une mise à jour, la verbosité de la console et le niveau de journalisation fichier sont distincts : Gateway --verbose affecte la sortie terminal/WebSocket, tandis que les journaux fichier nécessitent logging.level: "debug" ou "trace" dans la configuration. Voir Journalisation Gateway.

Note

En mode Nix (

OPENCLAW_NIX_MODE=1

), les exécutions modifiant

openclaw update

sont désactivées. Mettez plutôt à jour la source Nix ou l’entrée de flake pour cette installation ; pour nix-openclaw, utilisez le

Quick Start

orienté agent.

openclaw update status

et

openclaw update --dry-run

restent en lecture seule.

Warning

Les rétrogradations nécessitent une confirmation car les anciennes versions peuvent casser la configuration.

update status

Affiche le canal de mise à jour actif + la balise/branche/SHA git (pour les checkouts source), ainsi que la disponibilité de la mise à jour.

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

Options :

• --json : imprime l’état JSON lisible par machine.
• --timeout <seconds> : délai d’attente pour les vérifications (par défaut 3s).

update wizard

Flux interactif pour choisir un canal de mise à jour et confirmer s’il faut redémarrer le Gateway après la mise à jour (par défaut, redémarrage). Si vous sélectionnez dev sans un checkout git, il propose d’en créer un.

Options :

• --timeout <seconds> : délai d’attente pour chaque étape de mise à jour (par défaut 1800)

Ce qu’il fait

Lorsque vous changez de canal explicitement (--channel ...), OpenClaw maintient également la méthode d’installation alignée :

• dev → assure un git checkout (par défaut : ~/openclaw, ou $OPENCLAW_HOME/openclaw lorsque OPENCLAW_HOME est défini ; remplacer avec OPENCLAW_GIT_DIR), le met à jour, et installe le CLI global depuis ce checkout.
• stable → installe depuis npm en utilisant latest.
• beta → préfère le dist-tag npm beta, mais revient à latest lorsque la version bêta est manquante ou plus ancienne que la version stable actuelle.

Le mécanisme de mise à jour automatique du cœur du Gateway (lorsqu’il est activé via la configuration) lance le chemin de mise à jour du CLI en dehors du gestionnaire de requêtes du Gateway en direct. Les mises à jour du gestionnaire de paquets update.run du plan de contrôle utilisent également un transfert de service géré au lieu de remplacer l’arborescence des paquets à l’intérieur du processus du Gateway en direct. Le Gateway démarre un assistant détaché, se ferme, et l’assistant exécute le chemin normal du CLI openclaw update --yes --json à partir de l’extérieur de l’arborescence des processus du Gateway. Si ce transfert n’est pas disponible, update.run renvoie une réponse structurée avec la commande shell sûre à exécuter manuellement.

Pour les installations par gestionnaire de paquets, openclaw update résout la version du paquet cible avant d’invoquer le gestionnaire de paquets. Les installations globales npm utilisent une installation calendée : OpenClaw installe le nouveau paquet dans un préfixe npm temporaire, vérifie l’inventaire dist empaqueté à cet endroit, puis échange cette arborescence de paquets propre dans le préfixe global réel. Si la vérification échoue, les travaux de docteur post-mise à jour, de synchronisation des plugins et de redémarrage ne s’exécutent pas à partir de l’arborescence suspecte. Même lorsque la version installée correspond déjà à la cible, la commande rafraîchit l’installation globale du paquet, puis exécute la synchronisation des plugins, un rafraîchissement de la complétion des commandes principales, et les travaux de redémarrage. Cela maintient les sidecars empaquetés et les enregistrements de plugins détenus par le channel alignés avec le build OpenClaw installé tout en laissant les reconstructions complètes de la complétion des commandes de plugins aux exécutions explicites de openclaw completion --write-state.

Lorsqu’un service Gateway géré localement est installé et que le redémarrage est activé, les mises à jour via le gestionnaire de packages arrêtent le service en cours avant de remplacer l’arborescence des packages, puis actualisent les métadonnées du service à partir de l’installation mise à jour, redémarrent le service et vérifient que le Gateway redémarré signale la version attendue avant de signaler GatewayGatewayGateway: restarted and verified.macOSOpenClaw. Sur macOS, la vérification post-mise à jour s’assure également que le LaunchAgent est chargé/en cours d’exécution pour le profil actif et que le port de bouclage configuré est sain. Si le plist est installé mais que launchd ne le supervise pas, OpenClaw ré-amorce automatiquement le LaunchAgent, puis relance les vérifications de santé/version/disponibilité du canal. Un amorçage frais charge directement la tâche RunAtLoad, la récupération de mise à jour ne kickstart -kGatewayGateway donc pas immédiatement le Gateway nouvellement spawned. Si le Gateway ne devient toujours pas sain, la commande se termine avec un code non nul et affiche le chemin du journal de redémarrage ainsi que des instructions explicites de redémarrage, de réinstallation et de retour de version du package. Si le redémarrage ne peut pas être exécuté, la commande affiche Gateway: restart skipped (...) ou Gateway: restart failed: ... avec un indice de openclaw gateway restart manuel. Avec --no-restartGateway, le remplacement du package s’effectue toujours, mais le service géré n’est ni arrêté ni redémarré, le Gateway en cours d’exécution peut donc conserver l’ancien code jusqu’à ce que vous le redémarriez manuellement.

Forme de la réponse du plan de contrôle

Lorsque update.runGatewayCLIGateway est appelé via le plan de contrôle du Gateway sur une installation par gestionnaire de packages, le gestionnaire signale l’initiation du transfert séparément de la mise à jour CLI qui se poursuit après la fermeture du Gateway :

• ok: true, result.status: "skipped", result.reason: "managed-service-handoff-started", et handoff.status: "started"Gateway signifient que le Gateway a créé le transfert de service géré et planifié son propre redémarrage pour que l’assistant détaché puisse exécuter openclaw update --yes --json en dehors du processus de service en direct.
• ok: false, result.reason: "managed-service-handoff-unavailable", et handoff.status: "unavailable" signifient que OpenClaw n’a pas pu trouver de limite de service de supervision pour un transfert sécurisé. La réponse inclut handoff.command, la commande shell à exécuter en dehors du Gateway.
• ok: false, result.reason: "managed-service-handoff-failed" signifie que le Gateway a tenté de créer le transfert mais n’a pas pu générer l’assistant détaché.

La charge utile sentinel est toujours écrite avant que le Gateway ne quitte, et le transfert CLI met à jour la même sentinelle de redémarrage une fois les contrôles de santé du redémarrage du service géré terminés. Pendant le transfert, la sentinelle peut porter stats.reason: "restart-health-pending" sans continuation de succès ; le Gateway redémarré continue de l’interroger et ne déclenche la continuation qu’après que le CLI a vérifié la santé du service et réécrit la sentinelle avec le résultat final ok. openclaw status et openclaw status --all affichent une ligne Update restart tant que cette sentinelle est en attente ou a échoué, et update.status renvoie la dernière sentinelle mise en cache.

Flux de récupération Git

Sélection du canal

• stable : extraire le dernier tag non-bêta, puis construire et vérifier.
• beta : préférer le dernier tag -beta, mais revenir au dernier tag stable lorsque la bêta est manquante ou obsolète.
• dev : extraire main, puis récupérer et rebaser.

Étapes de mise à jour

1. Vérifier l'arbre de travail propre

   Nécessite aucune modification non commitée.

2. Changer de canal

   Bascule vers le canal sélectionné (balise ou branche).

3. Récupérer en amont

   Dev uniquement.

4. Préflight build (dev only)

   Exécute la build TypeScript dans un arbre de travail temporaire. Si la pointe échoue, remonte jusqu’à 10 commits pour trouver le dernier commit constructible. Définissez OPENCLAW_UPDATE_PREFLIGHT_LINT=1 pour également exécuter le lint pendant cette pré-vérification ; le lint s’exécute en mode série contraint car les hôtes de mise à jour utilisateur sont souvent plus petits que les runners CI.

5. Rebase

   Effectue un rebase sur le commit sélectionné (dev uniquement).

6. Installer les dépendances

   Utilise le gestionnaire de paquets du dépôt. Pour les extraits pnpm, le programme de mise à jour amorce pnpm à la demande (via corepack d’abord, puis un npm install pnpm@11 temporaire) au lieu d’exécuter npm run build dans un espace de travail pnpm.

7. Construire l'interface de contrôle

   Construit la passerelle et l’interface de contrôle.

8. Exécuter le docteur

   openclaw doctor s’exécute en tant que vérification finale de la mise à jour sécurisée.

9. Synchroniser les plugins

   Synchronise les plugins vers le channel actif. Dev utilise les plugins groupés ; stable et bêta utilisent npm. Met à jour les installations de plugins suivies.

Sur le canal de mise à jour bêta, les installations de plugins suivis via npm et ClawHub qui suivent la ligne par défaut/dernière essaient d’abord une version de plugin @beta. Si le plugin n’a pas de version bêta, OpenClaw revient à la spécification par défaut/dernière enregistrée et signale cela comme un avertissement. Pour les plugins npm, OpenClaw revient également lorsque le paquet bêta existe mais échoue à la validation de l’installation. Ces avertissements de repli de plugins ne font pas échouer la mise à jour principale. Les versions exactes et les balises explicites ne sont pas réécrites.

Warning

Si une mise à jour de plugin npm épinglée exacte résout en un artefact dont l’intégrité diffère de l’enregistrement d’installation stocké,

openclaw update

abandonne cette mise à jour d’artefact de plugin au lieu de l’installer. Réinstallez ou mettez à jour le plugin explicitement uniquement après avoir vérifié que vous faites confiance au nouvel artefact.

Note

Les échecs de synchronisation des plugins après mise à jour, qui sont limités à un plugin géré et que le chemin de synchronisation peut contourner (par exemple, un registre npm inaccessible pour un plugin non essentiel), sont signalés sous forme d’avertissements après la réussite de la mise à jour du cœur. Le résultat JSON conserve le status: "ok" de mise à jour de premier niveau et signale des postUpdate.plugins.status: "warning" avec des conseils openclaw doctor --fix et `openclaw plugins inspect

—runtime —json. Les exceptions inattendues du programme de mise à jour ou de la synchronisation font toujours échouer le résultat de la mise à jour. Corrigez l'erreur d'installation ou de mise à jour du plugin, puis réexécutez openclaw doctor —fixouopenclaw update`.

Après l’étape de synchronisation par plugin, openclaw update exécute un passage obligatoire de convergence post-core avant le redémarrage de la passerelle : il répare les charges utiles de plugin configurées manquantes, valide chaque enregistrement d’installation suivie active sur le disque et vérifie statiquement que son package.json est analysable (et que tout main déclaré explicitement existe). Les échecs de ce passage — et un instantané de configuration OpenClaw non valide — renvoient postUpdate.plugins.status: "error" et basculent le status de mise à jour de premier niveau sur "error", de sorte que openclaw update se termine avec un code non nul et la passerelle n’est pas redémarrée avec un ensemble de plugins non vérifié. L’erreur comprend des lignes postUpdate.plugins.warnings[].guidance structurées pointant vers openclaw doctor --fix et `openclaw plugins inspect

—runtime —jsonpour le suivi. Les entrées de plugin désactivées et les enregistrements qui ne sont pas des cibles de synchronisation officielles liées à une source approuvée sont ignorés ici, reflétant la stratégieskipDisabledPlugins` utilisée par la vérification des charges utiles manquantes, de sorte qu’un enregistrement de plugin désactivé obsolète ne peut pas bloquer une mise à jour par ailleurs valide.

Lorsque la Gateway mise à jour démarre, le chargement des plugins est en vérification uniquement : le démarrage n’exécute pas les gestionnaires de packages ni ne modifie les arbres de dépendances. Les redémarrages update.run du gestionnaire de packages sont transmis au chemin de service géré de la CLI, de sorte que l’échange de packages se produit en dehors de l’ancien processus de la Gateway et les contrôles de santé du service décident si la mise à jour peut être signalée comme complète.

Si l’amorçage pnpm échoue toujours, le programme de mise à jour s’arrête prématurément avec une erreur spécifique au gestionnaire de packages au lieu d’essayer npm run build dans l’extraction.

Raccourci --update

openclaw --update se réécrit en openclaw update (utile pour les shells et les scripts de lancement).

Connexes

• openclaw doctor (propose de lancer d’abord la mise à jour sur les extraits git)
• Canaux de développement
• Mise à jour
• Référence CLI