Cette fiche propose une acceptation minimale reproductible sur un Mac distant : soit le script d’installation officiel (flux curl copié depuis la documentation amont), soit npm install -g avec une version figée, puis une passerelle en boucle locale sur le port documenté 18789, la variable OPENCLAW_GATEWAY_TOKEN pour la sonde /v1/health, et enfin openclaw doctor puis openclaw config validate dans un seul script relié par &&.
L’alignement avec la documentation passerelle 2026 évite trois pièges récurrents : dérive entre Node interactif et launchd, PATH différent entre SSH et plist, et requêtes HTTP vers une mauvaise interface. Pour durcir le jeton avant d’élargir l’écoute, enchaînez avec le guide passerelle, jeton et validate. Pour industrialiser la porte merge, voyez openclaw config validate en porte CI.
Prérequis Node 22 ou plus récent sur Mac distant
La ligne de base documentée pour la passerelle repose sur Node 22 LTS ou une version 24 supportée par votre politique interne. La première ligne utile de tout runbook doit afficher node -v : elle constitue la preuve d’audit qu’une image dorée ou un runner CI n’a pas glissé silencieusement vers un runtime obsolète.
Exportez OPENCLAW_HOME et OPENCLAW_CONFIG_HOME par principal (compte de service ou job), appliquez chmod 700 sur l’arborescence avant d’y placer openclaw.json, et veillez à ce que le PATH utilisé sous launchd soit le même que celui avec lequel vous avez validé openclaw --version en SSH. Les shims nvm purement interactifs restent la cause numéro un des écarts « ça marche dans mon terminal mais pas au boot ».
Choix du chemin d’installation : script officiel curl contre npm global
Retenez exactement un chemin par image dorée et consignez la semver dans le ticket de changement : les équipes sécurité comparent ainsi les notes de version sans deviner quel binaire est réellement sur l’hôte.
| Voie | Quand elle est pertinente | Notes d’exploitation |
|---|---|---|
Installateur officiel (curl) |
Démarrages rapides sur Mac neufs, alignement mot pour mot avec la doc amont. | Journaliser une fois la sortie verbeuse ; intégrer les dépendances dans l’image de base plutôt que de retélécharger à chaque run. |
npm install -g (plage semver figée) |
Flottes avec miroir npm et gouvernance des versions. | Exemple : npm install -g "openclaw@^2026.3.0" ; puis command -v openclaw et openclaw --version pour verrouiller le chemin. |
Les pipelines non interactifs gagnent à fusionner stdout et stderr de doctor et validate dans un seul journal (voir aussi l’article du blog sur l’embarquement non interactif et la porte CI), afin qu’aucun résumé de build n’affiche accidentellement un secret.
Passerelle en boucle locale sur le port 18789 et jeton OPENCLAW_GATEWAY_TOKEN
Tant que vous apprenez les défauts, gardez l’écoute sur la boucle locale : la documentation 2026 positionne l’auditeur local sur le port 18789. Traitez OPENCLAW_GATEWAY_TOKEN comme une référence de secret (équivalent SecretRef sous Kubernetes) : variables chiffrées dans GitHub Actions, variables secrètes Azure DevOps, ou dictionnaire EnvironmentVariables du plist sans jamais l’écrire dans Slack ou dans un commentaire de merge request.
Sondez http://127.0.0.1:18789/v1/health avec l’en-tête Authorization: Bearer …. Un code 200 avec jeton correct confirme que l’authentification est en place ; un 401 lorsque vous retirez volontairement l’en-tête prouve que le refus est réel et non contourné par erreur de configuration.
Pour une lecture machine complémentaire après installation, la série statut JSON passerelle, doctor et port 18789 détaille openclaw gateway status et les artefacts CI.
Daemon launchd et vérification après redémarrage
Sur le Mac de production, exécutez openclaw onboard --install-daemon avec le compte de service qui portera le trafic, puis openclaw gateway status pour confirmer que libellés et chemins correspondent à ce que la supervision lira.
Planifiez une fenêtre de maintenance : redémarrez l’hôte, reconnectez-vous, enchaînez immédiatement openclaw gateway status et la commande curl Bearer ci-dessus. Un résultat vert en shell interactif mais rouge dans l’automation pointe presque toujours vers des valeurs divergentes de OPENCLAW_CONFIG_HOME entre profil utilisateur et plist.
Le cycle de vie des compétences et rollbacks métiers fait l’objet d’un autre article du blog (compétences, rollback et doctor) ; cette page reste centrée sur l’acceptation install / passerelle.
Chaîne d’acceptation : doctor, config validate et sonde santé
Reliez les étapes avec && pour que la première erreur stoppe la promotion : openclaw doctor, openclaw config validate --config "$OPENCLAW_CONFIG_HOME/openclaw.json", puis le curl vers 127.0.0.1:18789. Ajoutez openclaw gateway status lorsque vous devez exposer un JSON aux tableaux de bord.
Empreintes d’erreurs fréquentes et discipline de retour arrière
Comparez stderr à la page de dépannage amont qui correspond à votre semver : les formulations évoluent entre mineures. En cas de repli, restaurez la dernière archive connue bonne de openclaw.json, réinstallez la plage npm précédente si besoin, et enchaînez un cycle launchctl unload/load complet pour éviter un état partagé entre deux configurations.
| Symptôme ou extrait de journal | Cause probable | Action de stabilisation |
|---|---|---|
| Le processus quitte après élargissement de l’écoute hors loopback | OPENCLAW_GATEWAY_TOKEN vide alors que l’exposition est activée. |
Renseigner le jeton depuis le coffre, recharger launchd, relire le texte de sécurité amont. |
HTTP 401 sur /v1/health |
En-tête absent, mauvais schéma ou secret tronqué par une coupure de ligne. | Vérifier l’orthographe exacte Authorization: Bearer ; regénérer le jeton si la copie était corrompue. |
EADDRINUSE sur 18789 |
Double passerelle ou fumée CI résiduelle. | lsof pour identifier le PID, arrêter le processus parasite ou déplacer les tests jetables sur un autre hôte. |
command not found: openclaw sous launchd |
Le PATH du daemon n’inclut pas le répertoire des binaires npm globaux. | Pointer ProgramArguments vers le chemin absolu de openclaw ou exporter PATH dans le plist. |
FAQ
Faut-il installer le daemon sur chaque runner de pull request ?
Non en général : des contrôles CLI sans listener persistant évitent que des jobs concurrents se disputent le même port 18789. Réservez openclaw onboard --install-daemon aux Mac distants longue durée.
Pourquoi insister sur 127.0.0.1 au début ?
La boucle locale retarde toute exposition LAN accidentelle pendant que vous maîtrisez rotation du jeton et plist ; élargissez l’écoute seulement lorsque règles amont et proxy de bord sont prêts.
config validate remplace-t-il doctor ?
Non : doctor signale des avertissements système de fichiers et runtime que validate seul ne couvre pas ; les deux commandes sont peu coûteuses face à une indisponibilité.
Où acheter du temps Mac pour répéter la checklist ?
Ouvrez la page tarifs, finalisez sur achat, et le centre d’aide si le provisionnement bloque.
Synthèse et orientation achat
Vous disposez d’une checklist minimale calquée sur les thèmes documentation passerelle 2026 : Node 22+, un seul mode d’installation, 127.0.0.1:18789 avec OPENCLAW_GATEWAY_TOKEN, openclaw onboard --install-daemon pour la continuité, et un script unique combinant openclaw doctor, openclaw config validate et la sonde curl sur /v1/health.
Lorsque l’achat d’un Mac distant dédié est validé, parcourez l’accueil MacPull pour le positionnement produit, comparez les tarifs, passez par la page achat, et gardez le centre d’aide ouvert pendant le premier boot. Revenez à l’index du blog technique pour les matrices OpenClaw une fois la passerelle au vert.
Indicateur simple pour le management : le délai médian entre reboot et /v1/health vert — le réduire élimine la majeure partie des friction ops.