关于「AI Agent 执行沙箱」的一套完整资料：概念参考 + 系统教程 + 可运行实验。 最后更新：2026-10-22（第二版 2026-09-23；产品版图与本文件持续修订）
LLM 只能「说」，要真正「做」——跑代码、改文件、装依赖、发请求——就需要一个受控的执行环境，这就是 Agent 沙箱。
一句话：Agent 沙箱 = Agent 的计算机。它既是限制 Agent 的「笼子」，也是让 Agent 能干活的手脚。
本资料包从三个层次讲清楚它：
| 层次 | 目录 | 适合 |
|---|---|---|
| 📄 速查 / 参考 | ai-agent-sandbox.md |
已有概念，想快速查 |
| 📚 系统教程 | agent-sandbox-tutorial/ |
想从零系统学习 |
| 🧪 可运行实验 | agent-sandbox-lab/ |
想动手验证 |
| 🌐 在线文档站 | site/ |
想在浏览器里读 |
在线地址：**https://wurenrumian.github.io/agent-sandbox/**（由
site/构建，Astro + Starlight）
.├── README.md # 本文件：总入口├── ai-agent-sandbox.md # 参考版：10 个主题速查├── agent-sandbox-tutorial/ # 教程版：12 章 + 4 附录│ ├── README.md # 教程导航│ ├── 00-心智模型.md│ ├── 01-定位.md│ ├── 02-为什么需要沙箱.md│ ├── 03-能力清单.md│ ├── 04-架构.md│ ├── 05-隔离后端选型.md│ ├── 06-威胁模型.md│ ├── 07-场景与成本.md│ ├── 08-产品版图.md│ ├── 09-何时不需要沙箱.md│ ├── 10-实战搭建.md│ ├── 11-趋势与延伸.md│ ├── 附录A-速记.md│ ├── 附录B-术语表.md│ ├── 附录C-安全检查清单.md│ └── 附录D-证据与数据源.md└── agent-sandbox-lab/ # 实验版：真实可跑的沙箱 ├── README.md ├── sandbox_run.py # bwrap 沙箱执行包装器 ├── run_all.sh # 一键跑全部实验 ├── RESULTS.md # 实测输出记录 ├── exp/ # 5 个隔离实验 ├── code/sandbox_mcp.py # 把沙箱包成 MCP server └── work/agent_code.py # 模拟「Agent 生成的代码」├── docs/research/ # 调研原文：教程里那些带日期的数字出自这里├── tools/ # 仓库自检：check-links.py、check-stars.py└── site/ # Astro 文档站（部署到 GitHub Pages）只想快速了解 → 读 ai-agent-sandbox.md（约 10 分钟）。
想系统学习 → 从 agent-sandbox-tutorial/00-心智模型.md 开始，按顺序读到第 11 章（全套约 140–170 分钟；每章含导读、原理取舍、代码示例、常见误区与动手练习）。
想动手跑 → 直接进实验目录：
cd agent-sandbox-labchmod +x exp/*.sh run_all.sh sandbox_run.py./run_all.sh | tee RESULTS.md # 跑全部实验./sandbox_run.py 'echo hello; id' # 用沙箱执行任意命令实验不需要 Docker、不需要 root，普通 Linux 用户即可运行（依赖
bwrap+python3）。
根目录提供了 Makefile：
make help # 显示所有命令make lab # 运行全部沙箱实验make check-links # 检查所有 markdown 链接make site-sync # 从仓库 markdown 重新生成站点内容make site-dev # 启动文档站开发服务器make site-build # 构建文档站make clean # 清理实验生成物与缓存按角色的阅读路径
Section titled “按角色的阅读路径”| 你是 | 建议路径 |
|---|---|
| 应用开发者 | 00 → 02 → 03 → 04 → 05 → 10 → 附录C |
| 架构 / 选型 | 00 → 01 → 04 → 05 → 07 → 08 → 09 |
| 安全同学 | 01 → 06 → 附录C → 实验 05 |
| 快速了解 | 参考版 ai-agent-sandbox.md + 附录A |
| 想动手 | 直接跑 agent-sandbox-lab/，再回头看第 10 章 |
核心观点速览
Section titled “核心观点速览”- 沙箱对 Agent 是执行运行时，不只是安全笼子。
- 隔离不是一个强度滑块：先按五类边界定位（microVM / 用户态内核 gVisor / 容器+加固 / OS 系统调用策略 / WASM），再看取 KVM·GPU、syscall 兼容性、内核漏洞面、运维复杂度这四列。bwrap 属于「OS 系统调用策略」，不是「弱隔离」。
- 选型先看场景：四个属性（跑什么 / 跑多久 / 要不要留状态 / 谁在指挥）定下来，再问「账单会被什么撑爆」。
- 头号风险是 prompt injection 导致的数据外泄，不是沙箱逃逸。
- 最重要的三个开关：默认断网、不放长期凭据、短生命周期。
- 判断是否需要沙箱：出现「任意代码 / 任意 shell / 不可信输入驱动执行」就上。
- 选型三问：托管还是自建？隔离要多强？要 GPU 吗？
- 在 Fedora Linux 44 (WSL2) 上实测通过。
- 依赖：
bwrap（bubblewrap）、python3；unshare可选。 - 需要开启非特权 user namespace（
/proc/sys/user/max_user_namespaces > 0）。 - 实测结果见
agent-sandbox-lab/RESULTS.md。