OPENCLAW_2026
GATEWAY_
SYSTEMD_
LAUNCHD_RUNBOOK.

1. Diagnostic : ça s’installe mais ne reste pas debout

(1) Confondre shell de démo et prod : un openclaw gateway interactif prouve binaires et jetons, pas la politique de redémarrage. Sans superviseur unique, chaque reboot ou OOM ramène du travail manuel. (2) Contrats OS : Linux pense journald, limites cgroup et mises à jour de sécurité sans opérateur ; macOS pense sommeil capot fermé, App Nap et frontière LaunchDaemon / LaunchAgent. (3) Mises à jour sans retour arrière : la dérive OpenClaw + Node/Python désynchronise Gateway et adaptateurs ; les journaux ressemblent à « tout est mort » alors que le vrai problème est un couple de versions incohérent.

Sans contrat écrit, les équipes accumulent des « Gateway zombies » : un vieux processus premier plan garde le port pendant qu’un autre unit systemd démarre — TLS vacille, l’edge renvoie des 502. Hygiène : un seul propriétaire, adresses de bind explicites, ligne Runbook « arrêter le superviseur avant debug manuel ».

Autre piège : double source de vérité (openclaw.json serveur vs onboard local). Les canaux semblent verts tant que le dernier écrivain a eu raison. Git filtré, artefacts immuables, checksum au boot pour arrêter la roulette.

La dette d’observabilité devient du debug émotionnel : redémarrages aveugles, rotation de clés API. Une échelle fixe réduit le temps moyen jusqu’à l’innocence.

Sur Linux, les patchs non supervisés peuvent couper de longs jobs — fenêtres de maintenance ou mises à jour transactionnelles. Sur macOS, App Store / Xcode réordonnent les frameworks ; snapshots avant gros saut OS, répétition Gateway sur clone si possible.

Double démarrage = collision de ports. Règle prod : un seul superviseur ; arrêter l’unité avant foreground, vérifier le port libre.

2. Matrice systemd / launchd

2b. Règle du superviseur unique

Soit systemd/launchd possède le Gateway, soit un humain temporairement — jamais les deux. Le debug foreground est valide après arrêt d’unité et vérification du port. Cette règle seule supprime une part surprenante de Heisenbugs multi-canaux.

Modèle d’incident : nom d’unité, label launchctl bootout, port à libérer, délai avant « OK ». L’ambiguïté en secondes coûte des heures avec plusieurs intervenants.

3. Cinq étapes de durcissement

1. Geler la source de vérité : chaîne de version, chemin config, ligne de changelog.
2. Baseline : openclaw status, openclaw gateway status, openclaw channels status --probe.
3. Écrire le superviseur : systemd avec EnvironmentFile et ulimits ; plist avec WorkingDirectory et StdOut/Err.
4. Garde-fous : limite de taux de restart ; alerte si >3 crashs en 5 minutes.
5. Paquet rollback : avant upgrade, tarball config + checksum binaire.

L’étape 2 n’est pas négociable : si les probes échouent, launchd n’est pas la bonne couche. Les canaux doivent être verts à la main avant l’automatisation.

Étape 3 : User=/Group= sous Linux ; compte de service dédié sur Mac pour éviter que les dossiers skills ne flappent entre admin et utilisateur de session.

Étape 4 évite les boucles qui brûlent les quotas API, souvent prises pour une panne « modèle ».

Entre 3 et 4, game day : tuer le processus, le superviseur doit rétablir sans humain ; répéter après chaque upgrade majeur.

Si doctor est propre mais les réponses bloquent, remonter vers politiques de salon : mentions, allowlists, appairage, limites. Doctor valide l’environnement ; les probes valident le produit.

Corréler logs applicatifs et horodatage noyau : sur Mac, assertions d’alimentation et roam Wi‑Fi précèdent souvent des coupures silencieuses ; sur Linux, OOM dans dmesg explique des enfants perdus mieux que la stack seule.

4. Seuils citables (SRE)

5. Linux ou Mac

Utiliser la table en pré-mortem : si plusieurs lignes s’appliquent, scinder les rôles par hôte et documenter qui détient le coffre à jetons.

Le coût inclut les heures d’ingénierie : un Mac/heure légèrement plus cher peut battre des scripts de sync cross-OS sur le calendrier.

MACGPU s’adresse aux équipes voulant le comportement Apple natif sans CapEx, avec BOM prévisible — discipline de monitoring et rollback requise.

Hybride : tracer explicitement le plan de données — qui tient les WebSockets longue durée, qui signe les charges Apple, comment renouveler les certificats clients TLS.

Chaque tweak plist/unit dans le changelog, même une ligne — git blame sauve les régressions des mois suivants.

6. FAQ

Questions d’opérateurs début 2026, à adapter (chemins, politiques).

Doctor vert, pas de réponse ? Probes et allowlists. Deux utilisateurs sur un Mac ? HOME séparés, pas de config partagée en écriture. Cassé seulement après upgrade ? Ports, PIDs zombies, fichiers env écrasés.

Gateway dans Docker sur Mac ? Possible mais volumes d’identifiants et IPC complexes ; sans standard conteneurs, préférer supervision native. VPS IPv6 only ? DNS et SAN alignés ; erreurs AAAA = tunnels semi-ouverts. Trop de logs ? JSON structuré vers un collecteur ; pas de tail brut en prod.

Tester le failover ? Nom d’hôte staging, deux répétitions de rollback avant jetons prod. Secrets dans Git ? sops / sealed secrets ; jamais de clés brutes.

journald a mangé les preuves ? Logs structurés vers stockage externe. launchd chargé mais pas de processus ? Codes de sortie dans log show. Gateway en root ? Éviter ; moindre privilège.

7. Étude de cas : diagnostics en couches sauvent le sommeil

Les chronologies d’incident se répètent : capot ou maintenance hébergeur → Gateway down → heures à tweaker les modèles. Une échelle figée à cinq marches réduit le MTTR ; les erreurs coûteuses sont opérationnelles, rarement algorithmiques.

Les configs double source créent des succès fantômes ; GitOps avec checksum au boot rend la dérive visible tout de suite.

Les workflows Apple-heavy gagnent quand le Gateway vit sur un Mac distant — chemins et sandbox plus proches des tutoriels. TLS à grande échelle peut rester sur Linux en bordure, mais la topologie simple l’emporte.

Long terme, les équipes avec runbooks gagnent : ports, commandes de santé, chemins tarball rollback sur une page — ça paie chaque panne.

Sécurité : ne pas exposer les ports de gestion ; TLS au proxy contrôlé ; rotation des identifiants au même rythme que les upgrades de canaux.

Capacité : le CPU Gateway est rarement le goulot ; stalls réseau et quotas fournisseurs le sont. Mesurer hebdomadairement le p95 de latence des probes ; surveiller le disque des caches skills sur petits VPS.

Gestion du changement : plist/unit comme revue de code ; une ligne WorkingDirectory manquante casse les imports relatifs. Diff avant reload, copies .bak horodatées.

Fournisseurs : joindre version Gateway, sortie probes, extraits de config masqués — les tickets « pas de repro » se ferment plus vite.

Humains : astreinte hebdomadaire rotative mais un architecte Gateway unique pour les changements structurels — sinon politiques de restart contradictoires.

8. Clôture : Linux pour l’ingress, Mac pour la colle Apple

(1) Limites : Linux faible sur la colle Apple-only ; Mac moins bon sur l’egress brut le moins cher. (2) Valeur Mac distant : supervision unifiée avec stacks créatifs, moins de sauts de fichiers cross-OS. (3) MACGPU : louer un nœud Apple Silicon prévisible plutôt qu’un datacenter placard — CTA vers offres et aide.

Hybride acceptable : jetons sur Linux, workflows Apple sur Mac — automatiser la frontière par rsync ou stockage objet, pas par glisser-déposer sur tunnel instable.

Expérimentation : checks manuels → systemd ou launchd → alertes. Sauter l’étape du milieu garantit des pages à minuit.

Réalité budget : le temps d’ingénierie domine le TCO des petites équipes ; Mac distant managé bat souvent un VPS « gratuit » qui brûle les nuits. Inversement, équipe 100 % Linux sans API Apple : ne forcez pas le Mac.

Formation : enregistrer cinq minutes de séquence de probes saine à côté du runbook.

Célébrez les semaines ennuyeuses : les meilleures flottes OpenClaw sont plates — graphes stables, probes vertes, upgrades répétées.