环境准备

必要条件

• Docker 24+ 和 Docker Compose v2
• Node.js 24 (推荐) 或 Node.js 22.16+
• 8GB+ RAM
• 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 远程调试地址和 VNC 配置：

# 修改 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 官方文档