NVIDIA NemoClaw 参考栈：在 OpenShell 沙箱中安全运行 AI Agent 的安装、配置与贡献指南-平芜编程栈

NVIDIA NemoClaw 参考栈：在 OpenShell 沙箱中安全运行 AI Agent 的安装、配置与贡献指南

【免费下载链接】NemoClawRun agents like Hermes, LangChain Deep Agents, and OpenClaw more securely inside NVIDIA OpenShell with managed inference项目地址: https://gitcode.com/gh_mirrors/ne/NemoClaw

NemoClaw 是 NVIDIA 开源的参考实现栈（Reference Stack），用于在 NVIDIA OpenShell 沙箱中更安全地运行受支持的 AI Agent（默认 OpenClaw，另支持 Hermes 与 LangChain Deep Agents Code）。本文以仓库 README.md 为主线，结合 package.json、三个 Agent 的 manifest.yaml、blueprint.yaml、openclaw-sandbox.yaml 与 scripts/dev-setup.sh 等源码级证据，带你掌握 NemoClaw 的定位、安装流程、核心安全设计、CLI 用法及贡献者开发环境搭建，读完后即可独立完成从安装、选择 Agent 到接入托管推理与网络策略的完整闭环。

NemoClaw 是什么：一套"更安全的沙箱化 Agent"参考栈

根据 README.md 的定位，NemoClaw 是一个开源参考栈，核心目标是在 NVIDIA OpenShell 沙箱内更安全地运行受支持的 AI Agent。它并非重新实现 Agent，而是通过 NemoClaw CLI 及其 Agent 专属别名，为沙箱化运行提供一整套托管能力，主要包括：

Guided onboarding（引导式入门）：向导式安装与首次沙箱创建；
Managed inference（托管推理）：为沙箱内 Agent 提供受管理的模型推理路由；
Network policy（网络策略）：默认拒绝的外发访问控制；
Managed integrations（托管集成）：消息通道、MCP 服务器等集成的托管接入；
Snapshots（快照）：沙箱状态的备份与恢复；
Lifecycle operations（生命周期操作）：沙箱的启动、停止、重建、升级与卸载。

从源码结构看，CLI 本体是一个 oclif 应用，入口为 src/nemoclaw.ts，它作为"兼容性前端控制器"把实际语法适配交给 src/lib/cli/public-dispatch.ts（该文件刻意保持精简，命令发现与解析由src/commands/**下的 oclif 命令承担）。package.json 中的bin字段同时暴露了多条命令：nemoclaw、nemoclaw-acp、nemoclaw-blueprint-runner、nemohermes和nemo-deepagents——前两者分别是主 CLI 与 ACP 适配器，后两者是 Hermes 与 Deep Agents 的别名入口。

值得注意的运行前提：仓库 package.json 的engines声明Node.js >= 22.19.0，并以可选依赖方式引入@nvidia/openshell-sdk（0.0.116），这是 NemoClaw 与 OpenShell 协同工作的 SDK 基础。

支持的 Agent：三类运行时与 manifest 集成契约

README 明确列出三类受支持 Agent，其中OpenClaw 为默认 Agent：

Agent	定位	对应 Quickstart 文档
OpenClaw（默认）	基于网关（gateway）的 AI Agent，拥有插件生态	quickstart.mdx
Hermes	带学习闭环的自改进型 Agent（Nous Research）	quickstart-hermes.mdx
LangChain Deep Agents Code	基于 Deep Agents SDK 的终端编码 Agent	quickstart-langchain-deepagents-code.mdx

NemoClaw 与每个 Agent 的集成契约统一声明在agents/<agent>/manifest.yaml中，这是理解"参考栈"如何与三方 Agent 对接的关键入口：

agents/openclaw/manifest.yaml：声明 OpenClaw 以 npm 方式安装（openclaw gateway run为网关命令），健康探针位于http://localhost:18789/，配置目录为/sandbox/.openclaw（openclaw.json），并列出agents、workspace、skills、hooks、canvas、cron、memory、credentials等需要纳管的状态目录。值得注意的安全细节：identity与devices目录只销毁不备份，恢复副本无法通过认证（注释中引用 issue #6852），避免快照泄露网关鉴权状态。
agents/hermes/manifest.yaml：Hermes 以 curl 方式安装，健康探针为http://localhost:8642/health，配置在/sandbox/.hermes/config.yaml，并采用bearer_token（API_SERVER_KEY环境变量）的 Web 鉴权方式——与 OpenClaw 的 device pairing 机制不同。其runtime/state.db、kanban.db、gateway/discord_message_recovery.db等 SQLite 文件通过 SQLite 在线备份 API 捕获，保证一致性。
agents/langchain-deepagents-code/manifest.yaml：这是纯终端型（terminal）运行时，无长驻网关与仪表盘健康面；交互命令为dcode，无头模式为dcode -n，配置为/sandbox/.deepagents/config.toml。其config.toml的恢复采用 key-allowlist 合并策略：只有ui.*、threads.*、interpreter.*、startup.mode等用户键可恢复，NemoClaw 生成的models/update表必须"新鲜"（require_fresh_tables），其余未知或敏感键一律丢弃。

从这三个 manifest 可以看出 NemoClaw 的设计原则：Agent 自身仍是其配置、技能与状态的权威，NemoClaw 只负责沙箱化承载、状态纳管与推理注入。

快速开始：两条入口路径

README 提供了两条上手路径——给"编码 Agent"用的 Starter Prompt，以及给开发者直接在终端使用的 Installer。

从你的编码 Agent 开始（Starter Prompt）

如果你使用 Cursor、Claude Code、Codex、Copilot 等本地编码 Agent，可以先复制 NemoClaw 的 starter prompt 交给它来协助安装。该 prompt 会引导你的 Agent：

以 NemoClaw 官方文档与 skills 为信息来源；
一次只问一个问题；
只在获得你批准后运行命令；
把密钥留在聊天之外（避免 API Key 等敏感信息进入对话记录）。

仓库中以"AI Agent 使用文档"为核心设计的技能位于 skills/nemoclaw-user-guide/SKILL.md，它定义了文档检索顺序（优先 docs MCP 的searchDocs，其次使用仓库内 Markdown 索引与页面），并约束 Agent 不得凭过期副本作答、必须区分 Agent 变体（openclaw/hermes/deepagents）且不得混用变体专属指令。该技能还明确要求"在要求用户提供 API Key、机器人令牌或私有 URL 之前停下""绝不让用户把密钥粘贴进聊天"，并规定示例一律使用<PASTE_YOUR_API_KEY_HERE>之类的脱敏占位符。

使用终端安装器（Installer）

在安装前建议先阅读 prerequisites.mdx（硬件、软件与受支持平台）。在受支持的 DGX 或 WSL 主机上，安装器会询问：

Run express install with these settings? [Y/n]:

直接回车（Y）：使用该平台的推荐预设设置执行快速安装，默认安装 OpenClaw，安装完成后参考 quickstart.mdx；
输入n：进入交互模式，可自行选择 Hermes 或 LangChain Deep Agents Code、沙箱名称、推理提供商（inference provider）与模型。

README 还提示一个 Hermes 特例：当从轻量终端连接 Hermes 沙箱时，NemoClaw 可能安装一个受管的nemoclaw-lightHermes 皮肤以提供可读的助手文本；当终端不再需要时会移除该受管皮肤状态，并保留用户自选的 Hermes 皮肤。

从安装器实现看，根目录 install.sh 是一个"薄引导层"：它会先选定一个 ref（默认lkg，可用NEMOCLAW_INSTALL_TAG或NEMOCLAW_INSTALL_REF覆盖），浅克隆该 ref 后从同一克隆执行安装器逻辑，并对下载脚本做 shebang 与 SHA-256 完整性校验，避免"curl | bash"链路中的脚本替换风险。安装完成后，主 CLI 会被安装为nemoclaw（curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash），Hermes 变体为nemohermes（NEMOCLAW_AGENT=hermes bash），Deep Agents 变体为nemo-deepagents（NEMOCLAW_AGENT=langchain-deepagents-code bash）——详见 commands.mdx 中的 Agent 选择说明。

核心能力纵深：Blueprint、托管推理与网络策略

README 将文档按主题组织成表，其中几个主题直接对应仓库中的可验证实现，这里结合源码展开。

托管推理：Blueprint 中的五种推理档案

README 中的 "Choose an Inference Provider" 对应 blueprint.yaml。该文件是沙箱编排蓝图，声明了 OpenShell 最低版本要求（min_openshell_version: "0.0.116"）、固定到具体 digest 的沙箱镜像（ghcr.io/nvidia/openshell-community/sandboxes/openclaw@sha256:...，防止:latest被意外替换），并在inference.profiles中定义五种推理档案：

档案	provider_type	端点	说明
`default`	nvidia	`https://integrate.api.nvidia.com/v1`	默认 NVIDIA 托管推理，模型`nvidia/nemotron-3-super-120b-a12b`
`ncp`	nvidia	动态端点	走 NVIDIA NCP，凭据来自`NVIDIA_INFERENCE_API_KEY`
`nim-local`	openai	`http://nim-service.local:8000/v1`	本地 NIM 服务，超时 180s
`vllm`	openai	`http://localhost:8000/v1`	本地 vLLM，默认模型为 HF repo id`nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-FP8`，凭据默认值`dummy`
`routed`	openai	`http://localhost:4000/v1`	经内置推理路由器，池配置见`router/pool-config.yaml`

与routed档案配套，Blueprint 还启用了内置路由器（router.enabled: true，端口 4000），池配置在 nemoclaw-blueprint/router/pool-config.yaml。README 中的 "Choose an Inference Provider" 文档页即 choose-inference-provider.mdx，其路由推理（routed inference）配置与这里的routed档案一一对应。

网络策略：默认拒绝的外发控制

README 中 "Network Policies" 与 "Customize Network Policy" 分别对应 network-policies.mdx 和 customize-network-policy.mdx。其默认策略实现位于 openclaw-sandbox.yaml，策略原则在文件头部写得很明确：deny by default, allow only what's needed（默认拒绝，只放行核心功能所需）。

具体机制包括：

文件系统策略（filesystem_policy）：/usr、/lib、/proc、/etc、/var/log等只读；/tmp、/sandbox/.openclaw、/sandbox/.nemoclaw等可写；注释还解释了/dev/pts必须放行（否则 landlock 会以 EACCES 拒绝forkpty，导致 tmux 报create window failed，issue #4513）；
Landlock 兼容模式：当前为best_effort，注释明确说明暂未切换enforce（需跨内核版本充分测试，ref #516）；
进程策略：Agent 以sandbox用户/组运行；
网络策略（network_policies）：以nvidia为例，仅放行integrate.api.nvidia.com:443的POST /v1/chat/completions、POST /v1/completions、POST /v1/embeddings、GET /v1/models等 REST 规则，其余外发默认拒绝。

动态策略更新可参考 customize-network-policy.mdx（静态/动态修改与预设），整体安全控制框架见 best-practices.mdx 与 sandbox-hardening.mdx。

沙箱入口点：gateway 与 agent 的进程隔离

沙箱容器的入口脚本是 scripts/nemoclaw-start.sh（共 5000+ 行）。其注释揭示了核心安全设计：入口以 root 启动，先以gateway用户运行网关，再降权为sandbox用户执行 Agent 命令——这样沙箱内的 Agent 无法杀死网关或用篡改配置重启它（fake-HOME 绕过，CVE 防御），同时启动时会校验配置哈希以检测篡改。

脚本还支持一组启动期环境变量（可在不重建镜像的前提下覆盖运行时行为）：

变量	作用
`NVIDIA_INFERENCE_API_KEY`	NVIDIA 托管推理的 API Key
`NEMOCLAW_MODEL_OVERRIDE`	启动时覆盖主模型
`NEMOCLAW_INFERENCE_API_OVERRIDE`	跨提供商族切换 API 类型（如`anthropic-messages`/`openai-completions`）
`NEMOCLAW_CONTEXT_WINDOW`/`NEMOCLAW_MAX_TOKENS`	覆盖上下文窗口与最大输出 token
`NEMOCLAW_REASONING`/`NEMOCLAW_REASONING_EFFORT`	启用推理模式及 effort（low/medium/high）
`NEMOCLAW_CORS_ORIGIN`	追加允许的浏览器源（自定义域名/端口）

CLI 与生命周期操作

README 的 "CLI Commands" 对应 commands.mdx，其内容按 Agent 变体区分：

OpenClaw：主命令为nemoclaw，nemoclaw onboard默认选择 OpenClaw（除非用--agent <name>或NEMOCLAW_AGENT=<name>指定其他已安装 Agent，可用nemoclaw agents list查看）。沙箱内聊天界面还提供/nemoclaw斜杠命令：/nemoclaw（帮助）、/nemoclaw status（沙箱与推理状态）、/nemoclaw onboard（入门状态与重配置指引）、/nemoclaw eject（回滚到宿主安装的说明）。
Hermes：使用nemohermes别名，nemohermes onboard默认选 Hermes，nemohermes my-sandbox connect连接 Hermes 沙箱；它内置 Hermes 仪表盘与独立的 OpenAI 兼容 API 端点，并提供 NemoClaw Hermes 插件工具与on_session_start钩子。
LangChain Deep Agents Code：使用nemo-deepagents别名，运行时为终端型dcode（交互）与dcode -n（无头），配置托管在/sandbox/.deepagents。

社区、贡献者路径与安全报告

社区渠道

README 说明 NemoClaw 当前为alpha 项目，维护者按 best effort 处理 Issue、讨论与 PR，无固定响应时限。提问走 GitHub Discussions / Discord，可复现的 Bug 走 GitHub Issues，功能提案先 Discussions 后 Issue，示例投稿见社区仓库；漏洞严禁开公开 Issue，必须走 SECURITY.md 中的私有通道（NVIDIA 漏洞披露计划、加密邮件 psirt@nvidia.com、GitHub 私有漏洞报告）。

贡献者开发环境

贡献路径与终端用户安装器完全分离，核心脚本是 scripts/dev-setup.sh：

git clone https://gitcode.com/gh_mirrors/ne/NemoClaw cd NemoClaw ./scripts/dev-setup.sh # 仅准备仓库本地依赖、构建与钩子，不创建运行时沙箱

也可以用兼容编码 Agent 直接发起："Set up this machine as a NemoClaw contributor and prepare it for a first PR."

脚本支持四种模式：

模式	行为
默认 /`--repair`	安装或修复仓库本地贡献者工具链（依赖、构建、pre-commit/commit-msg/pre-push 钩子）
`--expose-cli`	显式选择暴露一个 PATH 可见的开发版 NemoClaw CLI
`--with-runtime`	依次完成 setup、暴露 CLI、验证 readiness，再进入运行时 onboarding（`bin/nemoclaw.js onboard`）
`--doctor [--json]`	只读的贡献者就绪度检查，`--json`输出结构化报告

从脚本实现看，它严格遵循"只改动仓库本地内容"的原则：不修改宿主包、全局 Git 配置、GitHub 状态、签名密钥、凭据、许可证或沙箱；CLI 暴露与运行时 onboarding 都必须显式 opt-in。它要求 Node.js >= 22.19、npm >= 10、Python >= 3.11，并支持 macOS/Linux 的 arm64/aarch64 与 x86_64 主机；--doctor还会检查 Docker 资源（最低 4 vCPU / 8 GiB，建议 16 GiB）、Git 身份与提交签名、GitHub CLI 认证、OpenShell SDK、构建产物新鲜度与本地 CLI 是否指向当前检出等。

当前优先级

README 公开了当前维护优先级（非交付承诺）：提升跨受测平台的安装与 onboarding 可靠性；强化沙箱加固、凭据处理与网络策略默认值；验证本地与路由推理的受支持提供商路径；保持文档、排障指南与 Agent skills 与受支持工作流对齐。

授权与使用注意

NemoClaw 以Apache 2.0授权，见 LICENSE。README 同时包含重要免责声明：该软件会自动检索、访问或与外部材料交互，这些外部材料不随软件分发，受其各自条款约束；使用方需自行核实所检索材料的合规性、安全性、完整性与适用性，软件按 "AS IS" 提供且不附带任何担保。

总体而言，NemoClaw 的价值在于把"跑一个 Agent"这件看似简单的事，收敛为一套可重复、可审计、默认安全的参考流程：统一的三方 Agent 集成契约（manifest）、声明式沙箱蓝图（blueprint）、默认拒绝的策略文件，以及围绕 onboarding、推理、快照、生命周期与贡献开发的完整工具链。对希望在生产环境或自有 DGX 上规范运行 OpenClaw/Hermes/Deep Agents 的团队而言，这份仓库就是最好的起点与事实来源。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考