OpenClaw Docker 部署：容器化运行完整指南

本教程属于《OpenClaw 从入门到精通》系列

第二阶段：部署与安装

查看系列目录

在上一篇文章中，我们学习了本地部署的基本方法。本文将详细介绍如何使用 Docker 部署 OpenClaw，实现容器化的隔离运行环境。

🤔 Docker 部署适合谁？

选择 Docker 部署的场景：

✅ 你希望获得隔离的、可丢弃的 Gateway 环境
✅ 你在不支持本地安装的托管环境中运行
✅ 你需要快速在不同机器间迁移服务
✅ 你偏好容器化带来的便捷管理

继续使用本地部署的场景：

❌ 你只是在个人电脑上运行
❌ 你追求最快的开发迭代速度
❌ 你不想增加 Docker 的资源开销

⚠️ 注意：即使不使用 Docker 部署，OpenClaw 的 Agent 沙箱功能仍然会用到 Docker 来隔离工具执行，但这不需要完整的 Gateway 运行在 Docker 中。

📋 环境要求

在开始之前，请确保你的系统满足以下要求：

组件	最低要求	推荐配置
Docker Desktop/Engine	20.10+	24.0+
Docker Compose	v2	v2.20+
内存	2 GB	4 GB+
磁盘空间	5 GB	10 GB+

💡 提示：镜像构建过程中需要至少 2GB 内存，否则 pnpm install 可能会因内存不足（exit 137）而失败。

支持的平台

✅ Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
✅ macOS (Docker Desktop)
✅ Windows (Docker Desktop + WSL2)

🚀 快速开始（推荐）

最简单的方式是使用官方提供的 docker-setup.sh 脚本：

# 克隆仓库（如果还没有）
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 运行自动设置脚本
./docker-setup.sh

这个脚本会自动完成以下工作：

构建 Gateway 镜像 - 编译 OpenClaw 容器镜像
运行引导向导 - 交互式配置 AI 提供商等
启动服务 - 通过 Docker Compose 启动 Gateway
生成令牌 - 创建 Gateway 令牌并写入 .env 文件

脚本可配置项

你可以通过环境变量自定义部署：

# 安装额外的系统包
export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"

# 添加额外的宿主机挂载
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"

# 使用命名卷持久化 /home/node
export OPENCLAW_HOME_VOLUME="openclaw_home"

# 执行自定义设置
./docker-setup.sh

设置完成后的操作

在浏览器中打开 http://127.0.0.1:18789/
将令牌粘贴到 Control UI (Settings → Token)

如需重新打开 Dashboard：

docker compose run --rm openclaw-cli dashboard --no-open

🛠️ 手动部署（Docker Compose）

如果你想更精细地控制部署过程，可以手动执行以下步骤：

步骤 1：构建镜像

git clone https://github.com/openclaw/openclaw.git
cd openclaw
docker build -t openclaw:local -f Dockerfile .

步骤 2：运行引导

docker compose run --rm openclaw-cli onboard

这将启动交互式配置向导，指导你完成：

选择 AI 提供商（OpenAI、Anthropic、Google 等）
配置 API 密钥
设置消息渠道（Telegram、Discord、WhatsApp 等）

步骤 3：启动服务

docker compose up -d openclaw-gateway

📂 数据持久化配置

方式一：绑定挂载（推荐）

默认情况下，配置和工作区通过绑定挂载持久化到宿主机：

~/.openclaw/          → 容器内 /home/node/.openclaw
~/.openclaw/workspace → 容器内 /home/node/.openclaw/workspace

⚠️ 确保宿主机上的目录由 UID 1000 拥有，否则可能出现权限问题：
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

方式二：命名卷持久化

如果你希望整个 /home/node 目录持久化（包括缓存、下载等）：

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

这会创建一个 Docker 命名卷，即使容器删除也能保留数据。

方式三：额外挂载

添加自定义宿主机目录挂载：

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

格式：source:target[:options]，多个挂载用逗号分隔。

🔧 消息渠道配置

使用 CLI 容器配置各种消息渠道：

WhatsApp（扫码登录）

docker compose run --rm openclaw-cli channels login

Telegram（Bot 令牌）

docker compose run --rm openclaw-cli channels add --channel telegram --token "<你的Bot令牌>"

Discord（Bot 令牌）

docker compose run --rm openclaw-cli channels add --channel discord --token "<你的Bot令牌>"

🔐 安全配置

权限问题处理

容器以非 root 用户 node (UID 1000) 运行。如果遇到权限错误：

# Linux 宿主机
sudo chown -R 1000:1000 ~/.openclaw ~/.openclaw/workspace

防火墙配置

# Ubuntu/Debian
sudo ufw allow 18789/tcp
sudo ufw enable

# 允许 Docker
sudo ufw allow from 172.17.0.0/16

生产环境建议

不要以 root 运行容器
限制容器资源（CPU、内存）
启用网络隔离（默认 network: none）
定期更新镜像
使用 Docker secrets 存储敏感信息

🐚 Shell 辅助工具（可选）

为了更方便地管理 Docker 容器，可以安装 ClawDock 辅助工具：

mkdir -p ~/.clawdock
curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

添加到 shell 配置：

# zsh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc
source ~/.zshrc

# bash
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.bashrc
source ~/.bashrc

常用命令：

命令	说明
`clawdock-start`	启动容器
`clawdock-stop`	停止容器
`clawdock-dashboard`	打开 Dashboard
`clawdock-logs`	查看日志
`clawdock-help`	查看所有命令

🔨 完整功能容器（可选）

默认 Docker 镜像是安全优先版本，以非 root 用户运行。如果需要更多功能：

1. 持久化 /home/node

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

2. 预装系统依赖

export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq ffmpeg build-essential"
./docker-setup.sh

3. 安装 Playwright 浏览器

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

4. 持久化浏览器下载

在 docker-compose.yml 中设置：

environment:
  - PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright

并确保 /home/node 通过命名卷持久化。

🔍 健康检查与监控

检查服务状态

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

查看日志

# 实时日志
docker compose logs -f openclaw-gateway

# 最近 100 行
docker compose logs --tail=100 openclaw-gateway

设备配对

如果看到 “unauthorized” 或 “pairing required” 错误：

# 获取新的 Dashboard 链接
docker compose run --rm openclaw-cli dashboard --no-open

# 查看待配对设备
docker compose run --rm openclaw-cli devices list

# 批准设备
docker compose run --rm openclaw-cli devices approve <requestId>

🧪 测试与验证

端到端测试

./scripts/e2e/onboard-docker.sh

QR 码导入测试

pnpm test:docker:qr

🩺 故障排查

常见问题

Q1: 镜像构建失败（OOM）

确保至少有 2GB 可用内存。可以增加 Docker 分配内存：

Docker Desktop: Settings → Resources → Memory

Q2: 权限被拒绝 (EACCES)

# 修复宿主机目录权限
sudo chown -R 1000:1000 ~/.openclaw ~/.openclaw/workspace

Q3: 端口被占用

修改 docker-compose.yml 中的端口映射：

ports:
  - "18790:18789"  # 改为 18790

Q4: 容器内工具找不到

OpenClaw 使用 sh -lc 执行命令，确保在 Dockerfile 中正确设置 PATH：

environment:
  - PATH=/custom/bin:/usr/local/share/npm-global/bin:/root/.bun/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Q5: 容器启动后立即退出

查看日志：

docker compose logs openclaw-gateway

📊 资源限制建议

在生产环境中，建议为容器设置资源限制：

services:
  openclaw-gateway:
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '2'
        reservations:
          memory: 1G
          cpus: '1'

✅ 验证清单

Docker 部署完成后，请 ] 确认：

[容器正常运行 (docker compose ps)
可以访问 http://127.0.0.1:18789/
Dashboard 可以正常打开
Token 已正确配置
消息渠道可以登录（如需要）
日志无错误输出

📞 下一步

Docker 部署完成后，你可以继续学习：

配置详解 - 深入理解各项配置选项
核心概念：记忆系统 - 了解 OpenClaw 的记忆机制
技能生态 - 安装和使用各种技能扩展

📚 参考资料

本教程由 AI 自动生成并发布