OpenClaw qui fonctionnait sur le portable d'un développeur échoue souvent sur un Mac headless hébergé dans le cloud, car les chemins LaunchAgent, les permissions TCC (Transparence, consentement et contrôle) et les adresses d'écoute diffèrent d'une session graphique locale. Ce guide 2026 suit le chemin courant — script d'installation officiel, Node 22 ou plus récent, et openclaw onboard --install-daemon — puis prouve que la passerelle est saine avec des commandes reproductibles. Vous obtiendrez six contrôles prérequis, un tableau d'acceptation sur quatre lignes, une matrice de symptômes à quatre colonnes et des options de tableau de bord distant via tunnels SSH ou VNC. Après lecture, vous devriez classer « démon absent » contre « panne fournisseur de modèle » en moins de deux minutes. Les équipes qui enregistrent chaque étape dans un ticket obtiennent en outre une base de connaissances exploitable lors des prochaines mises à niveau majeures.
Associez cette check-list au guide complet d'installation macOS pour l'ampleur et à secrets, variables d'environnement plist et Trousseau pour l'hygiène des identifiants. Lorsqu'il vous faut un consentement interactif, lisez la procédure VNC ainsi que l'aide générale pour les attentes de connectivité sur les hôtes NodeMac. Pour le dimensionnement commercial et les régions disponibles, la page tarifs complète le tableau. Garder ces quatre liens dans le même document réduit les allers-retours pendant l'astreinte.
Trois différences entre serveurs headless et portables
- Pas de béquille barre des menus : Les outils qui supposent Accessibilité ou Enregistrement d'écran exigent des charges MDM, VNC, ou un profil de capacité réduit jusqu'à ce que quelqu'un puisse cliquer les invites.
- Sessions de connexion contre shells SSH : Quitter SSH n'implique pas qu'une connexion graphique existe. Les LaunchAgents utilisateur exigent un
WorkingDirectoryvalide et des destinations de journaux inscriptibles appartenant au compte de service. - Politique réseau cloud : Les groupes de sécurité peuvent bloquer l'adresse d'écoute choisie. La CLI peut afficher « listening » alors que les contrôles de santé externes échouent si vous êtes lié à 127.0.0.1 mais attendez un accès inter-VPC sans tunnel.
Sur macOS, la frontière entre « service démarré » et « service joignable » est source de malentendus : un processus peut écouter en local pendant qu'un pare-feu applicatif ou une politique egress bloque ce dont les modèles ont besoin. Dès le premier jour, notez qui est autorisé à ouvrir un tunnel, sur quel port, et combien de temps la fenêtre reste valide — la conformité et la sécurité préfèrent ces détails écrits aux configurations « temporaires » oubliées pendant des mois.
Verrouiller versions, chemins et disque avant d'installer
- Architecture : Les hôtes Apple Silicon doivent annoncer
arm64. Mélanger des shells Rosetta duplique les téléchargements de dépendances et embrouille le support. - Majeure Node : Alignez-vous sur la doc OpenClaw actuelle — en général Node 22 LTS ou plus récent. Capturez
node -vetwhich nodepour que cron et shells interactifs concordent. - Présence CLI : Après installation,
openclaw versiondoit renvoyer un triplet semver, pascommand not found. - Répertoire d'espace de travail : Pré-créez par ex.
/Users/<svc>/openclaw-workspaceavec la bonne propriété pour que l'onboarding n'échoue pas à mi-écriture. - Marge disque : Modèles et journaux grossissent vite — gardez plus de 25 Go libres avant de commencer.
- Dérive d'horloge : Un décalage au-delà de 120 secondes par rapport au NTP se traduit souvent par des 401 intermittents des fournisseurs même si les clés sont valides.
Le point sur l'espace disque mérite une mention séparée : les caches Hugging Face, les artefacts npm et les journaux de passerelle se cumulent silencieusement jusqu'à ce que macOS commence à purger sous pression, ce qui perturbe les jobs en cours. Automatisez une alerte sur le pourcentage libre ou sur l'espace absolu, et planifiez un nettoyage documenté après chaque grosse mise à jour de modèle. Sur les nœuds NodeMac, la persistance du répertoire personnel est en général stable, mais votre procédure doit quand même prévoir le comportement après redémarrage (voir plus bas).
Signaux attendus de onboard --install-daemon
Exécutez la séquence suivante dans une seule session SSH. Si une étape reste bloquée plus de 10 minutes sans sortie, suspectez une interception TLS sortante ou des paramètres proxy avant d'accuser le CPU. Les environnements d'entreprise qui terminent SSL sur une appliance doivent valider les certificats racine dans le trousseau du compte de service, pas seulement dans celui de l'administrateur qui a fait le premier test manuel.
| Étape | Commande / action | Critère de réussite |
|---|---|---|
| 1 | curl -fsSL https://openclaw.ai/install.sh | bash (vérifiez l'URL dans la doc) |
Code de sortie 0, archives entièrement téléchargées |
| 2 | openclaw onboard --install-daemon |
Le plist LaunchAgent est posé dans le domaine utilisateur et launchctl list montre le job |
| 3 | Sonde de santé (HTTP ou statut intégré selon la version) | 3 sondes consécutives espacées de 5 secondes réussissent |
| 4 | Chat minimal ou ping d'outil | Réponse JSON structurée sans timeouts côté client |
Matrice de symptômes et premières actions
Utilisez le tableau comme script d'astreinte : une ligne à la fois, sans sauter la colonne « Prouvez-le », sinon vous remplacerez le plist trois fois sans traiter la cause racine. Les symptômes réseau prêtent souvent à confusion avec des pannes amont ; la distinction repose sur des preuves côté fournisseur (quotas, graphiques QPM) versus preuves locales (socket, PID, journaux LaunchAgent).
| Ce que vous voyez | Cause probable | Faites d'abord ceci | Prouvez-le |
|---|---|---|---|
| Plist présent, processus quitte instantanément | WorkingDirectory absent ou non inscriptible |
mkdir -p et propriété correcte |
log show --last 5m sans boucle de crash |
| La CLI affiche EADDRINUSE | Passerelle obsolète ou service CI sur le même port | Identifiez le PID avec lsof et coordonnez une fenêtre d'arrêt |
Port libre après arrêt propre |
| Vagues de 429 / 5xx des modèles | Quota, routage ou concurrence agressive | Tournez les clés si besoin, baissez la concurrence sous 2 pour un test de trempage | Le graphe QPM de la console fournisseur se stabilise |
| Atteignabilité type LAN uniquement | Mauvaise config de liaison loopback | Ajustez la politique d'écoute ou utilisez la redirection locale SSH | curl depuis la bastion atteint l'IP du service |
Hygiène de mise à niveau : Capturez la sortie de openclaw doctor avant de modifier les flags du démon. Pour les sauts majeurs, archivez le plist précédent et l'espace de travail afin de revenir en arrière en moins de 5 minutes.
Tableau de bord distant openclaw dashboard sans écran local
La documentation suppose souvent un navigateur sur portable. Sur serveurs headless, trois schémas fonctionnent : la redirection de port SSH locale du type ssh -L 18789:127.0.0.1:18789 user@host (remplacez le port par votre config), de courtes sessions VNC pour cliquer les TCC une fois, ou une validation 100 % CLI lorsque la sécurité interdit toute UI. Inscrivez dans le ticket de changement qui peut accéder à quelle URL pendant la fenêtre afin que personne n'expose par erreur un tableau de bord non authentifié sur Internet public.
Pendant l'acceptation, capturez trois faits : le PID parent de la passerelle dans l'arbre de processus, la liste des sockets en écoute, et l'horodatage du dernier RPC réussi. Les triages futurs ne comparent que ces signaux pour décider si vous avez perdu le processus, changé de port ou perdu les modèles amont en environ 90 secondes. Cette discipline rejoint le runbook d'exploitation pour les journaux et doit vivre dans le même classeur d'astreinte. Les équipes qui jettent ces captures dans un canal Slack éphémère régressent vite : centralisez-les dans l'outil de tickets ou la base de runbook.
Check-list fournisseur sur plateformes Mac cloud
NodeMac livre du bare metal Apple Silicon avec accès bi-protocole, mais vous devez encore valider la couche application pour ne jamais accuser « l'hôte » d'une erreur de pare-feu applicatif.
- Sortie 443 : Autorisez en continu les fournisseurs de modèles et les registres npm ; des blocages intermittents produisent des auto-contrôles de démon erratiques.
- Politique d'entrée : Si vous avez besoin d'un tableau de bord public, documentez la terminaison TLS et les groupes de sécurité ; le forwarding SSH reste plus sûr par défaut.
- Persistance : Vérifiez que les répertoires personnels et
~/Library/LaunchAgentssurvivent aux reboots. - Observabilité : Collectez pourcentage CPU, pression mémoire et liveness passerelle ; ne pagez qu'après 3 battements manqués pour ignorer le jitter.
Lorsque vous décompressez des espaces de travail copiés depuis des portables, macOS peut retirer les bits d'exécution des scripts utilitaires, produisant un Permission denied d'une ligne enfoui dans stderr. Effectuez un passage chmod +x délibéré sur les répertoires de scripts et consignez le résultat à côté de votre tableau d'acceptation. Les agents qui invoquent xcodebuild ont aussi besoin de licences Xcode acceptées et de chemins d'outils en ligne de commande cohérents — sinon vous croirez OpenClaw cassé alors que la chaîne n'est qu'à moitié configurée.
Enfin, répétez un test de redémarrage à froid : coupez l'instance, attendez la connexion automatique ou le bootstrap LaunchAgent, et confirmez que la passerelle répond avant de déclarer la production prête. Les équipes qui sautent cette répétition découvrent des conditions de course entre déverrouillage FileVault, montée réseau et premier RPC seulement après avoir basculé le trafic. Sur Mac mini M4, la mémoire unifiée et le NPU aident les sessions à contexte moyen et les appels d'outils concurrents sans la friction des conteneurs Linux qui simulent Darwin. Les nœuds NodeMac exposent SSH et VNC pour concilier démons headless et consentements graphiques ponctuels, avec des régions couvrant Hong Kong, le Japon, la Corée du Sud, Singapour et les États-Unis afin de rapprocher les passerelles des exigences de résidence des données. La location transforme les projets d'agents expérimentaux en dépense opérationnelle alignée sur la vélocité d'itération — exactement ce dont les équipes qui suivent cette check-list ont besoin pour itérer sans bloquer le reste de l'organisation.
En synthèse, l'acceptation headless n'est pas une case à cocher unique : c'est un petit programme d'ingénierie composé de versions figées, de preuves réseau, de journaux exploitables et d'un plan de retour arrière testé. Les organisations qui investissent une heure supplémentaire ici économisent des dizaines d'heures d'astreinte lors des premières montées en charge ou des incidents fournisseur — et gardent la confiance des équipes produit dans les automatisations qu'OpenClaw orchestre sur leurs Mac cloud.