故障排除

本页介绍在安装、引导或运行 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 守护进程：

$ sudo systemctl start docker

在使用 Docker Desktop 的 macOS 上，打开 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 委托。引导预检检查会检测到这一点并给出明确的错误消息。

运行 Spark 设置脚本修复 Docker cgroup 配置，然后重试引导：

$ sudo nemoclaw setup-spark
$ nemoclaw onboard

无效的沙箱名称

沙箱名称必须遵循 RFC 1123 子域名规则：仅允许小写字母数字字符和连字符，且必须以字母数字字符开头和结尾。大写字母会自动转换为小写。

如果名称不符合这些规则，向导会以错误退出。请选择类似 my-assistant 或 dev1 的名称。

DGX 上沙箱创建失败

在 DGX 机器上，如果 gateway 的 DNS 尚未完成传播或之前引导运行留下的端口转发仍然活跃，沙箱创建可能会失败。

运行 nemoclaw onboard 重试。向导会自动清理过时的端口转发并等待 gateway 就绪。

未检测到 Colima socket（macOS）

较新版本的 Colima 使用 XDG 基目录（~/.config/colima/default/docker.sock）而非旧路径（~/.colima/default/docker.sock）。 NemoClaw 会检查两个路径。如果两者都未找到，请验证 Colima 是否正在运行：

$ colima status

运行时

沙箱显示为已停止

沙箱可能已被停止或删除。运行 nemoclaw onboard 使用相同的蓝图和策略定义重新创建沙箱。

在沙箱内 status 显示”未运行”

这是预期行为。在活跃的沙箱内运行 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 实时流式输出日志。