Risoluzione dei Problemi

Questa pagina tratta i problemi comuni che potresti incontrare durante l’installazione, l’onboarding o l’esecuzione di NemoClaw, insieme ai passaggi di risoluzione.

Suggerimento: Se il tuo problema non è elencato qui, unisciti al canale Discord di NemoClaw per fare domande e ottenere aiuto dalla community. Puoi anche aprire una issue su GitHub.

Installazione

nemoclaw non trovato dopo l’installazione

Se usi nvm o fnm per gestire Node.js, l’installer potrebbe non aggiornare il PATH della shell corrente. Il binario nemoclaw è installato ma la sessione della shell non sa dove trovarlo.

Esegui source ~/.bashrc (o source ~/.zshrc per zsh), oppure apri una nuova finestra del terminale.

L’installer fallisce su piattaforma non supportata

L’installer verifica il sistema operativo e l’architettura supportati prima di procedere. NemoClaw richiede Linux Ubuntu 22.04 LTS o successivo. Se vedi un errore di piattaforma non supportata, verifica di essere in esecuzione su una distribuzione Linux supportata.

La versione di Node.js è troppo vecchia

NemoClaw richiede Node.js 20 o successivo. Se l’installer si chiude con un errore sulla versione di Node.js, controlla la versione corrente:

$ node --version

Se la versione è inferiore a 20, installa una versione supportata. Se usi nvm, esegui:

$ nvm install 20
$ nvm use 20

Poi riesegui l’installer.

Docker non è in esecuzione

L’installer e la procedura guidata di onboarding richiedono che Docker sia in esecuzione. Se vedi un errore di connessione a Docker, avvia il demone Docker:

$ sudo systemctl start docker

Su macOS con Docker Desktop, apri l’applicazione Docker Desktop e attendi che termini l’avvio prima di riprovare.

npm install fallisce con errori di permessi

Se npm install fallisce con un errore di permessi EACCES, non eseguire npm con sudo. Invece, configura npm per utilizzare una directory di tua proprietà:

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

Aggiungi la riga export al tuo ~/.bashrc o ~/.zshrc per renderla permanente, poi riesegui l’installer.

Porta già in uso

Il gateway NemoClaw utilizza la porta 18789 per impostazione predefinita. Se un altro processo è già in ascolto su questa porta, l’onboarding fallisce. Identifica il processo in conflitto, verifica che sia sicuro interromperlo e terminalo:

$ lsof -i :18789
$ kill <PID>

Se il processo non si chiude, usa kill -9 <PID> per forzarne la terminazione. Poi riprova l’onboarding.

Onboarding

Errori cgroup v2 durante l’onboarding

Su Ubuntu 24.04, DGX Spark e WSL2, Docker potrebbe non essere configurato per la delega cgroup v2. Il controllo preliminare dell’onboarding rileva questo problema e fallisce con un messaggio di errore chiaro.

Esegui lo script di configurazione Spark per correggere la configurazione Docker dei cgroup, poi riprova l’onboarding:

$ sudo nemoclaw setup-spark
$ nemoclaw onboard

Nome della sandbox non valido

I nomi delle sandbox devono seguire le regole dei sottodomini RFC 1123: solo caratteri alfanumerici minuscoli e trattini, e devono iniziare e terminare con un carattere alfanumerico. Le lettere maiuscole vengono automaticamente convertite in minuscole.

Se il nome non rispetta queste regole, la procedura guidata si chiude con un errore. Scegli un nome come my-assistant o dev1.

La creazione della sandbox fallisce su DGX

Sulle macchine DGX, la creazione della sandbox può fallire se il DNS del gateway non ha terminato la propagazione o se un port-forward obsoleto da una precedente esecuzione di onboarding è ancora attivo.

Esegui nemoclaw onboard per riprovare. La procedura guidata pulisce i port-forward obsoleti e attende automaticamente che il gateway sia pronto.

Socket Colima non rilevato (macOS)

Le versioni più recenti di Colima utilizzano la directory di base XDG (~/.config/colima/default/docker.sock) invece del percorso legacy (~/.colima/default/docker.sock). NemoClaw controlla entrambi i percorsi. Se nessuno dei due viene trovato, verifica che Colima sia in esecuzione:

$ colima status

Runtime

La sandbox risulta arrestata

La sandbox potrebbe essere stata arrestata o eliminata. Esegui nemoclaw onboard per ricreare la sandbox dallo stesso blueprint e dalle stesse definizioni di policy.

Lo status mostra “not running” dall’interno della sandbox

Questo è un comportamento atteso. Quando esegui openclaw nemoclaw status all’interno di una sandbox attiva, lo stato della sandbox lato host e la configurazione dell’inferenza non sono ispezionabili. Il comando status rileva il contesto sandbox e riporta “active (inside sandbox)”.

Esegui openshell sandbox list sull’host per controllare lo stato sottostante della sandbox.

Le richieste di inferenza vanno in timeout

Verifica che l’endpoint del provider di inferenza sia raggiungibile dall’host. Controlla il provider e l’endpoint attivi:

$ openclaw nemoclaw status

Se l’endpoint è corretto ma le richieste continuano a fallire, controlla le regole della policy di rete che potrebbero bloccare la connessione e verifica che la tua API key NVIDIA sia valida.

L’agente non riesce a raggiungere un host esterno

OpenShell blocca le connessioni in uscita verso host non elencati nella policy di rete. Apri la TUI per vedere le richieste bloccate e approvarle:

$ openshell term

Per consentire permanentemente un endpoint, aggiungilo alla policy di rete. Consulta Personalizzare la Policy di Rete per i dettagli.

Esecuzione del blueprint fallita

Visualizza l’output di errore per l’esecuzione del blueprint fallita:

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

Se l’ID dell’esecuzione è sconosciuto, ometti --run-id per visualizzare i log dell’esecuzione più recente. Usa --follow per trasmettere in streaming i log in tempo reale durante il debug.