OpenClaw Docker 沙箱隔离配置指南

2026-01-22 · 5 分钟安全运维

沙箱隔离概述

OpenClaw 提供两种沙箱隔离策略：完整容器化（将整个 OpenClaw 运行在容器中）和工具级沙箱（仅将特定工具的执行放入容器）。工具级沙箱更灵活，推荐在生产环境中使用。

沙箱模式配置

在 ~/.config/openclaw/openclaw.json5 中配置沙箱：

{
  sandbox: {
    // 沙箱模式：off / non-main / all
    mode: "non-main",

    // 沙箱作用域：session / agent / shared
    scope: "session",

    // 工作区访问权限：none / ro / rw
    workspaceAccess: "ro",

    // 使用的 Docker 镜像
    image: "openclaw-sandbox:bookworm-slim"
  }
}

mode 参数说明

模式	说明	适用场景
`off`	不使用沙箱	开发测试环境
`non-main`	仅非主工具在沙箱中运行	推荐的生产配置
`all`	所有工具均在沙箱中运行	最高安全等级

scope 参数说明

作用域	说明
`session`	每个会话独立容器，会话结束后销毁
`agent`	每个 Agent 共享容器，Agent 卸载后销毁
`shared`	所有任务共享同一容器

构建沙箱镜像

OpenClaw 自带了镜像构建脚本：

# 使用内置脚本构建
./scripts/sandbox-setup.sh

# 或手动构建
docker build -t openclaw-sandbox:bookworm-slim -f Dockerfile.sandbox .

构建完成后验证镜像：

docker images | grep openclaw-sandbox
# openclaw-sandbox   bookworm-slim   abc123def456   2 minutes ago   185MB

网络隔离

默认情况下沙箱容器运行在隔离网络中。按需配置网络访问：

{
  sandbox: {
    network: {
      // 完全隔离（默认）
      mode: "none",

      // 或允许外网访问
      // mode: "bridge",

      // DNS 设置（仅 bridge 模式生效）
      dns: ["8.8.8.8", "8.8.4.4"]
    }
  }
}

资源限制

防止沙箱中的进程消耗过多系统资源：

{
  sandbox: {
    resources: {
      // CPU 核心数限制
      cpus: 2,

      // 内存限制
      memory: "512m",

      // 进程数限制
      pidsLimit: 100,

      // 磁盘写入限制
      storageLimit: "1g"
    }
  }
}

用户权限

沙箱内的进程默认以非 root 用户运行：

{
  sandbox: {
    // 容器内运行用户
    user: "openclaw",
    uid: 1000,
    gid: 1000
  }
}

SELinux / AppArmor 集成

在启用了 SELinux 或 AppArmor 的系统上，可以指定安全配置文件：

{
  sandbox: {
    // AppArmor 配置
    apparmor: "openclaw-sandbox-profile",

    // 或 SELinux 标签
    selinux: "openclaw_sandbox_t"
  }
}

自动清理

空闲容器在指定时间后自动销毁，释放系统资源：

{
  sandbox: {
    // 空闲超时（秒），默认 300
    idleTimeout: 300,

    // 最大存活时间（秒），默认 3600
    maxLifetime: 3600
  }
}

工作区挂载

workspaceAccess 控制容器对宿主机工作区的访问：

# none: 容器内无法访问宿主机文件
# ro:   只读挂载工作目录（推荐）
# rw:   读写挂载工作目录

只读模式下，工具可以读取项目文件但无法修改，适合代码审查类场景。

常见问题排查

容器启动失败：运行 docker info 确认 Docker 守护进程正常，检查镜像是否已构建
权限不足：确认当前用户在 docker 组中，或使用 sudo 运行
网络不通：检查 network.mode 是否设为 none，按需切换为 bridge
资源耗尽：调整 resources 中的限制值，使用 docker stats 监控容器资源