Contrôle en amont · médecin · Matrice d'erreurs · Déploiement reproductible
Les constructeurs câblent leur premier canalgénéralement caler sur "La passerelle ne démarre pas" - pas des modèles faibles. Versions des nœuds, autorisations du répertoire,.envvs la dérive YAML, les ports occupés, les proxys et le DNS peuvent chacun exploser en journaux rouges. Ce guide donne unliste de contrôle avant le vol, unminimal vs multicanalcomparaison,six étapes de diagnostic(y comprisopenclaw doctor), unmatrice des symptômes d'erreur, et unauto-vérification de la migration vers le cloud. Pour les lignes de base pm2 et toujours actives, lisez lePlaybook de déploiement cloud persistant; pour le contexte de tarification, ouvrezprix de location.
Les scripts d'installation semblent courts ; la partie la plus coûteuse consiste à écrire des hypothèses d'exécution : quel utilisateur lance Gateway, où les configurations sont résolues, les chemins de journal par défaut, quels ports doivent être libres et qui possède le proxy/DNS. De nombreux incidents « La passerelle ne démarre pas » sont des interactions d'autorisation Node plus macOS, et non la logique OpenClaw. Les cinq lacunes ci-dessous apparaissent constamment dans les fils de discussion de la communauté : capturez-les dans un Runbook pour éviter de les réinstaller trois fois avant de remarquer une dérive de PATH.
Si vous planifiez Slack ou Telegram ensuite, décidezrotation des jetonsetrépertoires de moindre privilègetôt; Le succès du premier canal avec des variables d'environnement obsolètes rend la deuxième rotation douloureuse.
Dérive du gestionnaire de nœuds et de packages :OpenClaw s'attend à un Node LTS moderne. Mélanger nvm, fnm et nœud système donne souvent des résultats correctsnode -vdans un terminal mais un vieux binaire sous votre superviseur de processus. Épinglez une invocation en or et vérifiez le vrai binaire dans la sortie du médecin.
Répertoire de travail et limites des autorisations :Le clonage dans des dossiers de bureau ou sauvegardés par iCloud invite à des verrous ou à des surprises d'autorisation. Conservez les arborescences de production sous une sous-arborescence dédiée dans l'accueil de l'utilisateur du service et documentez les chemins AgentSkill accessibles en écriture.
Paramètres par défaut des ports et du pare-feu :Les écouteurs du tableau de bord et de la passerelle qui entrent en collision avec d'autres démons se ferment immédiatement ; les proxys d'entreprise ou les pare-feu hôtes peuvent bloquer les appels LLM sortants. Ajoutez une analyse de port et un test de fumée de boucle sortante sur une ligne au contrôle en amont.
Plusieurs sources de configuration : .env, les profils shell, les blocs d'environnement launchd/pm2 et les superpositions YAML créent ensemble des bogues « J'ai édité le mauvais fichier ». Choisissez une source unique de vérité et de priorité des documents.
Lacunes en matière de journalisation et d’observabilité :Sans destinations ni rotation de la sortie standard, la première longue exécution remplit les disques ou fait défiler la véritable erreur. Corrigez les chemins et la rétention au moment de l’installation – un ordre de grandeur moins cher que la modernisation des moniteurs.
Consultez la liste, puis choisissez un chemin d'installation dans la section suivante : passerelle minimale uniquement ou topologie de production multicanal.
L’activation de Slack, de la messagerie et des webhooks dès le premier jour fait exploser la matrice des échecs. Plus sûr :démarrer Gateway sur le plus petit profil avec des journaux sains, puis ajoutez un adaptateur de canal par fenêtre de modification afin que les restaurations restent évidentes. Le tableau aligne les attentes pour votre premier avis.
| Dimension | Minimal (passerelle + canal unique ou CLI) | Incrémental multicanal |
|---|---|---|
| But | Valider le processus, l'analyse de la configuration, la sortie LLM, les compétences de base | Valider le routage, la rotation des jetons, l'isolation des sessions simultanées |
| Surface de configuration | Peu de variables d'environnement, YAML superficiel | De nombreux webhooks/jetons ; la surface d'erreur augmente rapidement |
| Ordre de tri | Journaux de la passerelle et médecin d'abord, puis modèle de l'API | Séparer les erreurs de canal des erreurs d'agent |
| Coût de restauration | Faible - commentez un adaptateur et un diff | Élevé : conservez des instantanés par canal |
| Idéal pour | Constructeurs débutants et petites équipes | Les équipes avec des Runbooks se dirigent vers la production |
Stabiliser une passerelle inactive avant les adaptateurs ; l'inversion de l'ordre empile trois classes d'erreurs dans un seul flux de journaux.
Ces étapes isolentéchec au niveau du processus(sortie au démarrage, mauvaise configuration, ports occupés). Si le processus est sain mais que les messages n’arrivent jamais, déboguez les adaptateurs uniquement une fois que Gateway apparaît en vert. Les CLI communautaires expédient souventopenclaw doctor(ou une variante de correctif) — remplacez la sous-commande exacte de vos notes de version.
Gelez la commande repro :Enregistrez le script npm par rapport à la CLI globale par rapport à pm2, plus cwd, dans le ticket.
Exécutez l’auto-vérification de l’environnement :Exécuteropenclaw doctor, archivez la sortie complète et encerclez les chemins de nœuds, les refus d'autorisation, les dépôts manquants et les erreurs de schéma.
Validez les configurations par couches :Analysez YAML/JSON, puis vérifiez que les variables d'environnement ne sont pas remplacées par les profils shell.
Vérifiez les auditeurs :Assurez-vous que les ports du tableau de bord et de la passerelle sont libres ; notez les bizarreries du VPN lors du bouclage.
Capturez les 200 premières lignes de journal :Marchez vers le haut à partir de la première ERREUR – les causes profondes apparaissent souvent plus tôt sous forme d’avertissements.
Test de restauration minimal :Désactivez les adaptateurs facultatifs et les compétences tierces, conservez un échantillon officiel, puis divisez les restaurations en deux.
cd /path/to/openclaw node -v npm -v openclaw doctor openclaw doctor --fix npm run start 2>&1 | tee /tmp/openclaw-boot.log lsof -nP -iTCP -sTCP:LISTEN | grep -E '3000|8787'
Conseil: doctor --fixmute la configuration locale - fichiers d'instantanés ou exécute le contrôle des modifications avant de l'utiliser sur les nœuds de production.
Utilisez-le comme une carte de triche d'astreinte : faites correspondre le symptôme, exécutez la première action, puis élargissez ensuite la recherche. Si trois passes échouent, revenez à la section trois pour les journaux complets et divisez-les en deux.
| Symptôme | Cause probable | Première action |
|---|---|---|
| Sortie immédiate, pas de stack | Incompatibilité de nœud ou mauvais binaire sur PATH | Alignez le nœud nvm/pm2 ; relancer le docteur |
| Erreurs d'analyse YAML/JSON | Indentation, encodage, fusion indésirable | Valider la syntaxe ; restaurer la configuration minimale |
| Port déjà utilisé | Processus zombie ou démon en conflit | lsof, libère le port ou change le |
| Délais d'expiration LLM/erreurs TLS | Proxy, DNS, MITM d'entreprise | test de sortie de boucle ; chaîne de confiance / HTTPS_PROXY |
| L'authentification du canal échoue pendant la durée du processus | Dérive d'URL de jeton ou de webhook expiré | Faites pivoter les secrets ; vérifier l'hôte de rappel |
| AgentSkill EACCÈS | Autorisations du système de fichiers ou bac à sable | Corriger la propriété ; scripts de compétences d'audit |
Avertissement:Évitez les répétitionssudo npm install -gsans comprendre le modèle de processus - les globaux peuvent signaler "installé" alors que l'exécution résout toujours la mauvaise arborescence de modules.
La lutte contre les incendies et la fiabilité à long terme sont des disciplines adjacentes : la première optimise les démarrages à froid reproductibles, la seconde optimise la reprise après incident et l'auditabilité. Ces invites mesurables facilitent les révisions sans remplacer les documents en amont.
Quand les ordinateurs portables ne peuvent pas se rencontrersans surveillanceetdialogue zéroexigences, les auto-vérifications du cloud ajoutent une politique de redémarrage du tuteur, l'exposition du tableau de bord et la rotation des journaux - copiez les ancres de production duPlaybook cloud persistant.
Rappel de sécurité :Ne collez jamais complètement.envfichiers dans le chat ; utiliser des canaux secrets expirés et la révocation de documents.
Les ordinateurs portables jonglant avec la veille, les mises à jour et les sessions partagées injectent un caractère aléatoire que les installations fonctionnelles ne peuvent pas corriger. Les nœuds Mac cloud dédiés et placés par région facilitent les « démarrages quotidiens » plutôt que les « démarrages lorsque le couvercle est ouvert ». Pour les équipes intégrant OpenClaw dans les normes de livraison,La location cloud VpsMesh Mac Mini est généralement la meilleure solution: Apple Silicon natif, métal 24h/24 et 7j/7, fenêtres de location flexibles : passez des cycles sur la logique de la passerelle plutôt que sur l'état de la machine.
Généralementdérive cwdouremplacements d'environnement: pm2/systemd charge un autre chemin que votre shell interactif. Capturez argv et cwd de la section trois avant de faire à nouveau confiance au médecin.
Les SLA Heartbeat et sans surveillance survivent rarement aux ordinateurs portables. Lire leguide de déploiement persistant, puis utilisez lepage de commandeetpage de tarificationpour les régions.
Commencez par leCentre d'aidepour les sujets SSH/VNC ; conservez les résultats du médecin ainsi que les journaux de démarrage pour les escalades.