nemoclaw-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NemoClaw Setup

NemoClaw 安装配置

Install NVIDIA NemoClaw — a sandboxed AI agent platform built on OpenClaw with Landlock + seccomp + network namespace isolation. Runs inside Docker via k3s (OpenShell).

在Linux上安装NVIDIA NemoClaw——一款基于OpenClaw构建的沙箱化AI代理平台，采用Landlock + seccomp + 网络命名空间实现隔离。通过k3s（OpenShell）在Docker内部运行。

What You Get

你将获得

Sandboxed AI agent with web UI and terminal CLI
Powered by NVIDIA Nemotron models (cloud or local)
Network-policy-controlled access to external services
Optional remote access via Cloudflare Tunnel

带Web UI和终端CLI的沙箱化AI代理
由NVIDIA Nemotron模型驱动（云端或本地部署）
受网络策略管控的外部服务访问权限
可选的Cloudflare Tunnel远程访问功能

Prerequisites

前置要求

Requirement	Check	Install
Linux (Ubuntu 22.04+)	`uname -a`	—
Docker	`docker ps`	`sudo apt install docker.io`
Node.js 20+ (22 recommended)	`node --version`	`nvm install 22`
NVIDIA GPU (optional but recommended)	`nvidia-smi`	—
NVIDIA API key	—	https://build.nvidia.com/settings/api-keys

要求	检查方式	安装方法
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

Workflow

操作流程

Step 1: Pre-flight Checks

步骤1：预检查

bash

undefined

bash

undefined

Check Docker

检查Docker状态

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

docker ps 2>/dev/null || echo "Docker未运行或无访问权限"

Check Node.js

检查Node.js版本

node --version

Check if already installed

检查是否已安装NemoClaw和OpenShell

which nemoclaw && nemoclaw --version which openshell && openshell --version


If `nemoclaw` is already installed, skip to Step 4.

which nemoclaw && nemoclaw --version which openshell && openshell --version


如果`nemoclaw`已安装，直接跳至步骤4。

Step 2: Install NemoClaw

步骤2：安装NemoClaw

bash

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

This installs NemoClaw and OpenClaw via npm globally (to

~/.npm-global/bin/

If the installer can't find Node.js, install it first:

bash

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

bash

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

该命令会通过npm全局安装NemoClaw和OpenClaw（安装路径为

~/.npm-global/bin/

）。

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

bash

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

Step 3: Install OpenShell

步骤3：安装OpenShell

bash

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

Installs to

~/.local/bin/openshell

bash

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

安装路径为

~/.local/bin/openshell

。

Step 4: Fix Docker Permissions and cgroup

步骤4：修复Docker权限与cgroup配置

Docker group — the user must be in the

docker

group:

bash

sudo usermod -aG docker $USER
newgrp docker

Docker用户组配置——当前用户必须加入

docker

用户组：

bash

sudo usermod -aG docker $USER
newgrp docker

or log out and back in

或注销后重新登录


**cgroup v2 fix** — required for k3s inside Docker:
```bash


**cgroup v2修复**——Docker内部运行k3s的必要配置：
```bash

Check if needed

检查是否需要修复

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

grep cgroup2 /proc/filesystems && echo "检测到cgroup v2 —— 需要修复"

Apply fix (needs sudo)

应用修复（需sudo权限）

sudo $HOME/.npm-global/bin/nemoclaw setup-spark


This adds `"default-cgroupns-mode": "host"` to `/etc/docker/daemon.json` and restarts Docker.

**IMPORTANT**: The `nemoclaw setup-spark` command also asks for an NVIDIA API key. Have it ready (starts with `nvapi-`). Get one at https://build.nvidia.com/settings/api-keys.

sudo $HOME/.npm-global/bin/nemoclaw setup-spark


该命令会在`/etc/docker/daemon.json`中添加`"default-cgroupns-mode": "host"`并重启Docker。

**重要提示**：`nemoclaw setup-spark`命令还会要求输入NVIDIA API密钥，请提前准备（密钥以`nvapi-`开头）。可在https://build.nvidia.com/settings/api-keys获取。

Step 5: Run Onboarding

步骤5：运行引导配置

bash

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

The interactive wizard will:

Check Docker and OpenShell
Start the OpenShell gateway (k3s in Docker)
Ask for a sandbox name — use
```
claw
```
or any name
Configure the NVIDIA API key
Set up inference (Nemotron 3 Super 120B via cloud API)
Launch OpenClaw inside the sandbox
Apply network policy presets — select the ones you need

Common port conflict: If port 8080 is in use, find and kill the process:

bash

fuser -k 8080/tcp

bash

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

交互式向导将完成以下操作：

检查Docker和OpenShell状态
启动OpenShell网关（Docker中的k3s集群）
要求设置沙箱名称——推荐使用
```
claw
```
或自定义名称
配置NVIDIA API密钥
设置推理服务（通过云端API使用Nemotron 3 Super 120B模型）
在沙箱内部启动OpenClaw
应用网络策略预设——选择所需的策略即可

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

bash

fuser -k 8080/tcp

Step 6: Verify

步骤6：验证部署

bash

undefined

bash

undefined

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

undefined

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

undefined

Step 7: Set Up Web UI Access

步骤7：配置Web UI访问

The web UI runs inside the sandbox and needs a port forward:

bash

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

Then open:

http://127.0.0.1:18789/

Known bug (OpenClaw ≤ v2026.3.11): "device identity required" error. Workaround — append the gateway token to the URL:

bash

undefined

Web UI运行在沙箱内部，需要配置端口转发：

bash

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

之后打开链接：

http://127.0.0.1:18789/

已知Bug（OpenClaw ≤ v2026.3.11）：出现“device identity required”错误。解决方法——在URL后追加网关令牌：

bash

undefined

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'])""


Then visit: `http://127.0.0.1:18789/#token=<gateway-token>`

**Fix**: Update to OpenClaw v2026.3.12+ (see Updating section below).

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及以上版本（见下方升级章节）。

Step 8: Make the Port Forward Persistent

步骤8：配置端口转发持久化

Create a health-checked keepalive script:

bash

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

Create the systemd service:

bash

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

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

bash

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): 健康检查失败，正在重启..."
            kill $FORWARD_PID 2>/dev/null; wait $FORWARD_PID 2>/dev/null; break
        fi
        sleep 10
    done
    echo "$(date): 转发进程已终止，3秒后重启..."; sleep 3
done
KEEPALIVE
chmod +x ~/.local/bin/nemoclaw-keepalive.sh

创建systemd服务：

bash

sudo tee /etc/systemd/system/nemoclaw-forward.service << 'SERVICE'
[Unit]
Description=NemoClaw 带健康检查的端口转发服务
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

Step 9: Remote Access via Cloudflare Tunnel (Optional)

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

If you have a Cloudflare Tunnel already running, add NemoClaw to it.

Add DNS route:

bash

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

Update tunnel config (

/etc/cloudflared/config.yml

yaml

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

Restart tunnel:

bash

sudo systemctl restart cloudflared

Update sandbox allowed origins — SSH into the sandbox and add your domain:

bash

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\"])
"'

Protect with Cloudflare Access — add the hostname to your Access application in the Zero Trust dashboard.

Access URL:

https://nemoclaw.<domain>/#token=<gateway-token>

如果你已运行Cloudflare Tunnel，可将NemoClaw添加到隧道中。

添加DNS路由：

bash

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

更新隧道配置（路径

/etc/cloudflared/config.yml

）：

yaml

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

重启隧道：

bash

sudo systemctl restart cloudflared

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

bash

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(\"配置完成。令牌:\", config[\"gateway\"][\"auth\"][\"token\"])
"'

通过Cloudflare Access保护——在Zero Trust控制台中将该主机名添加到你的Access应用中。

访问链接：

https://nemoclaw.<domain>/#token=<gateway-token>

Step 10: Install Custom Skills

步骤10：安装自定义Skills

Skills are markdown files in

/sandbox/.openclaw/skills/<name>/SKILL.md

. SSH into the sandbox to create them:

bash

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]
---

Skills是存储在

/sandbox/.openclaw/skills/<name>/SKILL.md

中的Markdown文件。通过SSH登录沙箱创建自定义Skill：

bash

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: 该Skill的功能说明。
tools: [exec, read, write]
---

My Skill

我的自定义Skill

Instructions for the agent... EOF


Verify with: `openclaw skills list`

给AI代理的操作说明... EOF


通过以下命令验证：`openclaw skills list`

Step 11: Configure the Workspace

步骤11：配置工作区

Update the workspace files so the agent knows who you are:

```
/sandbox/.openclaw/workspace/USER.md
```
— your profile, preferences
```
/sandbox/.openclaw/workspace/TOOLS.md
```
— available tools and access
```
/sandbox/.openclaw/workspace/SOUL.md
```
— agent personality and behaviour

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

```
/sandbox/.openclaw/workspace/USER.md
```
—— 你的个人资料、偏好设置
```
/sandbox/.openclaw/workspace/TOOLS.md
```
—— 可用工具及访问权限
```
/sandbox/.openclaw/workspace/SOUL.md
```
—— AI代理的个性与行为设定

Updating OpenClaw

升级OpenClaw

The sandbox bundles OpenClaw at install time. To update:

bash

undefined

沙箱在安装时会捆绑OpenClaw版本。如需升级，请执行以下步骤：

bash

undefined

1. Update host-side packages

1. 更新主机端的包

npm install -g openclaw@latest

2. Destroy and recreate sandbox

2. 销毁并重新创建沙箱

nemoclaw claw destroy nemoclaw onboard

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

3. 重新配置远程访问（步骤9）和自定义Skills（步骤10）


**Note**: Sandbox network policies block npm/PyPI inside the sandbox. Updates must be done by rebuilding.


**注意**：沙箱的网络策略会阻止内部访问npm/PyPI，因此必须通过重建沙箱来完成升级。

Troubleshooting

故障排查

Issue	Cause	Fix
`Docker is not running`	Docker service stopped or user not in docker group	`sudo systemctl start docker` then `newgrp docker`
`cgroup v2 detected`	Docker not configured for cgroupns=host	`sudo nemoclaw setup-spark`
Port 8080 in use	Another service on that port	`fuser -k 8080/tcp`
`nemoclaw: command not found`	Not in PATH	`PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH`
`device identity required`	Bug in OpenClaw ≤ v2026.3.11	Append `#token=<gateway-token>` to URL, or update to v2026.3.12+
`gateway token mismatch`	Token changed after sandbox rebuild	Get new token from sandbox config
`too many failed auth attempts`	Rate limited from old token attempts	Restart gateway: `ssh -F /tmp/nemoclaw-ssh-config openshell-claw 'pkill -f "openclaw gateway"; sleep 2; openclaw gateway &'`
`origin not allowed`	Domain not in allowedOrigins	Add to `gateway.controlUi.allowedOrigins` in sandbox config
Port 18789 not responding	SSH tunnel died	`sudo systemctl restart nemoclaw-forward` (auto-recovers within 13s)
npm 403 Forbidden inside sandbox	Network policy blocking TLS	Cannot install packages inside sandbox — rebuild instead
`Tunnel not found` on DNS route	Wrong Cloudflare account/cert	Check `cloudflared tunnel list` matches your cert
Error 502 on Cloudflare	Tunnel connections dropped	`sudo systemctl restart cloudflared`
Assets 404 via Cloudflare	Browser not authenticated for sub-requests	Hard refresh (Ctrl+Shift+R) after Cloudflare Access login

问题	原因	解决方法
`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版本的已知Bug	在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）

Architecture

架构说明

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

Docker (openshell-cluster-<name>)
  └─ k3s集群
      ├─ NVIDIA设备插件
      └─ OpenShell沙箱
          ├─ OpenClaw代理
          ├─ NemoClaw插件
          ├─ 网关（WebSocket + REST）
          └─ 工作区（SOUL.md, USER.md, TOOLS.md, skills/）

端口转发（systemd）：localhost:18789 ←SSH隧道→ sandbox:18789
Cloudflare Tunnel（可选）：nemoclaw.domain → localhost:18789

nemoclaw-setup

Original

Translation

NemoClaw Setup

NemoClaw 安装配置

What You Get

你将获得

Prerequisites

前置要求

Workflow

操作流程

Step 1: Pre-flight Checks

步骤1：预检查

Check Docker

检查Docker状态

Check Node.js

检查Node.js版本

Check if already installed

检查是否已安装NemoClaw和OpenShell

Step 2: Install NemoClaw

步骤2：安装NemoClaw

Step 3: Install OpenShell

步骤3：安装OpenShell

Step 4: Fix Docker Permissions and cgroup

步骤4：修复Docker权限与cgroup配置

or log out and back in

或注销后重新登录

Check if needed

检查是否需要修复

Apply fix (needs sudo)

应用修复（需sudo权限）

Step 5: Run Onboarding

步骤5：运行引导配置

Step 6: Verify

步骤6：验证部署

Check sandbox is running

检查沙箱运行状态

Connect via terminal

通过终端连接沙箱

Step 7: Set Up Web UI Access

步骤7：配置Web UI访问

Get the token

获取网关令牌

Step 8: Make the Port Forward Persistent

步骤8：配置端口转发持久化

Step 9: Remote Access via Cloudflare Tunnel (Optional)

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

Step 10: Install Custom Skills

步骤10：安装自定义Skills

My Skill

我的自定义Skill

Step 11: Configure the Workspace

步骤11：配置工作区

Updating OpenClaw

升级OpenClaw

1. Update host-side packages

1. 更新主机端的包

2. Destroy and recreate sandbox

2. 销毁并重新创建沙箱

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

3. 重新配置远程访问（步骤9）和自定义Skills（步骤10）

Troubleshooting

故障排查

Architecture

架构说明

References

参考链接