Skip to main content

​
Docker 部署 OpenClaw

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

​
Docker 适合我吗?

  • 适合:您想要一个隔离的、可丢弃的网关环境,或者需要在没有本地安装的主机上运行 OpenClaw
  • 不适合:您在自己的机器上运行,并且只想要最快的开发循环,应该使用正常的安装流程
  • 沙箱说明:agent 沙箱也使用 Docker,但不要求整个网关都运行在 Docker 中

​
系统需求

在开始之前,请确保您的系统满足以下要求:
  • Docker Desktop(或 Docker Engine) + Docker Compose v2
  • 镜像构建至少需要 2 GB 内存(1 GB 主机会因为内存不足被 pnpm install 进程以 exit 137 退出)
  • 足够的磁盘空间用于镜像和日志
  • 如果运行在 VPS/公共主机上,请查看网络暴露的安全加固

​
快速开始(推荐)

此处的 Docker 默认绑定模式假设为绑定模式(lan/loopback),而非主机别名。 请在 gateway.bind 中使用绑定模式值(例如 lan 或 loopback),不要使用主机别名如 0.0.0.0 或 localhost。
在仓库根目录执行: 
./docker-setup.sh
该脚本会:
1

构建镜像

在本地构建网关镜像(如果设置了 OPENCLAW_IMAGE,则拉取远程镜像)
2

运行向导

运行入门向导
3

启动网关

通过 Docker Compose 启动网关
4

生成令牌

生成网关令牌并写入 .env

​
可选环境变量

  • OPENCLAW_IMAGE — 使用远程镜像代替本地构建(例如 ghcr.io/openclaw/openclaw:latest)
  • OPENCLAW_DOCKER_APT_PACKAGES — 构建期间安装额外的 apt 软件包
  • OPENCLAW_EXTRA_MOUNTS — 添加额外的主机绑定挂载
  • OPENCLAW_HOME_VOLUME — 使用命名卷持久化 /home/node
  • OPENCLAW_SANDBOX — 选择启用 Docker 网关沙箱引导,仅当值明确为 1、true、yes、on 时启用
  • OPENCLAW_INSTALL_DOCKER_CLI — 本地镜像构建时的构建参数传递(1 表示在镜像中安装 Docker CLI)
  • OPENCLAW_DOCKER_SOCKET — 覆盖 Docker 套接字路径(默认使用 DOCKER_HOST=unix://... 或 /var/run/docker.sock)
完成后:
  1. 在浏览器打开 http://127.0.0.1:18789/
  2. 将令牌粘贴到控制界面(设置 → 令牌)
  3. 需要再次获取 URL?运行 docker compose run --rm openclaw-cli dashboard --no-open

​
基础镜像

主 Docker 镜像当前使用:
  • 基础镜像: node:22-bookworm
  • 摘要: sha256:cd7bcd2e7a1e6f72052feb023c7f6b722205d3fcab7bbcbd2d1bfdab10b1e935
镜像包含以下 OCI 注解:

​
使用远程镜像

官方预构建镜像发布于: 使用镜像名 ghcr.io/openclaw/openclaw。 常用标签:
  • main — main 分支的最新构建
  • <version> — 发布版本标签构建(例如 2026.2.26)
  • latest — 最新稳定发布标签

​
拉取远程镜像

默认情况下,设置脚本从源码构建镜像。若想拉取预构建镜像,请在运行脚本前设置 OPENCLAW_IMAGE: 
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh
脚本会检测到 OPENCLAW_IMAGE 非默认值 openclaw:local,改为执行 docker pull 而非 docker build。其余(入门、网关启动、令牌生成)流程相同。

​
Docker Compose 配置

​
服务说明

docker-compose.yml 定义了两个服务: 
services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    environment:
      HOME: /home/node
      TERM: xterm-256color
      OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
    ports:
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
    init: true
    restart: unless-stopped
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${OPENCLAW_GATEWAY_BIND:-lan}",
        "--port",
        "18789",
      ]

​
手动流程

如果您想手动运行: 
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,setup 脚本会写入 docker-compose.extra.yml,在其他命令中需一并包含:
docker compose -f docker-compose.yml -f docker-compose.extra.yml <命令>

​
附加挂载(可选)

若想在容器中挂载额外主机目录,可在运行 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 后需重新运行 setup 脚本生成新 compose 文件
  • docker-compose.extra.yml 为生成文件,不建议手动编辑

​
持久化容器 home 目录(可选)

如果希望 /home/node 在容器重建时保持持久,设置命名卷 OPENCLAW_HOME_VOLUME。这会创建 Docker 卷,并挂载到 /home/node,同时保留标准配置/工作区绑定挂载。 示例: 
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 后需重新运行 setup 脚本
  • 命名卷会一直存在,直到使用 docker volume rm <name> 删除

​
健康检查

容器探针端点(无需认证): 
curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz
别名:/health 和 /ready。 Docker 镜像内置 HEALTHCHECK,后台定期 ping /healthz,Docker 通过检测 OpenClaw 响应性维护容器状态。若多次失败,Docker 标记容器为 unhealthy,容器编排系统(Docker Compose 重启策略、Swarm、Kubernetes 等)可自动重启或替换。

​
故障排查

​
权限问题

镜像以 node 用户(uid 1000)运行。若看到 /home/node/.openclaw 权限错误,请确保主机绑定挂载的目录归属 uid 1000。 示例(Linux 主机): 
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

​
局域网 vs loopback

docker-setup.sh 默认将 OPENCLAW_GATEWAY_BIND=lan,使主机能够通过 Docker 端口映射访问 http://127.0.0.1:18789。
  • lan(默认):主机浏览器和 CLI 可以访问发布的网关端口
  • loopback:仅容器内网络命名空间内的进程可访问网关,主机端口映射可能失效
若从 Docker CLI 命令看到 Gateway target: ws://172.x.x.x:18789 或多次出现 pairing required 错误,运行: 
docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

​
下一步

配置

配置您的 OpenClaw 实例

环境变量

了解环境变量配置