Docker(可选)

Docker 是可选的。仅在您需要容器化网关或验证 Docker 流程时使用。

Docker 适合我吗?

适合:您想要一个隔离的、一次性的网关环境,或在没有本地安装的主机上运行 OpenClaw。
不适合:您在自己的机器上运行,只想要最快的开发循环。请使用正常的安装流程。
沙箱说明:Agent 沙箱也使用 Docker,但不要求完整网关在 Docker 中运行。参见沙箱。

本指南涵盖:

容器化网关(完整的 OpenClaw 在 Docker 中)
按会话的 Agent 沙箱(主机网关 + Docker 隔离的 agent 工具)

沙箱详情:沙箱

要求

Docker Desktop(或 Docker Engine)+ Docker Compose v2
足够的磁盘空间用于镜像和日志

容器化网关(Docker Compose)

快速开始(推荐)

从仓库根目录:

bash

./docker-setup.sh

此脚本:

构建网关镜像
运行入门向导
打印可选的提供商设置提示
通过 Docker Compose 启动网关
生成网关令牌并写入 .env

可选环境变量:

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

完成后:

在浏览器中打开 http://127.0.0.1:18789/。
将令牌粘贴到控制 UI(设置 → 令牌)。
需要再次获取令牌化 URL?运行 docker compose run --rm openclaw-cli dashboard --no-open。

它在主机上写入 config/workspace:

~/.openclaw/
~/.openclaw/workspace

在 VPS 上运行?参见 Hetzner(Docker VPS)。

手动流程(compose)

bash

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 时需包含它:

bash

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

控制 UI 令牌 + 配对(Docker)

如果您看到"未授权"或"断开连接(1008):需要配对",请获取新的仪表板链接并批准浏览器设备:

bash

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 绑定挂载列表, 并通过生成 docker-compose.extra.yml 将它们应用到 openclaw-gateway 和 openclaw-cli。

示例:

bash

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/node 在容器重建后持久化,通过 OPENCLAW_HOME_VOLUME 设置命名卷。这会创建一个 Docker 卷并将其挂载到 /home/node,同时保留标准的 config/workspace 绑定挂载。这里使用命名卷(不是绑定路径);对于绑定挂载,使用 OPENCLAW_EXTRA_MOUNTS。

示例:

bash

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

您可以将此与额外挂载结合使用:

bash

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。这会在镜像构建期间安装包,因此即使容器被删除它们也会持久化。

示例:

bash

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 浏览器

如果您想要功能更完整的容器,使用这些选择加入选项:

持久化 /home/node 以便浏览器下载和工具缓存保留:

bash

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

将系统依赖项烘焙到镜像中(可重复 + 持久):

bash

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

在没有 npx 的情况下安装 Playwright 浏览器(避免 npm 覆盖冲突):

bash

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

如果您需要 Playwright 安装系统依赖项,使用 OPENCLAW_DOCKER_APT_PACKAGES 重建镜像, 而不是在运行时使用 --with-deps。

持久化 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 主机):

bash

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

如果您为了方便选择以 root 运行,您接受安全权衡。

更快的重建(推荐)

为了加速重建,安排您的 Dockerfile 使依赖层被缓存。这避免重新运行 pnpm install,除非锁文件更改:

dockerfile

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"]

频道设置(可选)

使用 CLI 容器配置频道,然后根据需要重启网关。

WhatsApp(QR):

bash

docker compose run --rm openclaw-cli channels login

Telegram(机器人令牌):

bash

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

Discord(机器人令牌):

bash

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 并粘贴回向导以完成身份验证。

健康检查

bash

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

E2E 冒烟测试(Docker)

bash

scripts/e2e/onboard-docker.sh

QR 导入冒烟测试(Docker)

bash

pnpm test:docker:qr

注意事项

网关绑定默认为 lan 用于容器使用。
Dockerfile CMD 使用 --allow-unconfigured;带有 gateway.mode 的挂载配置(而非 local)仍会启动。覆盖 CMD 以强制执行守护。
网关容器是会话(~/.openclaw/agents/<agentId>/sessions/)的真实来源。

Agent 沙箱(主机网关 + Docker 工具)

深入了解:沙箱

它的作用

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

作用域:默认为 "agent"(每个 agent 一个容器 + 工作区)
作用域:"session" 用于按会话隔离
按作用域的工作区文件夹挂载在 /workspace
可选的 agent 工作区访问(agents.defaults.sandbox.workspaceAccess)
允许/拒绝工具策略(拒绝优先)
入站媒体复制到活动沙箱工作区(media/inbound/*)以便工具可以读取它(使用 workspaceAccess: "rw"时,这会放入 agent 工作区)

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

按 agent 的沙箱配置文件(多 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(如需出站流量需明确选择加入)
默认允许: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"(无出站流量)。
readOnlyRoot: true 阻止包安装。
user 必须是 root 才能使用 apt-get(省略 user 或设置 user: "0:0")。当 setupCommand(或 docker 配置)更改时,OpenClaw 会自动重建容器, 除非容器最近使用过(约 5 分钟内)。热容器会记录警告并显示确切的 openclaw sandbox recreate ... 命令。

json5

{
  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" 时忽略)。

构建默认沙箱镜像

bash

scripts/sandbox-setup.sh

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

沙箱通用镜像(可选)

如果您想要一个包含常见构建工具(Node、Go、Rust 等)的沙箱镜像,构建通用镜像:

bash

scripts/sandbox-common-setup.sh

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

json5

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

沙箱浏览器镜像

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

bash

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

使用配置:

json5

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

自定义浏览器镜像:

json5

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

启用后,agent 收到:

一个沙箱浏览器控制 URL(用于 browser 工具)
一个 noVNC URL(如果启用且 headless=false)

记住:如果您对工具使用允许列表,添加 browser(并从拒绝列表中移除) 否则工具仍被阻止。清理规则(agents.defaults.sandbox.prune)也适用于浏览器容器。

自定义沙箱镜像

构建您自己的镜像并将配置指向它:

bash

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

json5

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

工具策略(允许/拒绝)

deny 优先于 allow。
如果 allow 为空:所有工具(除了拒绝的)都可用。
如果 allow 非空:只有 allow 中的工具可用(减去拒绝的)。

清理策略

两个选项:

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/ 下添加脚本。

Docker(可选) ​

Docker 适合我吗? ​

要求 ​

容器化网关(Docker Compose) ​

快速开始(推荐) ​

手动流程(compose) ​

控制 UI 令牌 + 配对(Docker) ​

额外挂载(可选) ​

持久化整个容器主目录(可选) ​

安装额外的 apt 包(可选) ​

高级用户/功能完整容器(选择加入) ​

权限 + EACCES ​

更快的重建(推荐) ​

频道设置(可选) ​

OpenAI Codex OAuth(无头 Docker) ​

健康检查 ​

E2E 冒烟测试(Docker) ​

QR 导入冒烟测试(Docker) ​

注意事项 ​

Agent 沙箱(主机网关 + Docker 工具) ​

它的作用 ​

按 agent 的沙箱配置文件(多 agent) ​

默认行为 ​

启用沙箱 ​

构建默认沙箱镜像 ​

沙箱通用镜像(可选) ​

沙箱浏览器镜像 ​

自定义沙箱镜像 ​

工具策略(允许/拒绝) ​

清理策略 ​

安全注意事项 ​

故障排除 ​

Docker(可选)

Docker 适合我吗?

要求

容器化网关(Docker Compose)

快速开始(推荐)

手动流程(compose)

控制 UI 令牌 + 配对(Docker)

额外挂载(可选)

持久化整个容器主目录(可选)

安装额外的 apt 包(可选)

高级用户/功能完整容器(选择加入)

权限 + EACCES

更快的重建(推荐)

频道设置(可选)

OpenAI Codex OAuth(无头 Docker)

健康检查

E2E 冒烟测试(Docker)

QR 导入冒烟测试(Docker)

注意事项

Agent 沙箱(主机网关 + Docker 工具)

它的作用

按 agent 的沙箱配置文件(多 agent)

默认行为

启用沙箱

构建默认沙箱镜像

沙箱通用镜像(可选)

沙箱浏览器镜像

自定义沙箱镜像

工具策略(允许/拒绝)

清理策略

安全注意事项

故障排除