Resolução de Problemas

Esta página aborda problemas comuns que você pode encontrar ao instalar, configurar ou executar o NemoClaw, junto com os passos de resolução.

Dica: Se o seu problema não está listado aqui, junte-se ao canal do NemoClaw no Discord para fazer perguntas e obter ajuda da comunidade. Você também pode abrir uma issue no GitHub.

Instalação

nemoclaw não encontrado após a instalação

Se você usa nvm ou fnm para gerenciar o Node.js, o instalador pode não atualizar o PATH do seu shell atual. O binário nemoclaw está instalado, mas a sessão do shell não sabe onde encontrá-lo.

Execute source ~/.bashrc (ou source ~/.zshrc para zsh), ou abra uma nova janela de terminal.

O instalador falha em plataforma não suportada

O instalador verifica o sistema operacional e a arquitetura suportados antes de prosseguir. O NemoClaw requer Linux Ubuntu 22.04 LTS ou posterior. Se você vir um erro de plataforma não suportada, verifique se está rodando em uma distribuição Linux suportada.

A versão do Node.js é muito antiga

O NemoClaw requer Node.js 20 ou posterior. Se o instalador sair com um erro de versão do Node.js, verifique sua versão atual:

$ node --version

Se a versão for inferior a 20, instale uma versão suportada. Se você usa nvm, execute:

$ nvm install 20
$ nvm use 20

Depois, re-execute o instalador.

O Docker não está rodando

O instalador e o assistente de configuração requerem que o Docker esteja em execução. Se você vir um erro de conexão com o Docker, inicie o daemon do Docker:

$ sudo systemctl start docker

No macOS com Docker Desktop, abra o aplicativo Docker Desktop e aguarde até que ele termine de iniciar antes de tentar novamente.

A instalação npm falha com erros de permissão

Se npm install falhar com um erro de permissão EACCES, não execute o npm com sudo. Em vez disso, configure o npm para usar um diretório que você possui:

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

Adicione a linha export ao seu ~/.bashrc ou ~/.zshrc para torná-la permanente, depois re-execute o instalador.

Porta já em uso

O gateway do NemoClaw usa a porta 18789 por padrão. Se outro processo já estiver vinculado a esta porta, a configuração falha. Identifique o processo conflitante, verifique se é seguro pará-lo e encerre-o:

$ lsof -i :18789
$ kill <PID>

Se o processo não encerrar, use kill -9 <PID> para forçar o encerramento. Depois, tente a configuração novamente.

Configuração

Erros de cgroup v2 durante o onboard

No Ubuntu 24.04, DGX Spark e WSL2, o Docker pode não estar configurado para delegação de cgroup v2. A verificação de pré-voo do onboard detecta isso e falha com uma mensagem de erro clara.

Execute o script de configuração do Spark para corrigir a configuração do cgroup do Docker, depois tente novamente a configuração:

$ sudo nemoclaw setup-spark
$ nemoclaw onboard

Nome de sandbox inválido

Os nomes de sandbox devem seguir as regras de subdomínio RFC 1123: apenas caracteres alfanuméricos minúsculos e hífens, e devem começar e terminar com um caractere alfanumérico. Letras maiúsculas são automaticamente convertidas para minúsculas.

Se o nome não corresponder a essas regras, o assistente sai com um erro. Escolha um nome como my-assistant ou dev1.

A criação do sandbox falha no DGX

Em máquinas DGX, a criação do sandbox pode falhar se o DNS do gateway ainda não tiver propagado ou se um port forward obsoleto de uma execução anterior do onboard ainda estiver ativo.

Execute nemoclaw onboard para tentar novamente. O assistente limpa port forwards obsoletos e aguarda a prontidão do gateway automaticamente.

Socket do Colima não detectado (macOS)

Versões mais recentes do Colima usam o diretório base XDG (~/.config/colima/default/docker.sock) em vez do caminho legado (~/.colima/default/docker.sock). O NemoClaw verifica ambos os caminhos. Se nenhum for encontrado, verifique se o Colima está em execução:

$ colima status

Execução

O sandbox aparece como parado

O sandbox pode ter sido parado ou excluído. Execute nemoclaw onboard para recriar o sandbox a partir do mesmo blueprint e definições de política.

O status mostra “not running” dentro do sandbox

Esse é o comportamento esperado. Ao executar openclaw nemoclaw status dentro de um sandbox ativo, o estado do sandbox no nível do host e a configuração de inferência não são inspecionáveis. O comando status detecta o contexto do sandbox e reporta “active (inside sandbox)” em vez disso.

Execute openshell sandbox list no host para verificar o estado subjacente do sandbox.

Requisições de inferência expiram

Verifique se o endpoint do provedor de inferência está acessível a partir do host. Verifique o provedor e endpoint ativos:

$ openclaw nemoclaw status

Se o endpoint estiver correto mas as requisições ainda falharem, verifique se há regras de política de rede que possam bloquear a conexão, e verifique se sua API key NVIDIA é válida.

O agente não consegue acessar um host externo

O OpenShell bloqueia conexões de saída para hosts não listados na política de rede. Abra o TUI para ver as requisições bloqueadas e aprová-las:

$ openshell term

Para permitir permanentemente um endpoint, adicione-o à política de rede. Consulte Personalizar a Política de Rede para detalhes.

A execução do blueprint falhou

Visualize a saída de erro da execução de blueprint que falhou:

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

Se o ID da execução for desconhecido, omita --run-id para visualizar os logs da execução mais recente. Use --follow para transmitir os logs em tempo real durante a depuração.