沙箱是什么
沙箱（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隔离 #工具策略 #龙虾技能库