OpenClaw Docker 部署完整指南

简介

OpenClaw 是一个自托管的 AI 代理网关，可以将多种聊天应用（Discord、Telegram、WhatsApp、Feishu 等）连接到 AI 编程助手。本文档介绍如何使用 Docker 部署 OpenClaw，并提供详细的运维命令说明。

为什么使用 Docker？

容器化部署：环境隔离，易于管理
快速部署：无需手动安装 Node.js 依赖
易于升级：通过 Docker 镜像更新
跨平台：支持 Linux、macOS、Windows

前置要求

硬件要求

至少 2 GB RAM（用于构建镜像）
足够的磁盘空间（镜像和日志）
稳定的网络连接

软件要求

Docker Desktop 或 Docker Engine
Docker Compose v2
Node.js 24（推荐）或 22.14+（兼容）

检查版本

docker --version          # Docker 版本
docker compose version    # Docker Compose 版本
node --version            # Node.js 版本

Docker 安装

Linux 安装

# 使用官方安装脚本（Ubuntu/Debian）
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 启动 Docker 服务
sudo systemctl start docker
sudo systemctl enable docker

# 添加当前用户到 docker 组（避免每次 sudo）
sudo usermod -aG docker $USER
newgrp docker

# 验证安装
docker run hello-world

macOS 安装

下载 Docker Desktop for Mac
安装并启动
验证安装：
bash docker --version docker compose version

Windows 安装

下载 Docker Desktop for Windows
启用 WSL 2（推荐）
安装并启动 Docker Desktop
验证安装

OpenClaw Docker 部署

方式一：使用自动化脚本（推荐）

# 克隆 OpenClaw 仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 运行 Docker 设置脚本（会自动构建镜像并完成引导）
./scripts/docker/setup.sh

脚本会自动完成：
– 构建或拉取 OpenClaw Docker 镜像
– 运行引导程序（需要 API 密钥）
– 生成配置文件（.env）
– 启动 Gateway 服务
– 创建 Docker Compose 配置

方式二：手动部署

1. 构建镜像

# 从本地构建
cd openclaw
./scripts/docker/setup.sh

# 或使用预构建镜像
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

2. 完成引导

引导程序会提示：
– 选择模型提供商（Anthropic、OpenAI、Google 等）
– 输入 API 密钥
– 设置网关认证（Token 或密码）
– 配置网络绑定模式

3. 打开控制台

# 通过 Docker Compose 打开控制台
docker compose run --rm openclaw-cli dashboard --no-open

浏览器访问：http://127.0.0.1:18789/

4. 配置渠道（可选）

# WhatsApp（扫码登录）
docker compose run --rm openclaw-cli channels login

# Telegram（需要机器人 Token）
docker compose run --rm openclaw-cli channels add --channel telegram --token "YOUR_BOT_TOKEN"

# Discord（需要应用 Token）
docker compose run --rm openclaw-cli channels add --channel discord --token "YOUR_APP_TOKEN"

# Feishu（需要飞书机器人 Token）
docker compose run --rm openclaw-cli channels add --channel feishu --token "YOUR_BOT_TOKEN"

自定义配置

环境变量

# 使用远程镜像
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

# 安装额外系统包（构建时）
export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"

# 预安装扩展依赖
export OPENCLAW_EXTENSIONS="extension-name1 extension-name2"

# 挂载额外目录
export OPENCLAW_EXTRA_MOUNTS="/host/path:/container/path:ro"

# 持久化 /home/node 目录
export OPENCLAW_HOME_VOLUME="openclaw_home"

# 启用沙箱
export OPENCLAW_SANDBOX=1

# 指定 Docker socket 路径（rootless Docker）
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock

配置文件

配置文件挂载在 /home/node/.openclaw，包含：
– openclaw.json – 网关配置
– agents/*/agent/auth-profiles.json – 认证配置
– .env – 环境变量和密钥

Docker 命令详解

基本命令

1. 查看容器状态

# 查看运行中的容器
docker ps

# 查看所有容器（包括停止的）
docker ps -a

# 查看资源使用情况
docker stats

2. 启动容器

# 启动所有服务
docker compose up -d

# 启动特定服务
docker compose up -d openclaw-gateway

# 启动并查看日志
docker compose up

3. 停止容器

# 停止所有服务
docker compose down

# 停止特定服务
docker compose stop openclaw-gateway

# 停止并删除容器
docker compose down -v  # 删除卷

4. 重启容器

# 重启所有服务
docker compose restart

# 重启特定服务
docker compose restart openclaw-gateway

5. 查看日志

# 实时查看日志
docker compose logs -f

# 查看特定服务日志
docker compose logs -f openclaw-gateway

# 查看最近 100 行
docker compose logs --tail=100

# 查看特定时间段的日志
docker compose logs --since="2024-01-01T00:00:00"

6. 进入容器

# 进入 CLI 容器
docker compose run --rm openclaw-cli /bin/bash

# 进入 Gateway 容器
docker compose exec openclaw-gateway /bin/bash

7. 执行命令

# 在 CLI 容器中执行命令
docker compose run --rm openclaw-cli openclaw --version

# 在 Gateway 容器中执行命令
docker compose exec openclaw-gateway node dist/index.js health --token "YOUR_TOKEN"

8. 删除容器

# 删除停止的容器
docker rm <container_id>

# 删除未使用的镜像
docker image prune -a

9. 镜像管理

# 查看镜像
docker images

# 删除镜像
docker rmi <image_id>

# 拉取最新镜像
docker compose pull

# 构建镜像
docker compose build

10. 清理资源

# 清理未使用的容器、网络、镜像
docker system prune

# 清理所有（包括卷）
docker system prune -a --volumes

Docker Compose 常用命令

# 查看服务状态
docker compose ps

# 查看服务配置
docker compose config

# 查看服务日志（不跟随）
docker compose logs

# 拉取镜像
docker compose pull

# 构建镜像
docker compose build

# 重新创建容器
docker compose up -d --force-recreate

# 扩展服务
docker compose up -d --scale openclaw-gateway=3

高级用法

1. 网络绑定模式

# LAN 模式（允许局域网访问）
export OPENCLAW_GATEWAY_BIND=lan

# Loopback 模式（仅本地）
export OPENCLAW_GATEWAY_BIND=loopback

# 自定义绑定
export OPENCLAW_GATEWAY_BIND=0.0.0.0:8080

2. 数据持久化

# 使用命名卷
docker compose up -d

# 查看卷
docker volume ls | grep openclaw

# 备份配置
docker cp openclaw-gateway:/home/node/.openclaw ./backup-config

# 恢复配置
docker cp ./backup-config openclaw-gateway:/home/node/.openclaw

3. 健康检查

# 健康检查端点
curl http://127.0.0.1:18789/healthz
curl http://127.0.0.1:18789/readyz

# 深度健康检查（需要 Token）
docker compose exec openclaw-gateway node dist/index.js health --token "YOUR_TOKEN"

OpenClaw 运维命令

网关管理

1. 查看网关状态

# 基本状态
openclaw gateway status

# 深度状态（包括系统服务）
openclaw gateway status --deep

# JSON 格式输出
openclaw gateway status --json

# 需要 RPC 证明
openclaw gateway status --require-rpc

2. 安装网关服务

# macOS LaunchAgent
openclaw gateway install

# Linux systemd 用户服务
openclaw gateway install

# Windows 任务计划程序
openclaw gateway install

3. 启动/停止/重启

# 启动网关
openclaw gateway start

# 停止网关
openclaw gateway stop

# 重启网关
openclaw gateway restart

# 强制启动（强制绑定到端口）
openclaw gateway --force

4. 启动网关（调试模式）

# 基本启动
openclaw gateway --port 18789

# 详细日志
openclaw gateway --port 18789 --verbose

# 指定端口
openclaw gateway --port 8080

配置管理

1. 查看配置

# 查看当前配置
openclaw config get

# 查看特定配置项
openclaw config get gateway.port
openclaw config get gateway.bind

2. 设置配置

# 设置单个配置项
openclaw config set gateway.port 8080

# 批量设置（JSON）
openclaw config set --batch-json '[{"path":"gateway.port","value":8080},{"path":"gateway.bind","value":"lan"}]'

3. 重载配置

# 重载配置（热重载）
openclaw secrets reload

# 查看重载模式
openclaw config get gateway.reload.mode

渠道管理

1. 查看渠道状态

# 渠道状态摘要
openclaw channels status

# 渠道状态（实时探测）
openclaw channels status --probe

# JSON 格式
openclaw channels status --json

2. 添加渠道

# 添加 Telegram 渠道
openclaw channels add --channel telegram --token "YOUR_BOT_TOKEN"

# 添加 Discord 渠道
openclaw channels add --channel discord --token "YOUR_APP_TOKEN"

# 添加 Feishu 渠道
openclaw channels add --channel feishu --token "YOUR_BOT_TOKEN"

# 添加 WhatsApp 渠道
openclaw channels login

3. 删除渠道

# 删除渠道
openclaw channels remove --channel telegram

4. 列出渠道

# 列出所有渠道
openclaw channels list

# 列出所有渠道（JSON）
openclaw channels list --json

设备管理

1. 列出设备

# 列出所有设备
openclaw devices list

# 列出所有设备（JSON）
openclaw devices list --json

# 指定网关 URL
openclaw devices list --url ws://127.0.0.1:18789

2. 审批设备

# 审批设备请求
openclaw devices approve <request_id>

# 批准所有请求
openclaw devices approve --all

日志管理

1. 查看日志

# 查看网关日志
openclaw logs

# 实时查看日志
openclaw logs --follow

# 查看最后 100 行
openclaw logs --tail=100

# 查看特定时间段的日志
openclaw logs --since="2024-01-01T00:00:00"

健康检查

1. 基本健康检查

# 基本健康检查
openclaw health

# 网关健康检查
openclaw gateway health

# 深度健康检查
openclaw doctor

2. 诊断工具

# 运行诊断
openclaw doctor

# 查看诊断详情
openclaw doctor --verbose

版本管理

# 查看版本
openclaw --version

# 检查更新
openclaw doctor --check-updates

# 更新 OpenClaw
npm install -g openclaw@latest

其他常用命令

# 打开控制台
openclaw dashboard

# 运行引导程序
openclaw onboard --install-daemon

# 查看帮助
openclaw --help
openclaw <command> --help

常用操作

日常运维

1. 检查服务状态

# 检查 Docker 容器状态
docker ps

# 检查 OpenClaw 状态
openclaw gateway status

# 检查渠道连接
openclaw channels status --probe

# 检查健康
openclaw health

2. 查看日志

# Docker 日志
docker compose logs -f

# OpenClaw 日志
openclaw logs --follow

3. 更新 OpenClaw

# 更新 Docker 镜像
docker compose pull
docker compose up -d

# 或使用脚本
./scripts/docker/setup.sh

4. 备份配置

# 备份配置目录
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw

# 备份 Docker 卷
docker run --rm -v openclaw_config:/data -v $(pwd):/backup alpine tar czf /backup/openclaw-config-backup.tar.gz /data

5. 恢复配置

# 解压备份
tar -xzf openclaw-backup-20240101.tar.gz -C ~/

# 恢复 Docker 卷
docker run --rm -v openclaw_config:/data -v $(pwd):/backup alpine sh -c "cd /data && tar xzf /backup/openclaw-config-backup.tar.gz"

安全加固

1. 配置认证

{
  "gateway": {
    "auth": {
      "token": "your-secure-token-here",
      "password": "your-secure-password"
    }
  }
}

2. 限制绑定模式

{
  "gateway": {
    "bind": "loopback"
  }
}

3. 配置安全策略

{
  "gateway": {
    "auth": {
      "mode": "trusted-proxy"
    },
    "security": {
      "allowCors": ["https://your-domain.com"]
    }
  }
}

故障排查

常见问题

1. 端口冲突

问题： EADDRINUSE 错误

解决方案：

# 查看占用端口的进程
lsof -i :18789

# 修改端口配置
openclaw config set gateway.port 8080

# 或使用 --force 强制启动
openclaw gateway --force

2. 权限错误

问题： EACCES 或权限被拒绝

解决方案：

# 修复目录权限
sudo chown -R 1000:1000 /path/to/openclaw

# 检查 Docker socket 权限
ls -l /run/user/1000/docker.sock

3. 容器无法启动

问题： 容器反复重启

解决方案：

# 查看容器日志
docker compose logs openclaw-gateway

# 检查资源使用
docker stats

# 检查磁盘空间
df -h

# 重新创建容器
docker compose up -d --force-recreate

4. 无法连接到网关

问题： 客户端无法连接到 Gateway

解决方案：

# 检查网关状态
openclaw gateway status

# 检查端口绑定
netstat -tuln | grep 18789

# 检查防火墙
sudo ufw status
sudo iptables -L

# 重新启动网关
openclaw gateway restart

5. 渠道连接失败

问题： 聊天渠道无法连接

解决方案：

# 检查渠道状态
openclaw channels status --probe

# 查看渠道日志
openclaw logs --channel telegram

# 重新登录
openclaw channels login

# 检查 Token 是否正确
openclaw channels list

6. 内存不足

问题： 容器被 OOM Killed

解决方案：

# 增加容器内存限制
docker compose up -d --scale openclaw-gateway=1

# 检查日志中的 OOM 指示
docker compose logs | grep -i "out of memory"

7. 镜像构建失败

问题： 构建镜像时失败

解决方案：

# 检查系统资源
free -h

# 清理 Docker 缓存
docker system prune -a

# 使用预构建镜像
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

调试技巧

1. 启用详细日志

# Docker 详细日志
docker compose logs -f --timestamps

# OpenClaw 详细日志
openclaw gateway --verbose

2. 使用 Shell 进入容器调试

# 进入 CLI 容器
docker compose run --rm openclaw-cli /bin/bash

# 进入 Gateway 容器
docker compose exec openclaw-gateway /bin/bash

# 在容器中执行命令
docker compose exec openclaw-gateway node dist/index.js health

3. 网络诊断

# 测试网关连通性
curl http://127.0.0.1:18789/healthz

# 测试 WebSocket 连接
wscat -c ws://127.0.0.1:18789

# 查看网络连接
netstat -an | grep 18789

4. 资源监控

# Docker 资源监控
docker stats

# 系统资源监控
htop
top

# 磁盘使用
du -sh ~/.openclaw

参考资料

更新日志

2024-04-21：初始版本，包含 Docker 安装、命令详解和运维指南

许可证

MIT License

文章版权归作者所有，未经允许请勿转载。

THE END

OpenClaw Docker 部署完整指南 – 详细教程

OpenClaw Docker 部署完整指南

目录

简介

为什么使用 Docker？

前置要求

硬件要求

软件要求

检查版本

Docker 安装

Linux 安装

macOS 安装

Windows 安装

OpenClaw Docker 部署

方式一：使用自动化脚本（推荐）

方式二：手动部署

1. 构建镜像

2. 完成引导

3. 打开控制台

4. 配置渠道（可选）

自定义配置

环境变量

配置文件

Docker 命令详解

基本命令

1. 查看容器状态

2. 启动容器

3. 停止容器

4. 重启容器

5. 查看日志

6. 进入容器

7. 执行命令

8. 删除容器

9. 镜像管理

10. 清理资源

Docker Compose 常用命令

高级用法

1. 网络绑定模式

2. 数据持久化

3. 健康检查

OpenClaw 运维命令

网关管理

1. 查看网关状态

2. 安装网关服务

3. 启动/停止/重启

4. 启动网关（调试模式）

配置管理

1. 查看配置

2. 设置配置

3. 重载配置

渠道管理

1. 查看渠道状态

2. 添加渠道

3. 删除渠道

4. 列出渠道

设备管理

1. 列出设备

2. 审批设备

日志管理

1. 查看日志

健康检查

1. 基本健康检查

2. 诊断工具

版本管理

其他常用命令

常用操作

日常运维

1. 检查服务状态

2. 查看日志

3. 更新 OpenClaw

4. 备份配置

5. 恢复配置

安全加固

1. 配置认证

2. 限制绑定模式

3. 配置安全策略

故障排查

常见问题

1. 端口冲突

2. 权限错误