OpenClaw Docker Compose 部署实战指南

2026-06-17阅读 0热度 0

OpenClaw

部署 OpenClaw 的 Docker Compose 版本，表面上一行命令就能搞定，实际操作过的人都知道，隐蔽的坑点不少：镜像拉不下来、内置飞书扩展干扰运行、浏览器里中文显示为方块、远程调试端口无法连接。下面直接从环境配置切入，逐条拆解这些典型故障，带你完整跑通整个容器化部署流程。

环境准备

前置要求

Docker 24+ 和 Docker Compose v2
Node.js 24（推荐）或 Node.js 22.16+
8GB+ 内存
20GB+ 可用磁盘空间

克隆仓库并切换分支

git clone https://github.com/openclaw/openclaw.git
cd openclaw
git checkout v2026.4.2

修复 Dockerfile 中的几个关键问题

问题一：Dockerfile 基础镜像拉取失败

若遇到如下报错：

ERROR: failed to solve: failed to resolve source metadata for docker.io/docker/dockerfile:1.7

手动拉取缺失的镜像即可解决：

docker pull docker/dockerfile:1.7

问题二：移除内置飞书扩展

打开 Dockerfile，定位到 USER node 行，在其后立即添加删除飞书扩展的指令：

USER node
RUN rm -rf /app/extensions/feishu

问题三：浏览器镜像添加中文字体支持

编辑 Dockerfile.sandbox-browser，在 apt-get install 段中追加中文字体包：

RUN apt-get update websockify x11vnc xvfb fonts-noto-cjk fonts-wqy-zenhei && rm -rf /var/lib/apt/lists/*

问题四：开放 Chrome 远程调试端口

修改 scripts/sandbox-browser-entrypoint.sh，两处调整：

# 修改 Chrome 远程调试地址
CHROME_ARGS+=("-"--remote-debugging-address=127.0.0.1"
+"--remote-debugging-address=0.0.0.0" "--remote-debugging-port=${CHROME_CDP_PORT}" "--user-data-dir=${HOME}/.chrome" "--no-first-run" # ... 其他参数)

# 修改 VNC 配置，允许非本地连接
- x11vnc -display :1 -rfbport "${VNC_PORT}" -shared -forever -rfbauth "${NOVNC_PASSWD_FILE}" -localhost &
+ x11vnc -display :1 -rfbport "${VNC_PORT}" -shared -forever -rfbauth "${NOVNC_PASSWD_FILE}" &

构建镜像

构建 OpenClaw CLI 和 Gateway 镜像

./docker-setup.sh

构建浏览器镜像

上述修改全部生效后，执行以下命令构建浏览器镜像：

./scripts/sandbox-browser-setup.sh

配置 Docker Compose

添加浏览器服务

在 docker-compose.yml 的 services 区块中插入以下配置：

services:
  openclaw-browser:
    image: ${OPENCLAW_BROWSER_IMAGE:-openclaw-sandbox-browser:bookworm-slim}
    user: root
    container_name: ${OPENCLAW_BROWSER_CONTAINER_NAME:-openclaw-chrome-vnc}
    environment:
      DISPLAY: ":1"
      HEADLESS: "0"
      OPENCLAW_BROWSER_NOVNC_PASSWORD: ${OPENCLAW_BROWSER_VNC_PASSWORD:-12345678}
      OPENCLAW_BROWSER_CDP_PORT: 9222
      OPENCLAW_BROWSER_NO_SANDBOX: 1
    privileged: true
    ports:
      - "${OPENCLAW_BROWSER_VNC_PORT:-5901}:5900"
      - "${OPENCLAW_BROWSER_NOVNC_PORT:-6080}:6080"
      - "${OPENCLAW_BROWSER_CDP_PORT:-9222}:9222"
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "wget", "--spider", "-q", "http://localhost:6080" ]
      interval: 30s
      timeout: 5s

配置环境变量（可选）

若希望避免每次修改端口，可创建 .env 文件固化参数：

OPENCLAW_BROWSER_IMAGE=openclaw-sandbox-browser:bookworm-slim
OPENCLAW_BROWSER_CONTAINER_NAME=openclaw-chrome-vnc
OPENCLAW_BROWSER_VNC_PASSWORD=12345678
OPENCLAW_BROWSER_VNC_PORT=5901
OPENCLAW_BROWSER_NOVNC_PORT=6080
OPENCLAW_BROWSER_CDP_PORT=9222

启动服务

启动所有容器

docker compose up -d

查看服务运行状态

docker compose ps

实时查看日志

docker compose logs -f

访问服务

部署完成后，通过以下地址访问各组件：

服务	地址	默认端口
OpenClaw Gateway	http://localhost:18789	18789
VNC 远程桌面	http://localhost:6080	6080
Chrome 调试端口	localhost:9222	9222

VNC 登录密码

默认密码：12345678

故障排除

常见问题

1. 镜像拉取失败

docker pull docker/dockerfile:1.7
docker pull docker/dockerfile:1.7@sha256:9ffd88ccead317bc2062a9b3d311357d4c645e01c751a7c286928e17c3e88f64

2. 中文字体显示异常

确认 Dockerfile.sandbox-browser 中已包含以下字体包：

fonts-noto-cjk
fonts-wqy-zenhei

3. Chrome 调试连接失败

检查 scripts/sandbox-browser-entrypoint.sh 中 CHROME_ARGS 的地址是否为 0.0.0.0 而非 127.0.0.1。

4. VNC 连接被拒绝

确保 x11vnc 启动参数中已移除 -localhost 选项。

检查容器健康状态

docker compose ps
docker inspect openclaw-browser | grep -A 10 Health

卸载

docker compose down
docker rmi openclaw-sandbox-browser:bookworm-slim

参考链接

OpenClaw 官方 GitHub
OpenClaw 官方文档