在 Linux 上安装配置 NVIDIA…

需要在 Linux 上用 Docker/k3s 部署带隔离的 NVIDIA NemoClaw/OpenClaw 沙箱代理，并配置 Cloudflare Tunnel 远程访问与排障时使用。

适用场景

解决思路

1. 1. 预检基础环境：检查 Linux 版本 `uname -a`（要求 Ubuntu 22.04+）；检查 Docker `docker ps`（缺失则 `sudo apt install docker.io`）；检查 Node.js `node --version`（要求 20+，推荐 22，可用 `nvm install 22`）；检查 NVIDIA GPU（可选但推荐）`nvidia-smi`；并准备 NVIDIA API key（访问 https://build.nvidia.com/settings/api-keys）。
2. 2. 执行 NemoClaw 预检：运行 `docker ps 2>/dev/null || echo 'Docker not running or no access'`；运行 `node --version`；检查是否已安装：`which nemoclaw && nemoclaw --version`、`which openshell && openshell --version`。如果 `nemoclaw` 已安装，跳过 Step 4。
3. 3. 安装 NemoClaw：`curl -fsSL https://nvidia.com/nemoclaw.sh | bash`。这会通过 npm 全局安装 NemoClaw 和 OpenClaw 到 `~/.npm-global/bin/`。
4. 4. 如果安装器找不到 Node.js，先安装 Node：`curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -`，然后 `sudo apt install -y nodejs`。
5. 5. 安装 OpenShell：`curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh`，安装到 `~/.local/bin/openshell`。
6. 6. 修复 Docker 权限：把当前用户加入 docker 组 `sudo usermod -aG docker $USER`，然后 `newgrp docker` 或重新登录。
7. 7. 修复 cgroup v2（Docker 内 k3s 需要）：先检查 `grep cgroup2 /proc/filesystems && echo 'cgroup v2 detected — fix needed'`；然后执行 `sudo $HOME/.npm-global/bin/nemoclaw setup-spark`。该命令会向 `/etc/docker/daemon.json` 添加 `"default-cgroupns-mode": "host"` 并重启 Docker。
8. 8. 注意 `nemoclaw setup-spark` 会询问 NVIDIA API key（以 `nvapi-` 开头），提前从 https://build.nvidia.com/settings/api-keys 获取。
9. 9. 运行 onboarding：`PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH nemoclaw onboard`。交互式向导会：检查 Docker 和 OpenShell；启动 OpenShell gateway（Docker 中的 k3s）；询问 sandbox 名称（可用 `claw` 或任意名称）；配置 NVIDIA API key；设置推理（通过云 API 使用 Nemotron 3 Super 120B）；在 sandbox 中启动 OpenClaw；应用网络策略预设（选择需要的预设）。
10. 10. 处理常见端口冲突：如果 8080 被占用，运行 `fuser -k 8080/tcp`。
11. 11. 验证 sandbox：`PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH nemoclaw claw status`；连接终端：`PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH nemoclaw claw connect`。
12. 12. 设置 Web UI 访问：启动端口转发 `PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH openshell forward start 18789 claw`，然后打开 `http://127.0.0.1:18789/`。
13. 13. 处理已知 bug（OpenClaw ≤ v2026.3.11）的 `device identity required` 错误：获取 gateway 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>`。
14. 14. 修复该 bug：更新到 OpenClaw v2026.3.12+（见更新部分）。
15. 15. 创建带健康检查的 keepalive 脚本：`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`。
16. 16. 创建 systemd service：`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`。
17. 17. 如已有 Cloudflare Tunnel，添加 NemoClaw：添加 DNS 路由 `cloudflared tunnel route dns <tunnel-name> nemoclaw.<domain>`。
18. 18. 更新 tunnel 配置 `/etc/cloudflared/config.yml`：` - hostname: nemoclaw.<domain> service: http://localhost:18789 originRequest: httpHostHeader: "127.0.0.1:18789"`。
19. 19. 重启 tunnel：`sudo systemctl restart cloudflared`。
20. 20. 更新 sandbox allowed origins：先 `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\"]) "'`。
21. 21. 用 Cloudflare Access 保护：在 Zero Trust dashboard 中把 hostname 加入 Access 应用。
22. 22. 访问 URL：`https://nemoclaw.<domain>/#token=<gateway-token>`。
23. 23. 安装自定义 Skills：Skills 是 `/sandbox/.openclaw/skills/<name>/SKILL.md` 中的 markdown 文件。SSH 进 sandbox 创建：`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`。
24. 24. 验证 skills：`openclaw skills list`。
25. 25. 配置工作区文件：更新 `/sandbox/.openclaw/workspace/USER.md`（个人资料、偏好）；`/sandbox/.openclaw/workspace/TOOLS.md`（可用工具和访问权限）；`/sandbox/.openclaw/workspace/SOUL.md`（代理个性与行为）。
26. 26. 更新 OpenClaw：sandbox 在安装时打包 OpenClaw。先在宿主机更新 `npm install -g openclaw@latest`；销毁并重建 sandbox `nemoclaw claw destroy`；`nemoclaw onboard`；重新配置远程访问（Step 9）和 skills（Step 10）。
27. 27. 注意：sandbox 网络策略阻止 sandbox 内访问 npm/PyPI，更新必须通过重建完成。
28. 28. `Docker is not running`：Docker 服务停止或用户不在 docker 组；运行 `sudo systemctl start docker`，然后 `newgrp docker`。
29. 29. `cgroup v2 detected`：Docker 未配置 cgroupns=host；运行 `sudo nemoclaw setup-spark`。
30. 30. Port 8080 in use：另一个服务占用；运行 `fuser -k 8080/tcp`。
31. 31. `nemoclaw: command not found`：不在 PATH；运行 `PATH=$HOME/.npm-global/bin:$HOME/.local/bin:$PATH`。
32. 32. `device identity required`：OpenClaw ≤ v2026.3.11 bug；在 URL 后追加 `#token=<gateway-token>`，或更新到 v2026.3.12+。
33. 33. `gateway token mismatch`：sandbox 重建后 token 变化；从 sandbox 配置获取新 token。
34. 34. `too many failed auth attempts`：旧 token 尝试导致限流；重启 gateway：`ssh -F /tmp/nemoclaw-ssh-config openshell-claw 'pkill -f "openclaw gateway"; sleep 2; openclaw gateway &'`。
35. 35. `origin not allowed`：域名不在 allowedOrigins；在 sandbox 配置的 `gateway.controlUi.allowedOrigins` 中添加。
36. 36. Port 18789 not responding：SSH tunnel 挂了；`sudo systemctl restart nemoclaw-forward`（13 秒内自动恢复）。
37. 37. npm 403 Forbidden inside sandbox：网络策略阻止 TLS；不能在 sandbox 内安装包，改为重建。
38. 38. `Tunnel not found` on DNS route：错误 Cloudflare 账户/证书；检查 `cloudflared tunnel list` 与证书匹配。
39. 39. Error 502 on Cloudflare：tunnel 连接断开；`sudo systemctl restart cloudflared`。
40. 40. Assets 404 via Cloudflare：浏览器未认证子请求；Cloudflare Access 登录后强制刷新（Ctrl+Shift+R）。

适用边界 · 注意事项

• 不在 Linux（Ubuntu 22.04+）环境，或无法使用 Docker/Node.js 20+ 时不要用。
• 没有 NVIDIA API key 且不准备从 https://build.nvidia.com/settings/api-keys 获取时不要用（安装向导和 setup-spark 需要）。
• 只需要普通 OpenClaw 而不需要 NemoClaw 沙箱、k3s/OpenShell、网络隔离或 Cloudflare Tunnel 远程访问时不要用。