2026 OpenClaw passerelle : doctor, diagnostic par couches et canaux silencieux

Trois douleurs

Les opérateurs OpenClaw ouvrent rarement un ticket intitulé « passerelle dégradée ». Ils signalent plutôt « le bot ne répond plus » ou « la console tourne indéfiniment ». Ces rapports subjectifs se mappent proprement sur trois schémas d’ingénierie récurrents dès que l’on distingue symptômes visibles par l’utilisateur et signaux de santé internes.

1) Canal muet. Telegram ou Slack n’affiche aucune réponse alors que le tableau de bord continue de charger les ressources statiques depuis la passerelle. Ce schéma isole presque toujours la livraison des événements entrants, les règles de routage ou le cycle de vie des jetons, et non une panne générique « le serveur est tombé ». Les équipes qui ne testent que l’interface web concluent à tort que la pile est saine et perdent des heures sur des quotas LLM qui n’étaient pas le goulet d’étranglement.

2) Erreurs intermittentes. Les plafonds de débit amont, les à-coups DNS, la pression mémoire et la latence à froid génèrent des timeouts qui disparaissent au prochain essai. Sans archives d’instantanés health --json et de lignes de journal horodatées, vous ne pouvez pas démontrer si la fenêtre d’échec coïncidait avec un incident fournisseur ou avec une saturation mémoire locale. Les revues post-incident dépourvues d’artefacts se réduisent à des opinions.

3) Dérive de configuration. Les modifications de allowedOrigins, des clés API dans les profils shell, des unités systemd ou des environnements Docker Compose n’atteignent souvent pas le processus en cours. L’opérateur observe des échecs CORS « aléatoires » ou des identifiants manquants parce que le démon lit encore le chemin de fichier d’hier. Documentez explicitement quel utilisateur, quel répertoire de travail et quelle commande de redémarrage s’appliquent après chaque changement.

Instrumentez avant d’escalader. L’habitude légère d’enregistrer le JSON de santé après chaque déploiement vous fournit une base comparable par diff lorsque les ponts se mettent à fluctuer la nuit ou après un renouvellement de certificat.

Quelle couche en premier

Gardez une séquence fixe à chaque incident : confirmez le processus passerelle et le port d’écoute, exécutez openclaw doctor pour la validation statique de configuration, capturez openclaw health --json pour l’état runtime des dépendances, puis suivez les journaux du pont pendant que vous reproduisez le problème utilisateur. Passer directement à la réinstallation des modules Node ou à la rotation des clés API saute l’étape preuve et masque souvent la véritable couche en faute.

La santé du processus répond à la question « quelque chose écoute-t-il ? » doctor répond « la configuration est-elle cohérente en interne ? » health répond « cette instance atteint-elle les fournisseurs et greffons ? » Les journaux répondent « qu’avons-nous réellement fait lorsque l’utilisateur a envoyé un message ? » Chaque question cible un responsable différent : initialisation OS, ingénieur plateforme, ingénieur intégration ou administrateur de canal.

Les portables qui dorment ou changent de réseau rompent les ponts WebSocket ou d’interrogation longue durée même lorsque le binaire reste sain. Cette classe d’échecs est environnementale, non un défaut d’OpenClaw, et pourtant elle domine les incidents des petites équipes. Si votre pipeline d’automatisation pousse aussi des artefacts par SSH depuis la même machine, les coupures liées au sommeil blessent deux fois.

Les passerelles multi-locataires ou partagées exigent des frontières explicites : jetons distincts, flux de journaux séparés et exports de santé par espace de travail. Sinon la mauvaise configuration de l’application Slack d’un partenaire ressemble à une « panne globale » dans vos métriques agrégées.

Les montées de version méritent un mini-canari : instantané du JSON de santé, mise à niveau sur un hôte de préproduction à configuration miroir, réexécution des cinq étapes CLI, puis promotion sur une fenêtre de faible trafic. Sauter la préproduction conduit souvent à déboguer des traces de pile sous charge production au lieu de comparer calmement les sorties health.

Documentez les URL sortantes requises depuis le sous-réseau passerelle ; les proxies d’entreprise qui interceptent HTTPS peuvent casser les SDK de façon que seul health révèle. Une liste d’autorisation réduit les tickets TLS qui rebondissent entre sécurité et plateforme. Prévoyez la rétention des journaux sensibles au RGPD.

Seuils et timeouts

Adoptez des références internes pour que les alertes signifient quelque chose de concret. Utilisez un délai d’expiration de cinq secondes pour les sondes HTTP locales rapides depuis l’hôte passerelle ; au-delà, les suspensions réelles se confondent avec la patience variable de l’opérateur. Conservez le health --json correspondant à côté de l’extrait de journal pris pendant l’incident pendant au minimum vingt-quatre heures, plus longtemps si votre équipe conformité exige une rétention pour les revues d’accès.

Maintenez environ 1,5 Gio de mémoire vive libre sur les petits déploiements mono-nœud. Les chaînes d’outils LLM font grimper la mémoire lors de conversations concurrentes ; le swap sur macOS ou Linux produit une latence qui ressemble à une lenteur du modèle alors que l’API est saine.

Lorsque les journaux montrent des réponses 403 répétées ou des échecs de type OAuth sur une fenêtre de trois minutes, ne faites tourner les identifiants qu’après avoir vérifié la dérive d’horloge système. Un écart au-delà d’environ soixante secondes casse la validation de signature pour plusieurs fournisseurs de messagerie et alimente des rapports exaspérants du type « ça marchait hier ».

Définissez des minuteries d’escalade : si doctor échoue, arrêtez-vous et corrigez la configuration avant de toucher aux fournisseurs. Si doctor réussit mais que health signale un greffon de canal dégradé depuis plus de quinze minutes, appelez le propriétaire intégration, pas l’astreinte LLM.

Les proxies inverses et terminateurs TLS méritent leur propre point de checklist. Lorsque health réussit en localhost mais que les utilisateurs voient des 502 intermittents, capturez à la fois le journal d’accès passerelle et le journal d’erreur du proxy avec des horodatages alignés. Des pools keepalive nginx vers Node mal configurés apparaissent souvent comme « erreurs aléatoires OpenClaw » alors que doctor n’observe jamais le chemin réseau des clients publics.

La rotation des secrets doit être un livret scripté : mettre à jour la console fournisseur, mettre à jour le coffre, redémarrer uniquement les composants documentés comme lecteurs de ce secret, puis relancer immédiatement health et archiver le nouveau JSON. Les exportations ad hoc laissées dans l’historique shell sont une voie classique de fuite de jetons et de divergence entre collègues.

Suivez les budgets d’erreur par fournisseur avec la latence des canaux pour éviter qu’un pic sur un modèle bon marché ne vide le quota premium et ne ressemble à un bogue passerelle. Répétez l’échec trimestriellement : tuez le processus, restaurez la config sauvegardée, vérifiez systemd, launchd ou le redémarrage conteneur face au runbook.

FAQ et intérêt du Mac distant

• Web ok mais chat mort : commencez par les journaux du pont messagerie et les champs canal dans health ; le tableau de bord statique prouve presque rien sur les événements entrants.
• Doctor vert mais timeouts : orientez l’attention vers les plafonds amont, la RAM et la sortie réseau ; joignez des horodatages lorsque vous contactez le vendeur de modèles.
• Changements de config ignorés : tracez le répertoire de travail réel, le fichier d’environnement et la politique de redémarrage du PID en cours avant de rééditer.

Résumé : le diagnostic par couches avec status, doctor, health et les journaux transforme les signalements bruyants « le bot est cassé » en propriété de sous-système actionnable.

Limitation : l’auto-hébergement sur portable échange la disponibilité contre la portabilité. Le sommeil, les changements de VPN et la dérive des permissions mono-utilisateur dominent le volume d’incidents pour les opérateurs isolés.

Angle SFTPMAC : un Mac distant hébergé vous donne une automatisation native Apple colocalisée avec des répertoires isolés par SFTP, une alimentation stable et des pratiques d’exploitation partagées, utile lorsqu’OpenClaw doit rester en ligne à côté des flux d’artefacts SSH auxquels votre équipe se fie déjà.

Nous insistons sur des nœuds joignables et des permissions fichiers de base pour standardiser les sorties doctor et la collecte de journaux entre environnements. Lorsque la fiabilité des agents prime sur l’économie d’un portable retiré du service, déplacez la passerelle vers une infrastructure conçue pour rester éveillée.

Si les builds passent par SFTP ou rsync, évitez d’héberger la passerelle sur le même portable que les visioconférences : un Mac distant stable isole l’automatisation des coupures liées au sommeil.