NVIDIA OpenShell

NVIDIA OpenShell 快速入门：先给 Agent 画好能碰什么，再让它自己干活

这是什么？适合谁？

OpenShell 是 NVIDIA 开源的 Agent 安全运行时。官方定义很短：「the safe, private runtime for fleets of autonomous AI agents」——Agent 最有用的时刻，正是它能够读文件、装包、调 API、用凭据的时候；OpenShell 要解决的矛盾是：既给它这些能力，又不给它对你数据、密钥、网络的无限访问权。做法是「先在策略里声明每个 Agent 能碰什么，再由 OpenShell 强制执行」。

它和「换一个更听话的模型」「在 prompt 里写不要删文件」不是一类东西。官方给了两条执行路径：

• 内核层强制（kernel-level enforcement）：每个 Agent 跑在独立沙箱里，内核控制它可访问的文件与可发起的系统调用；每一条网络连接在离开沙箱前都要过策略检查；Agent 拿不到真实凭据，OpenShell 只在请求发往「已批准的端点」时才把凭据注入进去。
• 策略变更的形式化验证（formally verified policy changes）：策略改动在生效之前，先算出它会新放开哪些危险访问——比如「带着凭据访问一个新主机」「调用一个新的 API 方法」——这类变更会停下来等人审。

适合谁：

• 要让 Agent 在有敏感数据、有内网、有真实凭据的环境里跑，而不敢直接给一台机器权限的团队；
• 需要把「Agent 能做什么」写成可审、可 diff、可回滚的策略文件，而不是散落在 prompt 与脚本里的运维与安全负责人；
• 要把 Agent 沙箱铺到多台机器或 Kubernetes 上、并且要求凭据统一从网关侧下发的平台团队。

不适合谁：只想在本机试一个 Agent 的普通用户——它默认沙箱镜像里连 Agent 都没装，先读完「Run Your First Agent」那页再动手。

与站内同类条目对比：Hive（本站 8.5）解决的是一堆工作单元如何并行与持久化，属于编排层；OpenShell 解决的是这些 Agent 允许碰什么，属于执行边界层。两者不冲突：CrewAI（本站 8.6）、AutoGen（本站 8.6）这类框架负责让 Agent 分工，OpenShell 负责把分工结果关进沙箱。

核验日期：2026-10-30。依据 官方仓库 README、官方文档站、GitHub API。

准备工作

• 系统：Linux、macOS（Apple Silicon），或 Windows + WSL 2（官方标注为 experimental）。支持矩阵在 Support Matrix。
• 容器/虚拟化：Docker、Podman，或宿主虚拟化，三选一——沙箱本身要靠它跑。
• 一个网关：安装脚本会同时装 CLI 与一个本地 gateway。要铺到集群则用 Helm（要求你的 CNI 能真正执行 NetworkPolicy）。
• 一个要被管住的 Agent：默认镜像是极简 Ubuntu，里面没有 Agent。教程用 OpenCode 配一个免费 OpenRouter 模型演示。
• 时间预算：从安装到跑通第一个带策略的 Agent，按官方教程顺序大约 30–60 分钟；如果卡在 WSL 2 或 CNI 上，另算。

费用：软件 Apache-2.0 免费；费用来自你放进去的 Agent 所用的模型，以及运行沙箱的机器/集群。

安装与首次启动

1. 装 CLI 与本地网关

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

2. 建第一个沙箱

openshell sandbox create --name demo

这一步能跑通，说明 CLI、网关与容器运行时这条链路是通的——但沙箱还是空的（极简 Ubuntu，无 Agent）。

3. 按教程放一个真 Agent 进去

照 Run Your First Agent 做：它用 OpenCode 配免费 OpenRouter 模型，并演示「Agent 需要新权限时，你怎么批准」这个关键动作。

成功判定

三个都成立才算装好：openshell sandbox create 能建成并进入；沙箱里能跑起一个模型 Agent；Agent 尝试访问未被策略允许的主机时被拦下，而你批准后同样的请求能通过。

首个任务：让 Agent 只能访问一个域名、只用一份凭据

目标：给一个「查文档 + 写文件」的 Agent 配最小权限，验证策略真的生效。

1. 建一个专用沙箱：openshell sandbox create --name scoped-demo。
2. 写一份策略，只放开：读 /workspace、写 /workspace/out、允许访问你指定的文档站主机；其余文件与网络一律关掉（策略字段见 Policies 概览）。
3. 用 provider 把凭据挂上去，而不是把 key 写进沙箱环境变量——OpenShell 的模型是「凭据只在发往已批准端点时才注入」，Agent 进程本身看不到明文（见 Providers）。
4. 让 Agent 做一件事：抓取该文档站的一页并总结，写到 /workspace/out/summary.md。
5. 再做一次反证：让它访问一个不在策略里的域名，确认被拒。

预期产出：/workspace/out/summary.md 存在且有内容；越权访问那条命令失败，且失败原因是策略而不是网络抖动。

成功判定：同一个 Agent、同一份代码，只改策略就能改变它能不能出网——这是整套东西的核心价值，也是验收时唯一有意义的判据。

初级用法

1. 用 advisor 先看「这条策略会放开什么」

策略改动之前先跑 advisor，它会把你即将授予的访问逐条列出来。配合 prover 用，比改完再出事便宜得多（Policies advisor 与 prover）。

2. 一个任务一个沙箱，而不是一个 Agent 一个沙箱

沙箱是有生命周期的（镜像、运行时、GPU、create/stop/remove），按任务开、按任务销毁，比长期养一个「万能沙箱」更接近最小权限。

3. 把 telemetry 关掉再进内网

默认会收集匿名运营类计数（不包含沙箱名、主机名、路径、prompt、凭据、provider 名、模型名、用户内容）。内网部署按官方给的方式关：网关侧设 OPENSHELL_TELEMETRY_ENABLED=false；Helm 安装用 server.telemetryEnabled=false；需要彻底干净就编译时把 telemetry 去掉。

高级玩法

1. 用 SDK 把沙箱变成业务能力

四种语言都能连网关：Python（uv add openshell）、TypeScript（npm install @nvidia/openshell-sdk，走 GitHub Packages）、Go、Rust。适合「用户点一个按钮 → 后台开沙箱 → 跑完回收」这类产品化用法。

2. 在 Kubernetes 里铺一层

网关用 Helm 部署，沙箱作为工作负载分发。前提是你的 CNI 真能执行 NetworkPolicy——否则「网络策略」只是文档上的字（Kubernetes setup）。

3. 用 middleware / interceptor / compute driver 扩展

扩展面分三类：middleware 与 interceptor 改请求路径上的行为，compute driver 换底层算力（含 GPU）。想在策略之外再加一层「业务级白名单」，这是入口（Extensibility）。

4. 让编码 Agent 自己会写策略

仓库自带一组公开 skills：npx skills add NVIDIA/OpenShell，教你的编码 Agent 驱动 OpenShell CLI、写沙箱策略、排查网关与推理路由。它不需要 checkout 源码。

五个小技巧

1. 先跑反证：新策略上线第一件事是验证「不该通的确实不通」，比验证「该通的通了」更能发现配置写错。
2. 凭据走 provider，不要走环境变量：环境变量是沙箱内的明文，provider 是「只在出站时注入」。
3. 镜像别用默认的：默认镜像是极简 Ubuntu 且没有 Agent，正式用要自己打镜像。
4. 策略改动一律走验证再合并：把它当代码审，而不是当配置热改。
5. WSL 2 只是 experimental：Windows 上真要长期跑，优先虚拟机或远端 Linux。

常见踩坑

坑 1：openshell sandbox create 之后以为可以立刻派活

现象：沙箱进去什么 Agent 都没有。 原因：官方默认镜像是极简 Ubuntu，故意不带 Agent。 解决：按「Run Your First Agent」放一个进去，或者自己打带 Agent 的镜像。

坑 2：Agent 报「连不上网」，其实是策略在拦

现象：网络请求失败，看起来像 DNS 或代理问题。 原因：每条出站连接都要过策略检查，未批准的主机会被拦在沙箱内。 解决：看策略与 advisor 输出，把目标主机加进允许列表；调试期不要图省事关掉整套策略。

坑 3：把 API key 写进沙箱环境变量

现象：策略配得很漂亮，但凭据泄漏风险仍在。 原因：环境变量对沙箱内进程是明文的，等于绕过了「Agent 看不到真实凭据」这条设计。 解决：用 provider 挂凭据，只在发往已批准端点时注入。

坑 4：Windows 上直接装，撞到 WSL 2 的坑

现象：安装或启动失败。 原因：Windows 支持走 WSL 2，官方标注 experimental；原生 Windows 支持走 Microsoft MXC，另有一份 Windows 指南，有当前限制。 解决：先按 WSL 2 路线排查；需要原生支持就照那份指南，别混用两套文档。

坑 5：Kubernetes 上策略不生效

现象：Helm 装完，Pod 之间照样随便连。 原因：网络策略靠 CNI 执行，CNI 不支持或未启用 NetworkPolicy 时，策略只是声明。 解决：先确认 CNI 能力，再谈策略；这条官方写在 Kubernetes 文档开头。

坑 6：把它当成「装完就安全」

现象：以为上了 OpenShell 就不用管镜像、依赖与模型。 原因：它管的是运行时访问边界（文件、系统调用、网络、凭据），不管镜像里的漏洞、模型输出质量、业务逻辑错误。 解决：把 OpenShell 当作安全栈的一层，而不是全部。

常见问题 FAQ

Q1：它和 Docker 沙箱有什么区别？

A：Docker 给你隔离的进程与文件系统；OpenShell 在隔离之上加了每条系统调用与网络连接都按策略检查、凭据只在出站时注入、以及策略变更前做形式化验证。它本身还要靠 Docker/Podman/宿主虚拟化来承载沙箱。

Q2：它是 Agent 框架吗？

A：不是。它不提供任务规划、多 Agent 协作或记忆，只负责「Agent 允许碰什么」。编排交给 Hive、CrewAI 或你自己的代码。

Q3：要钱吗？

A：软件 Apache-2.0 免费。成本来自沙箱所在的机器/集群，以及沙箱里跑的模型。

Q4：只能在 Linux 上跑吗？

A：Linux、Apple Silicon 的 macOS、以及 Windows + WSL 2（experimental）都能跑；原生 Windows 走 Microsoft MXC，另有一份指南与限制说明。

Q5：我的数据会被收集吗？

A：默认有匿名 telemetry，范围限于运营类目与计数，官方明确不含沙箱名、主机名、文件路径、prompt、凭据、provider/模型名与用户内容，并且可以关闭或编译掉。是否接受，按你的合规要求判断。

Q6：策略写错了会怎样？

A：两件事分别兜底：advisor 会先告诉你这条改动放开了什么；prover 做形式化验证，把「带凭据访问新主机」「调用新 API 方法」这类有风险的变更标出来等人工审。但最终仍然要人看——它是把错误变得可见，不是替你决策。

成本、权限与安全边界

• 成本：软件免费；GPU/集群资源与模型调用是实际支出。沙箱按任务开、按任务销毁可以显著压低成本。
• 权限：能力上限就是策略。管理员要能写、审、合并策略文件，否则这套东西会退化成「全放开」。
• 凭据：设计目标是 Agent 永远看不到明文凭据；一旦你把 key 塞进环境变量或镜像，这条保证就失效。
• 审计与数据：telemetry 可关；沙箱内的文件与日志仍在你自己的机器/集群上，谁有宿主权限谁就能读。
• 平台成熟度：当前是 0.1.x（官方称已进入稳定发布节奏，并暗示 API 面还会扩展）。生产采用前建议先锁版本、自己跑一轮升级演练（有 0.1.0 升级指南）。

进阶学习建议

1. 先读架构，再读策略：Architecture 讲 gateway / supervisor / sandbox 三者关系——不理解这三层，策略写错时你会不知道是哪一层在拦。
2. 把 Policies 的三块读全：overview（规则种类）+ advisor（改动影响预览）+ prover（形式化验证）。这三页是它区别于普通沙箱的全部所在。
3. 照 first-network-policy 教程 走一遍：这是唯一一条把「策略—拦截—批准」串起来的官方路径。
4. 再看 Providers 与 inference：凭据怎么只在出站注入、推理请求怎么被路由，是做内网落地时最容易写错的部分。
5. 最后看 Extensibility 与 SDK：要把沙箱做成产品能力时，SDK（Python/TypeScript/Go/Rust）比 CLI 更合适。
6. 社区侧：GitHub Discussions 问用法，issues 提 bug，安全漏洞走 SECURITY.md（官方要求不要开公开 issue）；路线图与 RFC 在 NVIDIA 的 project 233 看板上。

免责声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。

未安装 OpenShell，未在任何平台上执行安装脚本，未创建沙箱，未实测内核级策略拦截、形式化验证、provider 凭据注入与 Kubernetes 部署。文中能力、限制与数字均转述自官方 README、官方文档站与 GitHub 公开数据，属官方自述。

参考链接

• 官方仓库 README：定位、工作原理、quickstart、SDK、telemetry、社区
• 官方文档站：架构、策略、providers、gateways、Kubernetes、扩展性
• Run Your First Agent：用 OpenCode 跑通第一个受策略约束的 Agent
• Support Matrix：平台与运行时支持范围
• 0.1.0 升级指南：版本节奏与 API 变化
• Apache-2.0 许可
• GitHub API：stars / forks / 未关闭 issue / 创建与最近推送时间