La passerelle OpenClaw authentifie les clients RPC avec un secret partagé. En pratique, ce secret arrive par trois canaux sur macOS : l’arborescence openclaw.json sur disque, l’assistant de l’app macOS qui peut réécrire la config, et le bloc d’environnement du LaunchAgent qui injecte des variables pour les sessions headless. Dès qu’une couche diverge, les opérateurs courent après des fantômes : openclaw status paraît sain alors que l’app affiche déconnecté. Cet article donne deux matrices, huit étapes de déploiement et une séquence HowTo pour que votre hôte passerelle Mac mini M4 cesse d’osciller entre « réparé » et « 401 Unauthorized ».
Commencez par auth par jeton et dérive launchd, puis gardez le redémarrage de la passerelle hors des sessions agent. Installations de base : installation et déploiement ; automatisation santé : doctor et diagnostics. Comptes : aide ; ajoutez des hôtes via les tarifs.
Symptômes qui crient « jeton scindé », pas « mauvais modèle »
- Double personnalité : la CLI réussit pendant que l’app barre de menus boucle sur l’assistant.
- 401 après reboot uniquement : la session loginwindow n’a pas la variable d’env mais le jeton fichier est correct.
- 401 après upgrade : l’app a bumpé une mineure et réécrit le JSON alors que launchd exporte encore l’ancienne variable.
- Succès intermittent : deux processus passerelle se font brièvement concurrence avec des configs différentes pendant le reload.
Matrice A : d’où chaque client lit les identifiants
| Client | Source primaire | Dérive courante | Stabilisateur |
|---|---|---|---|
| CLI sur SSH | openclaw.json dans le home utilisateur |
$HOME différent pour l’utilisateur service vs admin |
Toujours sudo vers le compte service avant d’éditer |
| App macOS | Préférences sandbox + logique de fusion JSON | Réécriture de l’assistant après détection « pas de passerelle » | Épingler les versions app avec change control ; ouvrir l’app seulement quand le fichier est canonique |
| Passerelle launchd | EnvironmentVariables du plist + fichier dans le répertoire de travail | Export obsolète de OPENCLAW_GATEWAY_TOKEN |
Script d’écriture unique qui met à jour les deux atomiquement |
| Agent d’automatisation | Env héritée du shell parent | Jeton manquant quand le sandbox d’outil retire l’env | Drapeaux de chemin de config explicites dans le manifeste d’outil |
Matrice B : risque de déploiement vs atténuation
| Changement | Rayon d’explosion | Atténuation |
|---|---|---|
| Rotation mensuelle du jeton | Tous les canaux de chat jusqu’au rechargement des clients | Double écriture ancien+nouveau pendant 15 minutes avec surveillance du taux 401 |
| Déplacer l’utilisateur passerelle | Chemins absolus et labels plist | Recréer les symlinks ; relancer l’install avec motifs --force de l’article recovery |
| Ajouter un hôte région secondaire | Les opérateurs collent le jeton sur le mauvais hôte | Noms de secrets par hôte dans le coffre ; ne jamais réutiliser les macros presse-papiers |
| Activer bind non-loopback | Exigences d’auth plus strictes | Coupler avec des listes blanches de limites de débit passerelle |
Garde-fous numériques
- Chevauchement de rotation : garder l’ancien jeton valide au moins 900 s après publication du nouveau sur disque.
- Contrôles d’égalité : diff automatisé env plist vs jeton fichier toutes les 6 h sur les passerelles prod.
- Budget incident : si le taux 401 dépasse 1 % des RPC pendant cinq minutes, geler automatiquement les upgrades d’app.
Astuce GUI : quand les invites confidentialité macOS bloquent les écritures de jeton sans surveillance, utilisez VNC une fois, approuvez, puis revenez à la maintenance SSH seule.
Huit étapes de déploiement
- Déclarer la propriété du chemin canonique du jeton sur chaque hôte.
- Retirer les exports dupliqués des shells qui se battent avec launchd.
- Script d’updates atomiques vers JSON + plist en une transaction avec chemins de sauvegarde.
- Ajouter des contrôles style CI qui font échouer le déploiement si les hachages diffèrent entre couches.
- Documenter les épingles de version d’app à côté du semver passerelle dans la ligne CMDB.
- Lancer doctor après chaque upgrade avant d’annoncer « sain ».
- Former l’astreinte à lire les logs 401 comme dérive de config d’abord, panne de modèle ensuite.
- Séparer prod et lab sur des hôtes Mac mini M4 NodeMac distincts quand les équipes ne s’accordent pas sur un seul writer.
FAQ
Stocker le jeton dans le Trousseau est-il mieux ?
Cela peut l’être si tous les consommateurs le supportent de façon cohérente. Les piles mixtes synchronisent d’abord fichier+plist, puis migrent.
Et les laptops des membres d’équipe ?
Ne réutilisez jamais les jetons prod sur laptops. Utilisez des jetons dev à courte durée et des passerelles séparées pour éviter le RPC prod accidentel depuis un café.
launchd hérite-t-il de mon profil shell ?
Non. C’est exactement pourquoi les jetons « disparaissent » après reboot jusqu’à ce que vous les copiez dans le plist ou un fichier que la passerelle lit.
L’hygiène des jetons aime le matériel ennuyeux : un Mac mini M4 dédié chez NodeMac offre la marge Apple Silicon pour des passerelles toujours actives, le comportement macOS natif identique aux laptops des développeurs, et SSH plus VNC quand le consentement GUI bloque l’automatisation. Avec des nœuds à Hong Kong, au Japon, en Corée, à Singapour et aux États-Unis, vous placez les passerelles près des utilisateurs tout en gardant les secrets hors laptops partagés. Louer plutôt qu’acheter rend bon marché l’isolement « passerelle prod » vs « passerelle lab » pour que les rotations ne deviennent pas un conflit politique. Partez des tarifs par région lorsque vous scindez les hôtes.