OpenClaw Docker 部署完全指南 2026：从零到运行只需 5 分钟

Docker 部署 OpenClaw 有两个核心优势：环境隔离和一键复现。无论你是本地开发还是服务器部署，这篇教程帮你搞定。

为什么用 Docker 部署？

对比项	Docker 部署	本地安装
环境隔离	✅ 完全隔离	❌ 可能冲突
部署速度	⚡ 5 分钟	10-30 分钟
环境复现	✅ 完全一致	❌ 环境差异
清理卸载	✅ 一键删除	手动清理
更新维护	✅ 拉取新镜像	重新安装

Docker 部署适合你，如果：

• 想要隔离的测试环境
• 在服务器上部署（无本地安装环境）
• 需要快速复现相同环境
• 多人协作，统一环境

本地安装更适合，如果：

• 日常开发调试
• 需要最快响应速度
• 频繁修改配置

---

方案一：Docker Compose 一键部署（推荐）

这是最简单的方式，适合 90% 的用户。

Step 1：安装 Docker 和 Docker Compose

Windows：

下载 Docker Desktop，双击安装即可。

Mac：

brew install --cask docker

Linux（Ubuntu/Debian）：

# 安装 Docker
curl -fsSL https://get.docker.com | sh

# 安装 Docker Compose
sudo apt install docker-compose-plugin

# 将当前用户加入 Docker 组
sudo usermod -aG docker $USER
newgrp docker

验证安装：

docker --version
docker compose version

---

Step 2：创建项目目录

# 创建目录
mkdir -p ~/openclaw-docker
cd ~/openclaw-docker

# 创建数据目录
mkdir -p data

---

Step 3：创建 docker-compose.yml

在 ~/openclaw-docker 目录下创建 docker-compose.yml 文件：

version: '3.8'

services:
  openclaw:
    image: openclaiai/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "1878:1878"      # Web 控制台
      - "18789:18789"    # 内部通信
    volumes:
      - ./data:/root/.openclaw  # 数据持久化
    environment:
      - OPENCLAW_VERBOSE=0      # 详细日志（调试时改为 1）

配置说明：

配置项	说明
image	官方镜像，latest 为最新版
ports	端口映射，格式为 宿主机:容器
volumes	数据持久化，配置文件保存在宿主机
restart	自动重启策略

---

Step 4：启动服务

# 启动（后台运行）
docker compose up -d

# 查看日志
docker compose logs -f

# 查看容器状态
docker compose ps

---

Step 5：访问控制台

浏览器打开：

http://localhost:1878

首次访问需要生成 Token：

# 进入容器生成 Token
docker exec -it openclaw openclaw token generate

# 或直接访问（会自动跳转到登录页）
http://localhost:1878/?token=生成的token

---

Step 6：配置模型

进入容器配置 API Key：

# 进入容器
docker exec -it openclaw /bin/bash

# 配置 API Key
openclaw config set models.providers.openai.apiKey "sk-xxxxx"

# 设置默认模型
openclaw config set agents.defaults.model.primary "openai/gpt-4o"

# 退出容器
exit

或直接在 docker-compose.yml 中配置环境变量：

environment:
  - OPENAI_API_KEY=sk-xxxxx

---

方案二：手动 Docker 部署

适合需要精细控制的用户。

Step 1：拉取镜像

# 拉取最新镜像
docker pull openclaiai/openclaw:latest

# 查看镜像
docker images | grep openclaw

Step 2：运行容器

docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 1878:1878 \
  -p 18789:18789 \
  -v $(pwd)/data:/root/.openclaw \
  openclaiai/openclaw:latest

参数说明：

参数	说明
-d	后台运行
--name	容器名称
--restart	重启策略
-p	端口映射
-v	数据卷挂载

---

数据持久化详解

为什么需要持久化？

Docker 容器删除后，内部数据会丢失。持久化把数据保存在宿主机，容器重建后配置仍在。

持久化哪些数据？

数据	路径	说明
配置文件	/root/.openclaw/openclaw.json	Agent、模型配置
Token 文件	/root/.openclaw/token	访问凭证
Skills 目录	/root/.openclaw/skills/	已安装技能
日志文件	/root/.openclaw/logs/	运行日志

备份与恢复

备份：

# 备份数据目录
tar -czvf openclaw-backup-$(date +%Y%m%d).tar.gz ./data

恢复：

# 解压备份
tar -xzvf openclaw-backup-20260408.tar.gz

# 重启容器（会自动加载数据）
docker compose restart

---

常用命令速查

容器管理

# 启动
docker compose up -d

# 停止
docker compose down

# 重启
docker compose restart

# 查看日志
docker compose logs -f

# 进入容器
docker exec -it openclaw /bin/bash

更新镜像

# 拉取最新镜像
docker pull openclaiai/openclaw:latest

# 重建容器
docker compose down
docker compose up -d

清理资源

# 停止并删除容器
docker compose down

# 删除镜像
docker rmi openclaiai/openclaw:latest

# 清理悬空资源
docker system prune

---

常见问题解决

问题一：端口被占用

症状：

Error: bind: address already in use

解决：

# 查看端口占用
lsof -i :1878        # Mac/Linux
netstat -ano | findstr :1878  # Windows

# 修改 docker-compose.yml 中的端口
ports:
  - "1888:1878"  # 改为其他端口

---

问题二：权限被拒绝

症状：

Error: permission denied

解决：

# Linux：将用户加入 Docker 组
sudo usermod -aG docker $USER
newgrp docker

# 或使用 sudo
sudo docker compose up -d

---

问题三：容器启动后立即退出

症状：

docker compose ps
# 显示 Exited (1)

解决：

# 查看错误日志
docker compose logs

# 常见原因：
# 1. 配置文件错误 → 检查 docker-compose.yml
# 2. 数据目录权限 → chmod 777 ./data
# 3. 内存不足 → 增加 Docker 内存限制

---

问题四：无法访问控制台

症状：

浏览器打开 localhost:1878 无响应

解决：

# 检查容器是否运行
docker compose ps

# 检查端口映射
docker port openclaw

# 检查防火墙
# Windows：关闭防火墙或放行端口
# Linux：
sudo ufw allow 1878

---

问题五：配置不生效

症状：

修改配置后重启，配置未更新

解决：

# 确认数据卷挂载正确
docker inspect openclaw | grep -A 10 Mounts

# 手动删除旧数据（谨慎！）
rm -rf ./data/*

# 重启容器
docker compose down && docker compose up -d

---

高级配置

资源限制

限制容器资源使用：

services:
  openclaw:
    # ...
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

环境变量配置

通过环境变量配置 OpenClaw：

environment:
  - OPENAI_API_KEY=sk-xxxxx
  - OPENCLAW_VERBOSE=1
  - TZ=Asia/Shanghai

使用自定义配置文件

挂载自定义配置：

volumes:
  - ./data:/root/.openclaw
  - ./custom-config.json:/root/.openclaw/openclaw.json:ro

---

多环境部署

开发环境

# docker-compose.dev.yml
services:
  openclaw:
    image: openclaiai/openclaw:latest
    ports:
      - "1878:1878"
      - "18789:18789"
    volumes:
      - ./data:/root/.openclaw
    environment:
      - OPENCLAW_VERBOSE=1

生产环境

# docker-compose.prod.yml
services:
  openclaw:
    image: openclaiai/openclaw:v2026.4.8  # 固定版本
    restart: always
    ports:
      - "127.0.0.1:1878:1878"  # 只监听本地
      - "127.0.0.1:18789:18789"
    volumes:
      - ./data:/root/.openclaw
    environment:
      - OPENCLAW_VERBOSE=0
    deploy:
      resources:
        limits:
          memory: 4G

启动：

# 开发环境
docker compose -f docker-compose.dev.yml up -d

# 生产环境
docker compose -f docker-compose.prod.yml up -d

---

总结

步骤	操作
1	安装 Docker 和 Docker Compose
2	创建项目目录和 docker-compose.yml
3	docker compose up -d 启动
4	访问 localhost:1878 配置模型
5	开始使用

Docker 部署 vs 本地安装：

场景	推荐
服务器部署	Docker 部署
测试环境	Docker 部署
日常开发	本地安装
多环境管理	Docker 部署

Docker 部署让 OpenClaw 的环境管理变得简单。5 分钟搭建，随时丢弃，随时重建。先从默认配置开始，熟悉后再根据需求调整资源限制、环境变量等高级配置。