跳转至

镜像和设置

从源码检出或 npm 安装构建沙箱镜像，以及决定镜像必须预装内容的网络与证书默认设置。

镜像与设置

默认 Docker 镜像：openclaw-sandbox:bookworm-slim

Note

源码检出与 npm 安装

只有当您从源码检出运行时，scripts/sandbox-setup.sh、scripts/sandbox-common-setup.sh 和 scripts/sandbox-browser-setup.sh 辅助脚本才可用。它们不包含在 npm 包中。

如果您安装了全局 OpenClaw npm 包，请改用下面显示的内联 docker build 命令。

1. 构建默认镜像

从源码检出：

scripts/sandbox-setup.sh

从 npm 安装（无需源码检出）：

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
  bash ca-certificates curl git jq python3 ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN useradd --create-home --shell /bin/bash sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["sleep", "infinity"]
DOCKERFILE

默认镜像不包含 Node。如果某个技能需要 Node（或其他运行时），可以构建自定义镜像，或通过 sandbox.docker.setupCommand 安装（需要网络出口 + 可写根目录 + root 用户）。

当缺少 openclaw-sandbox:bookworm-slim 时，OpenClaw 不会静默替换为普通的 debian:bookworm-slim。针对默认镜像的沙箱运行会在您构建它之前快速失败并显示构建说明，因为捆绑镜像携带了用于沙箱写入/编辑辅助功能的 python3。

2. 可选：构建通用镜像

如需构建包含常用工具（例如 curl、jq、Node 24、pnpm、python3 和 git）的功能更全面的沙箱镜像：

从源码检出：

scripts/sandbox-common-setup.sh

若从 npm 安装，请先构建默认镜像（见上文）。从同一个 OpenClaw 提交或标签中，将 scripts/docker/sandbox/Dockerfile.common 和根目录下的 package.json 下载到一个空目录中。保持文件名不变，然后在该目录中运行：

docker build -t openclaw-sandbox-common:bookworm-slim -f Dockerfile.common .

package.json 提供了固定的 pnpm 版本，并且即使使用 --build-arg INSTALL_PNPM=0，它也必须位于构建上下文中。它是一个只读的构建输入；您不需要源码检出，也不需要宿主机上安装 pnpm。

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

3. 可选：构建沙箱浏览器镜像

从源码检出：

scripts/sandbox-browser-setup.sh

npm 包不包含浏览器 Dockerfile 或入口点。请使用源码检出来构建此镜像。

默认情况下，本地容器沙箱在无网络状态下运行。可通过 agents.defaults.sandbox.docker.network 覆盖。

默认关闭的秘密出口代理仅限 Gateway 回环。沙箱 exec 既不会收到其代理/CA 环境，也不会收到受保护哨兵。沙箱/容器代理可达性尚未实现；请勿为了在此版本中让秘密替换生效而启用沙箱网络。

Note

系统软件包安装和证书存储更改属于镜像预配置，而非正常的沙箱回合行为。这些默认设置刻意组合了无网络、只读根文件系统和非 root 镜像用户，因此在回合内安装系统软件包应当失败。当操作者启用网络出口时，可以在可写工作区中安装项目本地依赖。建议使用已包含系统软件包和私有证书根的自定义镜像。如果 Node 进程需要私有 CA，还需通过自定义镜像或 sandbox.docker.env 为 Node 配置 CA 路径，例如使用 NODE_EXTRA_CA_CERTS。

沙箱浏览器 Chromium 默认值

捆绑的沙箱浏览器镜像为容器化工作负载应用了保守的 Chromium 启动参数：

  • --remote-debugging-address=127.0.0.1
  • --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
  • --user-data-dir=${HOME}/.chrome
  • --no-first-run
  • --no-default-browser-check
  • --disable-dev-shm-usage
  • --disable-background-networking
  • --disable-breakpad
  • --disable-crash-reporter
  • --no-zygote
  • --metrics-recording-only
  • --password-store=basic
  • --use-mock-keychain
  • 当 browser.headless 启用时，使用 --headless=new。
  • --no-sandbox --disable-setuid-sandbox（在沙箱浏览器容器中始终启用）。
  • 默认启用 --disable-3d-apis、--disable-gpu、--disable-software-rasterizer；这些图形加固参数有助于无 GPU 支持的容器。如果您的负载需要 WebGL 或其他 3D 功能，请设置 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0。
  • 默认启用 --disable-extensions；对于依赖扩展的流程，请设置 OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0。
  • 默认 --renderer-process-limit=2；由 OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> 控制，其中 0 保留 Chromium 的默认值。

如果您需要不同的运行时配置，请使用自定义浏览器镜像并提供您自己的入口点。对于本地（非容器）Chromium 配置，请使用 browser.extraArgs 附加其他启动参数。

网络安全默认值
  • network: "host" 已被阻止。
  • network: "container:<id>" 默认被阻止（存在命名空间加入绕过风险）。
  • 紧急覆盖：agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true。

Docker 安装和容器化网关位于此处：Docker。

对于 Docker 网关部署，scripts/docker/setup.sh 可以引导沙箱配置。设置 OPENCLAW_SANDBOX=1（或 true/yes/on）以启用该路径。使用 OPENCLAW_DOCKER_SOCKET 覆盖 socket 位置。完整设置和环境变量参考：Docker。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw