Vous utilisez déjà une ancienne version d'OpenClaw et voulez passer à 2026.3.x mais craignez l'incompatibilité de config ? 2026.3.x a modifié la logique de config par défaut (tools.profile, dispatch ACP, etc.), les anciens tutoriels ne s'appliquent plus. Ce guide explique pourquoi migrer, les étapes obligatoires avant mise à jour (sauvegarde et vérifications), le flux de migration en 5 étapes (install/mise à jour → assistant onboard → API et permissions → démon → vérification), et les pièges courants — retrait de permissions, conflits de ports, variables d'environnement — ainsi que des conseils pour Mac distant VNC, pour éviter les mauvaises surprises.
① Pourquoi migrer vers 2026.3.x ? Anciens tutoriels et changements principaux
2026.3.x a durci la sécurité et les valeurs par défaut : en installation neuve tools.profile est par défaut messaging (outils messagerie/session uniquement). Si vous dépendez de la lecture/écriture de fichiers ou de l'exécution terminal, vous aurez « pas de permission » après mise à jour. Le dispatch ACP est activé par défaut et peut changer le routage multi-agents ; l'enregistrement HTTP des plugins a aussi changé. Réutiliser l'ancienne config ou copier les anciens tutoriels conduit souvent à un comportement cassé après mise à jour.
| Changement | Ancien / état courant | 2026.3.x défaut / recommandation |
|---|---|---|
| tools.profile | Non défini ou coding/full | Nouvelle install par défaut messaging ; mettre coding ou full si lecture/écriture/exécution nécessaires |
| acp.dispatch | Souvent non défini | Par défaut enabled ; désactiver si vous voulez seulement /acp sans routage auto |
| Enregistrement HTTP plugins | registerHttpHandler etc. | Comportement d'enregistrement modifié ; vérifier le code et la doc des plugins |
② Avant la mise à jour : sauvegarde, version, dépendances
Faire ces trois points avant la mise à jour évite un échec ou une perte de config sans rollback possible.
Sauvegarder config et workspace
Copier ~/.openclaw/openclaw.json et ~/.openclaw/workspace/ dans un endroit sûr. Lors d'un déplacement vers une nouvelle machine, copier les deux puis exécuter openclaw doctor et openclaw gateway restart.
Version et dépendances
Vérifier la version Node (20+ recommandé) ; openclaw doctor pour migration et correctifs ; openclaw config validate pour la syntaxe de la config.
Vérifier tools et ACP actuels
Exécuter openclaw config get tools pour le profile actuel ; si vous utilisez ACP, confirmer acp.dispatch.enabled.
③ Migration en 5 étapes : install/mise à jour → assistant onboard → API et permissions → démon → vérification
Étape 1 : Mettre à jour vers 2026.3.x avec npm install -g openclaw@latest ou le script d'installation officiel.
Étape 2 : Lancer openclaw onboard pour l'assistant de config ; choisir usage (personnel/équipe), type d'install (QuickStart etc.), modèle et API IA (OpenAI/Claude/tiers).
Étape 3 : Dans ~/.openclaw/openclaw.json définir ou confirmer tools.profile à coding (fichier et exécution normaux) ou full ; pour désactiver le routage auto ACP, mettre acp.dispatch.enabled: false.
Étape 4 : Si vous utilisez le démon/LaunchAgent, exécuter openclaw onboard --install-daemon ou configurer le démon selon la doc, et s'assurer que plist/variables d'environnement contiennent PATH et variables API.
Étape 5 : Exécuter openclaw gateway restart, puis openclaw health pour vérifier le service ; sur Mac distant, se connecter en VNC et faire un cycle complet pour s'assurer qu'aucune demande de permission ne reste en attente.
④ Pièges : retrait de permissions, conflits de ports, variables d'environnement, Mac distant VNC
Retrait de permissions : Si après mise à jour vous voyez « pas de permission lecture/écriture/exécution », tools.profile est probablement sur messaging ; repasser à coding ou full et redémarrer le gateway.
Conflits de ports : Si un port est utilisé, lsof -i :port pour trouver le processus, l'arrêter ou changer la config pour un autre port.
Variables d'environnement : Au démarrage via launchd ou PM2, définir explicitement PATH et variables API dans le plist ou la config ecosystem, sinon le terminal interactif peut marcher mais le service en arrière-plan échoue.
Mac distant VNC : Toujours se connecter en VNC pour la mise à jour et la première autorisation afin de gérer les dialogues système et Keychain. Après la mise à jour vous pouvez utiliser SSH pour l'automatisation. Faire la mise à jour en SSH seul peut laisser les dialogues non cliquables et bloquer le processus.
openclaw doctor après la mise à jour pour appliquer migration et correctifs ; lors d'un déplacement vers une nouvelle machine, copier ~/.openclaw/ et ~/.openclaw/workspace/ pour conserver config, état des canaux et identifiants.⑤ FAQ : rollback, multi-instance, liens vers nos articles dépannage
Comment faire un rollback ? Si vous avez une sauvegarde de openclaw.json et du workspace, les restaurer, installer l'ancienne version npm et redémarrer le service ; sans sauvegarde il faudra reconfigurer selon la nouvelle logique.
Migration multi-instance ? Chaque instance a son répertoire de config ; sauvegarder et mettre à jour chacune séparément et vérifier, en distinguant port et profile.
Articles connexes sur ce site : Pour les erreurs d'installation ou d'exécution voir OpenClaw erreurs courantes et dépannage ; pour les dialogues d'autorisation sur Mac distant voir OpenClaw VNC approbation et isolation sécurité ; pour le choix d'environnement voir OpenClaw v2026.3.7 choix d'environnement.
Pourquoi mettre à jour OpenClaw sur Mac distant avec VNC est plus simple
La migration 2026.3.x implique plusieurs « premières exécutions » et des dialogues possibles de permissions système et Keychain. En SSH seul vous ne pouvez pas cliquer sur ces dialogues, le processus peut rester bloqué. Sur un Mac distant VNC vous pouvez terminer onboard, gérer les dialogues et vérifier openclaw health et les logs comme en local, le parcours de mise à jour est clair et le dépannage plus rapide. Pour éviter les « ne démarre pas après mise à jour » ou « permissions incohérentes », faire la mise à jour et la vérification sur un nœud Mac distant VNCMac, puis utiliser SSH pour l'automatisation au quotidien si besoin — souvent le plus fiable et le plus rapide.