NVIDIA OpenShell 教程：免费沙箱隔离 AI Agent，保护 API Key

你的 AI Agent 可以读取文件、运行命令、使用你的 API 密钥。如果它被恶意指令诱导，或者自己跑偏了，损失由谁承担？英伟达给出的答案是：把它装进一个盒子，由你决定它具体能碰什么。这就是 OpenShell——一个免费开源的 Agent 沙箱，发布当天在 GitHub 上收获近千颗星，项目累计已超过 1 万 Star。

本文基于 B 站 UP 主的实操教程整理，从零开始搭建的每一步都经过真机验证，同时补充架构层面的分析，帮助你理解这套方案为什么值得关注。

OpenShell 是什么：运行时而非 Agent

OpenShell 的定位需要先说清楚：它是一个运行时，不是 Agent。你自带 Agent——OpenCode、Claude Code 或者你自己的脚本——打包进容器镜像，OpenShell 在沙箱里运行它，并对它打开的每个文件、发起的每一次系统调用、尝试的每一个网络连接强制执行策略。

项目用 Rust 编写，当前是 1.2 版本（两天前发布），属于一个「修修补补的 2.0 版本」。它与英伟达同期推出的「开放智能体安全平台」配套：OpenShell 是其中的软件部分，另一半是用于英伟达自家网络芯片的硬件看门狗。沙箱部分对所有人免费，这也是本教程要安装的东西。

从架构上看，这套系统分为三层：

• 网关（Gateway）：控制平面，负责策略分发与状态管理
• 监督程序（Supervisor）：位于沙箱之外，根据你的策略检查每一个连接
• 沙箱本身：Agent 所在的地方，Agent 从不直接与互联网通信

这个分层设计的关键在于「监督程序在沙箱外」。Agent 即使被完全攻陷，也无法篡改检查自己行为的那个组件。

安装前必读：支持矩阵与硬性前提

OpenShell 对运行环境有明确要求，而且不会悄悄降级运行——内核不支持就直接拒绝启动沙箱。

• 操作系统：Linux，或搭载 Apple Silicon 的 Mac，或通过 WSL2 运行的 Windows（Windows 标记为实验性支持）
• Docker 28 或更高版本
• Linux 内核 6.2 或更高版本，因为沙箱依赖名为 Landlock 的内核特性

安装脚本按平台分发：Ubuntu/Debian 获取 Debian 包并校验校验和，Fedora 使用 RPM 包，Mac 通过 Homebrew 安装并将网关作为 Homebrew 服务运行。各版本发布在 Releases 页面，包含软件包、独立二进制文件和校验和。体积方面，Linux 上的静态命令行工具约 10 MB，完整 Debian 包约 74 MB。

UP 主在 Windows 上的做法是直接把静态二进制文件下载到 WSL2 里，解压后运行即可。但这种「只下二进制」的方式会导致命令行显示网关未配置——因为完整包安装程序才会帮你注册网关。这是新手容易踩的第一个坑。

Landlock 是 Linux 内核 5.13 首次引入的非特权沙箱机制，到 6.2 才具备完整的网络与文件系统访问控制能力，这也是 OpenShell 把内核下限设在这里的直接原因。它允许一个进程在运行中主动声明「我此后只访问这些路径、只连接这些端口」，并由内核强制执行这一自我约束——即使进程之后被完全控制，也无法突破它已经声明的边界。与 Docker 默认依赖的 namespace 和 cgroups 不同，Landlock 不要求 root 权限，也不依赖容器编排层，因此可以在容器内部再叠加一层纵深防御。理解这一点就能明白 OpenShell 为何在检测到内核不支持时选择直接拒绝启动而非降级：缺少 Landlock 意味着监督程序之外的那道内核级防线不存在，静默降级会给出虚假的安全感。

从零搭建：八步跑通第一个沙箱 Agent

第一步：检查版本

确认内核版本、Docker 版本和 curl 可用。UP 主的笔记本在 WSL2 里内核版本远超 6.2，这一项顺利通过。

第二步：运行安装脚本

从官方仓库运行安装脚本，它会获取对应平台的软件包、校验校验和、完成安装，并将网关作为用户服务启动。

第三步：确认命令行与网关的连接

运行状态检查命令，Doctor 命令会逐项检查前置条件。UP 主在这里遇到 Docker 检查失败——原因是 Windows 上的 Docker Desktop 需要与 WSL 发行版共享。在 Docker Desktop 设置里为 Ubuntu 发行版开启 WSL 集成后，检查通过。这是 Windows 上最常见的坑，建议开始之前就处理好。

Linux 上网关作为 System 用户服务运行在端口 176070，文档提供了重启和日志命令；如果希望退出登录后继续运行，需要启用 Linger。

第四步：创建第一个沙箱

执行 openshell sandbox create 并命名为 demo，你会进入一个精简版 Ubuntu 镜像的 Shell，里面没有安装任何 Agent。这是一个可以安全探索的地方——默认情况下什么都不会泄露出去。

第五步：准备 OpenRouter 密钥

官方教程使用 OpenCode 搭配 OpenRouter 上的免费模型。注册 OpenRouter 账号并创建 API 密钥即可，免费模型不需要任何积分。

第六步：导入提供商配置

这一步值得细看配置文件实际写了什么：它只允许一个程序（OpenCode 二进制文件）与一个主机（OpenRouter API）通信。OpenShell 把密钥保存在自己的凭据存储中，Agent 根本看不到它——密钥只会被添加到发往那个已批准主机的请求中。

这是整套设计里最有价值的细节之一。传统做法是把密钥作为环境变量注入 Agent 进程，一旦 Agent 被诱导执行任意代码，密钥就暴露了。而 OpenShell 把密钥持有权上移到沙箱外的监督层，Agent 拿到的只是一个「被允许发请求」的通道。

凭据存储（credentials store）是 OpenShell 与「环境变量注入」最本质的分歧点。在传统模式里，API Key 作为进程环境变量存在，任何能读取 /proc/self/environ、打印环境变量或执行任意代码的 Agent 都能把它取走，且一旦取走就永久有效。OpenShell 的做法是把密钥托管在监督程序一侧的存储中，Agent 进程内根本不存在这个值；当 Agent 发起请求时，监督程序先按策略判定「该二进制是否有权访问该主机」，通过后才在转发瞬间把密钥附加到请求头上。由此形成两个结果：一是密钥从不进入沙箱的可寻址内存，提示注入无法直接窃取；二是密钥的使用被绑定到具体的主机和具体的程序，即使被泄露其作用范围也已被策略限定。

第七步：启动 Agent

创建沙箱并命名为 my-agent，拉取 OpenCode 镜像、挂载提供商，然后在英伟达的免费模型上启动 OpenCode。此时你就有了一个真正运行在沙箱里的编码 Agent。

第八步：处理待批准规则

新规则不会自动生效，需要列出待处理规则，批准你真正想要的那些。

策略实战：从全部拒绝到精细放行

官方有一个五分钟策略教程，演示了完整的放行流程。全新的沙箱什么都访问不了，向 GitHub API 发一个简单请求会被返回 403。每次拒绝都会被记录，包括尝试的动作和目标主机。

然后添加一条规则，允许 curl 读取 GitHub API——只读。同样的请求就能通过。但 POST 请求（比如创建 issue）仍然会被拦截，因为监督程序检查的是 HTTP 方法，而不只是主机名。

规则不需要重启即可生效，会实时重新加载。UP 主最喜欢的功能是：当 Agent 被拦截时，策略顾问会为它起草一条精细的规则，然后由你批准，或者先检查那条规则新允许了什么——比如是否会把凭证发送到新主机——再决定是否放行。这种「AI 提议、人类审批」的交互，把策略配置的门槛降到了普通用户可接受的程度。

几个必须知道的坑

• 默认镜像是空的：真正的工作是构建一个镜像，把你的 Agent 放进去
• 提供商配置写死了二进制路径：需要复制并编辑，不要盲目导入
• 网关默认发送匿名使用统计：一个环境变量就能关掉
• 项目迭代很快：四天发了三个版本，在任何自动化中都要固定版本号

为什么「把护栏放在 Agent 外面」是对的设计

UP 主的判断值得展开：这比信任 Agent 自己的权限提示要好。原因不复杂——Agent 的权限提示运行在 Agent 进程内，被提示注入攻破的 Agent 可以绕过自己的提示；而 OpenShell 的监督程序在沙箱外，Agent 无从触碰。这是操作系统安全里「引用监控机」思想的现代复刻：所有访问必须经过一个不可绕过的检查点。

从生态角度看，英伟达把沙箱免费开放、只把硬件看门狗留给自家芯片，是一个聪明的策略：用开源软件层建立 Agent 安全的事实标准，硬件层再变现。对于使用者来说，这意味着现在就可以免费拿到一套设计严谨的隔离方案。

如果你用 Linux，这周就可以试试 OpenRouter 的示例；Windows 上它能在 WSL2 里跑，但仍是实验性支持，先别用在生产环境。

「引用监控机」（Reference Monitor）是操作系统安全领域的经典概念，由 Anderson 在 1972 年的一份技术报告中提出，用以描述系统中那个「所有主体对客体的访问都必须经过、且自身不可被绕过」的抽象检查点。它需要同时满足三个性质：必须被调用（任何访问都无法跳过它）、足够小可验证（攻击面小到能被严格审计）、中介有效（其判定逻辑受保护，主体无法篡改）。OpenShell 把监督程序置于沙箱进程之外，正是让这三个性质同时成立的工程手段——Agent 的代码再复杂、再被污染，也运行在被检查的那一侧，而检查逻辑本身不在它的可写范围之内。这也是它与 Agent 内置权限提示的根本分野：后者本质上是「由被监管者自己执行监管」，在提示注入面前不具备任何强制性。