Mettre à jour OpenClaw (Moltbot/Clawdbot) vers la dernière version

OpenClaw (anciennement Moltbot/Clawdbot) évolue rapidement. Cette vélocité est excellente pour les fonctionnalités, mais elle implique également des changements fréquents dans :

• le comportement d'orchestration de l'agent
• la logique de battement de cœur (vérifications rapides d'abord, appels de modèle uniquement si nécessaire)
• les noms des variables d'environnement
• le schéma de persistance et le flux de migration
• les hypothèses des contrats de plugins et d'outils

Si vous mettez à jour de manière informelle (git pull && restart), vous risquez des ruptures silencieuses : les travailleurs semblent sains mais cessent d'accomplir leurs tâches, les adaptateurs d'outils échouent en raison de la dérive de schéma, ou des pics de coûts apparaissent parce que les seuils de battement de cœur/modèle ont changé.

Ce guide vous propose une stratégie de mise à jour sécurisée pour la production, avec des commandes concrètes et des étapes de vérification.

Avant la mise à jour : identifiez la topologie de votre installation

La plupart des déploiements réels d'OpenClaw correspondent à l'un de ces schémas :

1. Docker en mode nœud unique (auto-hébergement rapide)
2. Pile Docker Compose (OpenClaw + DB + Redis + sidecars)
3. Systemd + venv (installation depuis les sources sur VPS)
4. Configuration hybride en périphérie (EC2 + Tailscale + plan de contrôle privé)

Votre plan de mise à jour doit correspondre à votre topologie car les mécanismes de retour arrière diffèrent.

• Docker/Compose : retour arrière via le re-blocage de l'image.
• Installation depuis les sources : retour arrière via un tag git + verrouillage des dépendances.
• Base de données gérée : le retour arrière de schéma peut ne pas être trivial.

Si vous n'avez pas documenté votre topologie actuelle, faites-le en premier.

Étape 1 : Figez votre version actuelle et capturez l'état d'exécution

Considérez ceci comme votre point de restauration.

A. Enregistrez les métadonnées de version/build

Image de conteneur

docker ps --format 'table {{.Names}}\t{{.Image}}'

Si OpenClaw expose un point de terminaison de version

curl -s http://localhost:8080/version | jq

Installation basée sur Git

cd /opt/openclaw git rev-parse --short HEAD git describe --tags --always

B. Instantané de l'environnement et de la configuration

cp /etc/openclaw/.env /backups/openclaw-env-$(date +%F).bak cp -r /etc/openclaw/config /backups/openclaw-config-$(date +%F)

Exportez également les références des secrets (pas les secrets bruts) et confirmez les fournisseurs de jetons, les paramètres de routage des modèles et les seuils de battement de cœur.

C. Sauvegarde des données persistantes

Pour Postgres :

bash pg_dump -Fc -h  -U   > /backups/openclaw-$(date +%F).dump
Pour Redis (si les files d'attente/points de contrôle avec état sont importants) :
bash redis-cli -h  BGSAVE

Si vous ignorez cette étape, vous n'avez pas de plan de retour arrière.

Étape 2 : Lisez les notes de version pour les indicateurs de migration et les changements de comportement

Compte tenu de l'évolution récente d'OpenClaw (y compris les refactorisations de l'ère du renommage), les notes de version incluent souvent des exigences uniques telles que :

• renommage de variable d'environnement (modèles CLAW_* en OPENCLAW_*)
• modifications des commandes de migration
• valeurs par défaut du planificateur de battement de cœur
• mises à jour du format de manifeste de l'outil/plugin
• dépréciations des interfaces d'adaptateurs de modèles plus anciens

Établissez une courte liste de contrôle à partir des notes de version :

• renommages de configuration requis
• commande de migration
• changements de file d'attente/sujet
• nouvelles sémantiques des points de terminaison de santé
• modifications des gardes de délai d'attente/coût par défaut

Étape 3 : Organisez la mise à jour dans un environnement de pré-production

Ne testez jamais en production en premier. Clonez la forme de votre déploiement.

Fidélité minimale de la pré-production :

• même écart de version OpenClaw (actuelle -> cible)
• même version majeure du moteur de base de données
• même backend de file d'attente
• mêmes adaptateurs de fournisseurs de modèles
• flux de travail réels représentatifs (au moins 5 à 10)

Si votre équipe dispose d'API autour d'OpenClaw (outils personnalisés, webhooks, contrôle de tâches), c'est là qu'Apidog aide immédiatement.

Utilisez Apidog pour :

• importer/mettre à jour vos définitions OpenAPI
• valider les contrats requête/réponse pour vos points de terminaison d'outils
• exécuter des tests de régression basés sur des scénarios avant le déploiement
• publier des documents interactifs pour les points de terminaison modifiés afin que les équipes frontend/QA s'alignent rapidement

Cela évite les incidents du type « OpenClaw a été mis à jour correctement, mais les intégrations sont cassées ».

Étape 4 : Mise à jour par type de déploiement

Option A : Docker Compose

Épinglez des tags explicites dans docker-compose.yml (évitez latest en production).

yaml services: openclaw: image: ghcr.io/openclaw/openclaw:v1.14.2 env_file: - .env depends_on: - postgres - redis

Processus de mise à jour :

bash docker compose pull openclaw docker compose up -d openclaw

Si les migrations sont séparées :

bash docker compose run --rm openclaw openclaw migrate

Ensuite, redémarrez les travailleurs :

bash docker compose up -d worker scheduler

Option B : Docker simple

bash docker pull ghcr.io/openclaw/openclaw:v1.14.2 docker stop openclaw docker rm openclaw

docker run -d
 --name openclaw
 --env-file /etc/openclaw/.env
 -p 8080:8080
 ghcr.io/openclaw/openclaw:v1.14.2

Exécutez la commande de migration si nécessaire.

Option C : Source + systemd

bash cd /opt/openclaw git fetch --tags git checkout v1.14.2

Reconstruire l'environnement

source .venv/bin/activate pip install -r requirements.txt

Migrer

openclaw migrate

Redémarrer

sudo systemctl restart openclaw-api openclaw-worker openclaw-scheduler

Vérifiez que les remplacements d'unités systemd correspondent toujours aux nouveaux arguments de la ligne de commande.

Étape 5 : Validez la santé au-delà de « le processus est démarré »

Un processus en cours d'exécution n'est pas un système d'agent sain.

Vérifications de santé à exécuter immédiatement

Activité/préparation de l'APIbash curl -f http://localhost:8080/health/livecurl -f http://localhost:8080/health/ready

Débit de la file d'attente

• mettre en file d'attente une tâche de test
• confirmer la réclamation du travailleur
• confirmer la latence d'achèvement

1. Comportement du battement de cœurÉtant donné les tendances récentes de conception du battement de cœur (vérifications rapides d'abord), assurez-vous que :

• les sondes rapides s'exécutent selon le calendrier
• les vérifications basées sur le modèle ne se déclenchent qu'aux seuils attendus
• pas d'appels LLM toujours actifs accidentels

Garde-fous de coût et de latenceVérifiez la télémétrie de jetons/coûts avant/après la mise à jour pour la même charge de travail de test.

Invocation de plugin/outilExécutez au moins un appel par adaptateur d'outil critique.

Étape 6 : Exécutez les tests de contrat d'API et de régression avec Apidog

C'est là que de nombreux opérateurs d'OpenClaw peuvent rapidement améliorer la fiabilité.

Si OpenClaw interagit avec des API internes (API de tâches, API d'outils, points de terminaison de rappel), utilisez Apidog comme passerelle de qualité :

• Conception : maintenez les schémas de points de terminaison alignés dans un flux de travail OpenAPI-first.
• Tests : créez des scénarios de test automatisés pour le succès, le délai d'attente, la réessai et les charges utiles mal formées.
• Mocking : utilisez des points de terminaison de mock intelligents pour tester le comportement d'OpenClaw même lorsque les outils en aval sont hors ligne.
• Documentation : générez automatiquement la documentation pour les contrats modifiés afin que les équipes cessent d'utiliser des exemples obsolètes.
• CI/CD : exécutez la suite de régression à chaque mise à jour de version avant la promotion du déploiement.

Modèle pratique :

1. Importez la collection/spécification actuelle dans Apidog.
2. Ajoutez des assertions pour les champs dont OpenClaw dépend (task_id, status, tool_result, correlation_id).
3. Ajoutez des cas négatifs (429, 500, délai d'attente).
4. Exécutez en CI sur la branche de mise à jour.
5. Bloquez la publication si des différences rompant le contrat apparaissent.

C'est beaucoup plus sûr que de tester manuellement deux points de terminaison après un redémarrage.

Étape 7 : Stratégie de déploiement en production

Pour les configurations à nœud unique, prévoyez une courte fenêtre de maintenance.

Pour les configurations multi-instances, effectuez un déploiement progressif/canary :

1. mettez à jour une instance d'API
2. mettez à jour un segment du pool de travailleurs
3. observez le taux d'erreur, le décalage de la file d'attente, les dépenses de jetons pendant 15 à 30 minutes
4. continuez le déploiement si stable

Surveillez ces métriques :

• taux de réussite des tâches
• volume de réessais
• croissance de la file d'attente des messages morts
• temps d'achèvement des tâches p95
• taux de requêtes LLM/utilisation des jetons

Un changement subtil de configuration peut passer les vérifications de santé mais dégrader le débit.

Problèmes et correctifs courants de mise à niveau

1) Travailleurs inactifs après un démarrage réussi de l'API

Cause : l'espace de noms/sujet de la file d'attente a changé ou le renommage de la variable d'environnement a été manqué.

Correction : comparez les anciens et nouveaux fichiers d'environnement et vérifiez les paramètres de préfixe de la file d'attente.

2) Les battements de cœur déclenchent des appels de modèle excessifs

Cause : les valeurs par défaut ont changé ; le seuil de vérification rapide n'est pas défini.

Correction : définissez explicitement les niveaux de battement de cœur et les limites d'escalade du modèle dans la configuration.

3) Échecs d'outils/plugins avec des erreurs de schéma

Cause : dérive du contrat de charge utile après la mise à niveau.

Correction : exécutez les tests de contrat Apidog ; mettez à jour les adaptateurs d'outils avec les nouveaux champs requis.

4) Pics de coût de jeton après la mise à niveau

Cause : politique de réessai + changements de battement de cœur + fenêtres de contexte plus longues.

Correction : limitez les réessais, appliquez une politique budgétaire, comparez les traces de requêtes avec la version précédente.

5) Confusion de renommage (Moltbot/Clawdbot/OpenClaw)

Cause : noms de packages mélangés, tags de conteneurs, ancienne documentation.

Correction : standardisez les manuels internes sur une seule source d'artefact canonique et une convention de tags.

Notes de sécurité et de réseau pour les auto-hébergeurs

De nombreux développeurs déploient OpenClaw sur EC2/VPS avec un accès de maillage privé (par exemple, topologie de type Tailscale). Lors des mises à jour :

• vérifiez que les règles de pare-feu n'ont pas régressé
• assurez-vous que les points de terminaison d'administration restent privés
• faites pivoter les clés API si la mise à jour a impliqué des changements de gestion des secrets
• validez la terminaison TLS après les échanges de conteneurs/images

Confirmez également que les listes blanches de rappel de webhook correspondent toujours à l'adresse IP de sortie ou à l'identité du tunnel.

Liste de contrôle recommandée pour les mises à jour en production

Utilisez ceci à chaque fois :

• Identifiez la version/le tag/le commit actuel
• Sauvegardez la DB + la configuration + les références d'environnement
• Lisez les notes de version et extrayez les actions de migration obligatoires
• Organisez la mise à jour dans un environnement de pré-production réaliste
• Exécutez les tests de régression et de contrat Apidog
• Effectuez un déploiement contrôlé en production (canary/progressif)
• Validez la file d'attente, le battement de cœur, l'exécution des outils et les métriques de coût
• Gardez la séquence de commande de retour arrière testée prête
• Documentez la version finale et les différences de configuration dans le manuel d'exploitation

La cohérence est plus importante que la vitesse.

Réflexions finales

Mettre à jour OpenClaw en toute sécurité est une discipline d'ingénierie, pas une simple commande. Le parcours de renommage de Moltbot/Clawdbot à OpenClaw reflète un projet qui évolue rapidement, et votre processus opérationnel doit suivre le rythme.

Si vous associez une méthode de déploiement/retour arrière solide à des tests de contrat d'API, vous éviterez la plupart des difficultés de mise à niveau. Apidog s'intègre naturellement ici : concevez et versionnez les contrats d'API, exécutez des vérifications de régression automatisées, simulez les dépendances pendant la mise en scène et publiez une documentation précise pour chaque interface qu'OpenClaw touche.

Si votre flux de travail de mise à jour actuel est principalement manuel, commencez petit : ajoutez un portail de pré-production et une suite de tests Apidog automatisée cette semaine. Ce seul changement est généralement rentable dès la prochaine version.