## 沙箱是什么
沙箱（Sandbox）是 OpenClaw 的安全隔离机制。它使用 Docker 容器为智能体创建一个独立的执行环境——智能体在容器内运行命令、读写文件，即使出了问题也不会影响宿主机。
你可以把沙箱想象成一个"安全房间"：
- 智能体在房间里可以自由操作
- 房间外的系统文件、网络资源受到保护
- 即使智能体执行了危险命令，影响范围也被限制在容器内
- 容器销毁后，所有改动都会消失（除非配置了持久化）
## 沙箱 vs 工具策略 vs 提权
OpenClaw 有三种安全控制机制，它们解决不同层面的问题：
| 机制 | 控制什么 | 类比 |
|------|----------|------|
| 沙箱（Sandbox） | 执行环境在哪里运行 | 把人关在安全屋里 |
| 工具策略（Tools Allow/Deny） | 能使用哪些工具 | 决定给不给人工具 |
| 提权（Elevated） | 工具的权限级别 | 给的工具是普通版还是高级版 |
### 沙箱（Sandbox）
沙箱限制的是**执行环境**。开启沙箱后，智能体的 `exec`（命令执行）和文件操作都在 Docker 容器内进行，与宿主机隔离。
```json
{
"sandbox": {
"mode": "all"
}
}
```
效果：
- ✅ 智能体可以执行命令，但在容器内
- ✅ 智能体可以读写文件，但在容器的文件系统内
- ✅ 宿主机的文件和系统不受影响
### 工具策略（Tools Allow/Deny）
工具策略限制的是**可用工具**。通过 `allow` 和 `deny` 列表控制智能体能使用哪些工具。
```json
{
"tools": {
"allow": ["read", "write", "web_search"],
"deny": ["exec", "browser"]
}
}
```
效果：
- ✅ 智能体可以读写文件、搜索网页
- ❌ 智能体不能执行命令、不能使用浏览器
### 提权（Elevated）
提权控制的是**工具的权限级别**。某些工具有普通模式和提权模式，提权后可以执行更多操作。
```json
{
"tools": {
"elevated": true
}
}
```
效果：
- 普通模式：`exec` 工具只能执行白名单内的命令
- 提权模式：`exec` 工具可以执行任意命令
### 三者如何配合
最安全的配置是三者组合使用：
```json
{
"sandbox": {
"mode": "all"
},
"tools": {
"allow": ["exec", "read", "write"],
"deny": ["browser"]
}
}
```
这个配置的含义：
1. 智能体可以使用 exec、read、write 工具（工具策略）
2. 但所有操作都在 Docker 容器内执行（沙箱）
3. 不能使用浏览器工具（工具策略）
## 启用沙箱配置
### 前提条件
沙箱依赖 Docker，确保你的系统已安装 Docker：
```bash
# 检查 Docker 是否安装
docker --version
# 检查 Docker 是否在运行
docker info
```
如果未安装 Docker：
```bash
# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# macOS
brew install --cask docker
```
### sandbox.mode 配置
编辑 `~/.openclaw/openclaw.json`，添加沙箱配置：
```json
{
"sandbox": {
"mode": "off"
}
}
```
`mode` 有三个可选值：
| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `off` | 关闭沙箱（默认） | 个人使用，信任所有技能 |
| `all` | 所有操作都在沙箱内 | 生产环境，最高安全级别 |
| `untrusted` | 仅不受信任的技能在沙箱内 | 平衡安全和便利 |
### 模式详解
#### off — 关闭沙箱
```json
{
"sandbox": {
"mode": "off"
}
}
```
所有操作直接在宿主机上执行。适合个人开发环境，你完全信任所有安装的技能。
#### all — 全部沙箱化
```json
{
"sandbox": {
"mode": "all"
}
}
```
所有命令执行和文件操作都在 Docker 容器内进行。这是最安全的模式，推荐在以下场景使用：
- 生产环境
- 多用户共享的 Gateway
- 运行来源不明的技能
#### untrusted — 仅隔离不受信任的技能
```json
{
"sandbox": {
"mode": "untrusted"
}
}
```
只有标记为"不受信任"的技能会在沙箱内运行，其他操作直接在宿主机上执行。这是安全和便利的折中方案。
## 按智能体配置沙箱
如果你运行多个智能体，可以为每个智能体设置不同的沙箱策略：
```json
{
"agents": {
"list": [
{
"id": "trusted-coder",
"sandbox": {
"mode": "off"
}
},
{
"id": "public-assistant",
"sandbox": {
"mode": "all"
}
},
{
"id": "skill-tester",
"sandbox": {
"mode": "untrusted"
}
}
]
}
}
```
这个配置的含义：
- `trusted-coder`：你自己使用的编程助手，关闭沙箱以获得最大灵活性
- `public-assistant`：对外提供服务的助手，全部沙箱化保证安全
- `skill-tester`：用于测试新技能的智能体，仅隔离不受信任的技能
## 沙箱内安装依赖
沙箱容器是一个干净的环境，可能缺少你需要的工具和依赖。使用 `setupCommand` 可以在容器创建后自动安装依赖。
### setupCommand 配置
```json
{
"sandbox": {
"mode": "all",
"setupCommand": "apt-get update && apt-get install -y python3 pip git && pip install requests"
}
}
```
`setupCommand` 的特点：
- 在容器**创建后**运行一次
- 安装的依赖在容器生命周期内持续有效
- 容器销毁后需要重新安装
### 常见 setupCommand 示例
安装 Python 环境：
```json
{
"sandbox": {
"setupCommand": "apt-get update && apt-get install -y python3 python3-pip && pip3 install requests beautifulsoup4"
}
}
```
安装 Node.js 工具：
```json
{
"sandbox": {
"setupCommand": "apt-get update && apt-get install -y nodejs npm && npm install -g tsx typescript"
}
}
```
安装多种工具：
```json
{
"sandbox": {
"setupCommand": "apt-get update && apt-get install -y curl wget jq git python3 python3-pip && pip3 install pyyaml"
}
}
```
### 按智能体配置 setupCommand
不同智能体可能需要不同的依赖：
```json
{
"agents": {
"list": [
{
"id": "python-agent",
"sandbox": {
"mode": "all",
"setupCommand": "pip3 install pandas numpy matplotlib"
}
},
{
"id": "web-agent",
"sandbox": {
"mode": "all",
"setupCommand": "apt-get update && apt-get install -y chromium-browser"
}
}
]
}
}
```
## 网络和文件系统限制
沙箱不仅隔离了执行环境，还可以限制网络访问和文件系统权限。
### 网络限制
默认情况下，沙箱容器可以访问外部网络。如果你想限制网络访问：
```json
{
"sandbox": {
"mode": "all",
"network": "none"
}
}
```
网络模式选项：
| 模式 | 说明 |
|------|------|
| `bridge`（默认） | 容器可以访问外部网络 |
| `none` | 完全禁止网络访问 |
| `host` | 使用宿主机网络（不推荐，降低隔离性） |
### 文件系统限制
沙箱容器有自己独立的文件系统。默认情况下，容器内的文件改动在容器销毁后会丢失。
如果需要持久化某些目录，可以配置挂载：
```json
{
"sandbox": {
"mode": "all",
"mounts": [
{
"source": "/home/user/data",
"target": "/data",
"readonly": false
},
{
"source": "/home/user/config",
"target": "/config",
"readonly": true
}
]
}
}
```
⚠️ 挂载目录会打破沙箱的隔离性。只挂载必要的目录，并尽量使用 `readonly: true`。
### 资源限制
可以限制容器使用的系统资源：
```json
{
"sandbox": {
"mode": "all",
"resources": {
"memory": "512m",
"cpus": "1.0"
}
}
}
```
这可以防止智能体执行的命令消耗过多系统资源。
## 何时该用沙箱
### 推荐使用沙箱的场景
**运行不受信任的技能**
从 ClawHub 安装的第三方技能可能包含未知的命令执行逻辑。沙箱可以限制这些技能的影响范围：
```json
{
"sandbox": {
"mode": "untrusted"
}
}
```
**多用户共享 Gateway**
当多个用户共享同一个 Gateway 时，沙箱可以防止一个用户的操作影响其他用户：
```json
{
"sandbox": {
"mode": "all"
}
}
```
**生产环境**
在生产服务器上运行 OpenClaw 时，沙箱是必要的安全措施：
```json
{
"sandbox": {
"mode": "all",
"network": "none",
"resources": {
"memory": "1g",
"cpus": "2.0"
}
}
}
```
**测试新技能**
在安装和测试新技能时，使用沙箱可以安全地评估技能的行为：
```json
{
"agents": {
"list": [
{
"id": "skill-tester",
"sandbox": {
"mode": "all"
}
}
]
}
}
```
### 不需要沙箱的场景
- **个人开发环境**：你完全信任所有安装的技能，且只有你自己使用
- **只使用内置工具**：不运行第三方技能，只使用 OpenClaw 内置的工具
- **Docker 不可用**：某些环境（如某些 VPS、CI/CD）可能无法运行 Docker
## 沙箱排查
### 检查 Docker 状态
```bash
# Docker 是否在运行
docker info
# 查看沙箱容器
docker ps | grep openclaw
# 查看容器日志
docker logs
```
### 常见问题
**问题：沙箱启动失败**
```bash
# 检查 Docker 权限
docker run hello-world
# 如果权限不足
sudo usermod -aG docker $USER
# 重新登录后生效
```
**问题：setupCommand 执行失败**
```bash
# 手动进入容器测试
docker exec -it /bin/bash
# 在容器内手动执行 setupCommand
apt-get update && apt-get install -y python3
```
**问题：容器内无法访问网络**
检查网络配置是否设置为 `none`：
```json
{
"sandbox": {
"network": "bridge"
}
}
```
**问题：文件在容器重启后丢失**
这是正常行为。如果需要持久化，配置挂载目录：
```json
{
"sandbox": {
"mounts": [
{
"source": "/home/user/persistent-data",
"target": "/data",
"readonly": false
}
]
}
}
```
## 安全最佳实践
1. **生产环境必须开启沙箱**：`mode: "all"` 是生产环境的最低要求
2. **限制网络访问**：如果智能体不需要访问外部网络，设置 `network: "none"`
3. **最小化挂载**：只挂载必要的目录，尽量使用只读模式
4. **限制资源**：设置内存和 CPU 限制，防止资源耗尽
5. **配合工具策略**：沙箱 + 工具策略组合使用，双重保护
6. **定期清理容器**：清理不再使用的沙箱容器，释放资源
```bash
# 清理已停止的容器
docker container prune
# 清理未使用的镜像
docker image prune
```
## 小结
沙箱是 OpenClaw 安全体系的重要组成部分：
- 使用 Docker 容器隔离智能体的执行环境
- 三种模式：`off`（关闭）、`all`（全部隔离）、`untrusted`（仅隔离不受信任的技能）
- 与工具策略（allow/deny）和提权（elevated）配合使用，形成多层安全防护
- 通过 `setupCommand` 在容器内安装依赖
- 可以限制网络访问、文件系统和系统资源
- 生产环境和多用户场景强烈推荐开启沙箱
安全不是可选项——当你的 Gateway 面向外部用户或运行第三方技能时，沙箱是保护系统的第一道防线。
#沙箱隔离 #安全运行 #Docker隔离 #工具策略 #龙虾技能库