使用 Docker 快速部署 OpenClaw 教程

          
          2026-03-06 10:30        

          
          技术部        

← 返回

OpenClaw 官方从早期版本起就提供了优秀的 Docker 支持，尤其适合追求隔离性、便于迁移、24/7 运行在服务器上的用户。Docker 部署的最大优势在于：

环境干净，不污染宿主机
易于升级、回滚
支持沙箱（sandbox）模式，进一步隔离高危操作
一键 onboarding + 自动生成 token

本文基于官方仓库（github.com/openclaw/openclaw）的 docker-setup.sh + docker-compose.yml + Dockerfile，提供最简、最稳定的部署路径。适用于 Linux 服务器、Mac（Docker Desktop）、Windows（WSL2 / Docker Desktop）。

一、前置要求（5分钟检查）

Docker ≥ 24.0+（推荐最新稳定版）
Docker Compose ≥ v2.0+（现代版 compose 插件）
至少 4GB 可用内存（本地模型建议 8GB+）
磁盘 ≥ 20GB（含镜像、数据卷、浏览器缓存）
网络正常（首次构建/拉取镜像需要）

快速验证：

Bash

docker --version
docker compose version   # 注意是 compose，不是旧的 docker-compose

二、最推荐方式：使用官方 docker-setup.sh 一键脚本（强烈建议）

官方提供了 docker-setup.sh 脚本，它会自动完成构建、onboarding、token 生成、启动等全流程。

克隆官方仓库（包含所有 Docker 文件）

Bash

git clone https://github.com/openclaw/openclaw.git
cd openclaw

（可选）使用预构建镜像加速（跳过本地构建，推荐首次慢或服务器性能弱时用）
Bash
export OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest # 或指定特定 tag，如 :2026.3.x
执行一键脚本
Bash
chmod +x docker-setup.sh ./docker-setup.sh
脚本会依次执行：
- 构建（或拉取）镜像 openclaw:local 或指定的远程镜像
- 运行 openclaw onboard 向导（交互式配置模型、渠道、安全等）
- 生成 Gateway Token 并写入 .env
- 启动 docker compose up -d openclaw-gateway
- 输出 Dashboard 地址（默认 http://localhost:18789）

验证运行状态

Bash

docker compose ps
docker logs openclaw-openclaw-gateway-1   # 容器名通常是 openclaw-openclaw-gateway-1

看到类似 “Gateway listening on 0.0.0.0:18789” 即成功。

三、docker-compose.yml 核心配置解析（官方默认版）

官方的 docker-compose.yml（位于仓库根目录）大致结构如下（2026.3 版本关键点）：

YAML

services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    container_name: openclaw-gateway
    restart: unless-stopped
    ports:
      - "18789:18789"           # Web Dashboard & API
      - "18790:18790"           # Bridge / MCP (可选)
    volumes:
      - openclaw-data:/root/.openclaw   # 持久化配置、Memory、Skills
      - ./workspace:/workspace          # 项目工作目录（开发用）
      # 可选沙箱相关挂载（2026新增）
      - /var/run/docker.sock:/var/run/docker.sock:ro   # 如启用 sandbox
    environment:
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      # 其他可选：OPENCLAW_READ_ONLY=true 等
    # 可选：启用 sandbox 支持（高危操作隔离）
    # cap_add: ["SYS_ADMIN"] 等（视需求）

volumes:
  openclaw-data:

常用自定义修改建议：

改端口：- "8080:18789" → 外部访问 http://你的IP:8080
持久化工作目录：- /home/user/projects:/workspace
启用沙箱（推荐生产）：参考官方 docs/install/docker.md 中的 sandbox 叠加 compose 文件
加网络模式：network_mode: host（浏览器工具更稳定，但牺牲隔离）

四、手动部署流程（了解原理或自定义时用）

如果不想用脚本，可手动操作：

构建镜像

Bash

docker build -t openclaw:local -f Dockerfile .

首次初始化 & onboarding

Bash

docker compose run --rm openclaw-cli onboard
# 或指定远程镜像
docker compose run --rm -e OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest openclaw-cli onboard

启动 Gateway
Bash
docker compose up -d openclaw-gateway

五、常见 Docker 部署坑 & 解决（高频问题）

权限问题（EACCES mkdir /root/.openclaw）
- 预创建卷并 chown
  Bash
  
  mkdir -p ~/openclaw-data sudo chown -R $USER:$USER ~/openclaw-data
- 然后在 compose 中 volumes: - ~/openclaw-data:/root/.openclaw
浏览器工具（Puppeteer/Playwright）失败
- Linux 宿主机需安装 chromium 依赖（容器内通常已含，但 host 代理更好）
- 或启用 sandbox 模式挂载 /dev/shm 等
onboarding 卡住 / token 未生成
- 进容器手动 onboarding：
  Bash
  
  docker compose exec openclaw-gateway bash openclaw onboard
网络问题（Telegram/WhatsApp 收不到）
- 尝试 network_mode: host
- 或确认端口 18789 是否被防火墙挡（ufw allow 18789）

升级 OpenClaw

Bash

git pull
docker compose down
./docker-setup.sh   # 或 docker compose build --no-cache
docker compose up -d

六、进阶玩法推荐

本地模型（Ollama）：另起 ollama 容器，onboarding 时填 http://host.docker.internal:11434
沙箱模式：启用 Docker-in-Docker 或官方 sandbox 支持，限制 Agent 执行权限
远程访问：用 Nginx/Caddy 反代 18789 + HTTPS + Basic Auth
多实例：复制 compose 文件，改 container_name / ports / volumes

七、结语

使用 ./docker-setup.sh 是目前最省心、最接近官方推荐的 Docker 部署方式，通常 5–15 分钟即可跑通完整流程。完成后，你就拥有了一个隔离、可迁移、随时可销毁重来的 OpenClaw Gateway。

官方文档参考：https://docs.openclaw.ai/install/docker 遇到问题欢迎去 GitHub Issues 或 Discord 贴日志排查。