疑難排解

本頁涵蓋安裝、引導或運行 NemoClaw 時可能遇到的常見問題及解決方式。

提示： 如果你的問題不在清單中，歡迎加入 NemoClaw Discord 頻道向社群提問。你也可以在 GitHub 上提交 issue。

安裝

安裝後找不到 `nemoclaw`

如果你用 nvm 或 fnm 管理 Node.js，安裝程式可能沒有更新目前 shell 的 PATH。 nemoclaw 二進位程式已安裝，但 shell 不知道在哪裡找它。

執行 source ~/.bashrc（zsh 使用者執行 source ~/.zshrc），或開一個新的終端機視窗。

安裝程式在不支援的平台上失敗

安裝程式會在開始前檢查作業系統和架構。 NemoClaw 需要 Linux Ubuntu 22.04 LTS 或更新版本。如果看到不支援的平台錯誤，請確認你是在支援的 Linux 發行版上運行。

Node.js 版本太舊

NemoClaw 需要 Node.js 20 或更新版本。如果安裝程式因 Node.js 版本錯誤而結束，檢查你目前的版本：

$ node --version

如果版本低於 20，安裝一個受支援的版本。用 nvm 的話，執行：

$ nvm install 20
$ nvm use 20

然後重新執行安裝程式。

Docker 沒有在運行

安裝程式和引導精靈需要 Docker 在運行中。如果看到 Docker 連線錯誤，啟動 Docker daemon：

$ sudo systemctl start docker

macOS 上使用 Docker Desktop 的話，打開 Docker Desktop 應用程式，等它啟動完成再重試。

npm install 出現權限錯誤

如果 npm install 出現 EACCES 權限錯誤，不要用 sudo 跑 npm。改為設定 npm 使用你擁有的目錄：

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

把 export 那行加到你的 ~/.bashrc 或 ~/.zshrc 讓它永久生效，然後重新執行安裝程式。

連接埠已被占用

NemoClaw gateway 預設使用連接埠 18789。如果有另一個程序已經占用了這個埠，引導會失敗。找出衝突的程序，確認可以安全停止後將其終止：

$ lsof -i :18789
$ kill <PID>

如果程序沒有退出，用 kill -9 <PID> 強制終止。然後重試引導。

引導

引導時出現 cgroup v2 錯誤

在 Ubuntu 24.04、DGX Spark 和 WSL2 上，Docker 可能沒有為 cgroup v2 delegation 做好設定。引導的預檢會偵測到這個問題並顯示清楚的錯誤訊息。

執行 Spark 設定腳本修正 Docker cgroup 設定，然後重試引導：

$ sudo nemoclaw setup-spark
$ nemoclaw onboard

沙箱名稱無效

沙箱名稱必須遵循 RFC 1123 子網域規則：只能用小寫英數字元和連字號，且必須以英數字元開頭和結尾。大寫字母會自動轉為小寫。

如果名稱不符合規則，精靈會報錯退出。選一個像 my-assistant 或 dev1 這樣的名稱。

DGX 上沙箱建立失敗

在 DGX 機器上，如果 gateway 的 DNS 還沒完成傳播，或前一次引導留下的 port forward 還在，沙箱建立可能會失敗。

執行 nemoclaw onboard 重試。精靈會自動清理過期的 port forward 並等待 gateway 就緒。

偵測不到 Colima socket（macOS）

較新版的 Colima 使用 XDG 基礎目錄（~/.config/colima/default/docker.sock）而非舊版路徑（~/.colima/default/docker.sock）。 NemoClaw 會檢查兩個路徑。如果都找不到，確認 Colima 是否在運行：

$ colima status

運行時

沙箱顯示為已停止

沙箱可能已被停止或刪除。執行 nemoclaw onboard 用相同的藍圖和政策定義重建沙箱。

沙箱內 status 顯示「not running」

這是預期行為。在活躍的沙箱內執行 openclaw nemoclaw status 時，主機端的沙箱狀態和推論設定無法取得。 status 指令會偵測到沙箱環境並改為回報「active (inside sandbox)」。

在主機上執行 openshell sandbox list 檢查底層沙箱狀態。

推論請求逾時

確認推論提供者端點可從主機存取。檢查目前的提供者和端點：

$ openclaw nemoclaw status

如果端點正確但請求仍然失敗，檢查網路政策規則是否封鎖了連線，並確認你的 NVIDIA API key 有效。

代理無法連線到外部主機

OpenShell 會封鎖對網路政策未列出主機的出站連線。開啟 TUI 查看被封鎖的請求並進行審批：

$ openshell term

要永久允許某個端點，請將它加入網路政策。細節請參閱自訂網路政策。

藍圖執行失敗

查看失敗藍圖執行的錯誤輸出：

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

如果不知道執行 ID，省略 --run-id 即可查看最新一次的日誌。除錯時加上 --follow 可以即時串流日誌。