Lorsqu’OpenClaw cesse de répondre aux webhooks ou que la passerelle renvoie des erreurs 401, le retour le plus rapide au vert n’est pas une série de redémarrages aléatoires : c’est une passe diagnostic disciplinée avec openclaw doctor, des journaux structurés et des sondes de canaux. Ce playbook parcourt l’ensemble des commandes 2026, relie symptômes et correctifs, et explique pourquoi les équipes préfèrent enchaîner la boucle sur un Mac mini Apple Silicon loué plutôt que sur un portable qui s’endort dès que vous refermez le capot. L’excellence opérationnelle naît quand on traite les pannes récurrentes comme des signaux de dérive de configuration, de rotation de secrets insuffisante ou de divergence entre environnements. Dans les setups hybrides où les développeurs utilisent une version de Node différente du compte daemon, l’absence de doctor masque vite la cause réelle. Ce guide vise à vous fournir, avant même l’ouverture d’un ticket, un dossier factuel qui accélère les échanges avec la plateforme interne ou les fournisseurs. Sur le long terme, vous réduisez aussi la répétition d’incidents identiques parce que la dérive documentée est enfin corrigée à la racine.
Signaux qui exigent doctor en premier
Ignorez les forums lorsque vous voyez ces motifs : la passerelle paraît saine mais les agents ne prennent pas les jobs ; les logs affichent Unauthorized avec le code 1008 ; ou Slack duplique les événements après modification d’un tunnel. Dans tous ces cas, openclaw doctor expose décalage de version, variables d’environnement manquantes ou jetons obsolètes avant que vous ne perdiez des heures sur des piles d’appels sans rapport. Associez doctor à openclaw status --deep si vous venez de mettre à jour Node. La documentation OpenClaw 2026 suppose Node 22.16+ ou Node 24 pour plusieurs chemins CLI. Un runtime plus ancien peut laisser passer l’installation puis échouer dès qu’un plugin importe des helpers réservés à l’ESM. Lorsque CI et staging ne partagent pas la même mineure, les bugs ne se reproduisent que sur un chemin—doctor rend cette divergence visible avant d’explorer le code applicatif.
Exportez un instantané au début d’un incident : copiez la sortie doctor, masquez les secrets et joignez les 200 premières lignes de openclaw logs. Les équipes qui prennent cette habitude ferment leurs tickets 40 à 60 % plus vite, car tout le monde lit les mêmes faits plutôt que des captures reconstituées. Après un changement de split tunnel VPN, relancez doctor depuis le même chemin réseau que la passerelle. Le routage asymétrique explique souvent des sondes réussies depuis un portable et des échecs depuis le compte daemon. Pour les détails proxy et tunnel, consultez passerelle, proxy et durcissement tunnel.
Dans les environnements multi-profils, doctor signale parfois quel fichier ~/.openclaw est réellement lu ; vérifiez alors les plists LaunchAgent et les shells interactifs pour des exports dupliqués. Une erreur classique consiste à renouveler les jetons dans le shell interactif pendant que launchd charge encore un fichier d’environnement plus ancien. Documentez, pour chaque profil, le chemin de configuration attendu et, après chaque rotation, validez via une commande de statut courte que le processus actif a bien été redémarré. Sans cette étape, les tableaux de bord peuvent croire à une rotation réussie alors que la passerelle conserve d’anciens secrets en mémoire.
Matrice des symptômes : commande et sens
Utilisez la matrice comme tableau de triage. Les commandes sont sûres sur un staging proche de la production ; planifiez les changements exigeant un redémarrage de passerelle dans des fenêtres de maintenance.
| Symptôme | Première commande | Ce qu’« aller bien » veut dire |
|---|---|---|
| Passerelle up mais l’UI ne se connecte pas | openclaw gateway status | Un seul PID d’écoute, adresse attendue (souvent 127.0.0.1 derrière proxy) |
| Déconnexions aléatoires | openclaw logs --follow | Pas d’erreurs TLS ou jeton répétées pendant 5 minutes après un aller-retour chat |
| Slack/Discord silencieux | openclaw channels status --probe | Chaque canal actif signale des points de terminaison joignables et des scopes OAuth valides |
| Conflits de port après déploiement | lsof -nP -iTCP:PORT | grep LISTEN | Un seul processus lié à OpenClaw détient le port |
| LLM 401 côté fournisseur | Vérifier clé API et facturation | Des clés développeur à l’usage—pas des abonnements grand public—alimentent l’automatisation |
Jetons de passerelle et allowedOrigins
Beaucoup d’intégrations ont cassé quand la configuration est passée d’un champ plat gateway.token à gateway.auth.token. Si votre reverse proxy injecte encore un en-tête hérité, régénérez avec openclaw doctor --generate-gateway-token et mettez à jour proxy et copies locales de ~/.openclaw/openclaw.json. Les clients navigateur exigent des entrées allowedOrigins explicites—http://localhost:3000 en dev, vos noms d’hôte en prod. Le joker * est pratique mais dangereux ; les auditeurs le signalent dès qu’OpenClaw est exposé sur Internet. Pour les tunnels, alignez les origines sur le guide passerelle, proxy et durcissement tunnel.
L’erreur EADDRINUSE signifie souvent deux profils ou un node zombie sur le même port. Tuez l’ancien PID, confirmez avec un second lsof, redémarrez via votre orchestrateur documenté. Sur serveurs macOS, suivez les schémas LaunchAgent versus cron pour des redémarrages déterministes. Évitez les pkill globaux qui tuent aussi des healthchecks. Après rotation des secrets, vérifiez caches proxy et anciennes unités launchd qui chargent encore d’anciens environnements.
Sondes de canaux au-delà du HTTP 200
Un webhook peut renvoyer 200 OK tout en perdant des événements si la vérification de signature échoue silencieusement. Après rotation, exécutez openclaw channels status --probe et envoyez un message synthétique depuis chaque surface de chat. Conservez les identifiants de corrélation dans les logs ; beaucoup d’équipes gardent 14 jours de rétention staging pour comparer à la production. En curl manuel, reproduisez exactement les en-têtes de l’intégration ; un préfixe Authorization: Bearer … manquant ou un saut de ligne dans le jeton produit des 401 ressemblant à une panne fournisseur. Comparez aussi les tailles de corps : certains proxys tronquent au-delà d’1 Mo, cassant de gros appels JSON jusqu’à ce que vous montiez les limites ou passiez à des envois chunkés.
Pour WhatsApp ou les ponts mobile-first, déconnectez les sessions desktop concurrentes comme le recommandent les éditeurs ; les sessions dupliquées donnent l’illusion que tout est livré sauf dans OpenClaw. Discord et Slack souffrent souvent d’intentions Read Message History ou Send Messages manquantes après durcissement des politiques d’espace. Planifiez une sonde hebdomadaire de cinq minutes—par exemple openclaw health --json avec mail si le code de sortie est non nul—afin de détecter les régressions avant la réunion du lundi plutôt que pendant une démo client. Archivez les résultats dans le temps pour repérer lentement dérive de latence ou de scopes.
Pourquoi diagnostiquer sur Cloud Mac
Les portables se mettent en veille, les VPN fluctuent, les politiques MDM bloquent les daemons—rien d’idéal pour un test de résistance de 72 heures. Un Mac mini Apple Silicon loué reste en ligne, offre les mêmes outils Unix que macOS local et isole les secrets du matériel personnel. SSH accélère la boucle : doctor, édition vim, rebonds de service, streaming de logs sans vous déplacer. Comparez environ 16,9 $ par jour de location élastique au coût d’opportunité d’un ingénieur bloqué toute l’après-midi. Le diagnostic n’a pas besoin de GPU ; il exige alimentation stable, horloges justes et pas de reboot OS au milieu d’un triage. Incident clos : arrêtez la location—impossible avec du matériel amorti au fond d’un placard.
Astuce : reflétez l’arborescence entre hôte cloud et images CI pour garder les chemins de openclaw.json portables. Des chemins codés en dur comme /Users/alice/Projects coûtent des heures quand les jobs migrent vers des comptes d’automatisation partagés. Réservez au moins 4 Go de RAM libre avant d’activer plusieurs ponts de canaux ; memory_pressure ou vm_stat révèlent le thrash avant que doctor ne prévienne. Surveillez fuseaux et NTP pour éviter les rejets de webhooks signés. Apple Silicon offre assez de marge pour des doctor parallèles, agrégation de logs et navigateurs légers pour tester les webhooks sans le bruit d’une tour surdimensionnée.
FAQ
Où est passé gateway.token dans les builds OpenClaw récents ?
Les versions récentes imbriquent l’authentification sous gateway.auth.token. Si des tableaux de bord lisent encore une ancienne clé plate, régénérez le jeton avec openclaw doctor --generate-gateway-token et collez la valeur partout où le reverse proxy ou l’UI l’attendent.
Pourquoi vois-je EADDRINUSE juste après un reboot ?
Les LaunchAgents, terminaux manuels et processus node orphelins peuvent lier le même port passerelle. Utilisez lsof -i :PORT pour identifier le PID, arrêtez les profils dupliqués et assurez une seule instance openclaw gateway par profil.
Un Mac mini cloud est-il utile pour diagnostiquer OpenClaw ?
Oui. Les Mac mini Apple Silicon offrent les mêmes outils Unix que macOS local, une alimentation stable pour de longues files de logs et l’isolation des portables qui dorment. La location garde les coûts élastiques pendant que vous itérez sur le durcissement de la passerelle.
OpenClaw brille quand l’hôte est ennuyeux : alimentation fiable, SSD rapides, comportement macOS aligné sur la prod. Apple Silicon donne de la marge pour doctor simultanés, agrégation de logs et navigateurs légers sans le vacarme des ventilateurs. Ajoutez de l’automatisation SSH et du VNC optionnel pour les vérifications visuelles : vous obtenez un banc diagnostic qui monte en incident et redescend en semaine calme—l’élasticité voulue quand les agents IA rejoignent le tissu de déploiement des ateliers HTML façon Mac.
Stager OpenClaw sur Apple Silicon toujours allumé
Louez un Mac mini cloud pour enchaîner doctor, passerelle et sondes sans mise en veille surprise ni MDM capricieux. Commencez par les offres, puis branchez SSH via le guide d’aide.