Xử lý sự cố

Trang này đề cập các vấn đề phổ biến bạn có thể gặp khi cài đặt, onboard hoặc chạy NemoClaw, cùng với các bước giải quyết.

Mẹo: Nếu vấn đề của bạn không được liệt kê ở đây, hãy tham gia kênh Discord NemoClaw để đặt câu hỏi và nhận hỗ trợ từ cộng đồng. Bạn cũng có thể tạo issue trên GitHub.

Cài đặt

Không tìm thấy nemoclaw sau khi cài đặt

Nếu bạn sử dụng nvm hoặc fnm để quản lý Node.js, trình cài đặt có thể không cập nhật PATH của shell hiện tại. Binary nemoclaw đã được cài đặt nhưng phiên shell không biết tìm nó ở đâu.

Chạy source ~/.bashrc (hoặc source ~/.zshrc cho zsh), hoặc mở một cửa sổ terminal mới.

Trình cài đặt thất bại trên nền tảng không được hỗ trợ

Trình cài đặt kiểm tra hệ điều hành và kiến trúc được hỗ trợ trước khi tiến hành. NemoClaw yêu cầu Linux Ubuntu 22.04 LTS trở lên. Nếu bạn thấy lỗi nền tảng không được hỗ trợ, hãy xác minh rằng bạn đang chạy trên bản phân phối Linux được hỗ trợ.

Phiên bản Node.js quá cũ

NemoClaw yêu cầu Node.js 20 trở lên. Nếu trình cài đặt thoát với lỗi phiên bản Node.js, kiểm tra phiên bản hiện tại:

$ node --version

Nếu phiên bản dưới 20, cài đặt bản phát hành được hỗ trợ. Nếu bạn sử dụng nvm, chạy:

$ nvm install 20
$ nvm use 20

Sau đó chạy lại trình cài đặt.

Docker không chạy

Trình cài đặt và trình hướng dẫn onboard yêu cầu Docker đang chạy. Nếu bạn thấy lỗi kết nối Docker, khởi động daemon Docker:

$ sudo systemctl start docker

Trên macOS với Docker Desktop, mở ứng dụng Docker Desktop và đợi nó khởi động xong trước khi thử lại.

npm install thất bại với lỗi quyền

Nếu npm install thất bại với lỗi quyền EACCES, không chạy npm với sudo. Thay vào đó, cấu hình npm sử dụng thư mục bạn sở hữu:

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

Thêm dòng export vào ~/.bashrc hoặc ~/.zshrc để áp dụng vĩnh viễn, sau đó chạy lại trình cài đặt.

Cổng đã được sử dụng

Gateway NemoClaw sử dụng cổng 18789 theo mặc định. Nếu một tiến trình khác đã chiếm cổng này, onboard thất bại. Xác định tiến trình xung đột, xác minh an toàn để dừng và kết thúc nó:

$ lsof -i :18789
$ kill <PID>

Nếu tiến trình không thoát, sử dụng kill -9 <PID> để buộc kết thúc. Sau đó thử lại onboard.

Onboard

Lỗi cgroup v2 trong quá trình onboard

Trên Ubuntu 24.04, DGX Spark và WSL2, Docker có thể không được cấu hình cho ủy quyền cgroup v2. Kiểm tra tiền điều kiện onboard phát hiện điều này và thất bại với thông báo lỗi rõ ràng.

Chạy script thiết lập Spark để sửa cấu hình Docker cgroup, sau đó thử lại onboard:

$ sudo nemoclaw setup-spark
$ nemoclaw onboard

Tên sandbox không hợp lệ

Tên sandbox phải tuân theo quy tắc subdomain RFC 1123: chỉ ký tự chữ-số viết thường và dấu gạch ngang, phải bắt đầu và kết thúc bằng ký tự chữ-số. Chữ hoa tự động được chuyển thành chữ thường.

Nếu tên không khớp với các quy tắc này, trình hướng dẫn thoát với lỗi. Chọn tên như my-assistant hoặc dev1.

Tạo sandbox thất bại trên DGX

Trên các máy DGX, tạo sandbox có thể thất bại nếu DNS của gateway chưa truyền xong hoặc nếu một port forward cũ từ lần onboard trước vẫn đang hoạt động.

Chạy nemoclaw onboard để thử lại. Trình hướng dẫn tự động dọn dẹp các port forward cũ và đợi gateway sẵn sàng.

Không phát hiện socket Colima (macOS)

Các phiên bản Colima mới hơn sử dụng thư mục cơ sở XDG (~/.config/colima/default/docker.sock) thay vì đường dẫn cũ (~/.colima/default/docker.sock). NemoClaw kiểm tra cả hai đường dẫn. Nếu không tìm thấy đường dẫn nào, xác minh Colima đang chạy:

$ colima status

Thời gian chạy

Sandbox hiển thị đã dừng

Sandbox có thể đã bị dừng hoặc xóa. Chạy nemoclaw onboard để tạo lại sandbox từ cùng blueprint và định nghĩa chính sách.

Status hiển thị “not running” bên trong sandbox

Đây là hành vi mong đợi. Khi chạy openclaw nemoclaw status bên trong một sandbox đang hoạt động, trạng thái sandbox phía host và cấu hình suy luận không thể kiểm tra. Lệnh status phát hiện ngữ cảnh sandbox và báo cáo “active (inside sandbox)” thay vào đó.

Chạy openshell sandbox list trên host để kiểm tra trạng thái sandbox cơ bản.

Yêu cầu suy luận hết thời gian chờ

Xác minh rằng endpoint nhà cung cấp suy luận có thể truy cập từ host. Kiểm tra nhà cung cấp và endpoint đang hoạt động:

$ openclaw nemoclaw status

Nếu endpoint chính xác nhưng yêu cầu vẫn thất bại, kiểm tra các quy tắc chính sách mạng có thể chặn kết nối, và xác minh API key NVIDIA của bạn còn hợp lệ.

Tác nhân không thể truy cập host bên ngoài

OpenShell chặn các kết nối ra đến host không có trong chính sách mạng. Mở TUI để xem các yêu cầu bị chặn và phê duyệt chúng:

$ openshell term

Để cho phép vĩnh viễn một endpoint, thêm nó vào chính sách mạng. Tham khảo Tùy chỉnh chính sách mạng để biết chi tiết.

Chạy blueprint thất bại

Xem kết quả lỗi cho lần chạy blueprint thất bại:

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

Nếu không biết run ID, bỏ --run-id để xem nhật ký từ lần chạy gần nhất. Sử dụng --follow để truyền phát nhật ký theo thời gian thực trong khi gỡ lỗi.