openclaw docker部署失败的核心原因是五个可复现配置断点：docker服务未就绪、镜像拉取失败、环境变量错误、网关绑定地址不当、cors白名单未配置，按顺序排查即可解决终端红字、容器秒退、网页打不开及飞书无响应等问题。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw Docker部署报错时，终端红字满屏、容器秒退、Web页面打不开、飞书不响应——这些问题不是随机发生的，而是由几个高频且可复现的配置断点导致的。你不需要重装整个环境，只需按顺序检查这五个关键环节。
确认Docker基础环境是否就绪
先验证Docker服务本身是否健康运行：执行docker info，若提示“Cannot connect to the Docker daemon”，说明Docker守护进程未启动或当前用户无权限。
Linux用户必须将当前用户加入docker组：sudo usermod -aG docker $USER，然后彻底退出终端重新登录；Windows用户需确认WSL2已启用并完成内核更新，否则Docker Desktop会卡在“WSL2 backend installation is incomplete”。
这一步跳过会导致后续所有操作都失败，因为容器根本无法创建。
检查镜像拉取是否真正成功
方法一：直接拉取阿里云镜像源（推荐国内用户）
执行docker pull registry.cn-hangzhou.aliyuncs.com/qiluo-images/openclaw:latest，不要用docker pull openclaw/openclaw——后者在国内大概率超时或返回denied错误。
方法二：若坚持用官方源，必须先配置镜像加速器
编辑/etc/docker/daemon.json，写入{"registry-mirrors": ["https://hub-mirror.c.163.com"]}，【改完必须执行sudo systemctl restart docker】，否则配置永不生效。
验证是否拉取成功：docker images | grep openclaw，看不到镜像名就别往下走。
排查容器启动失败的核心原因
第一步：查看容器退出时的日志
执行docker compose up -d && docker compose logs --tail 50 openclaw，重点找Permission denied、Config validation failed、gateway token mismatch这几类关键词。
第二步：检查.env文件权限与内容chmod 600 .env防止密钥泄露；打开.env确认OPENCLAW_SECRET_KEY已生成（不能是空值或"123456"），且OPENCLAW_GATEWAY_TOKEN与~/.openclaw/openclaw.json中gateway.auth.token严格一致。
第三步：验证Gateway绑定地址是否适配Docker网络
打开~/.openclaw/openclaw.json，将"bind"字段从"local"改为"lan"，或直接设为"0.0.0.0"，否则容器内网关无法响应外部请求。
修复Web UI无法访问问题
现象：浏览器访问http://192.168.x.x:18789提示连接被重置，或显示空白页。
根本原因是CORS白名单拦截——OpenClaw网关默认只允许特定来源访问控制台。
修改~/.openclaw/openclaw.json中的gateway.controlUi.allowedOrigins节点：
添加"*"通配符（测试环境可用），或精确填写你实际访问的协议+域名，例如"http://openclaw.local"。
【改完必须重启容器：docker compose down && docker compose up -d】，热重载不生效。
解决设备配对卡在PENDING状态
步骤一：列出所有待批准设备
执行docker compose run --rm openclaw-cli devices list，观察输出中STATUS列是否为PENDING。
步骤二：批准指定设备ID
从上一步输出中复制ID（如dev_xyz789），执行docker compose run --rm openclaw-cli devices approve dev_xyz789。
步骤三：批量批准（适合多端调试）
执行docker compose run --rm openclaw-cli devices approve --all，避免逐个输入。
注意：清除浏览器缓存、更换手机访问、重建容器都会触发新设备注册，每次都要重新批准。
