OpenClaw Runbook d'exploitation quotidienne : contrôles Gateway 18789, mises à jour progressives & planification des logs (2026)

Cet article répond à une seule question

Une fois le script d'installation OpenClaw terminé et le Gateway 18789 au vert pour la première fois, les équipes entrent souvent dans une phase « ça marche jusqu'à ce que ça casse » : des 401 sporadiques, un nœud qui se comporte différemment après une mise à jour, ou le Gateway qui s'arrête silencieusement parce que le disque racine est plein. Ces problèmes ne sont pas couverts par le guide d'installation.

Cet article répond à une seule question : comment standardiser les opérations quotidiennes d'OpenClaw en un Runbook réutilisable permettant à n'importe quel membre de l'équipe de réaliser un contrôle de santé ou un rollback en 15 minutes ? Périmètre : sondes de santé Gateway → stratégie de mise à jour progressive → procédure de rollback → choix Tailscale / SSH → planification du disque de logs.

1. Sondes de santé Gateway 18789

Le « health check » de beaucoup d'équipes se résume à un simple curl — ce n'est pas suffisant. Lorsque le port est occupé par un processus résiduel ou que launchd n'a pas correctement redémarré le service, curl reste suspendu plutôt que d'échouer immédiatement. Une sonde correcte valide à la fois la réponse HTTP et le propriétaire du port.

# 1. Liveness HTTP : attendre 200, alerter en cas d'échec
curl -fsS --max-time 3 http://127.0.0.1:18789/health \
  && echo "gateway OK" || echo "GATEWAY FAIL"

# 2. Vérification du propriétaire du port : le PID doit appartenir à node/openclaw
lsof -nP -iTCP:18789 -sTCP:LISTEN

# 3. Dernières lignes d'erreur (ajuster le chemin selon l'installation)
tail -n 50 ~/.openclaw/logs/gateway.log | grep -i "error\|warn\|exit"

Si curl renvoie 200 mais que le Dashboard est lent, vérifiez d'abord les I/O disque : iostat -d 1 5. Confondre un pic d'écriture de logs avec une panne Gateway est la fausse alerte la plus fréquente. Maintenez un « nœud doré » sur la même version que la production pour comparer immédiatement en cas d'anomalie.

2. Trois vérifications avant chaque mise à jour

OpenClaw publie des mises à jour fréquemment. Suivre chaque version sans précaution introduit deux risques : des changements de clés de configuration empêchant le démarrage du Gateway, ou des incompatibilités avec la configuration existante des Channels. Les mises à jour progressives sont la méthode standard, mais beaucoup d'équipes interprètent « progressif » comme « essayer sur une machine d'abord » en omettant le gel de version et la vérification de l'espace disque.

# Enregistrer la version actuelle
npm list -g openclaw --depth=0 > .upgrade-memo

# Archiver la configuration actuelle
tar czf openclaw-config-$(date +%Y%m%d).tar.gz \
  ~/.openclaw/config/ \
  ~/Library/LaunchAgents/com.openclaw.gateway.plist

# Vérifier l'espace disque ≥ 15%
df -h / | awk 'NR==2 {print "Libre :"$4, "Utilisé :"$5}'

3. Rollback : restauration en deux étapes tarball + plist

La cause la plus fréquente d'échec d'un rollback n'est pas la version du binaire — c'est l'incompatibilité des clés de configuration. Une nouvelle version peut avoir ajouté des champs obligatoires ; revenir au binaire tout en laissant la nouvelle configuration provoque une erreur de démarrage du Gateway. L'ordre correct est : bootout → restaurer le tarball → rétrograder le binaire → bootstrap.

# Étape 1 : arrêter le service
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist

# Étape 2 : restaurer le tarball de configuration
tar xzf openclaw-config-20260604.tar.gz -C /

# Étape 3 : rétrograder le paquet npm
npm install -g openclaw@1.x.x   # remplacer par le tag de version enregistré

# Étape 4 : redémarrer le service
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist

# Étape 5 : vérification (laisser ~10 s au démarrage)
sleep 10 && curl -fsS http://127.0.0.1:18789/health && echo "Rollback OK"

Attention à la dérive du chemin plist : si l'installateur de la nouvelle version a réécrit ProgramArguments, le bootout doit utiliser le nouveau chemin plist et le bootstrap l'ancien plist restauré. Ces chemins peuvent différer — raison de plus pour comparer ancien et nouveau plist avant la mise à jour.

4. Tailscale vs SSH/rsync : lequel utiliser dans quel cas

Le débat classique « Tailscale ou SSH direct ? » est un faux dilemme. Chacun excelle dans un scénario différent. Tailscale brille pour l'accès multi-appareils et multi-régions sans règles de pare-feu. SSH/rsync est le bon choix pour les transferts massifs où le goulot d'étranglement est la bande passante sortante, pas le surcoût protocolaire.

# Récupérer les archives de logs depuis le nœud Canada, limite 50 Mo/s, reprise
rsync -avz --bwlimit=50000 --partial \
  user@canada-m4.hashvps.com:~/.openclaw/logs/archive/ \
  ./local-logs/

# Vérifier que Tailscale utilise une connexion directe (pas DERP)
tailscale ping canada-m4 --until-direct

5. Planification du disque de logs : logrotate et conseils de partition

Une part surprenante des arrêts inattendus du Gateway s'explique par un disque racine plein. Par défaut, OpenClaw écrit les logs dans le répertoire utilisateur — le même volume que le cache npm global. Ajoutez des exports Xcode ou des fichiers temporaires CI et vous pouvez remplir silencieusement un disque de 512 Go en quelques semaines. La bonne solution est logrotate, pas un rm périodique.

/Users/mac/.openclaw/logs/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    dateext
    copytruncate
}

# Ajouter à crontab (exécution à 03 h 00 chaque jour) :
# crontab -e, puis ajouter :
# 0 3 * * * /usr/local/bin/logrotate /Users/mac/.openclaw/logrotate.conf

Pour le cache npm, définissez npm config set cache-max 10240 pour le limiter à 10 Go et exécutez npm cache clean --force après chaque mise à jour. Sur un nœud 1 To, envisagez de déplacer ~/.openclaw/logs et le cache npm sur un volume séparé — si les logs explosent, cela n'affecte pas le disque racine ni le processus Gateway.

6. FAQ : six questions fréquentes en exploitation

Le health check Gateway 18789 renvoie autre chose que 200 — où regarder en premier ?

Exécutez lsof -nP -iTCP:18789 -sTCP:LISTEN pour vérifier qu'un processus écoute. Aucune sortie signifie que le processus ne tourne pas : vérifiez launchd avec launchctl list | grep openclaw, puis consultez les 50 dernières lignes de ~/.openclaw/logs/gateway.log. Si le port écoute mais que HTTP renvoie 500, suspectez une erreur de clé de configuration — comparez avec le tarball pré-mise à jour.

Après un rollback, faut-il modifier manuellement le chemin plist ?

Uniquement si l'installateur de la nouvelle version a modifié ProgramArguments. Pour une simple mise à jour npm sans changement d'installateur, la restauration du tarball laisse le plist intact. Si le chemin du binaire a changé, mettez à jour ProgramArguments dans le plist pour pointer vers l'ancien binaire avant de lancer bootstrap — c'est pourquoi comparer ancien et nouveau plist avant la mise à jour appartient au runbook.

Faut-il mettre à jour plusieurs nœuds simultanément ou un par un ?

Toujours un par un. Mettez à jour le nœud doré en premier ; observez la santé du Gateway et le SLA des Channels pendant 24 heures. Puis déployez les nœuds de production l'un après l'autre avec au moins 30 minutes d'intervalle. Une mise à jour simultanée signifie qu'en cas de problème, il n'y a aucune référence de comparaison et tous les nœuds tombent en même temps.

Le Dashboard affiche 100 % CPU — est-ce un bug OpenClaw ?

Pas nécessairement. Utilisez top -o cpu ou Activity Monitor pour identifier le PID réellement consommateur. Un processus Gateway OpenClaw sain devrait tourner à 1–5 % en régime permanent. Si c'est un processus node qui explose, vérifiez les requêtes Channel en attente ou des écritures de logs anormales. Sur un Mac mini dédié, utilisez renice pour baisser la priorité des processus Xcode qui concurrencent OpenClaw.

Tailscale est connecté mais impossible d'accéder au Dashboard — pourquoi ?

Vérifiez dans votre politique ACL Tailscale que le port 18789 est autorisé pour cet appareil. Récupérez ensuite l'IP tailnet avec tailscale ip -4 et testez directement : curl http://<tailnet-ip>:18789/health. Si l'IP fonctionne mais pas le nom d'hôte MagicDNS, c'est un problème de résolution DNS, pas un problème Gateway.

Après l'exécution de logrotate, le Gateway continue-t-il d'écrire dans le bon fichier ?

Avec copytruncate, logrotate copie le fichier puis tronque l'original sur place — le descripteur de fichier du Gateway reste valide tout au long. Si vous utilisez le mode create par défaut, envoyez un signal SIGHUP au Gateway ou utilisez un script postrotate pour exécuter launchctl kickstart et rouvrir le handle de log. copytruncate est plus simple et évite toute interruption de service.