I. 核心架构 - 10. Sandboxing

📍 课程位置

阶段：I. 核心架构
课序：第 10 课
前置知识：I-9. Multi-Agent
后续课程：I-11. Model Failover

---

🎯 本课核心问题（你不懂我就这样教你）

你可能会担心：

1. Agent 运行 exec、读写文件，会不会很危险？
2. 如果有人在群里做 prompt injection，让 Agent 执行破坏命令怎么办？
3. 能不能把 Agent 放进“笼子”里，让它只能在安全范围内操作？

答案是：可以，这就是 Sandboxing（沙箱）。

一句话：

Sandboxing = 让 Agent 的工具执行跑在隔离的容器里（通常是 Docker），把风险控制在可控范围。

---

🧠 先建立心智模型：沙箱是什么

类比：

• 不开沙箱：Agent 像在你电脑“裸奔”执行命令
• 开沙箱：Agent 像在一个“隔离的虚拟工地”里施工
  • 工地里有必要工具
  • 但默认看不到你电脑的隐私文件
  • 网络/目录/权限都可控

---

🧩 Sandboxing 的三个关键维度

1）mode：什么时候启用沙箱

mode	含义	典型用途
off	不启用	单人、全信任环境
non-main	除 main 会话外启用	推荐：对外 DM/群聊更安全
all	所有会话都启用	高安全要求

2）scope：容器复用策略

scope	含义	典型用途
session	每个会话一个容器	隔离最强，开销最大
agent	每个 Agent 一个容器	性能和隔离平衡（常用）
shared	多个会话共享容器	性能最好，隔离最弱

3）workspaceAccess：工作区访问权限

access	含义
none	容器看不到你的 workspace
ro	只读挂载 workspace
rw	可读写挂载 workspace（风险更高）

---

🔐 沙箱能保护你什么？

1）防止“误 exec”伤到主机

如果有人诱导 Agent 执行：

• 删除文件
• 修改配置
• 读取敏感目录

在沙箱里：

• 没挂载的目录根本看不到
• 即使执行 rm，也只影响容器内

2）降低 prompt injection 的破坏面

prompt injection 永远可能发生（尤其群聊）。

沙箱的价值在于：

• 就算被注入，伤害也被限制在容器里

3）让“工具权限”更可信

工具策略（policy）是“逻辑约束”，
沙箱是“物理隔离”。

二者叠加更稳。

---

🔧 实战：如何开启 Sandboxing（推荐配置）

推荐：对外会话启用（non-main）+ 每 Agent 一个容器（agent）

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",   // off | non-main | all
        scope: "agent",     // session | agent | shared
        workspaceAccess: "ro" // none | ro | rw
      }
    }
  }
}

你会得到：

• main 会话（你自己）不进沙箱，方便开发
• 其他会话（外部 DM/群）进沙箱，安全

---

🛠️ 沙箱的前置条件：要有容器镜像

通常需要先准备 sandbox image（里面有必要工具/依赖）。

你可以把它理解成：

• “工地”需要先搭好
• 不然工人进不去

（具体构建方式以官方 sandboxes 文档/脚本为准）

---

⚠️ 常见陷阱

陷阱	表现	原因	解决
沙箱不生效	仍在主机执行	mode=off 或配置没加载	检查配置是否生效、看 logs
工具找不到	exec 报缺命令	镜像里没装依赖	更新 sandbox 镜像
需要写 workspace	写文件失败	workspaceAccess=ro/none	仅对需要写的 Agent 调 rw
网络访问异常	无法 curl/git	网络策略限制	调整沙箱网络配置

---

📝 学习心得

Sandboxing 这章我最大的感受是：

• 工具策略只是“规则”，沙箱才是“隔离”
• 在多用户/群聊环境里，沙箱几乎是必选项
• 最好的做法：Multi-Agent + tools 最小权限 + sandbox

这三件套能显著降低“乱搞导致系统崩溃”的概率。

---

✅ 本课总结（记住 4 点）

1. Sandboxing 把 Agent 放进容器里，限制破坏范围。
2. mode 决定什么时候启用，scope 决定隔离强度/性能。
3. workspaceAccess 决定容器能否读写你的工作目录。
4. 推荐：non-main + agent + ro，安全和体验最平衡。

---

🔗 相关资源

• 官方 Sandboxing：https://docs.openclaw.ai/gateway/sandboxing
• 配置参考（sandbox）：https://docs.openclaw.ai/gateway/configuration-reference

下一课：I-11. Model Failover（模型/认证失败时如何自动降级）