OpenClaw Docker 部署完整教程

为什么用 Docker 部署 OpenClaw？

Docker 是运行 OpenClaw 的官方推荐方式。相比直接在宿主机上安装，Docker 带来三大优势：

• 环境隔离 — OpenClaw 运行在独立容器中，不会污染宿主机的 Node.js、系统库和端口。即使出现问题，删除容器即可干净卸载，不留残余。
• 跨平台一致 — 同一个镜像在 Ubuntu、CentOS、macOS、Windows WSL2 上行为完全相同，不存在"我本地能跑但服务器不行"的问题。
• 升级简单 — 拉取新镜像、停止旧容器、用相同参数重建即可。配置文件通过 Volume 挂载保留，升级不丢数据。

系统要求

如果只使用 Web UI 聊天，不需要公网 IP。但 Telegram 和 Discord 的 Webhook 模式需要服务器能被外部访问。

各系统 Docker 安装方法

Ubuntu / Debian

sudo apt update
sudo apt install -y docker.io docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
# 重新登录终端使 docker 组生效
docker --version

CentOS / RHEL / Rocky Linux

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

macOS

下载 Docker Desktop for Mac，安装后启动即可。支持 Intel 和 Apple Silicon（M1/M2/M3/M4）。

Windows（WSL2）

1. 以管理员身份打开 PowerShell，执行 wsl --install 启用 WSL2
2. 重启电脑
3. 下载安装 Docker Desktop for Windows
4. 在 Docker Desktop 设置中确认 "Use the WSL 2 based engine" 已勾选
5. 打开 WSL 终端（Ubuntu），执行 docker --version 验证

拉取 OpenClaw Docker 镜像

docker pull ghcr.io/openclaw/openclaw:latest

镜像托管在 GitHub Container Registry（ghcr.io），大小约 500MB。:latest 标签指向最新稳定版。

注意：不要使用 :main 标签 —— 这是开发分支的实时构建，可能包含未修复的 Bug（例如曾经出现过 Telegram 轮询问题）。

配置文件结构详解

OpenClaw 从 ~/.openclaw/openclaw.json 读取配置。这是一个 JSON 文件，包含以下主要部分：

完整配置示例

{
  "models": {
    "providers": {
      "openrouter": {
        "apiKey": "sk-or-v1-你的OpenRouter密钥"
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "你的Telegram Bot Token",
      "dmPolicy": "pairing"
    },
    "discord": {
      "enabled": true,
      "botToken": "你的Discord Bot Token",
      "dmPolicy": "open",
      "allowFrom": ["*"]
    }
  },
  "plugins": {
    "entries": {
      "telegram": { "enabled": true },
      "discord": { "enabled": true }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4.6"
      }
    }
  },
  "gateway": {
    "auth": {
      "token": "你的网关认证Token（随机UUID）"
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}

各部分说明

• models.providers — 配置 AI 模型提供商。填入 API 密钥。支持 OpenRouter（推荐，一个密钥访问所有模型）、OpenAI、Anthropic、Google 等。
• channels — 配置聊天渠道。每个渠道需要 enabled: true 和对应的 Token。Telegram 的 dmPolicy 建议用 "pairing"（防止陌生人滥用）；Discord 用 "open" + allowFrom: ["*"]（Discord 机器人需邀请才能加入，安全性由平台保障）。
• plugins.entries — 启用渠道插件。必须同时在 channels 和 plugins.entries 中启用，渠道才能工作。仅配置 channels 不启用 plugins 是最常见的新手错误。
• agents.defaults.model.primary — 默认使用的 AI 模型。格式为 提供商名/模型ID，例如 openrouter/anthropic/claude-sonnet-4.6。提供商名必须与 models.providers 中的键名一致。
• gateway.auth — 网关认证。必须是对象格式 { "token": "..." }，不能是字符串。Token 建议使用 UUID（uuidgen 命令生成）。
• gateway.controlUi.allowInsecureAuth — 设为 true 允许远程浏览器通过 Token 直接连接 Web UI，无需设备配对。在 HTTPS 环境下安全。

Docker Run 命令详解

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/home/node/.openclaw \
  --memory=2g \
  --memory-swap=3g \
  --restart unless-stopped \
  ghcr.io/openclaw/openclaw:latest \
  node openclaw.mjs gateway --allow-unconfigured

参数逐项解释

部署步骤汇总

常见 Docker 问题排查

权限错误（Permission Denied）

OpenClaw 容器以 node 用户（uid 1000）运行。如果挂载的 ~/.openclaw 目录权限不足，容器无法读写配置文件和凭证。解决方法：

chmod 777 ~/.openclaw
chmod 777 ~/.openclaw/credentials

为什么用 777？因为宿主机用户和容器内 node 用户的 uid 可能不同，chown 1000:1000 在非 root 用户下无法执行。777 是最简单可靠的方案。

国内镜像拉取慢

ghcr.io 在国内访问速度不稳定。可以配置 Docker 镜像加速器（详见下方"国内用户专区"）。或者使用代理拉取后导出：

# 在能访问 ghcr.io 的机器上拉取并导出
docker pull ghcr.io/openclaw/openclaw:latest
docker save ghcr.io/openclaw/openclaw:latest -o openclaw.tar

# 传输到目标机器后导入
docker load -i openclaw.tar

端口冲突

如果 18789 端口被占用，修改端口映射。例如映射到 28789：

docker run -d --name openclaw -p 28789:18789 ...

容器内部端口始终是 18789，只需修改宿主机端口（冒号左侧）。

OOM（内存不足）被 Kill

如果 docker logs openclaw 显示 Killed 或 OOMKilled，说明内存不够。确保使用 --memory=2g --memory-swap=3g，且宿主机有足够可用内存。512MB 内存必定 OOM。

Gateway Auth 格式错误

gateway.auth 必须是对象格式：

// 正确
"gateway": { "auth": { "token": "my-secret-token" } }

// 错误 — 不能是字符串
"gateway": { "auth": "my-secret-token" }

// 错误 — "none" 不被接受
"gateway": { "auth": "none" }

credentials 目录不存在

如果 Telegram 使用 dmPolicy: "pairing"，必须存在 ~/.openclaw/credentials/ 目录。否则 Telegram 插件会静默丢弃所有消息 —— 不报错、不响应。这是最隐蔽的 Bug 之一。

mkdir -p ~/.openclaw/credentials
chmod 777 ~/.openclaw/credentials

Docker Compose 部署

如果你更喜欢用 docker-compose（现在是 docker compose）管理容器，以下是完整的 docker-compose.yml 示例：

version: "3.8"

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    command: node openclaw.mjs gateway --allow-unconfigured
    ports:
      - "18789:18789"
    volumes:
      - ~/.openclaw:/home/node/.openclaw
    deploy:
      resources:
        limits:
          memory: 2g
        reservations:
          memory: 512m
    restart: unless-stopped

启动和管理命令：

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

# 查看日志
docker compose logs -f

# 停止
docker compose down

# 重建（更新镜像后）
docker compose pull
docker compose up -d

Docker Compose 的优势：所有参数写在 YAML 文件中，不用记住长长的 docker run 命令。升级时只需 docker compose pull && docker compose up -d。

如何升级 OpenClaw Docker 容器

自建用户升级步骤：

1. 拉取最新镜像：docker pull ghcr.io/openclaw/openclaw:latest
2. 停止并删除旧容器：docker stop openclaw && docker rm openclaw
3. 用相同的 docker run 命令重新创建容器（配置文件通过 Volume 挂载，不会丢失）

如果使用 Docker Compose：

docker compose pull
docker compose up -d

Compose 会自动检测镜像变化并重建容器，配置文件保留。

国内用户专区

Docker 镜像加速器

国内直接拉取 ghcr.io 镜像速度很慢甚至超时。以下是常用的加速方案：

• 阿里云加速器 — 登录 阿里云容器镜像服务，获取专属加速地址，配置到 Docker daemon.json
• 腾讯云加速器 — 腾讯云容器服务提供镜像加速，地址格式 https://mirror.ccs.tencentyun.com
• DaoCloud 加速器 — DaoCloud 镜像加速，免费使用

配置方法（以阿里云为例）：

# 编辑 Docker 配置
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{
  "registry-mirrors": [
    "https://你的ID.mirror.aliyuncs.com"
  ]
}
EOF

# 重启 Docker
sudo systemctl daemon-reload
sudo systemctl restart docker

注意：镜像加速器主要加速 Docker Hub（docker.io）镜像。ghcr.io（GitHub）镜像加速支持因服务商不同而异。如果加速器不支持 ghcr.io，可以使用上面提到的"导出/导入"方案。

AI 模型 API 代理

OpenClaw 需要调用 AI 模型 API（OpenAI、Anthropic、Google 等），这些 API 在国内可能无法直接访问。解决方案：

• 使用 OpenRouter（推荐）— 一个 API 密钥访问所有主流模型，部分地区可直接访问
• 使用国产模型 — 配置 DeepSeek、Kimi（Moonshot）、通义千问等国内 API，无需翻墙
• 搭建 API 代理 — 在海外服务器上搭建 OpenAI API 代理，将请求转发到官方 API
• 使用 OpenClaw Launch — 服务器在美国，直接访问所有 API，无需任何代理配置

Docker 自建 vs OpenClaw Launch 对比

自建给你完全的控制权，但需要投入时间和精力。OpenClaw Launch 则是"交钥匙"方案：

Docker 常用命令速查

• docker pull ghcr.io/openclaw/openclaw:latest — 拉取 / 更新最新镜像
• docker logs openclaw -f — 查看实时日志（-f 持续输出）
• docker logs openclaw --tail 100 — 查看最近 100 行日志
• docker restart openclaw — 重启容器
• docker stop openclaw — 停止容器
• docker start openclaw — 启动已停止的容器
• docker rm openclaw — 删除容器（需先 stop）
• docker exec -it openclaw sh — 进入容器内部 Shell
• docker stats openclaw — 查看容器 CPU / 内存占用
• docker inspect openclaw — 查看容器详细配置

进阶：反向代理和 HTTPS

如果需要通过域名 + HTTPS 访问（Telegram Webhook 必须 HTTPS），推荐使用 Caddy 反向代理：

# 安装 Caddy（Ubuntu）
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

# Caddyfile 配置
# /etc/caddy/Caddyfile
your-domain.com {
    reverse_proxy localhost:18789
}

Caddy 会自动申请和续期 SSL 证书（Let's Encrypt），比 Nginx 配置简单得多。

如何选择？

选择 Docker 自建 — 如果你有 Docker 经验、想完全掌控服务器和数据、享受折腾的过程。适合开发者和运维人员。

选择 OpenClaw Launch — 如果你想立刻用上 AI 智能体、不想管服务器和配置文件、或者是新手用户。$3/月起，10 秒部署，零运维。支持支付宝和微信支付。