AI 2026年7月3日 2 分钟阅读

Zerobox 完全指南：给 AI 编码 Agent 的命令执行加上安全沙箱

tinyash 0 条评论

文章信息

发布时间 2026年7月3日
作者 tinyash
阅读时长 2 分钟阅读

当 AI 编码 Agent（Claude Code、Codex、Cursor）在你的终端里自由运行命令时，你真的放心吗？一个 curl 可能泄露 API 密钥，一个 rm -rf 可能清空项目目录，一个 pip install 可能引入恶意依赖。这并非危言耸听——AI Agent 生成代码然后自动执行是现在的主流工作流，但传统的安全边界（Docker 容器、VM）太重了，启动延迟从秒到分钟不等，不适合 Agent 频繁的细粒度命令调用。

Zerobox 正是为解决这个问题而生。它由 OpenAI Codex 的沙箱运行时驱动，是一个轻量级的跨平台进程沙箱工具：拒绝所有文件写入、网络访问和环境变量泄露，除非你明确允许。更重要的是——它在 macOS 和 Linux 上仅需 ~10ms 的额外开销，不需要 Docker 或虚拟机，直接作为单个二进制运行。

安装

Zerobox 提供了多种安装方式，覆盖主流包管理器：

curl -fsSL https://raw.githubusercontent.com/afshinm/zerobox/main/install.sh | sh

npm install -g zerobox

pip install zerobox

cargo install zerobox

安装完成后，运行 zerobox --version 确认版本。

基础用法：零信任沙箱

Zerobox 遵循”默认拒绝”的安全模型。最简单的用法是运行一个不允许任何写入和网络的命令：

zerobox -- node -e "console.log('hello')"

这条命令在一个隔离的环境中执行，脚本只能读取系统库文件，无法写入磁盘、无法联网。

允许写入当前目录：

zerobox --allow-write=. -- node script.js

允许访问特定域名：

zerobox --allow-net=api.openai.com -- node agent.js

--allow-write 和 --allow-net 不带参数时表示”允许所有”——适用于需要完全网络访问但限制文件写入的场景：

zerobox --allow-write=/tmp/output --allow-net -- python3 /tmp/task.py

细粒度权限控制

Zerobox 的权限体系覆盖了沙箱进程的四个维度：

文件系统

标志	作用	默认值
`--allow-read`	限制可读路径	所有读取允许
`--deny-read`	阻止读取路径	—
`--allow-write [paths]`	允许写入路径	所有写入禁止
`--deny-write`	阻止写入路径	—

zerobox --allow-write=./dist --deny-write=./.git -- npm run build

网络

标志	作用	默认值
`--allow-net [domains]`	允许网络目标	所有网络禁止
`--deny-net`	阻止网络目标	—

zerobox --allow-net=api.openai.com -- node agent.js

环境变量

标志	作用	默认值
`--allow-env [keys]`	继承父进程环境变量	仅 PATH, HOME, USER, SHELL, TERM, LANG
`--deny-env`	排除特定变量	—
`--env KEY=VALUE`	设置自定义变量	—

zerobox --allow-env=PATH,DATABASE_URL -- node app.js

zerobox --allow-env --deny-env=AWS_SECRET_ACCESS_KEY -- node app.js

Secrets 凭证管理：API 密钥的零接触方案

这是 Zerobox 最独特的功能。你传入的 API 密钥在沙箱进程内显示为占位符（如 ZEROBOX_SECRET_a1b2c3d4e5），真实值只在网络代理层面为经过授权的目标主机注入。沙箱内的进程永远看不到真实的密钥值。

zerobox \
  --secret OPENAI_API_KEY=$(ADMIN_TOKEN) \
  --secret-host OPENAI_API_KEY=api.openai.com \
  -- node agent.js

工作原理：

沙箱进程读取 $OPENAI_API_KEY
  → 看到的是占位符 ZEROBOX_SECRET_a1b2c3d4e5

沙箱进程 curl https://api.openai.com/...
  → Zerobox 代理拦截请求
  → 将占位符替换为真实密钥
  → OpenAI 收到正常 Authorization 头

可以同时管理多个凭证，每个绑定不同的目标域名：

zerobox \
  --secret OPENAI_API_KEY=$(ADMIN_TOKEN) --secret-host OPENAI_API_KEY=api.openai.com \
  --secret GITHUB_TOKEN=$(GH_TOKEN) --secret-host GITHUB_TOKEN=api.github.com \
  -- node app.js

注意：Node.js 的 fetch 默认不遵循 HTTPS_PROXY 环境变量。在沙箱内运行 Node.js 并使用 secrets 时，需要额外传入 --use-env-proxy 参数。

Snapshot 快照机制：文件系统时光机

Zerobox 可以记录沙箱内进程的文件系统变更，并在完成后选择恢复或保留。这对 CI/CD 和实验性代码执行特别有用。

执行过程中记录变更，完成后自动回滚：

zerobox --restore --allow-write=. -- npm install

只记录不恢复，事后查看和手动回滚：

zerobox --snapshot --allow-write=. -- npm install

zerobox snapshot list

zerobox snapshot diff 

zerobox snapshot restore 

zerobox snapshot clean --older-than=7

性能基准

Zerobox 的单二进制、无虚拟化架构带来了极低的开销。以下是官方在 Apple M5 Pro 上的基准测试（10 次运行最佳值）：

命令	原生	沙箱内	额外开销	原生内存	沙箱内存
`echo hello`	<1ms	10ms	+10ms	1.2 MB	8.4 MB
`node -e '...'`	10ms	20ms	+10ms	39.3 MB	39.1 MB
`python3 -c '...'`	10ms	20ms	+10ms	12.9 MB	13.0 MB
`cat 10MB file`	<1ms	10ms	+10ms	1.9 MB	8.4 MB
`curl https://...`	50ms	60ms	+10ms	7.2 MB	8.4 MB

对几乎所有命令，额外开销稳定在 ~10ms 和 ~7MB 内存。这意味着你可以把每个 AI Agent 的工具调用都包裹在 Zerobox 中，而不影响用户体验。

集成 AI 编码 Agent

Zerobox 提供了完整的 SDK 支持（Rust、TypeScript、Python），可以直接在 Agent 的代码中使用。

TypeScript SDK 示例

import { Sandbox } from 'zerobox'

const sandbox = Sandbox.create({
  allowWrite: ['/tmp/output'],
  allowNet: ['api.openai.com'],
  secrets: {
    OPENAI_API_KEY: {
      value: process.env.OPENAI_API_KEY!,
      hosts: ['api.openai.com']
    }
  }
})

const result = await sandbox.exec('python3', ['/tmp/task.py']).output()
console.log(result.stdout)

Python SDK 示例

from zerobox import Sandbox

sandbox = Sandbox.create({
    "allow_write": ["."],
    "restore": True
})

result = sandbox.sh("npm install").output()
print(result.code)

实战场景

场景 1：AI Agent 生成代码的安全执行

Claude Code 生成了一段 Python 脚本来处理数据，但你担心它可能意外覆盖源文件。用 Zerobox 包裹执行，只允许写入输出目录：

zerobox --allow-write=/tmp/output -- python3 gen_data.py

场景 2：构建时限制网络和文件访问

让构建脚本有完全网络访问，但文件写入限制到 ./dist：

zerobox --allow-write=./dist --allow-net -- npm run build

场景 3：测试时阻止所有网络调用

单元测试不应该有外部依赖。用 Zerobox 确保测试的纯本地性：

zerobox --allow-write=/tmp -- npm test

若测试代码试图联网，Zerobox 会拒绝网络连接并记录日志。

场景 4：AI Agent Secret 注入

配置 Claude Code 或 Codex 在执行敏感操作时，通过 Zerobox 注入 API 密钥而不暴露原文：

zerobox \
  --secret OPENAI_API_KEY=$(ADMIN_TOKEN) \
  --secret-host OPENAI_API_KEY=api.openai.com \
  -- node $(AGENT_SCRIPT)

平台支持

平台	后端技术	状态
macOS	Seatbelt (`sandbox-exec`)	完全支持
Linux	Bubblewrap + Seccomp + Namespaces	完全支持
Windows	Restricted Tokens + ACLs + Firewall	计划中

Linux 上默认使用 Bubblewrap 实现沙箱。如果需要强制使用完整的 Bubblewrap 隔离（不降级），可以传入 --strict-sandbox。

总结

Zerobox 填补了 AI 编码 Agent 安全领域的一个重要空白：在 Docker 太重、裸执行太危险的中间地带，提供了一个 ~10ms 开销的轻量沙箱方案。它的”默认拒绝”安全模型、细粒度的四维权限控制（文件、网络、环境变量、凭证）、以及独特的 proxy-level 密钥注入机制，让 AI Agent 可以安全地运行任何命令而不泄露机密信息。

对于每天使用 Claude Code、Codex 或 Cursor 的开发者来说，Zerobox 是用几行命令就能获得的安全保障——不需要重构工作流，不需要学习复杂的配置语言，一个二进制文件就够。

GitHub: github.com/afshinm/zerobox
npm: npm install -g zerobox
PyPI: pip install zerobox
Cargo: cargo install zerobox
许可证: Apache-2.0

AI AI 安全 AI 工具 AI 编程开发者安全开源教程