OpenClaw Docker 安装指南

概述

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

Docker 适合我吗？

沙盒说明: Agent 沙盒也使用 Docker，但不需要完整的网关在 Docker 中运行。参见 Sandboxing。

要求

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

容器化网关（Docker Compose）

快速开始（推荐）

从仓库根目录运行：

./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（Settings → token）
• 需要再次获取 URL？运行 docker compose run --rm openclaw-cli dashboard --no-open

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

• ~/.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，设置脚本会写入 docker-compose.extra.yml；在其他地方运行 Compose 时包含它：

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

控制 UI 令牌 + 配对（Docker）

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

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。

额外挂载

如果想将额外的宿主机目录挂载到容器中，在运行 docker-setup.sh 之前设置 OPENCLAW_EXTRA_MOUNTS。这接受逗号分隔的 Docker 绑定挂载列表，并应用于 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/node，通过 OPENCLAW_HOME_VOLUME 设置命名卷。这创建了一个 Docker 卷并挂载在 /home/node，同时保持标准的 config/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 <volume> 删除之前一直存在。

系统包

如果需要在镜像中安装系统包（例如构建工具或媒体库），在运行 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

4. 持久化 Playwright 浏览器下载：

   • 在 docker-compose.yml 中设置 PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright
   • 确保 /home/node 通过 OPENCLAW_HOME_VOLUME 持久化，或通过 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 运行以方便使用，您接受安全风险。

频道设置（可选）

使用 CLI 容器配置频道，然后在需要时重新启动网关。

WhatsApp（QR）：

docker compose run --rm openclaw-cli channels login

Telegram（机器人令牌）：

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

Discord（机器人令牌）：

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"

相关文档

• Docker 安装
• Hetzner VPS 指南
• Sandboxing 文档

来源: https://docs.openclaw.ai/install/docker