教程导航
一套从「概念」到「动手搭建」的 Agent 沙箱教程。 12 章 + 4 附录，每章都能单独阅读。最后更新：2026-10-22（第三版：新增「场景与成本」章与「证据与数据源」附录）
这套教程讲什么
Section titled “这套教程讲什么”Agent 沙箱 = Agent 的计算机。它既是限制 Agent 的「笼子」，也是让 Agent 真正能「做事」的手脚。
本教程把这件事拆成 12 章 + 4 个附录，从心智模型一路讲到可运行的沙箱实现。
每一章都包含：
- 本章导读：这一章要回答什么问题、预计读多久；
- 原理与取舍：不只给结论，还讲「为什么」和「不这样做的后果」；
- 具体例子 / 代码：表格、图示、可直接运行或改写的最小示例；
- 常见误区：容易踩的坑；
- 动手练习：把抽象概念落到你自己的系统上。
- 做 AI Agent / LLM 应用，需要让模型真正「跑代码、动文件」的开发者
- 想搞清楚 E2B、Daytona、Modal 这类产品到底在解决什么的人
- 关心 Agent 安全（prompt injection、数据外泄）的工程 / 安全同学
不需要沙箱基础。只需要：
- 基本了解什么是 LLM / Agent / 工具调用
- 会一点命令行（读得懂
docker run、sh即可） - 想做实验的话：Linux 环境 +
bwrap+python3
读完你能做到
Section titled “读完你能做到”- 说清楚沙箱在 Agent 架构里的位置
- 根据场景选对隔离后端
- 用 bwrap / Docker 搭一个「默认断网」的最小沙箱
- 识别并防住 Agent 特有的安全风险
| 目标 | 时间 |
|---|---|
| 通读一遍 | 约 120–150 分钟 |
| 只读核心（00/01/02/05/06/09） | 约 80 分钟 |
| 加上动手实验 | 再 +40 分钟 |
| 章节 | 内容 | 你会得到 |
|---|---|---|
| 00 心智模型 | 先建立正确的心智模型 | 修正「沙箱 = 牢房」的误解；说清赋能与约束、沙箱与容器/VM 的区别 |
| 01 定位 | 从「防御机制」到「Agent 的手脚」 | 可写进设计文档的定义；明确沙箱不负责什么 |
| 02 为什么需要沙箱 | Agent 的六个刚需 | 一个多步任务的逐步拆解；三个 Agent 独有变量 |
| 03 能力清单 | 一个沙箱应提供的能力 | 最小接口集合、P0–P2 优先级、每项的坑与做法 |
| 04 架构 | 控制面与数据面，以及状态与生命周期机制 | 职责拆解、完整时序、快照与分叉、pause / resume、出网控制三段、凭据保险箱、编排与接入、反模式清单 |
| 05 隔离后端选型 | 五类隔离边界 + 四个配套机制 | 两层结构、五类边界逐档拆解、横向对照表、两条升级路径（强度 / 形态）、决策树 |
| 06 威胁模型 | Prompt Injection 与数据外泄 | 两类注入、STRIDE、纵深防御链、白名单代理设计 |
| 07 场景与成本 | 场景 → 硬需求 → 主导成本 | 描述场景的四个属性、两个架构分叉、九个场景骨架、场景→成本矩阵、场景→开源首选 |
| 08 产品版图 | 托管与自建选项、开源项目盘点 | 八类产品分类、1k+ stars 开源清单（含快照日期）、两个别踩的坑、评估产品的 8 个问题、选型三问、自建 vs 托管 |
| 09 何时不需要沙箱 | 避免过度设计 | 决策树、L0–L3 分级、过度设计的代价 |
| 10 实战搭建 | bwrap 沙箱 → Docker → MCP 工具 | 可运行步骤、参数对照、防目录穿越的 MCP 封装 |
| 11 趋势与延伸 | 沙箱要往哪走 | 五个趋势、八条延伸轴、按角色的下一步 |
| 附录 A 速记 | 核心结论 | 分主题的一句话版本 + 30 秒决策流 |
| 附录 B 术语表 | 术语解释 | 按主题分组的 40+ 术语，含「为什么重要」 |
| 附录 C 安全检查清单 | 上线前逐条核对 | 带红线的清单 + 最小可执行配置 |
| 附录 D 证据与数据源 | 每个易腐数字的出处与复查方法 | 快照声明、30 秒自查命令、来源等级表、未做实测的声明、已知薄弱处 |
00 心智模型 ─► 01 定位 ─► 02 为什么 ─► 03 能力 ─► 04 架构 ─► 05 选型 ─► 06 威胁模型 ─► 07 场景与成本 ─► 08 产品版图 ─► 09 何时不需要 ─► 10 实战搭建 ─► 11 趋势与延伸按角色选路径：
| 你是 | 建议顺序 |
|---|---|
| 应用开发者 | 00 → 02 → 03 → 04 → 05 → 10 → 附录C |
| 架构 / 选型 | 00 → 01 → 04 → 05 → 07 → 08 → 09 |
| 安全同学 | 01 → 06 → 附录C |
| 快速了解 | 00 → 01 → 06 → 附录A |
如何使用本教程
Section titled “如何使用本教程”- 顺序读：每章末尾都有「动手练习」，建议至少做一遍，把抽象概念落到你自己的系统上。
- 跳读：每章开头有「本章导读」，结尾有上一章 / 下一章导航，可按角色路径跳读。
- 动手：第 10 章配了可运行的实验，代码在
../agent-sandbox-lab/。
配套代码与实验（含实测记录）：
cd ../agent-sandbox-lab./run_all.sh | tee RESULTS.md./sandbox_run.py 'python3 /work/agent_code.py'| 日期 | 变更 |
|---|---|
| 2026-09-23 | 初版：11 章 + 3 附录，配套 bwrap 实验 |
| 2026-09-23 | 第二版：全部章节系统性加厚——新增本章导读、原理与取舍、代码示例、常见误区、小结；附录 A/B/C 扩充为分主题速记、40+ 术语、带红线的检查清单 |
| 2026-10-22 | 第三版：修订 08 产品版图（Daytona 归档并入「坑」、新增 1k+ stars 开源盘点与 30 秒自查命令） |
| 2026-10-22 | 第三版：新增 07 场景与成本 与 附录 D 证据与数据源；04 加厚「状态与生命周期机制」；05 重构为「五类隔离边界 + 四个配套机制」；原 07–10 顺移为 08–11 |
| 2026-10-22 | 04 补 4.11 编排与接入，四个配套机制至此在机制层（第 4 章）与选型层（第 5 章 5.7）各有落点；索引一致性检查纳入 tools/check_links.py |
| 2026-10-22 | 08 的 8.1 补上「8.2.3 编排层 / 8.2.4 底座与执行引擎」两组的入口（8.1 只按交付形态分八类，这两组在另一个轴上，原先扫 8.1 看不见）；8 章常见误区补「把编排层当沙箱产品比价」 |