OpenClaw Onboarding 2026 : modes passerelle, installation du démon et TCC macOS sur Mac cloud

La première configuration de OpenClaw sur macOS décide souvent si l’après-midi reste productif : mode passerelle, démons d’arrière-plan et invites Transparency, Consent, and Control (TCC) interagissent. Ce guide 2026 parcourt openclaw onboard, le moment d’ajouter --install-daemon, le comportement du LaunchAgent ai.openclaw.gateway et l’alignement entre l’app bureau et la CLI globale — surtout lorsque l’exécution vit sur un Mac mini loué accessible en SSH ou VNC. Pour les fichiers de configuration après onboarding, poursuivez avec openclaw.json, .env et profils.

Prérequis : Node 22/24 et installation CLI

La documentation OpenClaw cible Node.js 22 LTS (22.16+) ou Node 24 comme runtime de passerelle sur Mac. Installez via Homebrew, nvm ou l’installateur officiel, puis épinglez le paquet global sur le canal que votre équipe standardise :

npm install -g openclaw@latest
# ou épingler : npm install -g [email protected]

Évitez de mélanger une build app prérelease avec une CLI globale obsolète : l’écran d’onboarding lit la poignée de main de la passerelle et refuse des paires semver incohérentes. Après installation, vérifiez which openclaw sur les machines partagées. Sur environnements loués, documentez si Node est par utilisateur (nvm) ou système, pour que les jobs LaunchAgent et cron voient la même runtime.

Ajoutez au wiki interne une version Node « dorée » et un petit script pre-flight avant le premier openclaw onboard pour réduire les tickets où un prestataire utilise encore Node 20 et déclenche des problèmes ABI avec des modules natifs.

Passerelle locale vs distante

Mode	Idéal pour	Compromis
Passerelle locale sur le Mac	Développeur solo, automatisation navigateur, latence minimale	Démon et TCC sur la même machine
Passerelle distante (SSH/Tailnet)	Ops centralisées, GPU partagé ou coffre de clés	Chemin réseau et complexité d’auth
Reporter la configuration	Évaluation matérielle	Sans passerelle, les outils réels ne tournent pas

Les équipes front choisissent souvent local sur un Mac mini cloud pour partager la même instance OS entre automatisation WebKit et outils fichiers. Les équipes plateforme pointent les portables vers une passerelle distante tandis que les freelances utilisent des tunnels SSH ; documentez URL, origines autorisées et terminaison TLS. Avant toute exposition WAN, appliquez durcissement proxy et tunnel.

Prévoyez un plan B : si la passerelle distante tombe, un développeur doit pouvoir monter une passerelle locale en quelques minutes sans redistribuer des secrets. Des profils séparés sous ~/.openclaw et des variables documentées aident, en cohérence avec l’article JSON et profils.

Assistant d’onboarding et auth fournisseur

openclaw onboard lance le flux interactif : emplacement de la passerelle, clés fournisseur ou OAuth pris en charge, profil tools.profile par défaut comme coding pour garder fichiers et shell actifs. Les installs 2026 penchent vers des défauts plus sûrs ; vous pouvez resserrer les profils ensuite.

L’app peut ouvrir une session de chat guidée — traitez-la comme documentation vivante. Capturez chaque écran pour le dossier SOC : les auditeurs exigent de plus en plus la preuve que les secrets n’ont pas transité par Slack ou e-mail. Recoupez les variables d’environnement avec notre checklist de mise à niveau pour éviter les jetons orphelins après une mise à jour.

Pour les équipes avec passerelles staging et production séparées, limitez le premier run aux identifiants staging et n’ouvrez la production qu’après un smoke test réussi, afin d’éviter qu’un essai consomme des quotas production.

Démon LaunchAgent et propriété du port

L’arrière-plan s’appuie sur launchd. openclaw onboard --install-daemon écrit ~/Library/LaunchAgents/ai.openclaw.gateway.plist avec chemins StandardOut/Err à faire tourner mensuellement sur serveurs chargés. Si un autre processus occupe le port configuré, l’onboarding semble réussir alors que les healthchecks échouent — lancez openclaw doctor et cherchez EADDRINUSE dans les journaux.

Fermer OpenClaw.app ne démonte pas automatiquement la passerelle lorsque le démon est chargé — voulu pour les serveurs sans tête. Utilisez la commande unload documentée ou launchctl bootout gui/$UID/ai.openclaw.gateway pour un cold start. Après mise à jour macOS, relancez doctor : TCC peut invalider des binaires déplacés.

Versionnez la plist comme modèle sans secrets dans Git, pas comme copie live contenant des jetons, afin de pouvoir revoir les diffs lorsque Apple déprécie des clés LaunchAgent.

Permissions TCC qui bloquent l’automatisation

macOS demande accessibilité, automation (AppleEvents), notifications et parfois l’enregistrement d’écran lorsque les agents contrôlent des apps locales ou affichent des alertes UI. N’approuvez que sur des machines de confiance ; sur Mac cloud partagés, isolez un compte utilisateur par prestataire pour révoquer en supprimant le login.

Si les modales échouent silencieusement, ouvrez Réglages système → Confidentialité et sécurité et ajoutez manuellement le chemin binaire indiqué dans le toast d’erreur. Les sessions Bureau à distance masquent parfois les boîtes ; reconnectez-vous en VNC graphique pour cliquer Autoriser la première fois.

Les flottes d’entreprise peuvent pousser des profils de configuration pré-approuvant certaines équipes ; la plupart des locataires MacHTML restent sur approbation utilisateur standard. Journalisez chaque octroi TCC dans le ticket de changement pour accélérer les revues sécurité.

Alignement app/CLI et doctor

Trois contrôles mesurables à intégrer au runbook :

1. openclaw --version correspond à la chaîne « compatibilité passerelle » de l’app macOS sur la même version mineure.
2. openclaw doctor est vert pour connectivité des canaux, chemins disque et paquets pilotes navigateur optionnels.
3. Revue de diff de config : après onboarding, ~/.openclaw/openclaw.json doit refléter le port exposé derrière votre reverse proxy — lisez le guide de durcissement avant d’ouvrir le WAN.

Si doctor remonte HTTP 401 depuis l’API modèle, faites tourner les clés dans .env, pas dans le JSON partagé en visio. La CLI 2026 sépare plus clairement « jeton invalide » et « egress bloqué » que les anciens fetch génériques.

Planifiez un smoke test de 15 minutes post-onboarding : un appel d’outil sûr, une lecture fichier dans le dépôt, un échec volontaire (mauvais chemin) pour valider le format d’erreur. Les équipes qui sautent cette étape découvrent des allowedPaths mal réglés le week-end. Archivez la sortie doctor en texte dans le wiki.

Gardez une note de rollback avec l’ancienne sortie npm list -g openclaw et une archive ~/.openclaw ; en cas de défaut cassant, restaurez en environ trois minutes sur un réseau rapide.

Pour le diagnostic approfondi, reliez votre canal d’état à OpenClaw doctor et diagnostic passerelle.

Exploitation, journaux et escalade

Configurez une rotation des journaux LaunchAgent ou envoyez-les vers votre SIEM si la conformité l’exige. Surveillez tôt les alertes récurrentes sur l’expiration des jetons pour éviter une panne en démo. Pour le 24/7 sur matériel loué, définissez des niveaux d’escalade : niveau 1 vérifie doctor et les ports, niveau 2 touche au proxy, niveau 3 fait tourner les secrets.

Documentez quels comptes peuvent valider les invites TCC pour que les astreintes ne bloquent pas faute de session graphique. Les identifiants VNC persistants sont pratiques mais risqués ; préférez des accès courts avec justification.

Pourquoi onboarder sur un Mac cloud dédié

Onboarder sur un portable jetable fonctionne jusqu’à ce que quelqu’un reparte avec la machine et votre passerelle disparaisse. Un Mac mini en datacenter offre alimentation stable, IP de sortie optionnellement statiques et des performances Apple Silicon pour l’outillage LLM adjacent sans ventilateur sous le bureau. MacHTML fournit des Mac mini physiques en location avec SSH/VNC : installez OpenClaw une fois, laissez le démon tourner, donnez VNC aux prestataires pour les TCC tout en centralisant la politique root.

La efficacité énergétique d’Apple Silicon compte pour les passerelles always-on : faible idle, pics pour compiler des outils ou piloter le navigateur. Face aux VM macOS émulées, le bare metal évite des bugs subtils d’horloge et d’appels système avec les minuteurs launchd. Fin de projet : réduisez l’instance plutôt que de revendre du matériel.

FAQ

Pourquoi l’app macOS signale un décalage de version de passerelle ?

L’app compare la passerelle en cours à sa version embarquée. Mettez à jour la CLI globale openclaw vers la semver attendue, redémarrez launchd et relancez doctor.

Quitter OpenClaw arrête-t-il la passerelle ?

En mode démon local, launchd maintient la passerelle après fermeture de l’app. Utilisez launchctl bootout ou la commande d’arrêt documentée pour un redémarrage à froid.

Où stocker les clés API après l’onboarding ?

Dans ~/.openclaw/.env avec des permissions strictes, jamais dans Git ; voir l’article openclaw.json et profils pour séparer dev et prod.

Un onboarding OpenClaw fiable tient surtout à la discipline opérationnelle : runtime Node correct, installation explicite du démon, TCC complétée en session graphique et CLI verrouillée en version. Le faire sur un Mac mini Apple Silicon loué à la journée garde macOS natif, retire votre portable du chemin critique et s’accouple à l’automatisation SSH pour un diagnostic piloté par doctor dès que la passerelle déraille. MacHTML se concentre sur l’accès Mac cloud bare metal : provisionnez, onboardiez OpenClaw, validez, démontez sans racheter de postes.