L’onboarding fonctionne, mais le CLI ou le tableau de bord reste longtemps sur Gateway not ready / not ready : cela arrive en général avant que le processus écoute vraiment, une couche distincte de l’article gateway closed (1000) (sessions, scopes, tokens). Ce guide donne aux ingénieurs plateforme le chemin le plus court : sept points pour ports, mémoire, timeouts, images et droits sur volumes, un tableau bare metal systemd vs Docker pour choisir la bonne surface de logs, puis un runbook en six étapes (dont openclaw doctor et exemples de commandes), à lire avec le guide d’installation, la production Docker et l’observabilité.
not ready signifie souvent que le plan de contrôle n’a pas encore vu une écoute réussie, des dépendances prêtes ou des sondes de santé vertes ; ce n’est pas un décrochage policy après WebSocket ouvert—pour cela, voir d’abord closed (1000). Les sept points ci-dessous sont une auto-vérification plateforme la première semaine après installation.
Port retenu par un ancien processus ou un autre service : après upgrades ou docker compose up répétés, un ancien Gateway sur l’hôte peut garder le même port ; le nouveau démarre à moitié et la CLI affiche seulement not ready.
Mémoire et swap insuffisants (OOM) : sur un petit VPS qui tire un modèle et le Gateway, le processus Node peut être tué avant ready—souvent code 137 ou disparition silencieuse.
Timeout de démarrage trop court : pulls froids ou builds natifs dépassent le startupTimeout par défaut, les healthchecks échouent tôt, « not ready » infini.
Mauvais journal : en mélangeant systemd et Docker, on tail le conteneur alors qu’une unité hôte lance encore une ancienne binaire—ou l’inverse.
Droits sur volumes nommés et mapping UID : l’utilisateur conteneur ne peut pas écrire l’état ; le Gateway boucle en crash, l’extérieur ne voit que not ready.
Dérive digest d’image vs config : compose pointe sur :latest mais les couches en cache ne matchent pas les nouveaux champs openclaw.json ; le script d’entrée sort tôt.
Confondre réseau et échec de démarrage : timeouts registre modèle/plugin bloquent l’init—séparer DNS/egress du Gateway.
Point commun : jamais d’état servable, donc status/RPC « à moitié vert ». Mettez-les dans le modèle de ticket, puis utilisez le tableau pour choisir la surface de logs et éviter de sauter entre journal et docker logs.
Cohérent avec l’installation multiplateforme : là « ça s’installe » ; ici « ça ne monte pas ». Avec l’observabilité : là métriques longues durées et rollback ; ici pannes dures avant première disponibilité.
Sur un Mac distant dédié ou un petit VPS Linux, mettez mémoire minimale et marge disque dans la revue de changement, pas seulement les versions—sinon pics de not ready avant les démos. Le tableau condense « quel journal ? » en décision.
Enfin : n’exposez pas temporairement le Gateway sur Internet public pour « tester la connectivité » avant de savoir ce qui écoute ; suivez l’exposition minimale dans le durcissement sécurité.
Pour déboguer not ready, décidez d’abord de la forme d’entrée : systemd ou compose dans un conteneur ? Les mélanger fait perdre du temps.
| Dimension | Linux/macOS bare metal + systemd (ou launchd) | Docker / Compose |
|---|---|---|
| Premier écran de logs | journalctl -u <unit> -n 200 --no-pager ou équivalent plateforme | docker compose logs --tail=200 <service>, aligné sur les horodatages de redémarrage |
| Conflits de ports | Sur l’hôte, lsof -nP -iTCP:<port> -sTCP:LISTEN (exemple) | Écoute sur hôte et dans le conteneur ; ports publiés vs services hôte existants |
| Droits / volumes | Propriétaire du répertoire d’état vs utilisateur d’exécution | UID de volume nommé, root en lecture seule vs montages en écriture ; voir production Docker |
| Timeouts / retries | Unit TimeoutStartSec, politique Restart= | Healthcheck start_period, retries, démarrage à froid de l’image |
| Upgrade / rollback | Version du paquet + chemin de sauvegarde config saine | Digest d’image figé + fichiers compose versionnés ; même esprit que la section rollback observabilité |
« Confirmer l’écoute, puis parler sessions » : en phase not ready, le meilleur ROI est ports + ressources + bonne fenêtre de logs, pas changer les tokens en premier.
Avec Ubuntu 24.04 + systemd + Tunnel, vérifiez que l’amont tunnel pointe encore sur le bon port ; sinon le monde extérieur reste not ready alors que curl 127.0.0.1 semble bon localement.
Sous Docker, erreur fréquente : « conteneur Exited mais compose semble bloqué »—docker compose ps -a pour les codes de sortie, puis droits volumes et script d’entrée.
Quand le processus écoute et les sondes passent, si les clients dérivent encore, passez au chemin session dans closed (1000).
L’ordre met d’abord les contrôles peu coûteux : ressources et ports avant config et images. Les sous-commandes exactes dépendent de votre build OpenClaw.
Geler les retries concurrents : pausez les scripts de reconnexion auto pour éviter la tempête de connexions.
Capturer version et snapshot ressources : openclaw --version, uname -a, mémoire et disque libres dans le ticket.
Vérifier ports et processus obsolètes : test d’écoute sur le port configuré ; ancien PID stoppé/redémarré selon docs systemd/Docker.
doctor / validate : openclaw doctor ou équivalent, corriger les manques, relancer.
Élargir la fenêtre d’observation : si possible, augmenter temporairement gateway.startupTimeout ou le start_period du healthcheck compose pour distinguer « lent » et « mort ».
Acceptation minimale : après santé curl locale ou sous-commande status « ready », rouvrir aux autres ; sinon escalade avec extraits de la section 4.
openclaw --version openclaw doctor # exemple systemd : # journalctl -u openclaw-gateway -n 120 --no-pager # exemple Docker : # docker compose logs --tail=120 gateway # puis redémarrer l’unité / le service compose selon la doc
Remarque : si les logs CLI montrent des timeouts de téléchargement modèle/plugin, séparez l’egress du Gateway ; fenêtre de maintenance pour assouplir les allowlists, puis resserrer—voir durcissement sécurité.
Avec le guide d’installation : après changement de facturation Anthropic ou de forme de clé API, une seule source de vérité pour variables d’environnement et fichiers de config, sinon blocage sur les clés et aspect not ready.
Sur un Mac distant dédié avec Gateway longue durée, mettez politique de restart launchd/unit et nettoyage disque dans le même runbook pour éviter la boucle not ready quand le disque est plein.
Épinglez cette carte « description → action » dans le canal astreinte. Si les symptômes incluent déjà des codes de fermeture WebSocket, passez à closed (1000).
Port déjà utilisé : arrêter l’ancien processus avant le nouveau ; ne pas scaler sans port libre. Manque de mémoire : baisser la concurrence ou ajouter swap/montée de gamme avant le tuning. Échec de pull d’image : docker pull ou corriger les identifiants registry avant la config Gateway.
Attention : pas de nettoyage type docker system prune en production sans traçabilité ; risque de supprimer des sauvegardes de volumes nommés encore utiles. Documentez les chemins de nettoyage dans le changement.
Avec l’observabilité : après correction du not ready, étiquetez la cause racine (port/mémoire/image/volume) pour éviter la réouverture hebdomadaire.
Si le Gateway tourne avec des processus enfants MCP sur le même hôte, le démarrage doit aussi couvrir chemins binaires enfants et montages sandbox visibles dans le conteneur—sinon le parent bloque sur la découverte d’outils.
Ces champs alignent les équipes ; anonymisez avant diffusion externe.
Uniquement sur portable personnel : fragile face au sommeil et aux mises à jour OS ; petit VPS souvent OOM au démarrage à froid. Pour une couche d’exécution macOS durable et contractuelle avec OpenClaw et sa toolchain, un Mac distant dédié est en général plus stable qu’un portable emprunté. Face au bricolage matériel, la location cloud Mac Mini NodeMini offre SSH fixe et paliers disque clairs pour transférer « Gateway + toolchain » comme un nœud d’infrastructure. Spécifications et tarifs : tarifs Mac Mini ; accès et questions : centre d’aide ; série OpenClaw depuis la catégorie blog.
Utilisez cet article si le processus n’écoute pas ou si vous suspectez ports, mémoire ou timeouts ; closed (1000) si le WebSocket était ouvert puis fermé par politique ou session. Capacité et accès : tarifs Mac Mini et centre d’aide.
docker compose logs --tail=120 gateway plus dmesg hôte / snapshot ressources sur la même fenêtre ; si doute sur les droits volumes, ajoutez les codes de sortie de docker compose ps -a.
Ouvrez la catégorie OpenClaw du blog pour installation, Docker, systemd, sécurité, observabilité et MCP ; cet article correspond à la phase « ne démarre pas ».