Rozwiązywanie problemów

Ta strona opisuje typowe problemy, które możesz napotkać podczas instalacji, konfiguracji lub uruchamiania NemoClaw, wraz z krokami naprawczymi.

Wskazówka: Jeśli Twój problem nie jest tutaj wymieniony, dołącz do kanału Discord NemoClaw, aby zadawać pytania i uzyskać pomoc od społeczności. Możesz również zgłosić problem na GitHub.

Instalacja

nemoclaw nie znaleziono po instalacji

Jeśli używasz nvm lub fnm do zarządzania Node.js, instalator może nie zaktualizować zmiennej PATH bieżącej powłoki. Plik binarny nemoclaw jest zainstalowany, ale sesja powłoki nie wie, gdzie go znaleźć.

Uruchom source ~/.bashrc (lub source ~/.zshrc dla zsh) albo otwórz nowe okno terminala.

Instalator kończy się błędem na nieobsługiwanej platformie

Instalator sprawdza obsługiwany system operacyjny i architekturę przed kontynuacją. NemoClaw wymaga systemu Linux Ubuntu 22.04 LTS lub nowszego. Jeśli widzisz błąd nieobsługiwanej platformy, sprawdź, czy działasz na obsługiwanej dystrybucji Linux.

Wersja Node.js jest zbyt stara

NemoClaw wymaga Node.js 20 lub nowszego. Jeśli instalator kończy działanie z błędem wersji Node.js, sprawdź swoją aktualną wersję:

$ node --version

Jeśli wersja jest poniżej 20, zainstaluj obsługiwaną wersję. Jeśli używasz nvm, uruchom:

$ nvm install 20
$ nvm use 20

Następnie uruchom ponownie instalator.

Docker nie działa

Instalator i kreator konfiguracji wymagają uruchomionego Docker. Jeśli widzisz błąd połączenia Docker, uruchom demona Docker:

$ sudo systemctl start docker

Na macOS z Docker Desktop otwórz aplikację Docker Desktop i poczekaj, aż zakończy się uruchamianie, przed ponowną próbą.

npm install kończy się błędami uprawnień

Jeśli npm install kończy się błędem uprawnień EACCES, nie uruchamiaj npm z sudo. Zamiast tego skonfiguruj npm, aby używał katalogu, którego jesteś właścicielem:

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

Dodaj linię export do swojego ~/.bashrc lub ~/.zshrc, aby zmiana była trwała, a następnie ponownie uruchom instalator.

Port jest już w użyciu

Brama NemoClaw domyślnie używa portu 18789. Jeśli inny proces jest już przywiązany do tego portu, konfiguracja kończy się błędem. Zidentyfikuj kolidujący proces, upewnij się, że można go bezpiecznie zatrzymać, i zakończ go:

$ lsof -i :18789
$ kill <PID>

Jeśli proces nie kończy się, użyj kill -9 <PID>, aby wymusić jego zakończenie. Następnie ponów konfigurację.

Konfiguracja

Błędy cgroup v2 podczas konfiguracji

Na Ubuntu 24.04, DGX Spark i WSL2 Docker może nie być skonfigurowany do delegacji cgroup v2. Sprawdzenie wstępne podczas konfiguracji wykrywa to i kończy się czytelnym komunikatem o błędzie.

Uruchom skrypt konfiguracji Spark, aby naprawić konfigurację cgroup Docker, a następnie ponów konfigurację:

$ sudo nemoclaw setup-spark
$ nemoclaw onboard

Nieprawidłowa nazwa sandboxa

Nazwy sandboxów muszą być zgodne z regułami subdomen RFC 1123: tylko małe litery alfanumeryczne i myślniki, muszą zaczynać się i kończyć znakiem alfanumerycznym. Wielkie litery są automatycznie zamieniane na małe.

Jeśli nazwa nie spełnia tych reguł, kreator kończy się błędem. Wybierz nazwę taką jak my-assistant lub dev1.

Tworzenie sandboxa kończy się błędem na DGX

Na maszynach DGX tworzenie sandboxa może się nie powieść, jeśli DNS bramy nie zdążył się propagować lub jeśli aktywne jest stare przekierowanie portów z poprzedniej konfiguracji.

Uruchom nemoclaw onboard, aby spróbować ponownie. Kreator automatycznie czyści stare przekierowania portów i czeka na gotowość bramy.

Gniazdo Colima nie wykryte (macOS)

Nowsze wersje Colima używają katalogu bazowego XDG (~/.config/colima/default/docker.sock) zamiast starszej ścieżki (~/.colima/default/docker.sock). NemoClaw sprawdza obie ścieżki. Jeśli żadna nie zostanie znaleziona, sprawdź, czy Colima działa:

$ colima status

Działanie

Sandbox wyświetla się jako zatrzymany

Sandbox mógł zostać zatrzymany lub usunięty. Uruchom nemoclaw onboard, aby odtworzyć sandbox z tych samych definicji blueprintu i polityk.

Status pokazuje “nie działa” wewnątrz sandboxa

To jest oczekiwane zachowanie. Podczas uruchamiania openclaw nemoclaw status wewnątrz aktywnego sandboxa, stan sandboxa i konfiguracja inferencji po stronie hosta nie są dostępne do sprawdzenia. Polecenie status wykrywa kontekst sandboxa i raportuje “active (inside sandbox)”.

Uruchom openshell sandbox list na hoście, aby sprawdzić stan bazowy sandboxa.

Żądania inferencji przekraczają limit czasu

Sprawdź, czy punkt końcowy dostawcy inferencji jest osiągalny z hosta. Sprawdź aktywnego dostawcę i punkt końcowy:

$ openclaw nemoclaw status

Jeśli punkt końcowy jest poprawny, ale żądania nadal się nie powiodą, sprawdź reguły polityki sieciowej, które mogą blokować połączenie, i zweryfikuj, czy Twój klucz API NVIDIA jest prawidłowy.

Agent nie może połączyć się z zewnętrznym hostem

OpenShell blokuje połączenia wychodzące do hostów niewymienionych w polityce sieciowej. Otwórz TUI, aby zobaczyć zablokowane żądania i je zatwierdzić:

$ openshell term

Aby trwale zezwolić na punkt końcowy, dodaj go do polityki sieciowej. Zapoznaj się z Dostosowywanie polityki sieciowej, aby uzyskać szczegóły.

Uruchomienie blueprintu nie powiodło się

Wyświetl logi błędów dla nieudanego uruchomienia blueprintu:

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

Jeśli ID uruchomienia jest nieznane, pomiń --run-id, aby wyświetlić logi z ostatniego uruchomienia. Użyj --follow, aby wyświetlać logi w czasie rzeczywistym podczas debugowania.