OpenClaw Gateway installé n’est que le départ ; en production, l’astreinte part surtout dans des health checks trompeurs, des journaux introuvables et une dérive de configuration après upgrade. Cet article s’adresse aux équipes qui ont terminé Linux systemd + Tunnel, Docker Compose ou l’installation trois plateformes, et complète avec observabilité minimale, routage des logs, upgrade/rollback et tableau des symptômes. Pour la politique de routage, enchaînez avec l’article modelRouting.
Les tutoriels d’installation valident le happy path ; la production voit la longue traîne : processus en apparence vivants, collisions de ports, dérive des droits, timeouts des modèles en aval. Les six éléments ci-dessous sont la liste qui fait passer l’astreinte du devine au vérifie.
Health checks trop laxistes : seule l’existence du processus, sans vérifier que la passerelle route réellement, d’où un état à demi mort découvert après bascule du trafic.
Journaux éclatés : systemd, conteneurs, stdout applicatif et reverse proxy écrivent séparément, impossible de reconstituer une chronologie en incident.
Upgrade sans référence : pas de digest d’image précédente ni de version npm globale, le rollback devient « réinstaller au hasard ».
Config et secrets mélangés : openclaw.json et l’injection d’environnement se désynchronisent, d’où des 401 intermittents ou des échecs de routage silencieux.
Observabilité en retard sur les changements : adresse d’écoute ou cible Tunnel modifiée, chemins de sondes monitoring inchangés.
Passerelle vue comme exécuteur universel : charges Xcode lourdes sur le même petit VPS, CPU saturé, diagnostic erroné « le modèle est lent ».
Si au moins deux s’appliquent, complétez d’abord la couche d’observabilité minimale avant d’empiler les fonctionnalités ; sinon chaque release paie deux fois la même classe d’incident.
Un tableau sépare les rôles pour ne pas mêler « on sait installer » et « on reste stables » dans la même revue.
| Sujet | Articles installation / démon (systemd · Docker · trois plateformes) | Cet article (observabilité et changement en production) |
|---|---|---|
| Processus et surface d’exposition | unit/Compose, bind loopback, politique Tunnel ou pare-feu | sondes de liveness, contrôle des conflits de port, régression des chemins de sonde après changement |
| Modèle de configuration | première écriture de openclaw.json, droits des répertoires | revue de diff, sauvegardes, ordre canary et rollback |
| Journaux | d’abord persister sur disque ou être collectés par journal/docker | sens des champs, ID de corrélation, catalogue des motifs d’erreur fréquents |
| Upgrades | fournir une commande d’upgrade copiable ou un chemin d’image | noter digest/version, point de sauvegarde, checklist de validation du rollback |
| Routage des modèles | mention optionnelle | stratégie détaillée dans l’article modelRouting |
L’exploitabilité reproductible vient des mêmes commandes de contrôle et du même ordre de rollback, pas de la mémoire d’une personne.
L’ordre convient à systemd et Docker : d’abord la couche des faits (processus, port, endpoint de santé), puis la couche d’interprétation (journaux et aval). Les commandes varient un peu selon la distro, les points de contrôle doivent rester alignés.
Confirmer le processus principal : systemd avec systemctl status ; Docker avec docker compose ps ; compter les redémarrages et codes de sortie.
Vérifier l’écoute : ss -lntp ou mappage des ports conteneur aligné avec les cibles Tunnel/reverse proxy.
Health checks : sondes HTTP sur le chemin documenté ou personnalisé ; séparer « processus up » et « routage utilisable ».
Récupérer les journaux récents : journalctl -u ou docker compose logs --tail=200 ; fixer une fenêtre temporelle avant recherche plein texte.
Valider les modèles en aval : requête minimale pour écarter « passerelle OK, API amont défaillante ».
Tracer les changements : chaque release note version/digest, diff de config et preuves de sondes pour la prochaine astreinte.
# Exemple : passage rapide (adapter unité / nom du conteneur) systemctl status openclaw-gateway.service --no-pager || true ss -lntp | grep -E '18789|LISTEN' || true # Chemin Docker (exemple) # docker compose -f /opt/openclaw/docker-compose.yml ps # docker compose -f /opt/openclaw/docker-compose.yml logs --tail=200 gateway
Remarque : avec Cloudflare Tunnel, après modification validez à la fois sondes publiques et sondes loopback sur l’hôte, pour éviter les faux positifs si le bord conserve une ancienne route.
Un upgrade rollbackable exige trois éléments : instantané avant release, un seul vecteur de changement pendant la release, après coup la même batterie de sondes. Sur Docker privilégiez un digest figé ou une politique de tags en registre privé ; sur bare metal/npm figez la version du paquet global et le lockfile si pertinent.
Approche canary : valider d’abord sur un préproduction ou une réplique peu chargée, puis étendre ; si la passerelle soutient des exécuteurs distants, déploiement en couches—plan de contrôle d’abord, puis montée en charge de l’exécution.
Attention : sans sauvegarde de openclaw.json et de l’injection d’environnement, n’essayez pas en parallèle de « retoucher le routage » ; les pannes les plus fréquentes viennent d’une config à moitié appliquée.
Les chiffres ci-dessous sont des ordres de grandeur pour aligner les revues ; délais réels et quotas suivent fournisseur et contrat.
| Symptôme | Suspect prioritaire | Orientation |
|---|---|---|
| Sortie juste après démarrage | syntaxe JSON de config, variables d’environnement manquantes, port occupé | Reproduire une fois au premier plan, recouper avec les points de contrôle du guide d’installation |
| 401 intermittents | rotation de clés désynchronisée, plusieurs chemins de configuration | Unifier les sources d’injection, nettoyer les profils shell obsolètes |
| CPU saturé longtemps | charge d’exécution colocalisée avec la passerelle | Déplacer les tâches lourdes vers des exécuteurs dédiés ou un Mac distant |
| pics de latence | limitation en amont, DNS, poignée de main TLS | Journaliser et capturer par couches, isoler le réseau avant d’ajuster les modèles |
Empiler builds macOS lourds, signature et tâches dépendantes du GUI sur le même petit VPS Linux que la passerelle fait gagner du temps court terme mais dégrade la stabilité du plan de contrôle et le rapport signal/bruit au diagnostic ; un portable local seul rarement tient 24/7 avec isolation auditable. Les équipes qui ont besoin de CI iOS stable, agents d’automatisation et capacité contractuelle placent en général la passerelle sur un VPS générique et la couche macOS sur des nœuds Mac distants dédiés. Pour frontière d’exploitation et élasticité, la location Mac Mini cloud NodeMini convient à cette couche d’exécution : choisir région et disque, la placer sous le plan de contrôle OpenClaw, l’astreinte ne regarde qu’une surface d’observabilité claire.
Sur la liste du blog, utilisez le filtre catégorie OpenClaw et lisez dans l’ordre systemd → Docker → observabilité → modelRouting.
Comparez d’abord les tarifs de location et la commande de capacité, et budgétisez séparément la passerelle et la couche d’exécution macOS.
Consultez le centre d’aide, puis recoupez avec les sections health checks et journaux de cet article.