nemoclaw-setup

NemoClaw 设置

安装 NVIDIA NemoClaw——一个基于 OpenClaw 构建的沙盒化 AI Agent 平台，采用 Landlock + seccomp + 网络命名空间隔离。通过 k3s（OpenShell）在 Docker 中运行。

你将获得

• 带有 Web 界面和终端 CLI 的沙盒化 AI Agent
• 由 NVIDIA Nemotron 模型提供支持（云端或本地）
• 通过网络策略控制对外部服务的访问
• 可选通过 Cloudflare Tunnel 进行远程访问

先决条件

要求	检查方式	安装方式
Linux（Ubuntu 22.04+）	uname -a	—
Docker	docker ps	sudo apt install docker.io
Node.js 20+（推荐 22）	node --version	nvm install 22
NVIDIA GPU（可选但推荐）	nvidia-smi	—
NVIDIA API 密钥	—	https://build.nvidia.com/settings/api-keys

工作流

步骤 1：安装前检查

# Check Docker
docker ps 2>/dev/null || echo "Docker not running or no access"

# Check Node.js
node --version

# Check if already installed
which nemoclaw && nemoclaw --version
which openshell && openshell --version

如果已安装 nemoclaw，请跳到步骤 4。

步骤 2：安装 NemoClaw

curl -fsSL https://nvidia.com/nemoclaw.sh | bash

此操作会通过 npm 全局安装 NemoClaw 和 OpenClaw（安装到 ~/.npm-global/bin/）。

如果安装程序找不到 Node.js，请先安装：

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

步骤 3：安装 OpenShell

curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh

安装到 ~/.local/bin/openshell。

步骤 4：修复 Docker 权限和 cgroup

Docker 组——用户必须属于 docker 组：

sudo usermod -aG docker $USER
newgrp docker
# or log out and back in

cgroup v2 修复——在 Docker 中运行 k3s 时必需：

# Check if needed
grep cgroup2 /proc/filesystems && echo "cgroup v2 detected — fix needed"

# Apply fix (needs sudo)
sudo $HOME/.npm-global/bin/nemoclaw setup-spark

此操作会将 "default-cgroupns-mode": "host" 添加到 /etc/docker/daemon.json，并重启 Docker。

重要：nemoclaw setup-spark 命令也会要求提供 NVIDIA API 密钥。请提前准备好（以 nvapi- 开头）。请前往 https://build.nvidia.com/settings/api-keys 获取。

步骤 5：运行初始化向导

PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH nemoclaw onboard

交互式向导将会：

1. 检查 Docker 和 OpenShell
2. 启动 OpenShell 网关（Docker 中的 k3s）
3. 要求输入沙盒名称——使用 claw 或任意名称
4. 配置 NVIDIA API 密钥
5. 设置推理（通过云端 API 使用 Nemotron 3 Super 120B）
6. 在沙盒内启动 OpenClaw
7. 应用网络策略预设——选择所需的预设

常见端口冲突：如果端口 8080 正被占用，请查找并终止相关进程：

fuser -k 8080/tcp

步骤 6：验证

# Check sandbox is running
PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH nemoclaw claw status

# Connect via terminal
PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH nemoclaw claw connect

步骤 7：设置 Web 界面访问

Web 界面在沙盒内运行，需要进行端口转发：

PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH openshell forward start 18789 claw

然后打开：http://127.0.0.1:18789/

已知问题（OpenClaw ≤ v2026.3.11）：“device identity required”错误。解决方法——将网关令牌追加到 URL：

# Get the token
ssh -F /tmp/nemoclaw-ssh-config openshell-claw \
  "python3 -c \"import json; print(json.load(open('/sandbox/.openclaw/openclaw.json'))['gateway']['auth']['token'])\""

然后访问：http://127.0.0.1:18789/#token=<gateway-token>

修复方法：更新到 OpenClaw v2026.3.12+（参见下方“更新”部分）。

步骤 8：让端口转发保持运行

创建带健康检查的保活脚本：

cat > ~/.local/bin/nemoclaw-keepalive.sh << 'KEEPALIVE'
#!/bin/bash
export PATH="$HOME/.npm-global/bin:$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin"
cleanup() { kill %1 2>/dev/null; exit 0; }
trap cleanup SIGTERM SIGINT
while true; do
    fuser -k 18789/tcp 2>/dev/null; sleep 1
    openshell forward start 18789 claw &
    FORWARD_PID=$!; sleep 3
    while kill -0 $FORWARD_PID 2>/dev/null; do
        if ! curl -sf -o /dev/null --connect-timeout 3 http://127.0.0.1:18789/ 2>/dev/null; then
            echo "$(date): Health check failed, restarting..."
            kill $FORWARD_PID 2>/dev/null; wait $FORWARD_PID 2>/dev/null; break
        fi
        sleep 10
    done
    echo "$(date): Forward died, restarting in 3s..."; sleep 3
done
KEEPALIVE
chmod +x ~/.local/bin/nemoclaw-keepalive.sh

创建 systemd 服务：

sudo tee /etc/systemd/system/nemoclaw-forward.service << 'SERVICE'
[Unit]
Description=NemoClaw Port Forward with Health Check
After=docker.service
Requires=docker.service

[Service]
Type=simple
User=$USER
Group=docker
Environment=PATH=/home/$USER/.npm-global/bin:/home/$USER/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/home/$USER/.local/bin/nemoclaw-keepalive.sh
Restart=always
RestartSec=5
KillMode=control-group

[Install]
WantedBy=multi-user.target
SERVICE

sudo systemctl daemon-reload
sudo systemctl enable nemoclaw-forward
sudo systemctl start nemoclaw-forward

步骤 9：通过 Cloudflare Tunnel 进行远程访问（可选）

如果你已有正在运行的 Cloudflare Tunnel，可将 NemoClaw 添加到其中。

添加 DNS 路由：

cloudflared tunnel route dns <tunnel-name> nemoclaw.<domain>

更新 Tunnel 配置（/etc/cloudflared/config.yml）：

  - hostname: nemoclaw.<domain>
    service: http://localhost:18789
    originRequest:
      httpHostHeader: "127.0.0.1:18789"

重启 Tunnel：

sudo systemctl restart cloudflared

更新沙盒允许的来源——通过 SSH 登录沙盒并添加你的域名：

openshell sandbox ssh-config claw > /tmp/nemoclaw-ssh-config

ssh -F /tmp/nemoclaw-ssh-config openshell-claw 'python3 -c "
import json
with open(\"/sandbox/.openclaw/openclaw.json\") as f:
    config = json.load(f)
config[\"gateway\"][\"controlUi\"][\"allowedOrigins\"].append(\"https://nemoclaw.<domain>\")
config[\"gateway\"][\"trustedProxies\"] = [\"127.0.0.1\", \"::1\", \"172.0.0.0/8\", \"10.0.0.0/8\"]
config[\"gateway\"][\"allowRealIpFallback\"] = True
with open(\"/sandbox/.openclaw/openclaw.json\", \"w\") as f:
    json.dump(config, f, indent=2)
print(\"Done. Token:\", config[\"gateway\"][\"auth\"][\"token\"])
"'

使用 Cloudflare Access 进行保护——在 Zero Trust 控制面板的 Access 应用中添加该主机名。

访问 URL：https://nemoclaw.<domain>/#token=<gateway-token>

步骤 10：安装自定义技能

技能是位于 /sandbox/.openclaw/skills/<name>/SKILL.md 的 Markdown 文件。通过 SSH 登录沙盒来创建：

ssh -F /tmp/nemoclaw-ssh-config openshell-claw
mkdir -p /sandbox/.openclaw/skills/my-skill
cat > /sandbox/.openclaw/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: What this skill does.
tools: [exec, read, write]
---
# My Skill
Instructions for the agent...
EOF

使用以下命令验证：openclaw skills list

步骤 11：配置工作区

更新工作区文件，让 Agent 了解你的信息：

• /sandbox/.openclaw/workspace/USER.md — 你的个人资料和偏好
• /sandbox/.openclaw/workspace/TOOLS.md — 可用工具和访问权限
• /sandbox/.openclaw/workspace/SOUL.md — Agent 的个性与行为方式

更新 OpenClaw

沙盒在安装时会打包 OpenClaw。更新方法：

# 1. Update host-side packages
npm install -g openclaw@latest

# 2. Destroy and recreate sandbox
nemoclaw claw destroy
nemoclaw onboard

# 3. Reconfigure remote access (Step 9) and skills (Step 10)

注意：沙盒网络策略会阻止沙盒内访问 npm/PyPI。必须通过重建来更新。

故障排除

问题	原因	解决方法
Docker is not running	Docker 服务已停止，或用户不在 docker 组中	sudo systemctl start docker，然后运行 newgrp docker
cgroup v2 detected	Docker 未配置为使用 cgroupns=host	sudo nemoclaw setup-spark
端口 8080 已被占用	该端口上运行着其他服务	fuser -k 8080/tcp
nemoclaw: command not found	不在 PATH 中	PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH
device identity required	OpenClaw ≤ v2026.3.11 中的错误	在 URL 末尾追加 #token=<gateway-token>，或更新到 v2026.3.12+
gateway token mismatch	重建沙箱后令牌已更改	从沙箱配置中获取新令牌
too many failed auth attempts	多次尝试使用旧令牌，触发了速率限制	重启网关：ssh -F /tmp/nemoclaw-ssh-config openshell-claw 'pkill -f "openclaw gateway"; sleep 2; openclaw gateway &'
origin not allowed	域名不在 allowedOrigins 中	在沙箱配置的 gateway.controlUi.allowedOrigins 中添加该域名
端口 18789 无响应	SSH 隧道已断开	sudo systemctl restart nemoclaw-forward（将在 13 秒内自动恢复）
沙箱内 npm 返回 403 Forbidden	网络策略阻止了 TLS	无法在沙箱内安装软件包，请改为重建沙箱
DNS 路由出现 Tunnel not found	Cloudflare 账户或证书不正确	检查 cloudflared tunnel list 是否与您的证书匹配
Cloudflare 返回错误 502	隧道连接已断开	sudo systemctl restart cloudflared
通过 Cloudflare 访问时资源返回 404	浏览器未通过子请求的身份验证	登录 Cloudflare Access 后强制刷新（Ctrl+Shift+R）

架构

Docker (openshell-cluster-<name>)
  └─ k3s cluster
      ├─ NVIDIA device plugin
      └─ OpenShell sandbox
          ├─ OpenClaw agent
          ├─ NemoClaw plugin
          ├─ Gateway (WebSocket + REST)
          └─ Workspace (SOUL.md, USER.md, TOOLS.md, skills/)

Port forward (systemd): localhost:18789 ←SSH tunnel→ sandbox:18789
Cloudflare Tunnel (optional): nemoclaw.domain → localhost:18789

参考资料

• NemoClaw GitHub
• OpenShell GitHub
• OpenClaw 文档
• NemoClaw 快速入门
• awesome-nemoclaw 预设
• awesome-openclaw-skills
• 设备身份验证错误修复