OpenClaw Docker 部署完整教程

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

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

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

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

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

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

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

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

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 -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

参数作用 -d 后台运行（detached 模式），容器在后台持续运行 –name openclaw 给容器命名，方便后续 docker logs/stop/restart 操作 -p 18789:18789 端口映射：宿主机 18789 → 容器 18789（Gateway 默认端口） -v /.openclaw:/home/node/.openclaw 挂载配置目录。容器内以 /home/node/.openclaw 路径读取配置文件 –memory=2g 限制容器内存为 2GB。OpenClaw 在 512MB 下可能 OOM 崩溃 –memory-swap=3g 内存 + Swap 总量 3GB，提供额外缓冲 –restart unless-stopped 容器异常退出时自动重启，手动 stop 后不自动启动 node openclaw.mjs gateway –allow-unconfigured 启动 Gateway 模式，允许在未完全配置时启动（Web UI 可用）

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，只需修改宿主机端口（冒号左侧）。

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

gateway.auth 必须是对象格式：

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

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

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

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

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

如果你更喜欢用 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。

自建用户升级步骤：

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

如果使用 Docker Compose：

docker compose pull docker compose up -d

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

提示：升级前建议备份配置文件： cp -r ~/.openclaw ~/.openclaw.bak

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

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

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

# 编辑 Docker 配置 sudo mkdir -p /etc/docker sudo tee /etc/docker/daemon.json <

 "https://你的ID.mirror.aliyuncs.com" 
 ] } EOF
 重启 Docker
 sudo systemctl daemon-reload sudo systemctl restart docker
注意：镜像加速器主要加速 Docker Hub（docker.io）镜像。ghcr.io（GitHub）镜像加速支持因服务商不同而异。如果加速器不支持 ghcr.io，可以使用上面提到的"导出/导入"方案。
OpenClaw 需要调用 AI 模型 API（OpenAI、Anthropic、Google 等），这些 API 在国内可能无法直接访问。解决方案： 
    
    使用 OpenRouter（推荐）— 一个 API 密钥访问所有主流模型，部分地区可直接访问 
    使用国产模型 — 配置 DeepSeek、Kimi（Moonshot）、通义千问等国内 API，无需翻墙 
    搭建 API 代理 — 在海外服务器上搭建 OpenAI API 代理，将请求转发到官方 API 
    使用 OpenClaw Launch — 服务器在美国，直接访问所有 API，无需任何代理配置 
   
自建给你完全的控制权，但需要投入时间和精力。OpenClaw Launch 则是"交钥匙"方案： 
    
    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 访问（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 秒部署，零运维。支持支付宝和微信支付。

OpenClaw Docker 部署完整教程

重新登录终端使 docker 组生效

传输到目标机器后导入

查看日志

停止

重建（更新镜像后）

重启 Docker

Caddyfile 配置

/etc/caddy/Caddyfile

相关推荐