Fini les crashs Terminal : openclaw doctor pour passerelle inactive, auth modèle et runbook de secours en six étapes sur Mac (2026)

Vous double-cliquez un raccourci — ou tapez openclaw dans Terminal — et la fenêtre disparaît. Pas de stack trace, pas de boîte de dialogue claire, juste le silence. Pendant ce temps Slack affiche toujours « gateway not active », les sélecteurs de modèle tournent indéfiniment, et les pop-ups de permission que vous avez fermées hier reviennent en rouge. Ce n’est pas « vous n’y connaissez rien en informatique » ; c’est une dérive d’environnement : mauvais Node, mauvais utilisateur, mauvais fichier de config, ou un processus gateway qui n’a jamais survécu à launchd.

openclaw doctor est la commande officielle d’auto-diagnostic d’OpenClaw. Elle imprime une checklist structurée — CLI dans le PATH, lisibilité de la config, accessibilité du gateway, profils d’auth, espace disque — pour que vous corrigiez une ligne à la fois au lieu de tout réinstaller d’après un article de blog. Ce tutoriel est la voie de secours débutant : ce que doctor vérifie, comment lire les lignes jaunes vs rouges, un runbook en six étapes que vous pouvez coller dans un ticket, et deux recettes de dépannage pour les erreurs que les débutants voient vraiment. Pour une acceptation de niveau SLA après onboarding sur un Mac loué, lisez la matrice post-onboarding doctor séparée ; cet article, c’est « ça a encore planté aujourd’hui ».

À associer dès la première mention avec le contrat d’installation hour-zero OpenClaw (plancher Node 22+), les limites de débit et alertes budget (pour que les retries ne ressemblent pas à des crashes), et OpenClaw + Ollama quand les modèles locaux remplacent les clés cloud. Référence d’installation upstream : script d’installation OpenClaw et exemples de configuration gateway. Contexte matériel : spécifications Apple Mac mini.

Divulgation : KvmZone n’est mentionné que là où un Mac loué offre aux débutants un shell SSH propre pour openclaw doctor. La plupart des étapes fonctionnent sur n’importe quel Mac que vous possédez déjà.

Pourquoi doctor vaut mieux qu’une réinstallation complète

En Chine continentale, une sortie lente ou filtrée vers les miroirs npm peut ressembler à « OpenClaw est cassé » alors que la vraie cause est un timeout registry — les lignes réseau/TLS de doctor sont votre première preuve. Des hôtes Mac loués optionnels à Hong Kong ou Singapour ne sont pas requis pour doctor lui-même.

Architecture : ce qu’inspecte openclaw doctor

Terminal / launchd → openclaw CLI → doctor module → reads ~/.openclaw/* → probes gateway HTTP → prints PASS/WARN/FAIL lines

Fichiers et rôles

Doctor ne remplace pas les tests de charge ni la planification webhook POP — c’est la matrice post-onboarding. Il indique si vous avez le droit d’accuser le fournisseur de modèle.

Matrice de décision : type de crash → première commande

Chemin recommandé : Si le shell se ferme en flash, lancez doctor en interactif d’abord — ne déboguez jamais via un raccourci GUI. Si doctor est vert mais l’agent barre de menu dit encore inactive, corrigez l’utilisateur launchd et le port, pas la clé API LLM.

Runbook de secours openclaw doctor en six étapes

Étape 1 — Ouvrir un vrai shell (pas un alias double-clic)

# macOS: use Terminal.app or iTerm — note the user name
whoami
echo $SHELL

Conservez la sortie ; les raccourcis qui sautent les login shells masquent les corrections PATH.

Étape 2 — Confirmer Node 22+ et CLI dans le PATH

node -v
which openclaw
openclaw --version

Pass : node affiche v22 ou plus récent ; which openclaw renvoie un seul chemin sous /opt/homebrew ou votre préfixe global documenté.

Étape 3 — Lancer doctor et sauvegarder la transcription

openclaw doctor 2>&1 | tee ~/openclaw-doctor-$(date +%Y%m%d).log

Joignez ce fichier à tout ticket support. Relancez après chaque correction — n’empilez pas les suppositions.

Étape 4 — Corriger le premier FAIL (souvent PATH ou JSON config)

# Example: validate JSON before restart
python3 -m json.tool < ~/.openclaw/openclaw.json > /dev/null && echo "JSON OK"

Si le JSON échoue, restaurez depuis la sauvegarde :

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)

Étape 5 — Aligner l’utilisateur daemon (fix gateway inactive)

# See which user launchd uses (label varies by install)
launchctl print system/com.openclaw.gateway 2>/dev/null | head -20
# Run doctor as that user if different from Step 1
sudo -u _openclaw openclaw doctor 2>&1 | tee ~/openclaw-doctor-daemon.log

Pass : les transcriptions interactives et daemon correspondent, ou chaque écart est documenté.

Étape 6 — Redémarrer le gateway et vérifier le status

openclaw gateway restart   # or launchctl kickstart per your install doc
sleep 5
openclaw status
openclaw doctor

Pass : status affiche le port en écoute ; doctor n’a aucune ligne FAIL inexpliquée. Ensuite — et seulement ensuite — retentez votre agent ou raccourci.

Pour les hôtes loués SSH-only, utilisez le workflow SSH Mac distant plutôt que des outils pixel sauf si une porte GUI documentée l’exige.

Dépannage

Schéma d’erreur : zsh: command not found: openclaw (ou fermeture instantanée de fenêtre)

Symptômes : script ou wrapper .app quitte avant toute UI ; doctor ne s’exécute jamais.

Correctif :

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
npm install -g openclaw@latest
openclaw doctor

Alignez le même PATH dans le plist launchd EnvironmentVariables (voir le contrat hour-zero).

Schéma d’erreur : gateway not active / ECONNREFUSED 127.0.0.1

Symptômes : la CLI existe ; l’UI ou openclaw status n’atteint pas le gateway local.

Correctif :

lsof -iTCP -sTCP:LISTEN | grep -i openclaw
openclaw doctor
openclaw gateway restart

Si le port appartient à un autre utilisateur, arrêtez le processus orphelin ou changez gateway.port dans ~/.openclaw/openclaw.json, puis relancez doctor. Configurez les limites de débit une fois le gateway stable — les tempêtes de retry ressemblent à des crashes.

FAQ

Lecture associée

• Contrat d’installation hour-zero OpenClaw — discipline Node 22+
• Post-onboarding doctor + webhook POP — ingress des callbacks
• Limites de débit et alertes budget OpenClaw — tempêtes de retry vs crashes
• OpenClaw + Ollama sur M4 loué — modèles locaux sans clés cloud
• Workflow sécurité SSH Mac distant — opérations SSH-only