一、读懂沙箱：什么是执行环境隔离

沙箱基于Docker 容器打造独立运行环境，相当于给 AI 的命令执行、文件读写、代码运行配上一间「隔离安全屋」。

• 所有操作仅在容器内生效，异常、高危命令不会侵蚀宿主机
• 容器销毁后，临时数据自动清空，不留残留风险
• 与工具权限、提权机制分工不同，专注运行环境层面防护

三大安全机制核心区分

表格

防护机制	管控对象	核心作用	通俗类比
沙箱 Sandbox	执行环境位置	限定操作在哪运行	把行为关进独立房间
工具策略 Allow/Deny	可用工具列表	限定能调用哪些功能	决定允许使用哪些工具
提权 Elevated	工具权限等级	限定工具能力强弱	区分普通权限 / 高级权限

组合使用示例（双重防护）

json

{
  "sandbox": {
    "mode": "all"
  },
  "tools": {
    "allow": ["exec", "read", "write"],
    "deny": ["browser"]
  }
}

解读：允许使用执行、读写工具，禁用浏览器；所有操作强制在沙箱容器内运行。

二、前置准备：安装并运行 Docker

沙箱强依赖 Docker，部署前先完成环境校验与安装。

bash

运行

# 1. 检查Docker是否已安装
docker --version

# 2. 检查Docker服务是否正常运行
docker info

快速安装 Docker

bash

运行

# Ubuntu / Debian 系统
curl -fsSL https://get.docker.com | sh
# 将当前用户加入docker组，免sudo操作
sudo usermod -aG docker $USER

# macOS 系统
brew install --cask docker

操作后重新登录终端，权限即可生效。

三、基础配置：三种沙箱运行模式

编辑主配置文件 ~/.openclaw/openclaw.json，通过 sandbox.mode 切换模式。

1. mode: off 关闭沙箱（默认）

json

{
  "sandbox": {
    "mode": "off"
  }
}

• 特性：所有命令、文件操作直接在宿主机执行
• 适用：个人单机自用、完全信任所有技能、仅内部使用

2. mode: all 全局沙箱化（生产首选）

json

{
  "sandbox": {
    "mode": "all"
  }
}

• 特性：全部执行操作强制进入容器隔离，安全等级最高
• 适用：公网服务、多用户共享网关、生产环境、运行陌生第三方技能

3. mode: untrusted 按需隔离（折中方案）

json

{
  "sandbox": {
    "mode": "untrusted"
  }
}

• 特性：仅标记为不受信任的技能在沙箱运行，可信操作直连宿主机
• 适用：兼顾安全与效率，日常自用 + 偶尔测试新技能的场景

四、精细化配置：单智能体独立沙箱策略

多智能体场景下，可针对不同 Agent 单独配置沙箱规则，灵活区分权限。

json

{
  "agents": {
    "list": [
      {
        "id": "personal-coder",
        "sandbox": {
          "mode": "off"
        }
      },
      {
        "id": "public-service",
        "sandbox": {
          "mode": "all"
        }
      },
      {
        "id": "skill-tester",
        "sandbox": {
          "mode": "untrusted"
        }
      }
    ]
  }
}

五、容器环境定制：自动安装依赖（setupCommand）

沙箱容器是纯净系统，缺少运行所需工具，借助 setupCommand 实现容器启动后自动安装依赖。

基础用法

json

{
  "sandbox": {
    "mode": "all",
    "setupCommand": "apt-get update && apt-get install -y python3 python3-pip && pip3 install requests"
  }
}

• 执行时机：容器创建后仅运行一次
• 生效周期：容器存活期间依赖永久有效，容器销毁需重新安装

常用依赖模板

模板 1：Python 运行环境

json

"setupCommand": "apt-get update && apt-get install -y python3 python3-pip && pip3 install pandas numpy"

模板 2：Node.js 运行环境

json

"setupCommand": "apt-get update && apt-get install -y nodejs npm && npm install -g typescript"

模板 3：通用工具集（curl/git/jq 等）

json

"setupCommand": "apt-get update && apt-get install -y curl wget jq git"

单智能体独立依赖配置

json

{
  "agents": [
    {
      "id": "python-bot",
      "sandbox": {
        "mode": "all",
        "setupCommand": "apt-get install -y python3 && pip3 install pyyaml"
      }
    }
  ]
}

六、深度管控：网络、挂载、资源限制

从网络、文件、硬件资源三方面收紧权限，最大化隔离效果。

6.1 网络访问限制

通过 network 字段控制容器联网能力：

json

{
  "sandbox": {
    "mode": "all",
    "network": "none"
  }
}

表格

网络模式	说明	适用场景
bridge（默认）	允许访问内外网络	需要联网搜索、拉取资源
none	完全禁用网络	纯本地运算、禁止对外请求
host	复用宿主机网络（不推荐）	特殊调试场景，破坏隔离性

6.2 文件目录挂载（数据持久化）

容器默认数据随销毁丢失，如需读写宿主机目录，配置 mounts；优先使用只读挂载。

json

{
  "sandbox": {
    "mode": "all",
    "mounts": [
      {
        "source": "/home/yourname/work",
        "target": "/work",
        "readonly": false
      },
      {
        "source": "/home/yourname/config",
        "target": "/config",
        "readonly": true
      }
    ]
  }
}

重要提醒：挂载目录会弱化隔离性，仅挂载必要目录，非必要一律只读。

6.3 硬件资源限制

限制 CPU、内存，防止恶意脚本耗尽服务器资源：

json

{
  "sandbox": {
    "mode": "all",
    "resources": {
      "memory": "512m",
      "cpus": "1.0"
    }
  }
}

七、场景选型：什么时候必须用沙箱

✅ 强烈建议开启沙箱

1. 生产服务器、公网对外提供服务
2. 多用户共用一套 Gateway
3. 安装、测试来源不明的第三方技能
4. 允许用户自主提交代码、执行命令

❌ 可关闭沙箱

1. 纯个人本地使用，仅自己访问
2. 只使用文本问答、文件读取等低风险内置工具
3. 运行环境无法部署 Docker（特殊 VPS、容器化环境）

八、故障排查：沙箱常见问题与修复

8.1 基础状态检查

bash

运行

# 查看Docker整体状态
docker info

# 筛选OpenClaw相关沙箱容器
docker ps | grep openclaw

# 查看容器运行日志，定位报错
docker logs 容器ID

8.2 典型问题解决

问题 1：沙箱启动失败、权限报错

bash

运行

# 测试Docker基础运行
docker run hello-world
# 权限不足则重新加入用户组，重新登录终端
sudo usermod -aG docker $USER

问题 2：setupCommand 依赖安装失败

bash

运行

# 手动进入容器内部调试
docker exec -it 容器ID /bin/bash
# 在容器内逐条执行安装命令，排查报错
apt-get update && apt-get install -y python3

问题 3：容器无法联网

检查网络配置，将 network 改为默认 bridge：

json

{
  "sandbox": {
    "network": "bridge"
  }
}

问题 4：容器内文件重启后丢失

属于正常机制，需要持久化就配置 mounts 挂载宿主机目录。

8.3 容器定期清理（释放空间）

bash

运行

# 清理已停止的无用容器
docker container prune

# 清理闲置镜像
docker image prune

九、生产环境沙箱最佳实践

1. 公网 / 生产强制开启：统一使用 mode: all 全局隔离
2. 按需禁用网络：无联网需求设置 network: none，减少攻击面
3. 目录最小挂载：只挂载业务必需目录，优先 readonly: true
4. 硬性资源限制：配置内存、CPU 上限，杜绝资源溢出
5. 多层防护搭配：沙箱 + 工具黑白名单组合使用，双重安全
6. 定期运维：定时清理停止的容器与镜像，避免磁盘占用过高

十、总结

1. 沙箱依托 Docker 实现环境级隔离，和工具权限、提权机制互补，构成多层安全体系；
2. 三大运行模式按需选择：个人用off、测试新技能用untrusted、生产环境必用all；
3. 支持自定义容器依赖、网络、文件挂载、资源限制，适配各类业务场景；
4. 挂载、host 网络模式会削弱隔离能力，生产环境尽量规避；
5. 面向公众、多用户、第三方技能的场景，沙箱是不可或缺的安全底线。