Docker（可选）

Docker 是可选的。只有当你需要容器化网关或想验证 Docker 流程时才用它。

Docker 适合我吗？

  • 适合：你想要一个隔离的、用完即弃的网关环境，或者在没有本地安装的主机上运行 OpenClaw。
  • 不适合：你在自己的机器上开发，只想要最快的开发体验。直接用普通安装方式就好。
  • 沙箱说明：Agent 沙箱也用 Docker，但它不要求网关本身运行在 Docker 中。详见沙箱。

本指南涵盖：

  • 容器化网关（完整的 OpenClaw 跑在 Docker 里）
  • 按会话的 Agent 沙箱（网关在主机上 + Docker 隔离的 Agent 工具）

沙箱详情：沙箱

系统要求

  • Docker Desktop（或 Docker Engine）+ Docker Compose v2
  • 至少 2 GB 内存用于镜像构建（pnpm install 在 1 GB 主机上可能因 OOM 被杀死，退出码 137）
  • 足够的磁盘空间存放镜像和日志
  • 如果在 VPS/公网主机上运行，请查阅 网络暴露的安全加固， 特别是 Docker DOCKER-USER 防火墙策略。

容器化网关（Docker Compose）

快速开始（推荐）

注意： Docker 默认使用绑定模式（lan/loopback），而非主机别名。在 gateway.bind 中使用绑定 模式值（如 lan 或 loopback），不要用 0.0.0.0 或 localhost 之类的主机别名。

从仓库根目录：

./docker-setup.sh

这个脚本会：

  • 在本地构建网关镜像（或者在设置了 OPENCLAW_IMAGE 时拉取远程镜像）
  • 运行初始化引导向导
  • 打印可选的渠道配置提示
  • 通过 Docker Compose 启动网关
  • 生成网关 token 并写入 .env

可选环境变量：

  • OPENCLAW_IMAGE — 使用远程镜像代替本地构建（如 ghcr.io/openclaw/openclaw:latest）
  • OPENCLAW_DOCKER_APT_PACKAGES — 构建时安装额外的 apt 包
  • OPENCLAW_EXTENSIONS — 构建时预安装扩展依赖（空格分隔的扩展名，如 diagnostics-otel matrix）
  • OPENCLAW_EXTRA_MOUNTS — 添加额外的主机绑定挂载
  • OPENCLAW_HOME_VOLUME — 用命名卷持久化 /home/node
  • OPENCLAW_SANDBOX — 启用 Docker 网关沙箱引导。仅以下值会启用：1、true、yes、on
  • OPENCLAW_INSTALL_DOCKER_CLI — 构建参数透传，用于本地镜像构建（1 表示在镜像中安装 Docker CLI）。当 OPENCLAW_SANDBOX=1 进行本地构建时，docker-setup.sh 会自动设置此项。
  • OPENCLAW_DOCKER_SOCKET — 覆盖 Docker socket 路径（默认：DOCKER_HOST=unix://... 的路径，否则 /var/run/docker.sock）
  • OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 — 应急开关：允许对受信任的内网 ws:// 目标使用 CLI/引导客户端路径（默认仅限回环地址）
  • OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 — 禁用容器浏览器的图形加固标志 --disable-3d-apis、--disable-software-rasterizer、--disable-gpu，用于 需要 WebGL/3D 兼容性的场景。
  • OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 — 当浏览器流程需要扩展时保持扩展启用 （默认在沙箱浏览器中禁用扩展）。
  • OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> — 设置 Chromium 渲染进程 上限；设为 0 可跳过该标志，使用 Chromium 默认行为。

脚本完成后：

  • 在浏览器中打开 http://127.0.0.1:18789/。
  • 将 token 粘贴到 Control UI（Settings → token）。
  • 需要再次获取 URL？运行 docker compose run --rm openclaw-cli dashboard --no-open。

为 Docker 网关启用 Agent 沙箱（需主动开启）

docker-setup.sh 还可以为 Docker 部署引导配置 agents.defaults.sandbox.*。

启用方式：

export OPENCLAW_SANDBOX=1
./docker-setup.sh

自定义 socket 路径（例如 rootless Docker）：

export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./docker-setup.sh

注意：

  • 脚本只有在沙箱前置条件通过后才挂载 docker.sock。
  • 如果沙箱配置无法完成，脚本会将 agents.defaults.sandbox.mode 重置为 off， 避免重复运行时留下过期/损坏的沙箱配置。
  • 如果缺少 Dockerfile.sandbox，脚本会打印警告并继续； 需要时用 scripts/sandbox-setup.sh 构建 openclaw-sandbox:bookworm-slim。
  • 对于非本地的 OPENCLAW_IMAGE 值，镜像必须已包含 Docker CLI 支持以执行沙箱。

自动化/CI（非交互式，无 TTY 噪音）

在脚本和 CI 中，用 -T 禁用 Compose 的伪 TTY 分配：

docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

如果你的自动化流程未导出 Claude 会话变量，docker-compose.yml 中这些变量现在默认解析为空值，以避免反复出现”variable is not set”警告。

共享网络安全说明（CLI + 网关）

openclaw-cli 使用 network_mode: "service:openclaw-gateway"，这样 CLI 命令可以在 Docker 中通过 127.0.0.1 可靠地访问网关。

这意味着共享同一个信任边界：回环绑定并不构成两个容器之间的隔离。如果需要更强的隔离，请从独立容器/主机网络路径运行命令，而非使用自带的 openclaw-cli 服务。

为降低 CLI 进程被入侵的影响，compose 配置在 openclaw-cli 上删除了 NET_RAW/NET_ADMIN 能力并启用了 no-new-privileges。

配置/工作区写在主机上：

  • ~/.openclaw/
  • ~/.openclaw/workspace

在 VPS 上运行？请参阅 Hetzner (Docker VPS)。

使用远程镜像（跳过本地构建）

官方预构建镜像发布在：

使用镜像名 ghcr.io/openclaw/openclaw（不要用 Docker Hub 上名字相似的镜像）。

常用标签：

  • main — main 分支的最新构建
  • <version> — 发布标签构建（如 2026.2.26）
  • latest — 最新稳定发布标签

基础镜像信息

主 Docker 镜像当前使用：

  • node:24-bookworm

Docker 镜像现已发布 OCI 基础镜像注解（sha256 为示例，指向该标签的固定多架构 manifest 列表）：

  • org.opencontainers.image.base.name=docker.io/library/node:24-bookworm
  • org.opencontainers.image.base.digest=sha256:3a09aa6354567619221ef6c45a5051b671f953f0a1924d1f819ffb236e520e6b
  • org.opencontainers.image.source=https://github.com/openclaw/openclaw
  • org.opencontainers.image.url=https://openclaw.ai
  • org.opencontainers.image.documentation=https://docs.openclaw.ai/install/docker
  • org.opencontainers.image.licenses=MIT
  • org.opencontainers.image.title=OpenClaw
  • org.opencontainers.image.description=OpenClaw gateway and CLI runtime container image
  • org.opencontainers.image.revision=<git-sha>
  • org.opencontainers.image.version=<tag-or-main>
  • org.opencontainers.image.created=<rfc3339 timestamp>

参考：OCI 镜像注解

发布背景：本仓库的标签历史中，v2026.2.22 及更早的 2026 标签（如 v2026.2.21、v2026.2.9）已使用 Bookworm。

默认情况下，安装脚本从源码构建镜像。要改为拉取预构建镜像，在运行脚本前设置 OPENCLAW_IMAGE：

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

脚本检测到 OPENCLAW_IMAGE 不是默认的 openclaw:local 后，会执行 docker pull 而非 docker build。其他流程（引导、网关启动、token 生成）完全一样。

docker-setup.sh 仍需从仓库根目录运行，因为它使用本地的 docker-compose.yml 和辅助文件。OPENCLAW_IMAGE 只是跳过了本地镜像构建时间，并不替代 compose/setup 工作流。

Shell 辅助工具（可选）

为了方便日常 Docker 管理，可以安装 ClawDock：

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

添加到 shell 配置（zsh）：

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

然后就可以使用 clawdock-start、clawdock-stop、clawdock-dashboard 等命令。运行 clawdock-help 查看所有命令。

详见 ClawDock Helper README。

手动流程（compose）

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

注意：从仓库根目录运行 docker compose ...。如果启用了 OPENCLAW_EXTRA_MOUNTS 或 OPENCLAW_HOME_VOLUME，安装脚本会生成 docker-compose.extra.yml；在其他地方运行 Compose 时需要加上它：

docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>

Control UI token + 配对（Docker）

如果看到 “unauthorized” 或 “disconnected (1008): pairing required”，获取新的 dashboard 链接并批准浏览器设备：

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

更多细节：Dashboard、设备。

额外挂载（可选）

如果需要在容器中挂载额外的主机目录，在运行 docker-setup.sh 前设置 OPENCLAW_EXTRA_MOUNTS。它接受逗号分隔的 Docker 绑定挂载列表，会同时应用于 openclaw-gateway 和 openclaw-cli，通过生成 docker-compose.extra.yml 实现。

示例：

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

注意：

  • 路径必须在 macOS/Windows 的 Docker Desktop 中共享。
  • 每个条目格式为 source:target[:options]，不含空格、制表符或换行。
  • 修改 OPENCLAW_EXTRA_MOUNTS 后需重新运行 docker-setup.sh 以重新生成 extra compose 文件。
  • docker-compose.extra.yml 是自动生成的，不要手动编辑。

持久化整个容器 home 目录（可选）

如果希望 /home/node 在容器重建后仍然保留，可以通过 OPENCLAW_HOME_VOLUME 设置命名卷。这会创建一个 Docker volume 并挂载到 /home/node，同时保留标准的配置/工作区绑定挂载。这里请使用命名卷（不要用绑定路径）；绑定挂载请用 OPENCLAW_EXTRA_MOUNTS。

示例：

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

可以和额外挂载组合使用：

export OPENCLAW_HOME_VOLUME="openclaw_home"
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

注意：

  • 命名卷必须匹配 ^[A-Za-z0-9][A-Za-z0-9_.-]*$。
  • 修改 OPENCLAW_HOME_VOLUME 后需重新运行 docker-setup.sh 以重新生成 extra compose 文件。
  • 命名卷会一直保留，直到通过 docker volume rm <name> 删除。

安装额外的 apt 包（可选）

如果需要在镜像中安装系统包（如构建工具或多媒体库），在运行 docker-setup.sh 前设置 OPENCLAW_DOCKER_APT_PACKAGES。这些包在镜像构建时安装，即使容器被删除也会保留。

示例：

export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

注意：

  • 接受空格分隔的 apt 包名列表。
  • 修改 OPENCLAW_DOCKER_APT_PACKAGES 后需重新运行 docker-setup.sh 以重建镜像。

预安装扩展依赖（可选）

带有自己 package.json 的扩展（如 diagnostics-otel、matrix、msteams）会在首次加载时安装 npm 依赖。如果想在镜像中预装这些依赖，在运行 docker-setup.sh 前设置 OPENCLAW_EXTENSIONS：

export OPENCLAW_EXTENSIONS="diagnostics-otel matrix"
./docker-setup.sh

或在直接构建时：

docker build --build-arg OPENCLAW_EXTENSIONS="diagnostics-otel matrix" .

注意：

  • 接受空格分隔的扩展目录名（位于 extensions/ 下）。
  • 仅影响带有 package.json 的扩展；没有 package.json 的轻量插件不受影响。
  • 修改 OPENCLAW_EXTENSIONS 后需重新运行 docker-setup.sh 以重建镜像。

高级用户 / 全功能容器（需主动开启）

默认 Docker 镜像以安全优先，以非 root 用户 node 运行。这减小了攻击面，但也意味着：

  • 运行时无法安装系统包
  • 默认不含 Homebrew
  • 不打包 Chromium/Playwright 浏览器

如果需要更全面的容器功能，使用以下开关：

  1. 持久化 /home/node，让浏览器下载和工具缓存得以保留：
export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh
  1. 将系统依赖写入镜像（可重复 + 持久化）：
export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh
  1. 不用 npx 安装 Playwright 浏览器（避免 npm 覆盖冲突）：
docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

如果需要 Playwright 安装系统依赖，请通过 OPENCLAW_DOCKER_APT_PACKAGES 重建镜像，而非在运行时使用 --with-deps。

  1. 持久化 Playwright 浏览器下载：
  • 在 docker-compose.yml 中设置 PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright。
  • 通过 OPENCLAW_HOME_VOLUME 持久化 /home/node，或通过 OPENCLAW_EXTRA_MOUNTS 挂载 /home/node/.cache/ms-playwright。

权限 + EACCES

镜像以 node（uid 1000）运行。如果在 /home/node/.openclaw 上遇到权限错误，确保主机绑定挂载的所有者为 uid 1000。

示例（Linux 主机）：

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

如果你选择以 root 身份运行图方便，需接受相应的安全风险。

加速重建（推荐）

为加快重建速度，调整 Dockerfile 顺序以充分利用依赖层缓存。这样在 lockfile 不变时可以跳过 pnpm install：

FROM node:24-bookworm

# Install Bun (required for build scripts)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# Cache dependencies unless package metadata changes
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

渠道配置（可选）

使用 CLI 容器配置渠道，然后按需重启网关。

WhatsApp（扫码）：

docker compose run --rm openclaw-cli channels login

Telegram（bot token）：

docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

Discord（bot token）：

docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

文档：WhatsApp、Telegram、Discord

OpenAI Codex OAuth（无头 Docker）

如果在向导中选择了 OpenAI Codex OAuth，它会打开浏览器 URL 并尝试在 http://127.0.0.1:1455/auth/callback 捕获回调。在 Docker 或无头环境中，这个回调可能显示浏览器错误。复制你最终跳转到的完整重定向 URL，粘贴回向导即可完成认证。

健康检查

容器探测端点（无需认证）：

curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz

别名：/health 和 /ready。

/healthz 是浅层存活探测，表示”网关进程正在运行”。/readyz 在启动宽限期内保持就绪状态，之后只有在必需的托管渠道在宽限期后仍未连接或断开时才返回 503。

Docker 镜像内置了 HEALTHCHECK，会在后台定期请求 /healthz。简单来说：Docker 持续检查 OpenClaw 是否还在响应。如果检查持续失败，Docker 会将容器标记为 unhealthy，编排系统（Docker Compose 重启策略、Swarm、Kubernetes 等）可以自动重启或替换它。

带认证的深度健康快照（网关 + 渠道）：

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

E2E 冒烟测试（Docker）

scripts/e2e/onboard-docker.sh

QR 导入冒烟测试（Docker）

pnpm test:docker:qr

LAN 与回环（Docker Compose）

docker-setup.sh 默认设置 OPENCLAW_GATEWAY_BIND=lan，这样主机通过 Docker 端口映射访问 http://127.0.0.1:18789 就能正常工作。

  • lan（默认）：主机浏览器 + 主机 CLI 可以访问网关的映射端口。
  • loopback：只有容器网络命名空间内的进程可以直接访问网关；主机端口映射访问可能失败。

安装脚本还会在引导后固定 gateway.mode=local，使 Docker CLI 命令默认指向本地回环地址。

旧版配置说明：在 gateway.bind 中使用绑定模式值（lan / loopback / custom / tailnet / auto），不要用主机别名（0.0.0.0、127.0.0.1、localhost、::、::1）。

如果看到 Gateway target: ws://172.x.x.x:18789 或 Docker CLI 命令反复报 pairing required 错误，运行：

docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

补充说明

  • 容器使用时网关绑定默认为 lan（OPENCLAW_GATEWAY_BIND）。
  • Dockerfile CMD 使用 --allow-unconfigured；挂载的配置文件中 gateway.mode 不是 local 时仍可启动。要强制限制可覆盖 CMD。
  • 网关容器是会话的存储源（~/.openclaw/agents/<agentId>/sessions/）。

存储模型

  • 持久化主机数据： Docker Compose 将 OPENCLAW_CONFIG_DIR 绑定挂载到 /home/node/.openclaw，将 OPENCLAW_WORKSPACE_DIR 挂载到 /home/node/.openclaw/workspace，因此这些路径在容器替换后仍然存在。
  • 临时沙箱 tmpfs： 当启用 agents.defaults.sandbox 时，沙箱容器对 /tmp、/var/tmp 和 /run 使用 tmpfs。这些挂载独立于顶层 Compose 栈，随沙箱容器消失而消失。
  • 磁盘增长热点： 注意关注 media/、agents/<agentId>/sessions/sessions.json、转录 JSONL 文件、cron/runs/*.jsonl，以及 /tmp/openclaw/ 下的滚动文件日志（或你配置的 logging.file）。如果你同时在 Docker 之外运行 macOS 应用，其服务日志是独立的：~/.openclaw/logs/gateway.log、~/.openclaw/logs/gateway.err.log 和 /tmp/openclaw/openclaw-gateway.log。

Agent 沙箱（主机网关 + Docker 工具）

深入了解：沙箱

工作原理

当启用 agents.defaults.sandbox 时，非主会话的工具调用在 Docker 容器内执行。网关留在主机上，但工具执行是隔离的：

  • 作用域：默认 "agent"（每个 Agent 一个容器 + 工作区）
  • 作用域："session" 用于按会话隔离
  • 按作用域的工作区文件夹挂载在 /workspace
  • 可选的 Agent 工作区访问（agents.defaults.sandbox.workspaceAccess）
  • allow/deny 工具策略（deny 优先）
  • 入站媒体会被复制到活跃沙箱工作区（media/inbound/*），这样工具就能读取它们（当 workspaceAccess: "rw" 时，文件会落入 Agent 工作区）

警告：scope: "shared" 会禁用跨会话隔离。所有会话共享一个容器和一个工作区。

多 Agent 沙箱配置

如果使用多 Agent 路由，每个 Agent 可以覆盖沙箱和工具设置： agents.list[].sandbox 和 agents.list[].tools（以及 agents.list[].tools.sandbox.tools）。这样你可以在同一个网关中运行不同访问级别：

  • 完全访问（个人 Agent）
  • 只读工具 + 只读工作区（家庭/工作 Agent）
  • 无文件系统/shell 工具（公开 Agent）

详见多 Agent 沙箱与工具获取示例、优先级和排错信息。

默认行为

  • 镜像：openclaw-sandbox:bookworm-slim
  • 每个 Agent 一个容器
  • Agent 工作区访问：workspaceAccess: "none"（默认）使用 ~/.openclaw/sandboxes
    • "ro" 将沙箱工作区保留在 /workspace，并以只读方式挂载 Agent 工作区到 /agent（禁用 write/edit/apply_patch）
    • "rw" 以读写方式挂载 Agent 工作区到 /workspace
  • 自动清理：空闲 > 24h 或存活 > 7d
  • 网络：默认 none（需要出站时请显式开启）
    • host 被阻止。
    • container:<id> 默认被阻止（命名空间合并风险）。
  • 默认允许：exec、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
  • 默认拒绝：browser、canvas、nodes、cron、discord、gateway

启用沙箱

如果你打算在 setupCommand 中安装软件包，请注意：

  • 默认 docker.network 为 "none"（无出站）。
  • docker.network: "host" 被阻止。
  • docker.network: "container:<id>" 默认被阻止。
  • 应急覆盖：agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true。
  • readOnlyRoot: true 阻止包安装。
  • user 必须为 root 才能运行 apt-get（省略 user 或设置 user: "0:0"）。 OpenClaw 会在 setupCommand（或 docker 配置）变更时自动重建容器， 除非容器是最近使用过的（约 5 分钟内）。热容器会记录一条警告并给出具体的 openclaw sandbox recreate ... 命令。
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          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"],
        },
        prune: {
          idleHours: 24, // 0 disables idle pruning
          maxAgeDays: 7, // 0 disables max-age pruning
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

加固参数位于 agents.defaults.sandbox.docker 下： network、user、pidsLimit、memory、memorySwap、cpus、ulimits、 seccompProfile、apparmorProfile、dns、extraHosts、 dangerouslyAllowContainerNamespaceJoin（仅应急使用）。

多 Agent 场景：可通过 agents.list[].sandbox.{docker,browser,prune}.* 按 Agent 覆盖 agents.defaults.sandbox.{docker,browser,prune}.*（当 agents.defaults.sandbox.scope / agents.list[].sandbox.scope 为 "shared" 时忽略）。

构建默认沙箱镜像

scripts/sandbox-setup.sh

这会使用 Dockerfile.sandbox 构建 openclaw-sandbox:bookworm-slim。

沙箱通用镜像（可选）

如果需要一个带有常用构建工具（Node、Go、Rust 等）的沙箱镜像，构建通用镜像：

scripts/sandbox-common-setup.sh

这会构建 openclaw-sandbox-common:bookworm-slim。使用方式：

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
    },
  },
}

沙箱浏览器镜像

要在沙箱中运行浏览器工具，构建浏览器镜像：

scripts/sandbox-browser-setup.sh

这会使用 Dockerfile.sandbox-browser 构建 openclaw-sandbox-browser:bookworm-slim。容器运行启用了 CDP 的 Chromium，并可选 noVNC 观察器（通过 Xvfb 实现有头模式）。

注意：

  • 有头模式（Xvfb）比无头模式更不容易被反爬检测。
  • 仍可通过 agents.defaults.sandbox.browser.headless=true 使用无头模式。
  • 不需要完整的桌面环境（GNOME）；Xvfb 提供显示即可。
  • 浏览器容器默认使用专用 Docker 网络（openclaw-sandbox-browser），而非全局 bridge。
  • 可选的 agents.defaults.sandbox.browser.cdpSourceRange 通过 CIDR 限制容器边缘的 CDP 入站访问（如 172.21.0.1/32）。
  • noVNC 观察器默认需要密码保护；OpenClaw 提供短期有效的观察器 token URL，返回本地引导页面并将密码放在 URL fragment 中（而非 URL query）。
  • 浏览器容器的启动默认值针对共享/容器工作负载做了保守设置，包括：
    • --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-3d-apis
    • --disable-software-rasterizer
    • --disable-gpu
    • --disable-dev-shm-usage
    • --disable-background-networking
    • --disable-features=TranslateUI
    • --disable-breakpad
    • --disable-crash-reporter
    • --metrics-recording-only
    • --renderer-process-limit=2
    • --no-zygote
    • --disable-extensions
    • 如果设置了 agents.defaults.sandbox.browser.noSandbox，还会追加 --no-sandbox 和 --disable-setuid-sandbox。
    • 上述三个图形加固标志是可选的。如果你的工作负载需要 WebGL/3D，设置 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 即可不使用 --disable-3d-apis、--disable-software-rasterizer 和 --disable-gpu。
    • 扩展行为由 --disable-extensions 控制，可通过 OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 禁用（即启用扩展），用于依赖扩展的页面或工作流。
    • --renderer-process-limit=2 也可通过 OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT 配置；设为 0 可让 Chromium 使用其默认进程限制，适用于需要调优浏览器并发的场景。

以上默认值在自带镜像中已应用。如果需要不同的 Chromium 标志，请使用自定义浏览器镜像并提供你自己的入口点。

配置示例：

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}

自定义浏览器镜像：

{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-openclaw-browser" } },
    },
  },
}

启用后，Agent 会获得：

  • 一个沙箱浏览器控制 URL（供 browser 工具使用）
  • 一个 noVNC URL（如果启用且非无头模式）

注意：如果你使用了工具白名单，需要添加 browser（并从 deny 中移除），否则该工具仍被阻止。 清理规则（agents.defaults.sandbox.prune）同样适用于浏览器容器。

自定义沙箱镜像

构建自己的镜像并在配置中指向它：

docker build -t my-openclaw-sbx -f Dockerfile.sandbox .
{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-openclaw-sbx" } },
    },
  },
}

工具策略（allow/deny）

  • deny 优先于 allow。
  • 如果 allow 为空：所有工具（除 deny 外）可用。
  • 如果 allow 非空：仅 allow 中的工具可用（减去 deny）。

清理策略

两个参数：

  • prune.idleHours：移除超过 X 小时未使用的容器（0 = 禁用）
  • prune.maxAgeDays：移除存活超过 X 天的容器（0 = 禁用）

示例：

  • 保留活跃会话但限制生命周期： idleHours: 24，maxAgeDays: 7
  • 永不清理： idleHours: 0，maxAgeDays: 0

安全说明

  • 硬隔离仅适用于工具（exec/read/write/edit/apply_patch）。
  • 主机端工具（如 browser/camera/canvas）默认被阻止。
  • 在沙箱中允许 browser 会破坏隔离（浏览器在主机上运行）。

排错

  • 镜像缺失：用 scripts/sandbox-setup.sh 构建或设置 agents.defaults.sandbox.docker.image。
  • 容器未运行：按需在每次会话时自动创建。
  • 沙箱中的权限错误：将 docker.user 设为与挂载工作区所有者匹配的 UID:GID（或 chown 工作区文件夹）。
  • 自定义工具找不到：OpenClaw 用 sh -lc（登录 shell）运行命令，会加载 /etc/profile 并可能重置 PATH。设置 docker.env.PATH 以前置你的自定义工具路径（如 /custom/bin:/usr/local/share/npm-global/bin），或在 Dockerfile 中添加 /etc/profile.d/ 下的脚本。
arrow_back
上一页
Installer
下一页
Podman
arrow_forward