I. Pourquoi « ça tourne sur mon portable » bloque encore la première signature prod
Les extraits de forums optimisent le plaisir immédiat : on colle une commande, un bandeau s’affiche, et l’on croit l’essentiel acquis. Les incidents de production se manifestent rarement comme des erreurs de compilation. Ils arrivent sous forme de silence : le processus gateway vit, les métriques semblent plates, et pourtant aucun premier message visible pour le client n’atteint le canal promis. La cause habituelle est l’ordre des opérations, pas la qualité du modèle. On branche les canaux avant que openclaw doctor n’atteste que les clés fournisseur, les adresses d’écoute et les chemins reverse-proxy coïncident. La couche canal avale les écarts au lieu de livrer une pile claire. Un second motif est la dérive narrative entre ce qu’openclaw init a créé et ce que launchd exécute réellement : WorkingDirectory, chemins de logs et scripts de mise à niveau racontent chacun une histoire différente jusqu’à ce qu’un simple redémarrage transforme le diagnostic en archéologie. Un troisième motif est la sécurité réduite au folklore : sans openclaw security audit, les surfaces d’écoute, les droits sur les fichiers de jetons et la provenance des compétences ClawHub restent dans l’historique d’un seul ingénieur. Quand cette personne part en vacances, le système repasse de « ça marche » à « personne n’ose y toucher ». Cet article garde volontairement peu de sections larges ; chaque bloc doit pouvoir être collé tel quel dans un wiki interne plutôt qu’éclaté en douze micro-billets jamais lus jusqu’au bout.
Traduisez ces symptômes en langage de gouvernance : il manque des critères de validation. Les relecteurs ne savent pas ce que signifie « vert », et l’astreinte ne sait pas sur quelle couche arrêter un rollback. Le fil conducteur est la chaîne officielle install.sh, init, doctor, channels probe, security audit, avec la parité OPENCLAW_* sur Mac distant dans le même paquet de preuves. L’objectif est de répondre aux auditeurs avec des pièces jointes, pas des captures d’écran assemblées la veille d’un comité.
II. Choisir un chemin d’installation sans en faire une religion
La décision n’est pas de savoir quelle pile paraît moderne sur une diapositive, mais laquelle votre futur vous pourra reproduire dans douze mois avec les mêmes empreintes digest et les mêmes annexes. Le install.sh officiel encode l’ordre et les garde-fous dans le script, ce qui réduit le risque qu’un nouveau branche des canaux avant qu’un workspace n’existe. Les installations npm ou pnpm globales conviennent aux équipes qui traitent déjà les versions majeures de Node comme des contrats d’infrastructure, mais vous devez co-localiser règles PATH, frontières de droits et notes de rollback sur la même page de runbook ; sinon la mémoire musculaire devient silencieusement la configuration de production. Docker Compose gagne souvent en auditabilité et isolation, mais il vous oblige à concevoir des tests d’acceptation sur volumes, réseaux pont et pontage hôte-canal avant même que l’équipe ne comprenne le gateway ; empiler des conteneurs sur la confusion multiplie le temps de triage plutôt que de le réduire.
Quel que soit le chemin, figez la majeure Node, le gestionnaire de paquets et l’interdiction des drapeaux curl non documentés dans le README. Croisez l’article matrice npm/Docker/pnpm sur ce site et consignez une résolution d’équipe unique sur le chemin canonique de livraison au lieu de laisser trois portables inventer trois religions.
Une fois le chemin choisi, consacrez une heure à écrire les modes de défaillance que vous refusez de redécouvrir : rotation des racines TLS côté fournisseur, collègue qui met à jour Node dans la CI sans aligner la production, reverse-proxy qui impose un délai d’inactivité par défaut et casse des websockets longue durée, pression disque sur un Mac distant qui ralentit la rotation des logs jusqu’à ce que les clients remarquent en premier. Ces paragraphes vivent à côté du tableau car ils matérialisent le risque silencieux des seniors. Ils nourrissent aussi votre premier exercice de table : révoquer volontairement un jeton de test, relancer les probes, vérifier que la pagination alerte, restaurer les identifiants, horodater, et attacher le transcript au runbook de production pour montrer aux auditeurs que des humains ont pratiqué le chemin, pas seulement lu un PDF.
| Axe | install.sh officiel | npm global / pnpm | Docker Compose |
|---|---|---|---|
| Garde-fous d’ordre | Élevé ; séquence encodée | Moyen ; vous fournissez les portes | Faible ; stockage et réseau d’abord |
| Auditabilité | Digest du script | Lockfiles et chemins | Digest d’image |
| Adéquation launchd | Fort | Fort | Moyen ; surface d’exploitation |
III. Cinq étapes du répertoire vide au premier message défendable
La liste suivante est une checklist de pièces jointes de ticket, pas une affiche de motivation. Si une étape ne produit pas de journal ou d’artefact texte sauvegardable, l’étape n’est pas terminée. Cette discipline se paie la première fois que vous promouvez un environnement d’un portable perso vers un Mac distant partagé ou confiez le pager à quelqu’un qui n’était pas dans votre fil privé quand le cluster est né.
- Geler les frontières node et répertoire
- Exécuter install.sh officiel avec digest consigné
- Openclaw init en vérifiant workspace, configuration et mémoire ensemble
- Openclaw doctor comme portail dur avec sortie brute archivée
- Channels probe puis premier message gabarit avant d’inviter des humains.
Après les cinq étapes vous devez répondre à trois questions sans détour : quelle version est installée, quel répertoire est autoritaire, et si les poignées de main canal ont été validées indépendamment de votre optimisme. Sinon vous avez bougé sans preuve : suspendez les features et réparez la chaîne.
IV. Triage en couches quand les canaux se taisent
Le silence pousse à retoucher le modèle ou monter la concurrence. Une séquence plus calme : santé fournisseur, routage gateway et adresses de bind, puis adaptateurs de canal et URL de rappel. Les journaux de channels probe doivent dire si les identifiants ont expiré, si les webhooks sont joignables, si le mode socket exige encore un tunnel oublié, et si le gateway se lie à l’interface que vous croyez. Lisez l’article 429 et logs en parallèle pour séparer limites de débit et silence de poignée : les throttles laissent souvent des codes HTTP explicites ou des erreurs fournisseur, tandis que dérives DNS, horloge ou timeouts idle se déguisent en silence intermittent.
Quand n8n ou d’autres orchestrateurs HTTP précèdent OpenClaw, l’idempotence et les signatures ne remplacent pas les probes gateway. Gardez des pièces jointes stratifiées dans le ticket plutôt que de mélanger des logs sans lien ; sinon le prochain post-mortem perd des heures à prouver si des relivraisons ont noyé une file interne ou si le gateway a jeté des événements.
Charge et coût appartiennent à la même histoire : tests de rafale sur projets fournisseur isolés et canaux synthétiques, en notant CPU, mémoire et descripteurs de fichiers ouverts. Inonder les canaux de production avec du trafic synthétique mérite l’orage de pagers que vous récoltez. Sur Apple Silicon hébergeant d’autres services IA, rapprochez-vous de l’article concurrence sur la pression mémoire unifiée pour ne pas confondre throttling thermique et bug logique. Plafonds de jetons et requêtes par minute sur les tableaux de bord à côté des taux d’échec de probe, alertes quand coût et erreurs franchissent ensemble un seuil ; la fatigue d’alerte masque les vraies régressions.
| Symptôme | Hypothèse | Action |
|---|---|---|
| Doctor vert, canal muet | Identifiants ou URL de rappel | Probe ; comparer la console fournisseur |
| Échecs majoritaires, rares succès | DNS, horloge, idle proxy | NTP ; régler l’idle du reverse-proxy |
| Tout meurt après upgrade | État ou variables migrées | Runbook d’upgrade ; diff plist avant le code |
V. security audit, droits workspace et vide fournisseur
security audit doit couvrir écoute, modes de fichiers de jetons, provenance ClawHub avec épinglage et diff, et cohérence reverse-proxy, Tailscale ou tunnels SSH avec l’architecture écrite. Croisez l’article surface d’attaque gateway et assignez propriétaire et échéance à chaque finding plutôt que de traiter l’audit comme ménage du week-end. Sur Mac distant, incluez partage d’écran et fichiers dans la même discussion que le port gateway. Les workspaces init contiennent souvent des emplacements de secrets et des fichiers mémoire : documentez permissions Unix, politique de groupe, comptes de service autorisés en lecture, CI en lecture seule, et si les portables développeurs peuvent écrire des chemins prod. Secrets lisibles par plusieurs utilisateurs : bloqueurs de release, pas simples avertissements. Multi-tenant : un utilisateur OS par instance gateway plutôt que sudo partagé.
Entre doctor et probe se trouve le vide fournisseur : facturation, politique d’organisation, listes IP, enregistrement des IP de sortie, dates de rotation des clés. Les IP de sortie distantes diffèrent des portables ; pré-enregistrez-les ou vous chasserez du vert intermittent qui échoue en production. Classez les changements d’IP de sortie comme les edits plist pour que l’exploitation et l’application relisent les deux côtés de la frontière. La rotation mérite un paragraphe runbook : second jeton, bascule console, double probe, révocation, audit relancé, ticket collé au merge plist. Les équipes qui éditent plist en prod sans copie ont déjà écrit leur incident.
VI. launchd distant, seuils, observabilité, MACGPU
Sur Mac distant partagé, précisez si OPENCLAW_* et secrets modèle viennent de EnvironmentVariables, EnvironmentFiles ou coffre. Après upgrade, diff plist avant le code applicatif. Séparez SSH d’administration de l’entrée webhook publique selon le guide SSH/VNC. Fenêtre d’upgrade : snapshot plist et manifeste workspace masqué, doctor, puis canaux. Ne mélangez pas changement de routage fournisseur et upgrade gateway dans le même ticket.
- Trois échecs de probe incohérents en une heure : geler les nouveaux canaux jusqu’à baseline réseau et identités.
- Plus de deux secrets world-readable ou binds dangereux : bloquer démos publiques jusqu’à correctifs et retests.
- Pas de confirmation du premier message en quinze minutes : revenir à la baseline doctor-only.
Observabilité : cinq pièces — doctor, logs probe bruts, résumé audit, plist masqué, identifiants d’événements fournisseur. Démos externes : au moins les trois premières. Drills trimestriels à froid avec runbook public et miroir interne. CI nocturne : répertoire jetable, install digest figé, doctor en artefact ; alignez majeurs Node CI et prod ; métriques utiles (taux de succès probe, médiane temps jusqu’au premier jeton, nombre de findings audit) plutôt que tuiles uptime vides de définition ; couplez métriques gateway et quotas fournisseur.
Les portables excellent pour valider mais mal comme unique porte client : sommeil, PATH, proxies navigateur déforment le comportement. Les Mac distants offrent launchd dédié, versions épinglées, pièces jointes partagées. Pour de l’Apple Silicon toujours allumé sans transformer un portable en placard, MACGPU publie des offres et une entrée d’aide sans mur de login. Dernière vérif avant démo externe : doctor, probe, audit présents ensemble ; en omettre un fait revenir les régressions silencieuses sur scène.
Versionnez un dossier par environnement, lié depuis l’en-tête d’astreinte, pour que les post-mortems ne pourrissent pas dans Slack. Après chaque incident, accrochez le lien du post-mortem à côté des seuils déclenchés afin que la prochaine lectrice hérite du contexte plutôt que du folklore. Une fois par trimestre, quelqu’un hors noyau dur doit rejouer les cinq étapes avec seulement le runbook public et le miroir interne ; les lacunes — liens morts, identifiants manquants, approbations floues — montent dans le backlog avec une priorité supérieure aux nouvelles fonctionnalités. Cela garde votre dossier d’incident auditable au lieu d’être recomposé à partir de captures.
Les sauvegardes doivent être restaurées, pas seulement exister : chaque mois, rejouez tarball de workspace et plist sur un hôte de secours, relancez doctor et un message gabarit, notez checksum et version OpenClaw pour voir les frontières d’upgrade incompatibles. La chaîne d’approvisionnement du install.sh mérite le même sérieux que le code applicatif : mettez le script dans un dépôt d’artefacts interne, exigez des revues digest et vérifiez les hachages dans le même paragraphe que l’URL de téléchargement pour éviter qu’un copier-coller wiki ne saute l’étape de vérification.
Alignez l’environnement CI et l’hôte gateway : un lint JSON sans doctor exécuté prouve peu. Un job nocturne qui installe depuis le digest figé et archive les logs détecte la dérive avant les clients. Documentez fuseaux et déclencheurs cron ou launchd à côté des résultats de probe pour que le support corrèle les pics. Une fois par an, invitez la sécurité à observer l’exercice pour stabiliser le vocabulaire des risques ; un glossaire commun évite que « critique » signifie tantôt bloqueur d’audit, tantôt slogan marketing.
Comptez visiblement la dette documentaire : combien de pages d’astreinte sans pin digest, combien de plists sans commentaire OWNER, combien de canaux sans ID de gabarit. Quand ces compteurs tombent à zéro pour un environnement, déclarez-le prêt runbook, non parce qu’un GIF de démo a bouclé une fois proprement. Si deux ingénieurs passent plus de quatre heures à basculer des drapeaux sans produire de nouvelles pièces jointes, arrêtez-vous et écrivez la ligne runbook manquante ; le débogage héroïque sans preuves recrée une magie non reproductible pour laquelle la rotation suivante paiera encore. Ajoutez enfin une phrase claire sur la propriété : un titulaire et un suppléant pour le pin digest, les modèles plist et le corpus de gabarits, avec rotation trimestrielle du suppléant pour éviter que le savoir ne parte en congés.