OpenClaw 2026 : mise à niveau majeure après le 22.03.2026 — doctor, migration Plugin SDK et variables d'environnement OPENCLAW_* (SSH Mac distant reproductible)

Ce qui casse le plus souvent après le 22.03.2026

On observe trois familles d'erreurs : environnements launchd/LaunchAgent figés qui ne voient jamais les nouvelles variables, extensions qui ciblent encore l'ancienne surface de hooks pré-SDK, et configurations « silencieusement » invalides que les anciennes versions toléraient. Pour la performance bare metal et l'hébergement dédié, voir aussi Performance OpenClaw 2026 : pourquoi le Mac mini bare metal reste la référence pour ClawHub et NanoClaw.

• Garde-fous doctor : les contrôles de santé échouent désormais en mode strict lorsque les manifestes de plugins ou les profils API sont incomplets.
• ABI des plugins : les entrées héritées extensions/*.js sans version SDK déclarée sont ignorées ou font échouer bruyamment le chargement.
• Espace de noms des variables : les alias dépréciés disparaissent du chemin de recherche par défaut ; seule la famille OPENCLAW_* est garantie stable entre versions mineures.

Checklist SSH sur Mac distant (reproductible)

Exécutez d'abord tout dans une session SSH interactive. Les shells non interactifs de la CI omettent souvent votre profil — c'est précisément là que les services macOS et cron perdent les variables.

1. ssh utilisateur@votre-mac — privilégiez un compte d'automatisation avec un répertoire personnel connu.
2. Vérifiez le shell : echo $SHELL et chargez le même fichier que votre démon (~/.zprofile / ~/.bash_profile).
3. Épinglez le runtime : notez openclaw --version (ou l'équivalent de votre gestionnaire de paquets) avant et après la mise à niveau.
4. Mettez à niveau sur place (npm, script d'installation ou archive — comme lors du provisionnement initial), puis ouvrez une nouvelle session SSH avant de lancer doctor.
5. Exportez ou sourcez les variables OPENCLAW_* dans le même fichier que le wrapper LaunchAgent référencé dans ProgramArguments.

Après la mise à niveau, revérifiez vos profils API et l'injection des secrets : les shells CI omettent souvent les exports définis uniquement en session interactive. Si vous enchaînez avec des builds iOS sur la même machine, Guide 2026 : éviter les pièges du premier build iOS sur Mac distant couvre signatures, caches et premiers échecs typiques.

Doctor : correctifs attendus et ordre d'exécution

Traitez openclaw doctor (ou la sous-commande de santé documentée pour votre distribution) comme source de vérité. Lancez-le deux fois : avant les migrations automatiques, puis après.

Séquence de remédiation typique

1. Résoudre les erreurs « manifeste manquant » — chaque extension doit exposer la version SDK, les permissions et le chemin du module d'entrée.
2. Réparer les fichiers de profil API : URL de base, identifiant de modèle par défaut et références de secrets conformes au nouveau schéma.
3. Réassocier les répertoires de données si la mise à niveau a déplacé l'état sous ~/.openclaw (adaptez selon la doc d'installation).
4. Relancer doctor jusqu'à un rapport propre ; seulement ensuite redémarrez les services launchd.

Migration Plugin SDK (bascule pratique)

Déplacez chaque intégration personnalisée vers un paquet Plugin SDK : déclarez la version sdk, exportez les hooks de cycle de vie attendus par le runtime (activate, enregistrement d'outils, teardown) et épinglez les dépendances dans le package.json du plugin si vous livrez des outils Node.

• Recopiez la logique héritée dans src/index.ts (ou .js) derrière les types adaptateur du SDK.
• Remplacez les accès directs au disque par le handle d'espace de travail injecté par l'hôte.
• Ajoutez des tests d'intégration headless en SSH — même utilisateur, même fichier d'environnement — que votre agent de production.

Tableau des variables OPENCLAW_* (mémo)

Les noms suivent le préfixe unifié 2026. Les valeurs sont des exemples ; substituez secrets et chemins réels. Les alias dépréciés sont notés pour faciliter un grep dans vos anciens plists launchd.

Après modification des fichiers d'environnement, validez avec launchctl kickstart -k gui/$(id -u)/com.votre.openclaw (adaptez l'étiquette) ou redémarrez l'agent utilisateur depuis Réglages Système — toujours sous le même utilisateur macOS propriétaire du répertoire de données OpenClaw.

Posture de retour arrière

Conservez une archive de OPENCLAW_HOME et de l'ancien binaire ou préfixe npm. Si doctor ne peut pas réconcilier l'état, restaurez le répertoire et réinstallez la version précédente, puis fournissez un plugin minimal qui échoue au contrôle de manifeste SDK — cet artefact accélère les correctifs amont.

Pourquoi un Mac mini distant reste idéal pour ce parcours de mise à niveau

Les upgrades OpenClaw dépendent de processus longue durée et d'un environnement POSIX cohérent. macOS offre un userland Unix natif, des chemins prévisibles pour les LaunchAgents et des performances Apple Silicon sans le bruit thermique d'un portable allumé 24h/24. Un Mac mini M4 consomme très peu au repos tout en gardant SSH, les passes doctor et les builds de plugins prêts à la connexion — pratique quand on itère sur des migrations cassantes.

Gatekeeper, SIP et FileVault réduisent la surface d'attaque par rapport à beaucoup d'hôtes Windows d'automatisation, et l'architecture mémoire unifiée garde les charges multi-outils réactives. Si vous voulez déployer la pile de cet article sur du matériel conçu pour rester allumé en continu, le Mac mini M4 reste l'un des nœuds dédiés les plus rentables ; découvrez les offres SSHMac sur la page d'accueil pour coupler la machine à un flux Mac distant géré.