Probleemoplossing

Deze pagina behandelt veelvoorkomende problemen die u kunt tegenkomen bij het installeren, onboarden of draaien van NemoClaw, samen met de bijbehorende oplossingen.

Tip: Als uw probleem hier niet wordt vermeld, sluit u aan bij het NemoClaw Discord-kanaal om vragen te stellen en hulp te krijgen van de community. U kunt ook een issue aanmaken op GitHub.

Installatie

nemoclaw niet gevonden na installatie

Als u nvm of fnm gebruikt om Node.js te beheren, heeft de installer mogelijk het PATH van uw huidige shell niet bijgewerkt. De nemoclaw-binary is geïnstalleerd maar de shell-sessie weet niet waar deze te vinden is.

Voer source ~/.bashrc uit (of source ~/.zshrc voor zsh), of open een nieuw terminalvenster.

Installer mislukt op niet-ondersteund platform

De installer controleert op een ondersteund besturingssysteem en architectuur voordat deze doorgaat. NemoClaw vereist Linux Ubuntu 22.04 LTS of hoger. Als u een fout voor een niet-ondersteund platform ziet, controleer dan of u op een ondersteunde Linux-distributie draait.

Node.js-versie is te oud

NemoClaw vereist Node.js 20 of hoger. Als de installer afsluit met een Node.js-versiefout, controleer uw huidige versie:

$ node --version

Als de versie lager is dan 20, installeer dan een ondersteunde release. Als u nvm gebruikt, voer uit:

$ nvm install 20
$ nvm use 20

Voer vervolgens de installer opnieuw uit.

Docker draait niet

De installer en onboard-wizard vereisen dat Docker draait. Als u een Docker-verbindingsfout ziet, start de Docker-daemon:

$ sudo systemctl start docker

Op macOS met Docker Desktop opent u de Docker Desktop-applicatie en wacht u tot deze volledig is opgestart voordat u het opnieuw probeert.

npm install mislukt met machtigingsfouten

Als npm install mislukt met een EACCES-machtigingsfout, voer npm niet uit met sudo. Configureer in plaats daarvan npm om een map te gebruiken waarvan u eigenaar bent:

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

Voeg de export-regel toe aan uw ~/.bashrc of ~/.zshrc om het permanent te maken en voer vervolgens de installer opnieuw uit.

Poort is al in gebruik

De NemoClaw gateway gebruikt standaard poort 18789. Als een ander proces al aan deze poort is gebonden, mislukt de onboarding. Identificeer het conflicterende proces, controleer of het veilig is om te stoppen en beëindig het:

$ lsof -i :18789
$ kill <PID>

Als het proces niet afsluit, gebruik kill -9 <PID> om het geforceerd te beëindigen. Probeer vervolgens de onboarding opnieuw.

Onboarding

Cgroup v2-fouten tijdens onboard

Op Ubuntu 24.04, DGX Spark en WSL2 is Docker mogelijk niet geconfigureerd voor cgroup v2-delegatie. De onboard-preflightcontrole detecteert dit en mislukt met een duidelijke foutmelding.

Voer het Spark-configuratiescript uit om de Docker cgroup-configuratie te repareren en probeer vervolgens de onboarding opnieuw:

$ sudo nemoclaw setup-spark
$ nemoclaw onboard

Ongeldige sandboxnaam

Sandboxnamen moeten voldoen aan RFC 1123 subdomain-regels: alleen kleine alfanumerieke tekens en koppeltekens, en moeten beginnen en eindigen met een alfanumeriek teken. Hoofdletters worden automatisch omgezet naar kleine letters.

Als de naam niet aan deze regels voldoet, sluit de wizard af met een fout. Kies een naam zoals my-assistant of dev1.

Sandboxcreatie mislukt op DGX

Op DGX-machines kan sandboxcreatie mislukken als de DNS van de gateway nog niet is gepropageerd of als een verouderde port-forward van een eerdere onboard-uitvoering nog actief is.

Voer nemoclaw onboard uit om het opnieuw te proberen. De wizard ruimt verouderde port-forwards op en wacht automatisch op gateway-gereedheid.

Colima-socket niet gedetecteerd (macOS)

Nieuwere Colima-versies gebruiken de XDG-basisdirectory (~/.config/colima/default/docker.sock) in plaats van het legacy-pad (~/.colima/default/docker.sock). NemoClaw controleert beide paden. Als geen van beide wordt gevonden, controleer dan of Colima draait:

$ colima status

Runtime

Sandbox wordt weergegeven als gestopt

De sandbox is mogelijk gestopt of verwijderd. Voer nemoclaw onboard uit om de sandbox opnieuw aan te maken op basis van dezelfde blueprint- en beleidsdefinities.

Status toont “not running” in de sandbox

Dit is verwacht gedrag. Wanneer u openclaw nemoclaw status uitvoert in een actieve sandbox, zijn hostgerichte sandboxstatus en inferentieconfiguratie niet te inspecteren. Het statuscommando detecteert de sandboxcontext en rapporteert in plaats daarvan “active (inside sandbox)”.

Voer openshell sandbox list uit op de host om de onderliggende sandboxstatus te controleren.

Inferentieverzoeken verlopen

Controleer of het eindpunt van de inferentieprovider bereikbaar is vanaf de host. Controleer de actieve provider en het eindpunt:

$ openclaw nemoclaw status

Als het eindpunt correct is maar verzoeken nog steeds mislukken, controleer dan op netwerkbeleidsregels die de verbinding mogelijk blokkeren en controleer of uw NVIDIA API key geldig is.

Agent kan een externe host niet bereiken

OpenShell blokkeert uitgaande verbindingen naar hosts die niet in het netwerkbeleid zijn vermeld. Open de TUI om geblokkeerde verzoeken te bekijken en goed te keuren:

$ openshell term

Om een eindpunt permanent toe te staan, voeg het toe aan het netwerkbeleid. Raadpleeg Het netwerkbeleid aanpassen voor details.

Blueprint-uitvoering mislukt

Bekijk de foutuitvoer voor de mislukte blueprint-uitvoering:

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

Als de uitvoerings-ID onbekend is, laat --run-id weg om logs van de meest recente uitvoering te bekijken. Gebruik --follow om logs in realtime te streamen tijdens het debuggen.