Solución de Problemas
Esta página cubre los problemas comunes que puede encontrar al instalar, configurar o ejecutar NemoClaw, junto con sus pasos de resolución.
Consejo: Si su problema no está listado aquí, únase al canal de Discord de NemoClaw para hacer preguntas y obtener ayuda de la comunidad. También puede crear un issue en GitHub.
Instalación
nemoclaw no se encuentra después de la instalación
Si usa nvm o fnm para gestionar Node.js, el instalador puede no actualizar el PATH de su shell actual.
El binario nemoclaw está instalado pero la sesión del shell no sabe dónde encontrarlo.
Ejecute source ~/.bashrc (o source ~/.zshrc para zsh), o abra una nueva ventana de terminal.
El instalador falla en una plataforma no compatible
El instalador verifica si el sistema operativo y la arquitectura son compatibles antes de continuar. NemoClaw requiere Linux Ubuntu 22.04 LTS o posterior. Si ve un error de plataforma no compatible, verifique que esté ejecutando una distribución de Linux compatible.
La versión de Node.js es demasiado antigua
NemoClaw requiere Node.js 20 o posterior. Si el instalador se cierra con un error de versión de Node.js, verifique su versión actual:
$ node --versionSi la versión es inferior a 20, instale una versión compatible. Si usa nvm, ejecute:
$ nvm install 20
$ nvm use 20Luego vuelva a ejecutar el instalador.
Docker no está en ejecución
El instalador y el asistente de configuración requieren que Docker esté en ejecución. Si ve un error de conexión de Docker, inicie el daemon de Docker:
$ sudo systemctl start dockerEn macOS con Docker Desktop, abra la aplicación Docker Desktop y espere a que termine de iniciar antes de reintentar.
La instalación de npm falla con errores de permisos
Si npm install falla con un error de permisos EACCES, no ejecute npm con sudo.
En su lugar, configure npm para usar un directorio de su propiedad:
$ mkdir -p ~/.npm-global
$ npm config set prefix ~/.npm-global
$ export PATH=~/.npm-global/bin:$PATHAgregue la línea export a su ~/.bashrc o ~/.zshrc para hacerla permanente, luego vuelva a ejecutar el instalador.
Puerto ya en uso
El gateway de NemoClaw usa el puerto 18789 de forma predeterminada.
Si otro proceso ya está enlazado a este puerto, la configuración falla.
Identifique el proceso en conflicto, verifique que sea seguro detenerlo y termínelo:
$ lsof -i :18789
$ kill <PID>Si el proceso no se cierra, use kill -9 <PID> para forzar su terminación.
Luego reintente la configuración.
Configuración Inicial
Errores de cgroup v2 durante la configuración
En Ubuntu 24.04, DGX Spark y WSL2, Docker puede no estar configurado para la delegación de cgroup v2. La verificación previa de la configuración detecta esto y falla con un mensaje de error claro.
Ejecute el script de configuración de Spark para corregir la configuración de cgroup de Docker, luego reintente la configuración:
$ sudo nemoclaw setup-spark
$ nemoclaw onboardNombre de sandbox no válido
Los nombres de sandbox deben seguir las reglas de subdominios RFC 1123: solo caracteres alfanuméricos en minúsculas y guiones, y deben comenzar y terminar con un carácter alfanumérico. Las letras mayúsculas se convierten automáticamente a minúsculas.
Si el nombre no coincide con estas reglas, el asistente se cierra con un error.
Elija un nombre como my-assistant o dev1.
La creación del sandbox falla en DGX
En máquinas DGX, la creación del sandbox puede fallar si el DNS del gateway no ha terminado de propagarse o si un reenvío de puerto obsoleto de una ejecución anterior de configuración aún está activo.
Ejecute nemoclaw onboard para reintentar.
El asistente limpia los reenvíos de puerto obsoletos y espera a que el gateway esté listo automáticamente.
Socket de Colima no detectado (macOS)
Las versiones más recientes de Colima usan el directorio base XDG (~/.config/colima/default/docker.sock) en lugar de la ruta heredada (~/.colima/default/docker.sock).
NemoClaw verifica ambas rutas.
Si ninguna se encuentra, verifique que Colima esté en ejecución:
$ colima statusTiempo de Ejecución
El sandbox aparece como detenido
El sandbox puede haber sido detenido o eliminado.
Ejecute nemoclaw onboard para recrear el sandbox a partir del mismo blueprint y las mismas definiciones de política.
El estado muestra “not running” dentro del sandbox
Este es el comportamiento esperado.
Cuando ejecuta openclaw nemoclaw status dentro de un sandbox activo, el estado del sandbox y la configuración de inferencia del lado del host no se pueden inspeccionar.
El comando de estado detecta el contexto del sandbox y reporta “active (inside sandbox)” en su lugar.
Ejecute openshell sandbox list en el host para verificar el estado subyacente del sandbox.
Las solicitudes de inferencia agotan el tiempo de espera
Verifique que el endpoint del proveedor de inferencia sea accesible desde el host. Compruebe el proveedor y el endpoint activos:
$ openclaw nemoclaw statusSi el endpoint es correcto pero las solicitudes aún fallan, verifique si hay reglas de política de red que puedan bloquear la conexión, y confirme que su API key de NVIDIA sea válida.
El agente no puede acceder a un host externo
OpenShell bloquea las conexiones salientes a hosts no listados en la política de red. Abra el TUI para ver las solicitudes bloqueadas y aprobarlas:
$ openshell termPara permitir permanentemente un endpoint, agréguelo a la política de red. Consulte Personalizar la Política de Red para más detalles.
La ejecución del blueprint falló
Vea la salida de error para la ejecución fallida del blueprint:
$ openclaw nemoclaw logs --run-id <id>Si el ID de ejecución es desconocido, omita --run-id para ver los registros de la ejecución más reciente.
Use --follow para transmitir los registros en tiempo real durante la depuración.