一、什么是 Docker 方式部署 OpenClaw

OpenClaw 是开源 AI Agent 网关，提供工具调用、Checkpointer 会话持久化、多模型统一网关能力。 Docker 部署就是把 OpenClaw 连同 Node 运行环境打包进容器，做到环境隔离、一次配置到处运行。

• 官方镜像仓库：ghcr.io/openclaw/openclaw:latest（GHCR 官方镜像，优先使用）
• 对外网关端口：18789
• 持久化目录：容器内/home/node/.openclaw，存放openclaw.json配置、Checkpointer 会话快照、技能插件、工作区数据。

对比 WSL2/npm 全局部署：Docker 不需要宿主机安装 Node22，消除版本冲突；升级降级仅需要拉取镜像，配置数据通过卷挂载保留。

二、为什么选择 Docker 部署 OpenClaw

• 环境零污染：不需要宿主机安装 Node.js22，不会和本机其他 Node 项目版本冲突。
• 部署一致性：Windows (Docker Desktop)、WSL2、Linux 服务器、NAS，同一套 compose 配置直接运行。
• 数据持久化：卷挂载把配置、Checkpointer 会话快照存宿主机，容器删除重建数据不丢失openclaw-a...。
• 运维便捷：一键启停、版本升级简单；支持设置 CPU 内存资源限制，适合 VPS 服务器上线。
• 网络灵活：容器网络可以对接宿主机 Ollama 服务，也可以直接调用云端大模型 API。

注意坑：容器内部用户 uid=1000，挂载目录会出现权限拒绝 EACCES，需要修改宿主机目录属主，这是 docker 部署高频问题GitHub。

三、适合与不适合场景

适合场景

1. VPS 云服务器部署 OpenClaw 对外提供 Agent 网关服务；
2. Windows/macOS 不想在本机安装 Node22 环境；
3. 需要多套 OpenClaw 实例隔离运行；
4. NAS 容器平台部署；
5. 项目工程化，CI/CD 流水线。

不适合场景

1. 需要高频执行本地系统命令、访问宿主机大量本地文件；
2. 网络环境很差，无法拉取 ghcr 镜像。

四、Docker Compose 部署步骤

前置条件

• 已安装 Docker + Docker Compose
• 网络可以访问 ghcr.io 镜像仓库；
• 创建本地存放 OpenClaw 配置目录，例如./openclaw_data，用于挂载容器.openclaw目录。

步骤 1：编写 docker‑compose.yml

version: "3.8"

services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    environment:
      - NODE_ENV=production
      - HOME=/home/node
    volumes:
      # 持久化配置、checkpointer会话快照、工作区
      - ./openclaw_data:/home/node/.openclaw
    # 资源限制，服务器环境建议配置
    deploy:
      resources:
        limits:
          cpus: "2"
          memory: 2G
    healthcheck:
      test: ["CMD","curl","-f","http://127.0.0.1:18789/health"]
      interval:30s
      timeout:10s
      retries:3

步骤 2：处理目录权限（非常关键，防止 EACCES 报错）

容器内部运行用户 uid=1000，宿主机目录权限不匹配会报权限拒绝，无法写入 openclaw.json 和 Checkpointer

Linux/WSL2 执行：

mkdir -p ./openclaw_data
chown -R 1000:1000 ./openclaw_data

Windows Docker Desktop 一般不会出现权限报错，Linux 服务器必须执行上面命令。

步骤 3：执行初始化 onboard 向导

不要直接启动网关，先运行 cli 容器执行交互式初始化流程：

docker compose run --rm openclaw-gateway openclaw onboard --flow quickstart

交互式关键选项：

1. 网关模式：local（必须选 local，否则网关启动报错）
2. 模型提供商：可先跳过，后续修改openclaw.json
3. 是否安装守护进程：n（docker 环境不需要 systemd 守护）

初始化完成后，配置文件生成在宿主机./openclaw_data/openclaw.json。

步骤 4：修改 openclaw.json 配置文件

方案 A：对接阿里云百炼（国内云端模型）

编辑./openclaw_data/openclaw.json

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "host":"0.0.0.0"
  },
  "agents":{
    "defaults":{
      "model":"aliyun/qwen-plus",
      "temperature":0.7
    }
  },
  "models":{
    "providers":{
      "aliyun":{
        "apiKey":"你的dashscope api‑key",
        "baseUrl":"https://dashscope.aliyuncs.com/compatible-mode/v1",
        "api":"openai‑completions",
        "models":[
          {
            "id":"qwen‑plus",
            "name":"qwen‑plus",
            "contextWindow":128000
          }
        ]
      }
    }
  }
}

方案 B：容器访问宿主机 Ollama

docker 容器访问宿主机服务：

• Docker Desktop Windows/macOS：特殊 DNS host.docker.internal
• Linux 服务器：使用宿主机物理网卡 IP，不要使用 127.0.0.1

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "host":"0.0.0.0"
  },
  "agents":{
    "defaults":{
      "model":"ollama/qwen2.5:7b",
      "temperature":0.7
    }
  },
  "models":{
    "providers":{
      "ollama":{
        "apiKey":"dummy",
        "baseUrl":"http://host.docker.internal:11434/v1",
        "api":"openai‑completions",
        "models":[
          {
            "id":"qwen2.5:7b",
            "name":"qwen2.5‑7b",
            "contextWindow":32768
          }
        ]
      }
    }
  }
}

步骤 5：启动网关服务

#后台启动
docker compose up -d

#查看运行日志
docker compose logs -f openclaw-gateway

步骤 6：健康检查验证

curl http://127.0.0.1:18789/health

返回ok代表网关正常运行。浏览器访问http://127.0.0.1:18789打开控制面板。

常用运维命令

#进入容器执行openclaw命令
docker compose exec -it openclaw-gateway sh

#执行诊断工具
docker compose exec openclaw-gateway openclaw doctor --fix

#查看debug日志
docker compose exec openclaw-gateway openclaw logs --level debug

#版本升级
docker compose pull
docker compose up -d

#停止（数据保留在openclaw_data目录）
docker compose down