Docker（可选）

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

Docker 适合我吗?

  • 适合：你想要一个隔离的、可随时删除的 Gateway 环境,或者在没有本地安装的主机上运行 OpenClaw。
  • 不适合：你在自己的机器上运行,只想要最快的开发循环。用正常的安装流程就行。
  • Sandbox 说明：Agent Sandbox 也用 Docker,但不需要整个 Gateway 都在 Docker 里运行。详见 Sandbox。

本指南涵盖:

  • 容器化 Gateway（完整的 OpenClaw 在 Docker 中）
  • 按 Session 隔离的 Agent Sandbox（主机上的 Gateway + Docker 隔离的 Agent 工具）

Sandbox 详情：Sandbox

要求

  • Docker Desktop（或 Docker Engine）+ Docker Compose v2
  • 足够的磁盘空间存放镜像和日志

容器化 Gateway（Docker Compose）

快速开始（推荐）

在仓库根目录运行:

./docker-setup.sh

这个脚本会:

  • 构建 Gateway 镜像
  • 运行引导向导
  • 打印可选的 Provider 设置提示
  • 通过 Docker Compose 启动 Gateway
  • 生成 Gateway Token 并写入 .env

可选的环境变量:

  • OPENCLAW_DOCKER_APT_PACKAGES — 在构建时安装额外的 apt 包
  • OPENCLAW_EXTRA_MOUNTS — 添加额外的主机绑定挂载
  • OPENCLAW_HOME_VOLUME — 在命名卷中持久化 /home/node

完成后:

  • 在浏览器中打开 http://127.0.0.1:18789/。
  • 把 Token 粘贴到控制界面（Settings → token）。

它会在主机上写入配置和 Workspace:

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

在 VPS 上运行？详见 Hetzner (Docker VPS)。

手动流程（compose）

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

额外挂载（可选）

如果你想把额外的主机目录挂载到容器中,在运行 docker-setup.sh 前设置 OPENCLAW_EXTRA_MOUNTS。它接受逗号分隔的 Docker 绑定挂载列表,并通过生成 docker-compose.extra.yml 应用到 openclaw-gateway 和 openclaw-cli。

示例:

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

注意:

  • 在 macOS/Windows 上,路径必须与 Docker Desktop 共享。
  • 如果你修改了 OPENCLAW_EXTRA_MOUNTS,重新运行 docker-setup.sh 来重新生成额外的 compose 文件。
  • docker-compose.extra.yml 是自动生成的。不要手动编辑它。

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

如果你想让 /home/node 在容器重建后保持,通过 OPENCLAW_HOME_VOLUME 设置一个命名卷。这会创建一个 Docker 卷并挂载到 /home/node,同时保留标准的配置和 Workspace 绑定挂载。这里用命名卷（不是绑定路径）；绑定挂载用 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

注意:

  • 如果你修改了 OPENCLAW_HOME_VOLUME,重新运行 docker-setup.sh 来重新生成额外的 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 来重新构建镜像。

更快的重新构建（推荐）

为了加快重新构建速度,调整 Dockerfile 的顺序让依赖层被缓存。这样可以避免重新运行 pnpm install,除非锁文件改变:

FROM node:22-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"]

Channel 设置（可选）

用 CLI 容器配置 Channel,然后根据需要重启 Gateway。

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

健康检查

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

E2E 冒烟测试（Docker）

scripts/e2e/onboard-docker.sh

二维码导入冒烟测试（Docker）

pnpm test:docker:qr

注意事项

  • Gateway 绑定默认为 lan 以便容器使用。
  • Gateway 容器是 Session 的真实来源（~/.openclaw/agents/<agentId>/sessions/）。

Agent Sandbox（主机 Gateway + Docker 工具）

深入了解：Sandbox

它做什么

当 agents.defaults.sandbox 启用时,非主 Session 会在 Docker 容器内运行工具。Gateway 留在主机上,但工具执行是隔离的:

  • scope: 默认为 "agent"（每个 Agent 一个容器 + Workspace）
  • scope: "session" 用于按 Session 隔离
  • 每个 scope 的 Workspace 文件夹挂载到 /workspace
  • 可选的 Agent Workspace 访问（agents.defaults.sandbox.workspaceAccess）
  • 允许/拒绝工具策略（拒绝优先）
  • 入站媒体会复制到活动 Sandbox Workspace（media/inbound/*）以便工具读取（使用 workspaceAccess: "rw" 时,会放到 Agent Workspace）

警告：scope: "shared" 会禁用跨 Session 隔离。所有 Session 共享一个容器和一个 Workspace。

按 Agent 的 Sandbox 配置（多 Agent）

如果你使用多 Agent 路由,每个 Agent 可以覆盖 Sandbox 和工具设置: agents.list[].sandbox 和 agents.list[].tools（加上 agents.list[].tools.sandbox.tools）。这让你可以在一个 Gateway 中运行混合访问级别:

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

详见 Multi-Agent Sandbox & Tools 了解示例、优先级和故障排除。

默认行为

  • 镜像：openclaw-sandbox:bookworm-slim
  • 每个 Agent 一个容器
  • Agent Workspace 访问：workspaceAccess: "none"（默认）使用 ~/.openclaw/sandboxes
    • "ro" 保持 Sandbox Workspace 在 /workspace,并将 Agent Workspace 只读挂载到 /agent（禁用 write/edit/apply_patch）
    • "rw" 将 Agent Workspace 读写挂载到 /workspace
  • 自动清理：空闲 > 24 小时或年龄 > 7 天
  • 网络：默认为 none（如果需要出站流量需要明确选择）
  • 默认允许：exec、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
  • 默认拒绝：browser、canvas、nodes、cron、discord、gateway

启用 Sandbox

如果你计划在 setupCommand 中安装包,注意:

  • 默认 docker.network 是 "none"（无出站流量）。
  • readOnlyRoot: true 会阻止包安装。
  • user 必须是 root 才能用 apt-get（省略 user 或设置 user: "0:0"）。 当 setupCommand（或 docker 配置）改变时,OpenClaw 会自动重建容器,除非容器最近使用过（约 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。

多 Agent：通过 agents.list[].sandbox.{docker,browser,prune}.* 覆盖每个 Agent 的 agents.defaults.sandbox.{docker,browser,prune}.*（当 agents.defaults.sandbox.scope / agents.list[].sandbox.scope 是 "shared" 时会被忽略）。

构建默认 Sandbox 镜像

scripts/sandbox-setup.sh

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

Sandbox 通用镜像（可选）

如果你想要一个带常用构建工具（Node、Go、Rust 等）的 Sandbox 镜像,构建通用镜像:

scripts/sandbox-common-setup.sh

这会构建 openclaw-sandbox-common:bookworm-slim。使用它:

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

Sandbox 浏览器镜像

要在 Sandbox 内运行浏览器工具,构建浏览器镜像:

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 提供显示。

使用配置:

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

自定义浏览器镜像:

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

启用后,Agent 会收到:

  • Sandbox 浏览器控制 URL（用于 browser 工具）
  • noVNC URL（如果启用且 headless=false）

记住：如果你对工具使用白名单,添加 browser（并从拒绝列表中移除它）否则工具会被阻止。清理规则（agents.defaults.sandbox.prune）也适用于浏览器容器。

自定义 Sandbox 镜像

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

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

工具策略（允许/拒绝）

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

清理策略

两个选项:

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

示例:

  • 保留繁忙的 Session 但限制生命周期: idleHours: 24、maxAgeDays: 7
  • 永不清理: idleHours: 0、maxAgeDays: 0

安全注意事项

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

故障排除

  • 镜像缺失：用 scripts/sandbox-setup.sh 构建或设置 agents.defaults.sandbox.docker.image。
  • 容器未运行：它会按需为每个 Session 自动创建。
  • Sandbox 中的权限错误：设置 docker.user 为与挂载的 Workspace 所有权匹配的 UID:GID（或 chown Workspace 文件夹）。
  • 找不到自定义工具：OpenClaw 用 sh -lc（登录 shell）运行命令,它会加载 /etc/profile 并可能重置 PATH。设置 docker.env.PATH 来添加你的自定义工具路径（例如 /custom/bin:/usr/local/share/npm-global/bin）,或在 Dockerfile 中的 /etc/profile.d/ 下添加脚本。