Docker 部署 OpenClaw 程教程

📋 目录

•一、OpenClaw 简介

•二、部署架构图

•三、环境准备

•四、快速部署（一键脚本）

•五、手动部署（完整流程）

•六、配置详解

•七、常见问题与解决方案

•八、进阶配置

•九、运维管理

一、OpenClaw 简介

1.1 什么是 OpenClaw？

OpenClaw 是一个在 GitHub 上获得超过 100,000 Stars 的开源个人 AI 助手平台。它运行在你的电脑或服务器上,通过 WhatsApp、Telegram、Discord 等聊天应用与你的 AI 助手交互,帮你处理邮件、日历、文件等日常事务。

1.2 汉化版特色

•全中文界面 - CLI 命令行和 Dashboard 网页控制台均已深度汉化

•每小时自动同步 - 汉化版延迟小于 1 小时

•多平台支持 - WhatsApp、Telegram、Discord 等

•丰富插件 - 1Password、Apple Notes 等扩展

1.3 为什么选择 Docker 部署？

•环境隔离 - 不影响系统环境,避免依赖冲突

•快速部署 - 镜像已包含所有依赖,开箱即用

•易于迁移 - 数据持久化,备份和恢复简单

•国内优化 - Docker Hub 镜像源,拉取速度快

二、部署架构图

2.1 系统架构脑图

📱 用户访问层

WhatsApp / Telegram / Discord / 浏览器

🐳 Docker 容器层

├─ OpenClaw 网关服务 (端口 18789) ├─ AI 模型连接 (Claude/ChatGPT/Ollama) ├─ 聊天平台适配器 └─ 技能插件系统

💾 数据持久层

Docker Volume: openclaw-data → /root/.openclaw

2.2 部署流程图

阶段

操作步骤

1️⃣ 环境准备

安装 Docker / 拉取镜像

2️⃣ 初始化配置

运行向导 → 配置 AI 模型 → 设置 API 密钥

3️⃣ 启动服务

配置网关模式 → 启动容器 → 验证运行

4️⃣ 访问使用

打开 Dashboard → 连接聊天平台 → 开始使用

三、环境准备

3.1 系统要求

3.2 安装 Docker

Ubuntu/Debian 系统

方法一：使用官方脚本（推荐）

curl -fsSL https://get.docker.com | bash

方法二：使用国内镜像源

curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun

CentOS/RHEL 系统

curl -fsSL https://get.docker.com | bash

验证安装

查看 Docker 版本 docker --version # 查看 Docker 服务状态 sudo systemctl status docker

配置普通用户使用 Docker（可选）

将当前用户添加到 docker 组 sudo usermod -aG docker $USER # 重新登录或执行以下命令生效 newgrp docker

3.3 拉取 OpenClaw 镜像

选择镜像源

镜像源Docker Hub

适用场景
1186258278/openclaw-zh:latest 国内用户推荐,拉取速度快

镜像源GitHub Container Registry

ghcr.io/1186258278/openclaw-zh:latest 海外用户使用

国内用户（推荐） docker pull 1186258278/openclaw-zh:latest # 海外用户 docker pull ghcr.io/1186258278/openclaw-zh:latest

验证镜像

docker images | grep openclaw

四、快速部署（一键脚本）

4.1 Linux/macOS 系统

使用国内镜像（推荐）:

curl -fsSL https://cdn.jsdelivr.net/gh/1186258278/OpenClawChineseTranslation@main/docker-deploy.sh | bash -s -- --china

使用国外镜像:

curl -fsSL https://cdn.jsdelivr.net/gh/1186258278/OpenClawChineseTranslation@main/docker-deploy.sh | bash -s

4.2 Windows 系统（PowerShell）

使用国内镜像（推荐）:

irm https://cdn.jsdelivr.net/gh/1186258278/OpenClawChineseTranslation@main/docker-deploy.ps1 | iex # 或者: .\docker-deploy.ps1 -China

4.3 脚本执行流程

1.检查 Docker 环境 - 验证 Docker 是否已安装并运行

2.拉取最新镜像 - 下载 OpenClaw Docker 镜像

3.创建数据卷 - 创建 openclaw-data 持久化存储

4.启动初始化容器 - 运行交互式配置向导

5.配置网关模式 - 设置为 local 模式

6.启动服务容器 - 以后台守护进程方式运行

五、手动部署（完整流程）

5.1 步骤一：初始化配置

国内用户 IMAGE=1186258278/openclaw-zh:latest # 海外用户 # IMAGE=ghcr.io/1186258278/openclaw-zh:latest # 运行初始化向导（交互式） docker run --rm -it \ -v openclaw-data:/root/.openclaw \ $IMAGE \ openclaw onboard

参数说明

配置向导流程

1.选择 AI 模型 - Claude 3.5 Sonnet / GPT-4o / Ollama 本地模型

2.配置 API 密钥 - 输入对应的 API Key（Anthropic / OpenAI）

3.设置聊天通道 - WhatsApp / Telegram / Discord

4.确认配置 - 检查配置摘要并完成

5.2 步骤二：配置网关模式

配置为 local 模式（仅本地访问） docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config set gateway.mode local # 如果需要局域网访问，配置为 lan 模式 docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config set gateway.mode lan

5.3 步骤三：启动服务容器

启动 OpenClaw 网关服务 docker run -d \ --name openclaw \ -p 18789:18789 \ -v openclaw-data:/root/.openclaw \ --restart unless-stopped \ $IMAGE \ openclaw gateway run

启动参数详解

5.4 步骤四：验证服务运行

查看容器运行状态 docker ps | grep openclaw # 查看容器日志 docker logs openclaw # 查看实时日志 docker logs -f openclaw

访问 Dashboard

本地访问：http://localhost:18789 局域网访问：http://<服务器IP>:18789

六、配置详解

6.1 AI 模型配置

Claude 模型

配置 Claude 3.5 Sonnet docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config set llm.model "claude-3.5-sonnet" docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config set llm.apiKey "your-anthropic-api-key"

ChatGPT 模型

配置 GPT-4o docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config set llm.model "gpt-4o" docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config set llm.apiKey "your-openai-api-key"

Ollama 本地模型

配置 Ollama（需要先在宿主机或单独容器运行 Ollama） docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config set llm.model "ollama/llama3.2" docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config set llm.baseURL "http://host.docker.internal:11434/v1"

6.2 网络配置

网关模式说明
local -仅监听 localhost，只允许本机访问。适合单机使用
lan -监听所有网卡，允许局域网访问。适合多设备使用

配置局域网访问

修改为 lan 模式 docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config set gateway.mode lan # 重启容器使配置生效 docker restart openclaw

6.3 安全配置

关闭设备认证（Docker 用户常用）

关闭设备认证（允许直接访问 Dashboard） docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth true # 重启容器 docker restart openclaw

⚠️ 安全提示

•关闭设备认证后，任何能访问服务器的人都可以使用 Dashboard

•建议使用防火墙限制访问来源 IP

•生产环境建议配置 Nginx 反向代理并启用 HTTPS

七、常见问题与解决方案

7.1 容器启动后立即退出

问题现象

•容器启动后状态为 Exited

•无法访问 Dashboard

排查步骤

1.查看容器退出代码

docker inspect openclaw --format='{{.State.ExitCode}}' docker logs openclaw

2.检查启动命令

确保命令包含 openclaw gateway run docker inspect openclaw --format='{{.Args}}'

3.检查配置文件

查看配置是否完整 docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config list

解决方案

1. 重新初始化配置 docker run --rm -it -v openclaw-data:/root/.openclaw $IMAGE \ openclaw onboard # 2. 删除容器重新创建 docker rm -f openclaw docker run -d --name openclaw -p 18789:18789 \ -v openclaw-data:/root/.openclaw --restart unless-stopped \ $IMAGE openclaw gateway run

7.2 Dashboard 无法访问

问题现象

•浏览器显示 无法访问此网站

•连接被拒绝

排查步骤

1.检查容器是否运行

docker ps | grep openclaw

2.检查端口是否监听

docker exec openclaw netstat -tlnp | grep 18789 # 或者 docker exec openclaw ss -tlnp | grep 18789

3.检查网关模式

docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config get gateway.mode

解决方案

如果是本地访问问题:

使用 docker dashboard 命令（自动带 token） docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw dashboard

如果是局域网访问问题:

修改为 lan 模式 docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config set gateway.mode lan # 重启容器 docker restart openclaw # 检查防火墙 sudo ufw allow 18789/tcp # Ubuntu/Debian sudo firewall-cmd --add-port=18789/tcp --permanent && sudo firewall-cmd --reload # CentOS/RHEL

7.3 API 密钥配置错误

问题现象

•AI 对话无响应

•日志显示 API 调用失败

解决方案

查看 API 密钥配置 docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config get llm.apiKey # 重新设置 API 密钥 docker run --rm -v openclaw-data:/root/.openclaw $IMAGE \ openclaw config set llm.apiKey "your-correct-api-key" # 重启容器 docker restart openclaw

7.4 数据卷问题

查看数据卷

查看所有数据卷 docker volume ls | grep openclaw # 查看数据卷详情 docker volume inspect openclaw-data # 查看数据卷占用空间 docker system df -v | grep openclaw

备份配置

备份数据卷 docker run --rm -v openclaw-data:/data -v $(pwd):/backup \ ubuntu tar czf /backup/openclaw-backup-$(date +%Y%m%d).tar.gz /data # 恢复数据卷 docker run --rm -v openclaw-data:/data -v $(pwd):/backup \ ubuntu tar xzf /backup/openclaw-backup-YYYYMMDD.tar.gz -C /

八、进阶配置

8.1 使用 Docker Compose

docker-compose.yml version: '3.8' services: openclaw: image: 1186258278/openclaw-zh:latest container_name: openclaw ports: - "18789:18789" volumes: - openclaw-data:/root/.openclaw restart: unless-stopped command: openclaw gateway run # 可选：环境变量 # environment: # - NODE_ENV=production # - TZ=Asia/Shanghai volumes: openclaw-data: driver: local

使用 Docker Compose 部署

启动服务 docker-compose up -d # 查看日志 docker-compose logs -f # 停止服务 docker-compose down # 重启服务 docker-compose restart

8.2 Nginx 反向代理 + HTTPS

/etc/nginx/conf.d/openclaw.conf server { listen 80; server_name your-domain.com; # 强制 HTTPS return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; location / { proxy_pass http://localhost:18789; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_cache_bypass $http_upgrade; } }

获取 SSL 证书（Let's Encrypt）

安装 certbot sudo apt install certbot python3-certbot-nginx # 获取证书（自动配置 Nginx） sudo certbot --nginx -d your-domain.com # 自动续期 sudo certbot renew --dry-run

8.3 资源限制

docker run -d \ --name openclaw \ -p 18789:18789 \ -v openclaw-data:/root/.openclaw \ --restart unless-stopped \ --memory="2g" \ --cpus="2.0" \ $IMAGE \ openclaw gateway run

参数说明

•--memory="2g" - 限制内存使用为 2GB

•--cpus="2.0" - 限制 CPU 使用为 2 核

九、运维管理

9.1 日常管理命令
启动
docker start openclaw

停止
docker stop openclaw

重启
docker restart openclaw

删除
docker rm -f openclaw

查看日志
docker logs -f openclaw

进入容器
docker exec -it openclaw bash

9.2 版本更新

更新到最新版本

1. 停止并删除旧容器 docker stop openclaw && docker rm openclaw # 2. 拉取最新镜像 docker pull 1186258278/openclaw-zh:latest # 3. 启动新容器 docker run -d --name openclaw -p 18789:18789 \ -v openclaw-data:/root/.openclaw --restart unless-stopped \ 1186258278/openclaw-zh:latest \ openclaw gateway run

9.3 监控与日志

查看容器资源使用

查看资源使用情况 docker stats openclaw # 查看详细信息 docker inspect openclaw

日志管理

查看最近 100 行日志 docker logs --tail 100 openclaw # 查看最近 10 分钟的日志 docker logs --since 10m openclaw # 导出日志到文件 docker logs openclaw > openclaw.log # 清理日志（谨慎使用） docker run --rm -v /var/lib/docker/containers:/containers \ ubuntu find /containers -name "*.json" -type f -size +100M -delete

9.4 完全卸载

1. 停止并删除容器 docker stop openclaw && docker rm -f openclaw # 2. 删除数据卷（⚠️ 会删除所有配置和日志） docker volume rm openclaw-data # 3. 删除镜像 docker rmi 1186258278/openclaw-zh:latest # 4. 清理悬空镜像和容器 docker system prune -a

📚 参考资源

官方文档:

•OpenClaw 汉化官网: https://openclaw.qingtong.cloud

•GitHub 仓库: https://github.com/1186258278/OpenClawChineseTranslation

•Docker Hub: https://hub.docker.com/r/1186258278/openclaw-zh