Docker（可选）

Docker 是可选的。只有当你希望使用容器化 gateway，或需要验证 Docker 流程时才使用它。

Docker 适合我吗？

• 是：你想要一个隔离、可随时丢弃的 gateway 环境，或想在不进行本地安装的主机上运行 OpenClaw。
• 否：你在自己的机器上运行，只想要最快的开发循环。请走普通安装流程。
• Sandboxing 说明：agent sandboxing 也会用 Docker，但它不要求把整个 gateway 运行在 Docker 内。见 Sandboxing。

本指南覆盖：

• Containerized Gateway（把完整 OpenClaw 运行在 Docker 内）
• Per-session Agent Sandbox（宿主机 gateway + Docker 隔离 agent tools）

Sandboxing 细节：Sandboxing

依赖

• Docker Desktop（或 Docker Engine）+ Docker Compose v2
• 足够的磁盘空间用于镜像与日志

Containerized Gateway（Docker Compose）

快速开始（推荐）

在仓库根目录运行：

./docker-setup.sh

该脚本会：

• 构建 gateway image
• 运行 onboarding wizard
• 打印可选的 provider setup 提示
• 通过 Docker Compose 启动 gateway
• 生成一个 gateway token 并写入 .env

可选环境变量：

• OPENCLAW_DOCKER_APT_PACKAGES — 在 build 过程中安装额外 apt 包
• OPENCLAW_EXTRA_MOUNTS — 添加额外的宿主机 bind mounts
• OPENCLAW_HOME_VOLUME — 用 named volume 持久化 /home/node

执行完成后：

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

它会把 config/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 compose ...。如果你启用了 OPENCLAW_EXTRA_MOUNTS 或 OPENCLAW_HOME_VOLUME，setup 脚本会生成 docker-compose.extra.yml；在其他位置运行 Compose 时请把它也带上：

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

Control UI token + pairing（Docker）

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

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、Devices。

Extra mounts（可选）

如果你想把额外的宿主机目录挂载进容器，请在运行 docker-setup.sh 前设置 OPENCLAW_EXTRA_MOUNTS。 它接受逗号分隔的 Docker bind mounts 列表，并通过生成 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 以重新生成 extra compose 文件。
• docker-compose.extra.yml 是自动生成的，不要手工编辑。

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

如果你希望 /home/node 在容器重建后仍保留，使用 OPENCLAW_HOME_VOLUME 设置一个 named volume。 它会创建一个 Docker volume 并挂载到 /home/node，同时保留标准的 config/workspace bind mounts。 这里请使用 named volume（不是 bind path）；bind mounts 请用 OPENCLAW_EXTRA_MOUNTS。

示例：

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

你可以与 extra mounts 组合使用：

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 以重新生成 extra compose 文件。
• named volume 会一直存在，直到你运行 docker volume rm <name> 移除。

安装额外 apt 包（可选）

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

示例：

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

注意：

• 该变量接受用空格分隔的 apt 包名。
• 如果你修改了 OPENCLAW_DOCKER_APT_PACKAGES，需要重新运行 docker-setup.sh 以重建 image。

Power-user / 全功能容器（opt-in）

默认 Docker image 是 security-first：以非 root 的 node 用户运行。 这能缩小攻击面，但也意味着：

• 运行时无法安装系统包
• 默认不提供 Homebrew
• 不内置 Chromium/Playwright browsers

如果你想要更“全功能”的容器，可使用这些 opt-in 开关：

1）持久化 /home/node：让浏览器下载与 tool caches 得以保留：

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

2）把系统依赖烘焙进镜像（可重复、可持久）：

export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh

3）不用 npx 安装 Playwright browsers（避免 npm override 冲突）：

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

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

4）持久化 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 上看到权限错误，请确保宿主机 bind mounts 的所有者为 uid 1000。

示例（Linux host）：

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

如果你为了方便选择以 root 运行，就需要自行接受安全权衡。

更快的重建（推荐）

为了加快重建，请把 Dockerfile 按依赖层可缓存的方式排序。 这样除非 lockfiles 变化，否则不必重复跑 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 容器配置 channels，必要时重启 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

OpenAI Codex OAuth（headless Docker）

如果你在 wizard 里选择 OpenAI Codex OAuth，它会打开一个浏览器 URL，并尝试在 http://127.0.0.1:1455/auth/callback 捕获 callback。 在 Docker 或 headless 环境下，这个 callback 可能在浏览器里报错。 请把你最终落到的完整 redirect URL 复制出来，并粘贴回 wizard，以完成鉴权。

健康检查

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

E2E smoke test（Docker）

scripts/e2e/onboard-docker.sh

QR import smoke test（Docker）

pnpm test:docker:qr

备注

• 为了容器使用，Gateway bind 默认是 lan。
• Dockerfile 的 CMD 使用 --allow-unconfigured；因此即使挂载的 config 中 gateway.mode 不是 local，也会启动。若要强制 guard，请覆盖 CMD。
• gateway container 是 sessions 的事实来源（~/.openclaw/agents/<agentId>/sessions/）。

Agent Sandbox（宿主机 gateway + Docker tools）

深入阅读：Sandboxing

它做什么

当启用 agents.defaults.sandbox 时，non-main sessions 会在 Docker 容器里运行 tools。 gateway 仍在宿主机上运行，但 tool execution 会被隔离：

• 默认 scope 为 "agent"（每个 agent 一个容器 + workspace）
• scope 为 "session" 可实现 per-session 隔离
• 按 scope 的 workspace 目录会挂载到 /workspace
• 可选的 agent workspace 访问（agents.defaults.sandbox.workspaceAccess）
• allow/deny 的 tool policy（deny 优先）
• 入站媒体会被复制到当前 sandbox workspace（media/inbound/*）以供 tools 读取（当 workspaceAccess: "rw" 时，会落到 agent workspace）

警告：scope: "shared" 会禁用跨 session 隔离。所有 sessions 会共享一个容器与一个 workspace。

Per-agent sandbox profiles（multi-agent）

如果你使用 multi-agent routing，每个 agent 都可以覆盖 sandbox + tools 设置： agents.list[].sandbox 与 agents.list[].tools（以及 agents.list[].tools.sandbox.tools）。 这样你可以在同一个 gateway 中混合不同权限级别：

• 全权限（个人 agent）
• 只读 tools + 只读 workspace（家庭/工作 agent）
• 无文件系统/shell tools（公共 agent）

示例、优先级与排障见 Multi-Agent Sandbox & Tools。

默认行为

• Image：openclaw-sandbox:bookworm-slim
• 每个 agent 一个容器
• Agent workspace access：workspaceAccess: "none"（默认）使用 ~/.openclaw/sandboxes
  • "ro"：sandbox workspace 位于 /workspace，并把 agent workspace 以只读方式挂载到 /agent（会禁用 write/edit/apply_patch）
  • "rw"：把 agent workspace 以读写方式挂载到 /workspace
• Auto-prune：idle > 24h 或 age > 7d
• Network：默认 none（需要出站时必须显式开启）
• Default allow：exec、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
• Default deny：browser、canvas、nodes、cron、discord、gateway

启用 sandboxing

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

• 默认 docker.network 是 "none"（无出站）。
• readOnlyRoot: true 会阻止包安装。
• apt-get 需要 root 用户（省略 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"],
      },
    },
  },
}

Hardening knobs 位于 agents.defaults.sandbox.docker 下： network、user、pidsLimit、memory、memorySwap、cpus、ulimits、 seccompProfile、apparmorProfile、dns、extraHosts。

Multi-agent：可通过 agents.list[].sandbox.{docker,browser,prune}.* 为每个 agent 覆盖 agents.defaults.sandbox.{docker,browser,prune}.* （当 agents.defaults.sandbox.scope / agents.list[].sandbox.scope 为 "shared" 时会被忽略）。

构建默认 sandbox image

scripts/sandbox-setup.sh

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

Sandbox common image（可选）

如果你希望 sandbox image 内带常见构建工具（Node、Go、Rust 等），可构建 common image：

scripts/sandbox-common-setup.sh

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

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

Sandbox browser image

要在 sandbox 内运行 browser tool，请构建 browser image：

scripts/sandbox-browser-setup.sh

它会使用 Dockerfile.sandbox-browser 构建 openclaw-sandbox-browser:bookworm-slim。 该容器运行启用了 CDP 的 Chromium，并提供可选的 noVNC observer（通过 Xvfb 以 headful 方式运行）。

注意：

• Headful（Xvfb）相比 headless 更不容易被 bot blocking。
• 仍可通过设置 agents.defaults.sandbox.browser.headless=true 使用 headless。
• 不需要完整桌面环境（GNOME）；Xvfb 提供 display。

配置示例：

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

自定义 browser image：

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

启用后，agent 会收到：

• sandbox browser control URL（供 browser tool 使用）
• noVNC URL（当启用且 headless=false）

记住：如果你使用 tool allowlist，请把 browser 加入 allow（并从 deny 中移除），否则该 tool 仍会被阻止。 prune 规则（agents.defaults.sandbox.prune）也会应用到 browser containers。

自定义 sandbox image

构建你自己的 image，并在 config 中指向它：

docker build -t my-openclaw-sbx -f Dockerfile.sandbox .

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

Tool policy（allow/deny）

• deny 优先于 allow。
• 如果 allow 为空：除 deny 外的所有 tools 都可用。
• 如果 allow 非空：只有 allow 列表中的 tools 可用（再减去 deny）。

Pruning 策略

两个开关：

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

示例：

• 保留活跃 sessions 但限制生命周期：idleHours: 24、maxAgeDays: 7
• 永不 prune：idleHours: 0、maxAgeDays: 0

安全说明

• “硬墙”只对 tools 生效（exec/read/write/edit/apply_patch）。
• browser/camera/canvas 这类 host-only tools 默认被阻止。
• 在 sandbox 中允许 browser 会破坏隔离（browser 在宿主机运行）。

排障

• 镜像缺失：运行 scripts/sandbox-setup.sh 构建，或设置 agents.defaults.sandbox.docker.image。
• 容器未运行：会按 session 需求自动创建。
• sandbox 权限错误：将 docker.user 设为与你挂载的 workspace 所有权匹配的 UID:GID（或对 workspace 目录执行 chown）。
• 找不到自定义 tools：OpenClaw 用 sh -lc（login shell）运行命令，会 source /etc/profile 并可能重置 PATH。 通过 docker.env.PATH 前置你的自定义路径（例如 /custom/bin:/usr/local/share/npm-global/bin），或在 Dockerfile 里加入 /etc/profile.d/ 脚本。