Docker（可选）

Docker ?可选的*。仅在你想要容器化的 gateway 或验?Docker 流程时才使用?

Docker 适合我吗?

• **?*：你想要一个隔离的、可丢弃?gateway 环境，或者在没有本地安装的主机上运行 OpenClaw?
• **?*：你正在自己的机器上运行，只想要最快的开发循环。请改用正常的安装流程?
• 沙箱说明：代理沙箱也使用 Docker，但**不需?*完整?gateway ?Docker 中运行。参见沙箱?

本指南涵盖：

• 容器?Gateway（Docker 中的完整 OpenClaw?
• 每个会话的代理沙箱（主机 gateway + Docker 隔离的代理工具）

沙箱详情：沙箱

要求

• Docker Desktop（或 Docker Engine? Docker Compose v2
• 至少 2 GB RAM 用于镜像构建（pnpm install ?1 GB 主机上可能被 OOM 杀死，退出码 137?
• 足够的磁盘空间用于镜像和日志

容器?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 粘贴?Control UI（设??token）?
• 再次需?URL？运?docker compose run --rm openclaw-cli dashboard --no-open?

它在主机上写入配?工作区：

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

?VPS 上运行？参见 Hetzner（Docker VPS）?

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 辅助工具自述文件?

手动流程（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?

如果看到”未授??已断开连接?008）：需要配?，请获取新的 仪表板链接并批准浏览器设备：

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>

更多详情：仪表板、设备?

额外挂载（可选）

如果你想将额外的主机目录挂载到容器中，请在运?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 以重新生? 额外?compose 文件?
• docker-compose.extra.yml 是生成的。不要手动编辑它?

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

如果你希?/home/node 在容器重新创建后仍然保留，请通过 OPENCLAW_HOME_VOLUME 设置命名 卷。这会创建一?Docker 卷并将其挂载?/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 以重新生? 额外?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 以重新构? 镜像?

高级用户/全功能容器（可选加入）

默认 Docker 镜像**以安全为?*，以?root node 用户运行。这保持了较小的攻击面，但意味着?

• 运行时无法安装系统包
• 默认没有 Homebrew
• 没有捆绑?Chromium/Playwright 浏览?

如果你想要更全功能的容器，请使用这些可选配置：

1. 持久?`/home/node” 以便浏览器下载和工具缓存保留?

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

2. **将系统依赖烘焙到镜像?*（可重复 + 持久）：

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

3. 安装 Playwright 浏览器而不使用 npx（避?npm 覆盖冲突）：

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 上看到权限错误，请确保你的主机绑定挂载由 uid 1000 拥有?

示例（Linux 主机）：

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

如果你选择方便地以 root 运行，你需要接受安全权衡?

更快重新构建（推荐）

为了加速重新构建，请按缓存依赖层的顺序排列 Dockerfile? 这避免了在锁文件未更改时重新运行 pnpm install?

FROM node:22-bookworm

# 安装 Bun（构建脚本需要）
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# 缓存依赖，除非包元数据更?
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 容器配置频道，如需要则重启 gateway?

WhatsApp（QR）：

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 并将其粘贴回向导以完成认证?

健康检?

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

端到端冒烟测试（Docker?

scripts/e2e/onboard-docker.sh

QR 导入冒烟测试（Docker?

pnpm test:docker:qr

注意?

• Gateway 绑定默认?lan 用于容器使用?
• Dockerfile CMD 使用 --allow-unconfigured；挂载的配置带有 gateway.mode 不是 local 仍会启动。覆?CMD 以强制执行保护?
• Gateway 容器是会话的真实来源（~/.openclaw/agents/<agentId>/sessions/）?

代理沙箱（主?gateway + Docker 工具?

深入了解：沙箱

它做什?

?agents.defaults.sandbox 启用时，非主会话?Docker 容器内运行工具。gateway 保持在你的主机上，但工具执行是隔离的?

• 作用域：默认?"agent"（每个代理一个容?+ 工作区）
• 作用域："session" 用于每个会话隔离
• 每个作用域的工作区文件夹挂载?/workspace
• 可选的代理工作区访问（agents.defaults.sandbox.workspaceAccess?
• 允许/拒绝工具策略（拒绝优先）
• 入站媒体被复制到活动沙箱工作区（media/inbound/*），以便工具可以读取它（使用 workspaceAccess: "rw" 时，这会进入代理工作区）

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

每个代理的沙箱配置文件（多代理）

如果你使用多代理路由，每个代理可以覆盖沙?+ 工具设置? agents.list[].sandbox ?agents.list[].tools（加?agents.list[].tools.sandbox.tools）。这允许你在一?gateway 中运行混合访问级别：

• 完全访问（个人代理）
• 只读工具 + 只读工作区（家庭/工作代理?
• 无文件系?shell 工具（公共代理）

示例、优先级和故障排除参见多代理沙箱和工具?

默认行为

• 镜像：openclaw-sandbox:bookworm-slim
• 每个代理一个容?
• 代理工作区访问：workspaceAccess: "none"（默认）使用 ~/.openclaw/sandboxes
  • "ro" 将沙箱工作区保持?/workspace 并将代理工作区只读挂载在 /agent（禁?write/edit/apply_patch?
  • "rw" 将代理工作区读写挂载?/workspace
• 自动清理：空?> 24 小时或年?> 7 ?
• 网络：默?"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"）? ?setupCommand（或 docker 配置）更改时，OpenClaw 会自动重新创建容器， 除非容器?最近使用的*（在?5 分钟内）。热容器会记录警告， 其中包含确切?openclaw sandbox recreate … 命令?

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared（agent 是默认值）
        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 禁用空闲清理
          maxAgeDays: 7, // 0 禁用最大年龄清?
        },
      },
    },
  },
  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（仅用于打破玻璃）?

多代理：通过 agents.list[].sandbox.{docker,browser,prune}.* 为每个代理覆?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 中共享原始密码?

使用配置?

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

自定义浏览器镜像?

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

启用后，代理会收到：

• 沙箱浏览器控?URL（用?browser 工具?
• noVNC URL（如果启用且 headless=false?

请记住：如果你使用工具允许列表，请添?browser（并从拒绝中移除? 否则该工具仍被阻止? 清理规则（agents.defaults.sandbox.prune）也适用于浏览器容器?

自定义沙箱镜?

构建你自己的镜像并将配置指向它：

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 小时未使用的容器? = 禁用?
• prune.maxAgeDays：移除超?X 天的容器? = 禁用?

示例?

• 保持繁忙的会话但限制生命周期? idleHours: 24、maxAgeDays: 7
• 从不清理? idleHours: 0、maxAgeDays: 0

安全说明

• 硬墙仅适用?工具*（exec/read/write/edit/apply_patch）?
• 主机专用工具?browser/camera/canvas 默认被阻止?
• 在沙箱中允许 browser **会破坏隔?*（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/ 下的脚本?