OpenClaw Docker Compose 部署完整指南

📋 目录

一、前置要求

必需软件

• Docker Desktop（Windows/macOS）或 Docker Engine + Docker Compose v2（Linux）
• 系统资源：至少 2GB RAM（防止构建时 OOM），10GB 可用磁盘空间
• 网络：需要访问 GitHub Container Registry 和 npm 仓库

可选但推荐

• Node.js 24+（用于本地开发和 CLI 操作）
• pnpm 10.23.0+（包管理器）

二、快速部署（推荐）

这是最简单的方式，脚本会自动完成所有配置：

# 1. 克隆项目
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 2. 运行设置脚本
./scripts/docker/setup.sh

脚本会自动：

• ✅ 构建 Docker 镜像
• ✅ 生成 Gateway Token
• ✅ 运行 Onboarding 向导
• ✅ 启动 Gateway 服务
• ✅ 配置必要的环境变量

访问控制 UI

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

将终端显示的 token 粘贴到 Settings 中即可。

三、手动部署步骤

如果您想完全控制部署过程：

步骤 1：构建 Docker 镜像

方式 A：本地构建

cd openclaw
docker build -t openclaw:local -f Dockerfile .

方式 B：使用预构建镜像

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
docker pull $OPENCLAW_IMAGE

💡 预构建镜像地址：https://github.com/openclaw/openclaw/pkgs/container/openclaw

• [main](file://d:\\project\\openclaw\\scripts\\ui.js#L161-L193) – 主分支最新
• [latest](file://d:\\project\\openclaw\\src\\cli\\gateway-cli\\register.ts#L76-L76) – 最新稳定版
• <version> – 特定版本（如 2026.2.26）

步骤 2：准备环境变量

创建 [.env](file://d:\\project\\openclaw\\openclaw.podman.env) 文件：

# 基础配置
OPENCLAW_CONFIG_DIR=$HOME/.openclaw
OPENCLAW_WORKSPACE_DIR=$HOME/.openclaw/workspace
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_TZ=Asia/Shanghai

# 认证 Token（可选，不设置则自动生成）
OPENCLAW_GATEWAY_TOKEN=your-secret-token-here

# 镜像配置
OPENCLAW_IMAGE=openclaw:local

# 沙箱配置（可选）
OPENCLAW_SANDBOX=
OPENCLAW_DOCKER_SOCKET=/var/run/docker.sock

# 额外配置（可选）
OPENCLAW_EXTRA_MOUNTS=
OPENCLAW_HOME_VOLUME=
OPENCLAW_DOCKER_APT_PACKAGES=
OPENCLAW_EXTENSIONS=

步骤 3：初始化配置目录

# 创建目录结构
mkdir -p $OPENCLAW_CONFIG_DIR
mkdir -p $OPENCLAW_WORKSPACE_DIR
mkdir -p $OPENCLAW_CONFIG_DIR/identity
mkdir -p $OPENCLAW_CONFIG_DIR/agents/main/agent
mkdir -p $OPENCLAW_CONFIG_DIR/agents/main/sessions

步骤 4：运行 Onboarding

docker compose run –rm –no-deps –entrypoint node openclaw-gateway \\
dist/index.js onboard –mode local –no-install-daemon

按照提示完成：

• 选择 AI 提供商（OpenAI、Anthropic 等）
• 输入 API Key
• 配置模型偏好

步骤 5：配置 Gateway

# 设置 Gateway 模式为 local
docker compose run –rm –no-deps –entrypoint node openclaw-gateway \\
dist/index.js config set gateway.mode local

# 设置绑定地址为 lan（允许主机访问）
docker compose run –rm –no-deps –entrypoint node openclaw-gateway \\
dist/index.js config set gateway.bind lan

# 配置 Control UI 允许的源（重要！）
docker compose run –rm –no-deps –entrypoint node openclaw-gateway \\
dist/index.js config set gateway.controlUi.allowedOrigins \\
'["http://localhost:18789","http://127.0.0.1:18789"]' –strict-json

步骤 6：启动 Gateway

docker compose up -d openclaw-gateway

步骤 7：验证安装

# 查看日志
docker compose logs -f openclaw-gateway

# 健康检查
curl -fsS http://127.0.0.1:18789/healthz

# 就绪检查
curl -fsS http://127.0.0.1:18789/readyz

看到 [ok](file://d:\\project\\openclaw\\ui\\src\\ui\\app-chat.ts#L107-L107) 表示成功！

四、配置通讯渠道

WhatsApp（二维码登录）

docker compose run –rm openclaw-cli channels login

扫描二维码后，WhatsApp 设备即连接成功。

Telegram（Bot Token）

docker compose run –rm openclaw-cli channels add \\
–channel telegram \\
–token "123456:ABCDEF-GHIJKLMNOPQRSTUVWXYZ"

Discord（Bot Token）

docker compose run –rm openclaw-cli channels add \\
–channel discord \\
–token "MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.GJKLmN.OpQrStUvWxYzAbCdEfGhIjKlMnOpQrStUvWx"

Slack

# 需要设置两个环境变量
export SLACK_BOT_TOKEN=xoxb-your-bot-token
export SLACK_APP_TOKEN=xapp-your-app-token

docker compose run –rm openclaw-cli channels add \\
–channel slack

Signal

需要先安装 signal-cli，然后配置：

docker compose run –rm openclaw-cli channels add \\
–channel signal \\
–phone "+1234567890"

五、健康检查

基础检查（无需认证）

# Liveness probe（存活检查）
curl -fsS http://127.0.0.1:18789/healthz

# Readiness probe（就绪检查）
curl -fsS http://127.0.0.1:18789/readyz

深度检查（需要认证）

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

获取 Dashboard URL

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

六、高级配置选项

1. 启用 Agent 沙箱（推荐生产环境）

沙箱可以让非主会话在隔离的 Docker 容器中运行，提高安全性：

export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/var/run/docker.sock
./scripts/docker/setup.sh

对于 rootless Docker：

export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh

2. 自定义 apt 包（构建时安装）

export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq wget"
docker build \\
–build-arg OPENCLAW_DOCKER_APT_PACKAGES="$OPENCLAW_DOCKER_APT_PACKAGES" \\
-t openclaw:local \\
-f Dockerfile \\
.

3. 预安装扩展

export OPENCLAW_EXTENSIONS="diagnostics-otel matrix tavily"
docker build \\
–build-arg OPENCLAW_EXTENSIONS="$OPENCLAW_EXTENSIONS" \\
-t openclaw:local \\
-f Dockerfile \\
.

支持的扩展在 extensions/ 目录下。

4. 安装 Playwright 浏览器（用于浏览器自动化）

export OPENCLAW_INSTALL_BROWSER=1
docker build \\
–build-arg OPENCLAW_INSTALL_BROWSER=1 \\
-t openclaw:local \\
-f Dockerfile \\
.

或在运行时安装：

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

5. 额外挂载（访问宿主机文件）

export OPENCLAW_EXTRA_MOUNTS="/host/data:/container/data:ro,/host/logs:/container/logs"

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

6. 使用命名卷持久化（而非 bind mount）

export OPENCLAW_HOME_VOLUME="openclaw_home"

这会将 /home/node 整个目录持久化到 Docker 卷中。

7. 配置示例（openclaw.json）

编辑 $OPENCLAW_CONFIG_DIR/openclaw.json：

{
"agent": {
"model": "anthropic/claude-opus-4-6",
"defaults": {
"sandbox": {
"mode": "non-main", // off | non-main | all
"scope": "agent", // session | agent | shared
"workspaceAccess": "none"
}
}
},
"gateway": {
"auth": {
"mode": "token",
"token": "your-token-here"
},
"bind": "lan",
"controlUi": {
"allowedOrigins": [
"http://localhost:18789",
"http://127.0.0.1:18789"
]
}
},
"channels": {
"whatsapp": {
"allowFrom": ["*"],
"dmPolicy": "pairing"
},
"telegram": {
"botToken": "123456:ABCDEF",
"allowFrom": ["*"]
}
}
}

七、常用管理命令

日志查看

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

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

服务管理

# 停止服务
docker compose down

# 重启服务
docker compose restart openclaw-gateway

# 完全清理（包括数据卷）
docker compose down -v

# 重新构建并启动
docker compose up -d –build openclaw-gateway

设备配对

# 列出待批准的设备
docker compose run –rm openclaw-cli devices list

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

# 拒绝设备
docker compose run –rm openclaw-cli devices reject <requestId>

发送消息测试

# 发送测试消息
docker compose run –rm openclaw-cli message send \\
–to "+1234567890" \\
–message "Hello from OpenClaw!"

# 与 Agent 对话
docker compose run –rm openclaw-cli agent \\
–message "Ship checklist" \\
–thinking high

配置管理

# 查看当前配置
docker compose run –rm openclaw-cli config get

# 修改配置
docker compose run –rm openclaw-cli config set gateway.bind loopback

# 重置配置
docker compose run –rm openclaw-cli config reset

技能管理

# 列出已安装技能
docker compose run –rm openclaw-cli skills list

# 安装新技能
docker compose run –rm openclaw-cli skills install <skill-name>

# 更新技能
docker compose run –rm openclaw-cli skills update <skill-name>

八、故障排查

问题 1：权限错误（EACCES）

症状：容器内无法写入配置文件

解决：

sudo chown -R 1000:1000 $OPENCLAW_CONFIG_DIR $OPENCLAW_WORKSPACE_DIR

问题 2：Gateway 无法从主机访问

症状：浏览器无法打开 http://127.0.0.1:18789/

解决：

# 检查绑定地址配置
docker compose run –rm openclaw-cli config get gateway.bind

# 如果不是 lan，修改
docker compose run –rm openclaw-cli config set gateway.bind lan

# 重启服务
docker compose restart openclaw-gateway

问题 3：沙箱容器未启动

症状：Agent 工具执行失败，提示找不到 sandbox

解决：

# 构建沙箱镜像
./scripts/sandbox-setup.sh

# 或指定自定义镜像
# 编辑 openclaw.json，设置 agents.defaults.sandbox.docker.image

问题 4：构建时 OOM（exit 137）

症状：pnpm install 过程中容器被杀死

解决：

• 增加 Docker 内存限制到至少 2GB
• 或使用更大的虚拟机
• 或分步构建，减少并发依赖安装

问题 5：Dashboard 显示配对请求

症状：Control UI 显示需要配对设备

解决：

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

# 在浏览器打开链接并批准设备

# 或直接通过 CLI 批准
docker compose run –rm openclaw-cli devices list
docker compose run –rm openclaw-cli devices approve <requestId>

问题 6：WebSocket 连接失败

症状：macOS/iOS App 无法连接

解决：

# 重置 Gateway 模式
docker compose run –rm openclaw-cli config set gateway.mode local
docker compose run –rm openclaw-cli config set gateway.bind lan

# 确保防火墙允许 18789 端口
# macOS: 系统设置 > 网络 > 防火墙
# Linux: sudo ufw allow 18789/tcp

问题 7：渠道消息不响应

症状：WhatsApp/Telegram 消息发送后无回复

排查步骤：

# 1. 检查渠道状态
docker compose run –rm openclaw-cli channels list

# 2. 查看渠道日志
docker compose logs openclaw-gateway | grep -i "channel\\|whatsapp\\|telegram"

# 3. 检查 DM 策略（是否启用了 pairing）
docker compose run –rm openclaw-cli config get channels.whatsapp.dmPolicy

# 4. 如果是 pairing 模式，需要批准发送者
docker compose run –rm openclaw-cli pairing list
docker compose run –rm openclaw-cli pairing approve whatsapp <code>

九、安全加固

1. DM（私信）安全策略

默认行为：DM 配对模式（dmPolicy="pairing"）

• 未知发送者会收到配对码
• Bot 不会处理未配对的私信
• 防止垃圾消息和提示注入攻击

批准流程：

# 查看待批准的配对
docker compose run –rm openclaw-cli pairing list

# 批准
docker compose run –rm openclaw-cli pairing approve <channel> <code>

开放模式（仅限可信环境）：

{
"channels": {
"whatsapp": {
"dmPolicy": "open",
"allowFrom": ["*"] // 允许所有人
}
}
}

2. 网络暴露安全

如果在 VPS 上部署：

Docker 防火墙规则

# 添加 DOCKER-USER 链规则
iptables -A DOCKER-USER -i eth0 -p tcp –dport 18789 -j ACCEPT
iptables -A DOCKER-USER -i eth0 -p tcp –dport 18790 -j ACCEPT
iptables -A DOCKER-USER -i eth0 -j DROP

使用 Tailscale（推荐）

{
"gateway": {
"tailscale": {
"mode": "serve", // serve（尾网）| funnel（公开）| off
"resetOnExit": true
},
"bind": "loopback", // 必须保持 loopback
"auth": {
"mode": "token"
}
}
}

3. Token 认证强化

生成强 Token：

# 使用 openssl 生成
openssl rand -hex 32

# 或使用 Python
python3 -c "import secrets; print(secrets.token_hex(32))"

设置密码认证（替代 Token）：

{
"gateway": {
"auth": {
"mode": "password",
"password": "your-strong-password-here"
}
}
}

4. 容器安全

Docker Compose 已经配置了以下安全措施：

services:
openclaw-cli:
cap_drop:
– NET_RAW
– NET_ADMIN
security_opt:
– no–new–privileges:true

进一步加固：

services:
openclaw-gateway:
read_only: true
tmpfs:
– /tmp
cap_drop:
– ALL
cap_add:
– NET_BIND_SERVICE

5. 沙箱隔离

启用沙箱后，非主会话的工具执行会在隔离容器中进行：

{
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main", // 非主会话启用沙箱
"scope": "agent",
"workspaceAccess": "none", // 禁止访问工作区
"allowTools": [
"bash", "process", "read", "write", "edit",
"sessions_list", "sessions_history", "sessions_send"
],
"denyTools": [
"browser", "canvas", "nodes", "cron", "discord", "gateway"
]
}
}
}
}

十、持久化说明

数据持久化策略

Docker Compose 使用 bind mount 持久化关键数据：

目录结构

~/.openclaw/
├── openclaw.json # 主配置文件
├── identity/ # 身份和密钥存储
│ └── default/
├── credentials/ # 渠道凭证（加密存储）
├── agents/ # Agent 配置
│ └── main/
│ ├── agent/ # Agent 专属文件
│ └── sessions/ # 会话历史
└── workspace/
├── skills/ # 已安装技能
├── media/ # 媒体文件缓存
└── cron/
└── runs/ # 定时任务记录

磁盘增长监控

以下目录可能快速增长，需定期清理：

# 查看各目录大小
docker compose exec openclaw-gateway du -sh \\
/home/node/.openclaw/workspace/media \\
/home/node/.openclaw/agents/main/sessions \\
/home/node/.openclaw/workspace/cron/runs \\
/tmp/openclaw

# 清理旧会话（保留最近 7 天）
docker compose run –rm openclaw-cli sessions prune –older-than 7d

# 清理媒体缓存
docker compose exec openclaw-gateway rm -rf /home/node/.openclaw/workspace/media/*

备份策略

完整备份：

# 停止服务
docker compose down

# 备份配置和工作区
tar -czvf openclaw-backup-$(date +%Y%m%d).tar.gz \\
~/.openclaw

# 重新启动
docker compose up -d

增量备份（仅配置文件）：

cp ~/.openclaw/openclaw.json ~/backups/openclaw-$(date +%Y%m%d).json

恢复备份：

# 停止服务
docker compose down

# 解压备份
tar -xzvf openclaw-backup-20260401.tar.gz -C ~/

# 重新启动
docker compose up -d

🎯 下一步

部署完成后，建议：

详细使用文档请参考：

• Channels 配置
• Skills 系统
• Gateway 配置
• 安全指南

祝您部署顺利！🦞