跳到主要内容
中文
← 工具
工具 · 代码仓库

让 AI 在沙箱里干活,权限由你掌控

让 AI 在沙箱里工作,明确它能读写哪些文件、访问哪些网络。NVIDIA OpenShell 在 Agent 外部执行权限策略,将凭据用于配置允许的端点,并让你决定是否批准新增网络访问。

@NVIDIA NVIDIA OpenShell
  • 智能体权限管理
  • AI 智能体
  • 沙箱

前置要求

  • Docker Desktop / Docker Engine >= 28.0
  • Git
  • OPENROUTER_API_KEY

概览

你会得到什么

  • 通过文件、网络和进程策略约束 Agent 的沙箱运行环境。
  • 仅在配置授权的端点使用模型服务等外部服务的凭据。
  • 沙箱运行期间可查看、批准或拒绝的新增网络访问建议。

适用场景

  • 运行编程 Agent,明确项目文件和外部服务的访问范围。
  • 将访问策略纳入版本管理,查看被拒绝的请求。

教程

先看懂它能管什么

让 AI 改代码,通常也要允许它读文件、运行命令和联网。OpenShell 把 Agent 放进独立沙箱,再由运行时执行访问策略,让权限范围落实到实际请求上。

你关心什么OpenShell 怎样控制
AI 能读写哪些文件文件策略限定沙箱内允许访问的路径
AI 能访问哪些服务网络规则限定目标地址、调用程序及可用请求
模型 API Key 怎样使用Provider 保存凭据,按配置在授权端点使用

接下来用 OpenCode 和 OpenRouter 跑通一个例子:让 AI 为小项目编写 README,再学习如何处理被拦截的联网请求。文件和进程策略在创建沙箱时确定;网络规则可在运行期间更新。

跑通第一个 AI 沙箱

准备本地环境

本教程使用 OpenShell 0.1.5 + Docker。准备 Git、运行中的 Docker Desktop 或 Docker Engine 28.0+,以及 OpenRouter API Key。

支持的平台包括 Linux x86_64 / arm64、Apple Silicon Mac;Windows 的 WSL 2 + Docker Desktop 路线为实验性支持。Linux 沙箱需要启用 Landlock ABI 3(通常为 Linux 6.2+),以及所需的 seccomp 能力;完整条件见官方支持矩阵。

  1. 在宿主机终端安装并检查连接:

    curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/v0.1.5/install.sh | OPENSHELL_VERSION=v0.1.5 sh
    openshell status

    安装器安装 CLI、策略检查器和本地网关。status 应能返回网关状态;连接失败时,先按安装文档检查网关服务。

  2. 配置模型服务。OpenRouter 是本例的模型 API 服务;Provider 是 OpenShell 保存其凭据与访问配置的对象。在同一个宿主机终端执行,先替换 API Key:

    export OPENROUTER_API_KEY='替换为你的 OpenRouter API Key'
    
    # 导入 OpenCode 访问 OpenRouter 的配置
    openshell profile import \
      --url https://raw.githubusercontent.com/NVIDIA/OpenShell/v0.1.5/providers/openrouter.yaml
    
    # 从当前环境读取 API Key,创建名为 openrouter 的 Provider
    openshell provider create --name openrouter --type openrouter --from-existing

    该配置允许镜像中的 /usr/local/bin/opencode 访问 openrouter.ai。创建 Provider 成功后,下一步用名称 openrouter 将它附加到沙箱。

启动 OpenCode

在宿主机终端 A 中执行:

openshell sandbox create \
  --name my-agent \
  --from ghcr.io/anomalyco/opencode:latest \
  --provider openrouter \
  -- opencode -m openrouter/nvidia/nemotron-3.5-lightning:free

这采用官方首个 Agent 示例的镜像和模型路线。启动后应看到 OpenCode 界面;保持这个终端打开,后面在这里给 AI 发任务。官方例子使用 OpenRouter 的免费模型,模型列表可用镜像内的 opencode models openrouter 查看。

--from 选择装有 Agent 的镜像。默认 Ubuntu 镜像只提供基础系统,运行 OpenCode 要使用上面的 OpenCode 镜像。

让 AI 完成一个小任务

传入示例项目

  1. 在宿主机另开终端 B,创建一个独立的小项目:

    mkdir greeting-demo
    cd greeting-demo
    git init
    cat > main.py <<'PY'
    def greet(name):
        return f"Hello, {name}!"
    
    if __name__ == "__main__":
        print(greet("Ada"))
    PY
    cd ..
  2. 仍在终端 B,将目录传入正在运行的沙箱:

    openshell sandbox upload my-agent ./greeting-demo

    未指定目标路径时,上传位置是沙箱工作目录,目录名 greeting-demo 会保留。这里先启动沙箱再上传,避免 AI 在文件传完之前就开始读取。

编写并取回 README

  1. 回到终端 A 的 OpenCode 界面,发送下面的任务。这是本站为教学编写的练习请求:

    读取当前工作目录下 greeting-demo/main.py。
    在 greeting-demo/README.md 中说明程序用途、函数输入与输出、运行方式及预期输出。
    根据源码说明即可,不安装依赖,不修改 main.py。
    完成后列出新增的文件。
  2. AI 完成后,在宿主机终端 B 中取回并查看文件:

    openshell sandbox download my-agent greeting-demo/README.md ./greeting-demo/README.md
    cat ./greeting-demo/README.md

    README 应说明 greet(name) 返回问候语,直接运行程序时打印 Hello, Ada!。核对说明与源码是否一致,比只看“任务完成”更有用。

遇到联网拦截,按需放行

以后给 Agent 增加查文档、下载依赖等任务时,可能遇到新地址被拒绝。OpenShell 会记录拒绝,并为新增访问生成规则建议。

  1. 在宿主机终端 B 中查看日志和待批准建议:

    openshell logs my-agent --since 5m --source sandbox
    openshell rule get my-agent --status pending

    关注目标域名、端口和发起请求的程序。前面的 README 任务不需要联网,列表为空时可以直接进入下一节。

  2. 若有与当前任务相符的建议,将下面的 <chunk-id> 替换为列表中的实际 ID,再批准:

    openshell rule approve my-agent --chunk-id <chunk-id>

    不需要的访问则用拒绝命令,填写实际理由:

    openshell rule reject my-agent --chunk-id <chunk-id> --reason "当前任务不需要此访问"
  3. 批准后回到 OpenCode,让 AI 重试刚才被拦截的操作。网络规则会在运行期间生效,无需重启沙箱。

这里学到的判断是:根据任务批准具体访问,而不是遇到报错就扩大整个沙箱的联网范围。

只允许读取,拦截写入

只允许访问某个域名还不够细时,可以进一步区分读取与写入。下面用一个独立的 curl 沙箱观察变化,沿用官方网络策略教程的规则写法。

准备带 curl 的镜像

在宿主机终端 B 中执行:

mkdir openshell-policy-demo
cd openshell-policy-demo
cat > Dockerfile <<'DOCKER'
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \
    && rm -rf /var/lib/apt/lists/*
RUN mkdir -p /workspace && chown 1000:1000 /workspace
USER 1000:1000
WORKDIR /workspace
DOCKER
docker build -t openshell-curl-demo:local .
openshell sandbox create --name api-demo --from openshell-curl-demo:local --no-auto-providers

Docker 在构建时安装 curl;沙箱创建后使用已准备好的镜像。命令结束后,终端 B 会进入 api-demo 沙箱终端,保持它打开。

先观察拒绝,再允许读取

  1. 在终端 B 的沙箱内请求 GitHub API:

    curl -sS https://api.github.com/zen

    在新本地网关的默认网络策略下,这个地址尚未获准,请求应被拦截。

  2. 另开宿主机终端 C,只允许 /usr/bin/curl 读取这个服务:

    openshell policy update api-demo \
      --rule-name github_api \
      --binary /usr/bin/curl \
      --add-endpoint api.github.com:443:read-only:rest:enforce \
      --wait

    read-only 允许 GET、HEAD、OPTIONS;rest 检查 HTTP 请求;enforce 拦截不符合规则的请求。这条命令只修改网络规则。

  3. 回到终端 B 的沙箱内,比较同一地址的 GET 和 POST:

    curl -sS https://api.github.com/zen
    curl -sS -X POST https://api.github.com/zen

    GET 应返回一句文本;POST 应被 OpenShell 拒绝,响应中包含 policy_denied。这样就能看到“允许连接”和“允许写入”是两层不同的控制。

  4. 在宿主机终端 C 中查看刚才的规则与拒绝记录:

    openshell policy get api-demo --full
    openshell logs api-demo --since 5m --source sandbox

    日志应能定位发起程序、目标地址和被拒绝的请求方法。如果首个请求已经成功,先查看完整策略中是否已有允许规则,再比较更新前后的访问范围。

换成自己的项目

迁移时按这四处调整:

替换什么根据什么决定
上传目录选本次任务需要的项目;Git 仓库上传默认遵循 .gitignore
Agent 镜像镜像中必须已有 Agent 和所需工具,使用明确的镜像引用
Provider按模型服务配置凭据、端点和镜像内的实际程序路径
网络规则按任务需要的服务和读取/写入范围开放

将下面方括号替换后发给沙箱内的 Agent:

项目位于 [沙箱工作目录下的项目路径]。
目标是 [本次希望完成的改动]。
可以修改 [文件范围],保留 [不需要改动的内容]。
需要查阅或调用的服务是 [域名及用途]。
先读取已有文件,说明实施步骤,再完成改动并给出检查结果与产物路径。

这是本站提供的需求模板。文件限制还需在创建沙箱时用策略落实;请求文字用于表达任务,不会自动成为 OpenShell 权限规则。自定义策略见策略文档。

取回所需产物后,在宿主机终端删除本次练习沙箱:

openshell sandbox delete api-demo
openshell sandbox delete my-agent

如果你还创建了概览用法里的 demo,也可用 openshell sandbox delete demo 删除。