跳至主要內容

[OpenClaw]SOP1从0到1搭建含沙盒的openclaw

whoway2026/4/15大约 3 分钟

[OpenClaw]SOP1从0到1搭建含沙盒的openclaw

1、源码下载

2、准备全沙盒配置

将OpenClaw安全模型全部放入沙盒的配置，要启用全沙盒模式，修改 ~/.openclaw/config.json：

  {
    "agents": {
      "defaults": {
        "sandbox": {
          // 模式：所有会话都沙盒化
          "mode": "all",

          // 后端：Docker（默认）
          "backend": "docker",

          // 作用域：每个会话独立容器
          "scope": "session",

          // Docker配置
          "docker": {
            // 使用增强沙盒镜像（包含开发工具）
            "image": "openclaw-sandbox-common:bookworm-slim",

            // 可选：自定义网络（默认：openclaw-sandbox-browser）
            "network": "openclaw-sandbox-browser",

            // 可选：挂载目录
            "binds": [
              "/home/user/projects:/workspace/projects:rw"
            ]
          },

          // 浏览器沙盒配置（可选）
          "browser": {
            "enabled": true,
            "image": "openclaw-sandbox-browser:bookworm-slim",
            "network": "openclaw-sandbox-browser",
            "autoStart": true,
            "autoStartTimeoutMs": 30000
          },

          // 工作区访问权限
          "workspaceAccess": "rw"
        }
      }
    }
  }

关键配置项说明

  1. mode: "all" - 所有会话都使用沙盒（最严格）
  2. scope: "session" - 每个会话独立容器（避免交叉污染）
  3. image选择：
    - openclaw-sandbox:bookworm-slim - 基础隔离
    - openclaw-sandbox-common:bookworm-slim - 开发环境
    - openclaw-sandbox-browser:bookworm-slim - 浏览器隔离（需配合browser.enabled: true）
  4. network: "openclaw-sandbox-browser" - 专用网络，与主机隔离

验证步骤

  1. 应用配置：openclaw config set agents.defaults.sandbox.mode all
  2. 重启网关：openclaw gateway restart 或重启OpenClaw应用
  3. 验证沙盒状态：openclaw agents status --detail

▎ 注意：全沙盒模式会增加容器开销，但提供最强的安全隔离。如需在沙盒中使用开发工具，建议使用
openclaw-sandbox-common:bookworm-slim 镜像。

具体镜像构建

步骤1，基础镜像：debian:bookworm-slim

➜  skills docker pull debian:bookworm-slim@sha256:98f4b71de414932439ac6ac690d7060df1f27161073c5036a7553723881bffbe
docker.io/library/debian@sha256:98f4b71de414932439ac6ac690d7060df1f27161073c5036a7553723881bffbe: Pulling from library/debian
Digest: sha256:98f4b71de414932439ac6ac690d7060df1f27161073c5036a7553723881bffbe
Status: Downloaded newer image for debian@sha256:98f4b71de414932439ac6ac690d7060df1f27161073c5036a7553723881bffbe
docker.io/library/debian:bookworm-slim@sha256:98f4b71de414932439ac6ac690d7060df1f27161073c5036a7553723881bffbe
➜  skills

步骤2：【openclaw-sandbox:bookworm-slim】基于前一个基础镜像在本地构建 openclaw-sandbox:bookworm-slim 镜像

  • Dockerfile.sandbox可以构造名字为openclaw-sandbox:bookworm-slim的镜像
    • （基础沙盒镜像） 基于 debian:bookworm-slim，安装基础工具（bash、curl、git、jq、python3、ripgrep）
    • 用途：默认沙盒容器，提供最基本的安全隔离
      注意，这个默认镜像不包含 Node。如果某个 Skill 需要 Node（或 其他运行时），你需要构建自定义镜像，或通过 sandbox.docker.setupCommand 安装（要求网络出口 + 可写根文件系统 + root 用户）。

步骤3：【openclaw-sandbox-common:bookworm-slim】最高层级的沙盒， 使用Dockerfile.sandbox-common文件

  • 官方文档：https://docs.openclaw.ai/zh-CN/gateway/sandboxing#setupcommand（一次性容器设置）
  • Dockerfile.sandbox-common可以基于构建出来的 openclaw-sandbox:bookworm-slim 镜像进一步构建最终版的openclaw-sandbox-common:bookworm-slim【包含node】
    • 比Dockerfile.sandbox更牛的地方在：如果你想要功能更完整、带常用工具的沙箱镜像（例如 curl、jq、nodejs、python3、git），请构建这个

然后将 agents.defaults.sandbox.docker.image 设置为 openclaw-sandbox-common:bookworm-slim。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          // 基础版的镜像是：     openclaw-sandbox:bookworm-slim
          // 更多功能完整的镜像是：openclaw-sandbox-common:bookworm-slim
          image: "openclaw-sandbox:bookworm-slim", 
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        }
	}
}

步骤4：【openclaw-sandbox-browser:bookworm-slim】要基于openclaw-sandbox:bookworm-slim镜像和Dockerfile.sandbox-browser文件构造openclaw-sandbox-browser:bookworm-slim镜像

browser: {
	  enabled: false,
	  image: "openclaw-sandbox-browser:bookworm-slim",
	  network: "openclaw-sandbox-browser",
	  cdpPort: 9222,
	  cdpSourceRange: "172.21.0.1/32",
	  vncPort: 5900,
	  noVncPort: 6080,
	  headless: false,
	  enableNoVnc: true,
	  allowHostControl: false,
	  autoStart: true,
	  autoStartTimeoutMs: 12000,
	},

备注：如果你不使用vscode的构建，那就可以执行./scripts/sandbox-setup.sh 之类的脚本，他们本质就是直接调用的这些内容的