Symptôme : le Gateway OpenClaw démarre depuis votre terminal, mais vous ne savez pas quel runtime il utilise réellement ni si SQLite est compatible.
Solution rapide : pour un nouveau Gateway permanent sur Mac distant, privilégiez Node 26 si la version d’OpenClaw ciblée le recommande et si le contrôle SQLite réussit. Choisissez plutôt Node 24 lorsque vous devez reproduire le CI et les procédures de publication d’OpenClaw. Dans les deux cas, vérifiez le runtime réellement utilisé par le service, et pas seulement celui de votre session SSH. La documentation officielle sur le runtime Node.js distingue la recommandation d’exécution de l’usage de Node 24 LTS dans le CI et les publications.
Cette décision concerne le runtime de la CLI et du Gateway, pas automatiquement les exigences de l’application macOS. Vérifiez séparément les prérequis de l’application de bureau et ceux du processus Gateway.
Cet article s’adresse aux développeurs qui déploient un Gateway OpenClaw permanent sur un Mac distant. Il aide aussi les ingénieurs CI à décider s’ils doivent reproduire leur environnement de publication, ainsi que les responsables DevOps chargés de vérifier l’installation, la version de Node et les preuves de reprise.
Dernière vérification : 15 novembre 2026, à partir de la documentation Node.js d’OpenClaw, de ses règles de compatibilité, de ses instructions macOS et de la documentation SQLite sur le mode WAL. Les exigences peuvent évoluer selon la version d’OpenClaw visée.
Choisir Node 26 ou Node 24 selon le scénario de Gateway
OpenClaw sur Mac distant : Node 26 ou Node 24 pour un Gateway permanent ?
Pour un nouveau déploiement autonome, partez du runtime recommandé par la documentation OpenClaw au moment de l’installation, puis confirmez que le contrôle de compatibilité SQLite réussit. Au moment de la vérification indiquée ci-dessus, OpenClaw recommande Node 26 pour l’exécution et indique que Node 24 LTS est utilisé dans ses flux CI et de publication. Ces versions répondent à des objectifs distincts : l’une sert de recommandation pour l’exécution, l’autre de référence pour les flux de CI et de publication.
Le score ci-dessous indique l’adéquation au scénario, et non une mesure de vitesse :
- Node 26 : très favorable pour un nouveau Gateway permanent si c’est le runtime recommandé pour la version d’OpenClaw déployée et si les contrôles de compatibilité aboutissent.
- Node 24 : très favorable lorsque votre priorité est de reproduire l’environnement CI ou de publication décrit par OpenClaw. Il peut également convenir à un déploiement, sous réserve de respecter les exigences de la version cible et de valider SQLite.
- Déploiement à reporter : préférable si vous ignorez quel runtime le service lance, si le contrôle SQLite échoue ou si le système hôte ne permet pas d’installer un runtime pris en charge.
Ne confondez pas « le programme démarre » et « le déploiement est validé ». Un lancement manuel confirme seulement qu’un processus a fonctionné dans l’environnement courant. Il ne prouve pas que le service retrouvera le même exécutable après une reconnexion SSH, une fermeture de session ou un redémarrage du Gateway.
Faire du CI la référence lorsque la reproductibilité prime
Si le Gateway sert à des essais indépendants du pipeline ou à des tâches permanentes qui n’ont pas à reproduire une publication, l’alignement sur le CI n’est pas nécessairement votre premier critère. En revanche, si le Mac distant reproduit une étape de publication, de validation ou de construction, comparez les versions déclarées par le pipeline avec celles du Gateway. La documentation OpenClaw indique Node 24 LTS pour le CI et les publications. Si votre objectif est de reproduire ces flux, évaluez donc Node 24 en premier, puis vérifiez les exigences de la version déployée dans les règles de compatibilité Node.js.
Un écart de runtime n’est pas automatiquement une anomalie. Il devient difficile à diagnostiquer lorsque personne ne sait où il se trouve : scripts exécutés localement dans une session SSH, service géré par un mécanisme de lancement, tâches d’intégration et environnement d’installation peuvent sélectionner des exécutables différents. Une erreur fréquente consiste à ne conserver que la sortie d’une commande lancée dans le shell, puis à la traiter comme preuve du runtime réellement utilisé par le Gateway.
Pour comparer l’environnement distant au CI, archivez ensemble :
- la version d’OpenClaw et la révision du dépôt utilisées pour le test ;
- la sortie de
node --versiondans le contexte du service, ainsi que le chemin renvoyé parcommand -v node; - le mode d’installation et le chemin du binaire choisi par ce mode ;
- le résultat du contrôle de compatibilité SQLite recommandé pour cette version ;
- les journaux montrant le démarrage du Gateway, puis son état après un arrêt et un nouveau démarrage contrôlés ;
- la version de Node déclarée par le pipeline qui sert de référence.
Évaluer l’effet de Node 24 sur le Gateway
Node 24 ne compromet pas, à lui seul, le déploiement. La compatibilité dépend de la version d’OpenClaw visée, de ses exigences runtime et du contrôle SQLite applicable. Un runtime aligné sur le CI ne dispense donc pas de ces vérifications. Consultez les exigences de compatibilité de la version installée et exécutez les diagnostics correspondants avant de déclarer Node 24 utilisable pour votre Gateway.
Le compromis est opérationnel. Si vos artefacts, scripts et procédures de publication sont validés avec Node 24, changer de runtime sans raison peut introduire une différence entre le CI et le Gateway. Si la documentation de la version installée recommande un autre runtime pour l’exécution, rester sur Node 24 uniquement par habitude demande une validation explicite : vous devez démontrer que le Gateway et SQLite passent les contrôles dans cette configuration. Ni l’alignement ni la nouveauté d’un runtime ne constituent, seuls, une preuve de compatibilité.
Vérifier le runtime sélectionné par l’installation
Le chemin d’installation influe sur le runtime visible. L’installateur, une installation Node déjà présente et une installation avec préfixe local ne sont pas nécessairement équivalents. La documentation de l’installateur OpenClaw détaille les comportements associés aux différentes situations ; ne transformez pas un choix par défaut de l’installateur en règle obligatoire pour toutes les installations.
Si Node était déjà présent, l’installateur peut s’appuyer sur l’environnement disponible plutôt que créer celui que vous aviez prévu. Une installation locale avec préfixe peut isoler des fichiers et des exécutables de ceux du système. Pour un Gateway permanent, l’identité de l’utilisateur de service et son PATH comptent autant que les options choisies pendant l’installation : le contexte de la session SSH n’est pas nécessairement celui du processus de fond.
Pour limiter les faux diagnostics, consignez le mode d’installation avant toute modification. Vérifiez le chemin du binaire dans votre session, puis confirmez quel exécutable voit le service. Si le Gateway est lancé par un gestionnaire de processus ou par les mécanismes de session macOS, son environnement peut différer de celui de votre shell interactif. Un command -v node réussi dans votre compte ne prouve pas que le service dispose du même chemin.
Dans votre compte rendu, distinguez le Node installé, le Node présent dans le PATH du shell et le Node exécuté par le Gateway. Si ces valeurs divergent, corrigez d’abord la configuration de lancement ou l’environnement du service ; ne réinstallez pas plusieurs runtimes à l’aveugle. Arrêtez et relancez ensuite proprement le Gateway, puis répétez les contrôles dans son contexte effectif. Cette méthode est particulièrement utile lorsque plusieurs projets ou tâches d’agent ne partagent pas la même installation.
Vérifiez séparément les prérequis de l’application macOS et ceux de la CLI ou du Gateway. Ils ne sont pas automatiquement identiques. OpenClaw présente sa prise en charge de la plateforme dans ses instructions macOS et documente séparément le Gateway intégré à l’application macOS. Avant d’interpréter une erreur, identifiez si vous lancez la CLI installée séparément ou le Gateway associé à l’application.
Contrôler SQLite avant de déclarer le Gateway compatible
Confirmer la compatibilité entre Node.js et SQLite
Ne déduisez pas la compatibilité SQLite du seul numéro de Node. La version d’OpenClaw peut préciser des conditions propres au runtime et aux bibliothèques utilisées ; lancez le contrôle prévu pour la version que vous installez et conservez son résultat. Les exigences peuvent changer d’une version à l’autre, de sorte que le diagnostic doit être associé à la version précise du logiciel.
Ce contrôle importe même lorsque le Gateway semble démarrer. Une erreur peut n’apparaître qu’à l’ouverture ou à la mise à jour d’une base, ou lorsque le service reprend après une interruption. Pour interpréter le diagnostic, associez-le à la version d’OpenClaw, au runtime effectivement chargé et aux journaux du Gateway. Sans ces éléments, comparer des sorties obtenues dans des environnements différents risque de conduire à un faux verdict.
Si le contrôle échoue, suspendez la mise en service et vérifiez dans cet ordre :
- le binaire Node réellement utilisé par le Gateway ;
- la version exacte d’OpenClaw testée et les exigences qui lui correspondent ;
- les erreurs complètes émises par le diagnostic SQLite et par le service ;
- l’état de la base et les opérations en cours au moment de l’échec ;
- la reproduction du problème dans un environnement de test isolé, avant toute intervention sur les données de production.
Distinguez également un avertissement de compatibilité, une erreur de démarrage et une corruption de données : ces cas n’appellent pas le même remède. Un contrôle défavorable justifie une investigation, mais ne prouve pas à lui seul que la base est endommagée. Inversement, un lancement réussi ne garantit pas que toutes les opérations SQLite nécessaires au Gateway fonctionneront.
Examiner les correctifs et les limites du Mac hôte
Un runtime installé peut ne pas satisfaire les recommandations de sécurité actuelles. Le fait d’avoir Node 24 ou Node 26 ne garantit pas, à lui seul, un niveau de correctifs adéquat. Vérifiez la version complète installée ainsi que les exigences associées à la version d’OpenClaw ciblée. Les recommandations runtime et les exigences de sécurité doivent être relues au moment du déploiement, car elles peuvent évoluer.
Le système hôte constitue une autre limite. Une ancienne version de macOS peut restreindre les runtimes installables ou pris en charge, indépendamment de la préférence de votre équipe pour un numéro de Node. Vérifiez donc le système installé, ses possibilités de mise à jour et les exigences de la version d’OpenClaw visée. Si le Mac ne peut pas satisfaire ces conditions, ne prétendez pas que le Gateway est validé : choisissez un hôte pris en charge ou différez le déploiement.
Les équipes qui doivent garantir la reproductibilité peuvent fixer une version et la documenter dans leurs scripts et procédures. Cette stratégie est utile à condition de prévoir comment réévaluer ce choix lorsque les exigences officielles changent. Un verrouillage qui n’est ni vérifié ni révisé transforme une précaution de reproductibilité en dette de maintenance. Ajoutez au processus de publication une vérification des exigences runtime et SQLite, puis conservez une trace de la date et des documents consultés.
Si le service est déjà installé, ne changez pas son Node en production avant d’avoir identifié le binaire réellement appelé, protégé les données nécessaires et rejoué le contrôle dans un environnement de test. Une mise à jour du shell seule peut laisser le Gateway inchangé.
Valider le déploiement distant avant la mise en service
La liste suivante transforme le choix en procédure d’acceptation. Utilisez le même Mac, le même mode d’installation et la même version d’OpenClaw que ceux prévus pour le Gateway permanent.
- [ ] Notez la version d’OpenClaw et le mode d’installation ; consultez les exigences correspondant précisément à cette version.
- [ ] Choisissez Node 26 si la documentation actuelle le recommande pour l’exécution et si le contrôle SQLite réussit ; choisissez Node 24 si l’alignement avec le CI est prioritaire et si la version ciblée le prend en charge.
- [ ] Relevez
node --versionetcommand -v nodedans l’environnement de service, pas uniquement dans votre session interactive. - [ ] Exécutez le diagnostic de compatibilité SQLite recommandé pour la version installée, puis archivez son résultat avec les journaux.
- [ ] Démarrez le Gateway avec la méthode prévue en exploitation et vérifiez son état à partir des journaux ou du mécanisme de supervision retenu.
- [ ] Arrêtez et relancez le Gateway proprement ; vérifiez qu’il reprend avec le même exécutable, les mêmes paramètres et un état de base cohérent.
- [ ] Comparez la version runtime et les résultats enregistrés avec le pipeline CI de référence ; expliquez tout écart avant la mise en service.
- [ ] Différez le déploiement si le contrôle SQLite échoue, si le runtime du service reste inconnu ou si l’hôte ne satisfait pas les exigences courantes.
Préparer un environnement distant sans figer le mauvais choix
Si vous ne pouvez pas modifier sans risque le Mac déjà utilisé par votre équipe, validez d’abord le couple runtime-Gateway dans un environnement séparé. Vous pourrez comparer la procédure d’installation, le chemin Node sélectionné, le diagnostic SQLite et le redémarrage sans perturber le service existant. Pour examiner les options de Mac distant proposées par MACGPU, vérifiez les conditions correspondant à votre usage avant de réserver un environnement.
Cette approche ne convient pas à tous les projets. Si vous avez besoin d’une machine dédiée en permanence, d’un accès physique à des périphériques ou d’un environnement strictement contrôlé sur site, l’achat et l’administration de votre propre Mac peuvent être plus adaptés. Une machine virtuelle non macOS ne remplace pas non plus les contrôles qui doivent être réalisés dans un véritable environnement macOS. À l’inverse, un CI Linux ou un terminal local peut rester préférable pour les tâches qui ne dépendent pas d’OpenClaw sur Mac.
Le CI existant offre souvent une référence pratique, mais il ne reproduit pas forcément le contexte d’un Gateway permanent : son cycle de vie, son environnement utilisateur et ses données persistantes diffèrent. Un Mac local est accessible directement, mais les essais de reprise dépendent alors de la disponibilité de cette machine et de sa configuration. Si vous souhaitez évaluer ces contraintes avant de les intégrer à votre chaîne habituelle, un Mac distant loué permet de mener un essai isolé ; vous pouvez consulter les solutions MACGPU pour Mac distant, puis décider à partir des preuves de démarrage et de reprise obtenues.
Au moment de trancher, retenez le runtime recommandé pour l’exécution si vous installez un Gateway neuf et que SQLite passe. Retenez Node 24 si l’alignement avec le CI et les publications est prioritaire et que la version OpenClaw ciblée le permet. Si vous ne pouvez pas confirmer le runtime utilisé ou le résultat SQLite, reportez la mise en service : le numéro affiché dans un shell ne suffit pas à valider un service permanent.