Dépannage

Cette page couvre les problèmes courants que vous pouvez rencontrer lors de l’installation, de la configuration ou de l’exécution de NemoClaw, ainsi que les étapes de résolution.

Conseil : Si votre problème n’est pas listé ici, rejoignez le canal Discord NemoClaw pour poser des questions et obtenir de l’aide de la communauté. Vous pouvez également signaler un problème sur GitHub.

Installation

nemoclaw introuvable après l’installation

Si vous utilisez nvm ou fnm pour gérer Node.js, l’installateur peut ne pas mettre à jour le PATH de votre shell actuel. Le binaire nemoclaw est installé mais la session shell ne sait pas où le trouver.

Exécutez source ~/.bashrc (ou source ~/.zshrc pour zsh), ou ouvrez une nouvelle fenêtre de terminal.

L’installateur échoue sur une plateforme non prise en charge

L’installateur vérifie le système d’exploitation et l’architecture pris en charge avant de continuer. NemoClaw nécessite Linux Ubuntu 22.04 LTS ou ultérieur. Si vous voyez une erreur de plateforme non prise en charge, vérifiez que vous utilisez une distribution Linux prise en charge.

La version de Node.js est trop ancienne

NemoClaw nécessite Node.js 20 ou ultérieur. Si l’installateur se termine avec une erreur de version Node.js, vérifiez votre version actuelle :

$ node --version

Si la version est inférieure à 20, installez une version prise en charge. Si vous utilisez nvm, exécutez :

$ nvm install 20
$ nvm use 20

Puis relancez l’installateur.

Docker ne fonctionne pas

L’installateur et l’assistant de configuration nécessitent que Docker soit en cours d’exécution. Si vous voyez une erreur de connexion Docker, démarrez le démon Docker :

$ sudo systemctl start docker

Sur macOS avec Docker Desktop, ouvrez l’application Docker Desktop et attendez qu’elle ait fini de démarrer avant de réessayer.

L’installation npm échoue avec des erreurs de permission

Si npm install échoue avec une erreur de permission EACCES, n’exécutez pas npm avec sudo. Configurez plutôt npm pour utiliser un répertoire dont vous êtes propriétaire :

$ mkdir -p ~/.npm-global
$ npm config set prefix ~/.npm-global
$ export PATH=~/.npm-global/bin:$PATH

Ajoutez la ligne export à votre ~/.bashrc ou ~/.zshrc pour la rendre permanente, puis relancez l’installateur.

Port déjà utilisé

Le gateway NemoClaw utilise le port 18789 par défaut. Si un autre processus est déjà lié à ce port, la configuration échoue. Identifiez le processus en conflit, vérifiez qu’il est sûr de l’arrêter, et terminez-le :

$ lsof -i :18789
$ kill <PID>

Si le processus ne se termine pas, utilisez kill -9 <PID> pour le forcer à s’arrêter. Puis relancez la configuration.

Configuration

Erreurs cgroup v2 lors de la configuration

Sur Ubuntu 24.04, DGX Spark et WSL2, Docker peut ne pas être configuré pour la délégation cgroup v2. La vérification préliminaire de la configuration détecte cela et échoue avec un message d’erreur clair.

Exécutez le script de configuration Spark pour corriger la configuration cgroup de Docker, puis relancez la configuration :

$ sudo nemoclaw setup-spark
$ nemoclaw onboard

Nom de sandbox invalide

Les noms de sandbox doivent suivre les règles de sous-domaine RFC 1123 : caractères alphanumériques minuscules et tirets uniquement, et doivent commencer et se terminer par un caractère alphanumérique. Les lettres majuscules sont automatiquement converties en minuscules.

Si le nom ne correspond pas à ces règles, l’assistant se termine avec une erreur. Choisissez un nom tel que my-assistant ou dev1.

La création du sandbox échoue sur DGX

Sur les machines DGX, la création du sandbox peut échouer si le DNS du gateway n’a pas fini de se propager ou si un ancien transfert de port d’une précédente configuration est encore actif.

Exécutez nemoclaw onboard pour réessayer. L’assistant nettoie les anciens transferts de port et attend automatiquement que le gateway soit prêt.

Socket Colima non détecté (macOS)

Les versions récentes de Colima utilisent le répertoire de base XDG (~/.config/colima/default/docker.sock) au lieu du chemin historique (~/.colima/default/docker.sock). NemoClaw vérifie les deux chemins. Si aucun n’est trouvé, vérifiez que Colima fonctionne :

$ colima status

Exécution

Le sandbox apparaît comme arrêté

Le sandbox a peut-être été arrêté ou supprimé. Exécutez nemoclaw onboard pour recréer le sandbox à partir du même blueprint et des mêmes définitions de politique.

Le statut affiche « not running » à l’intérieur du sandbox

C’est un comportement attendu. Lorsque vous exécutez openclaw nemoclaw status à l’intérieur d’un sandbox actif, l’état du sandbox côté hôte et la configuration d’inférence ne sont pas inspectables. La commande de statut détecte le contexte du sandbox et signale « active (inside sandbox) » à la place.

Exécutez openshell sandbox list sur l’hôte pour vérifier l’état sous-jacent du sandbox.

Les requêtes d’inférence expirent

Vérifiez que l’endpoint du fournisseur d’inférence est accessible depuis l’hôte. Vérifiez le fournisseur et l’endpoint actifs :

$ openclaw nemoclaw status

Si l’endpoint est correct mais que les requêtes échouent toujours, vérifiez les règles de politique réseau qui pourraient bloquer la connexion, et vérifiez que votre clé API NVIDIA est valide.

L’agent ne peut pas atteindre un hôte externe

OpenShell bloque les connexions sortantes vers les hôtes non listés dans la politique réseau. Ouvrez le TUI pour voir les requêtes bloquées et les approuver :

$ openshell term

Pour autoriser un endpoint de manière permanente, ajoutez-le à la politique réseau. Consultez Personnaliser la politique réseau pour les détails.

L’exécution du blueprint a échoué

Consultez la sortie d’erreur pour l’exécution de blueprint échouée :

$ openclaw nemoclaw logs --run-id <id>

Si l’identifiant d’exécution est inconnu, omettez --run-id pour consulter les journaux de l’exécution la plus récente. Utilisez --follow pour diffuser les journaux en temps réel pendant le débogage.