openclaw web ui白屏的首要原因是服务未真正启动或端口绑定错误，需依次验证gateway状态、0.0.0.0:18789监听、curl健康检查、前端资源404、浏览器兼容性及docker映射与静态文件完整性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw部署后访问Web UI出现白屏（空白页），页面标题能加载但主体内容缺失，说明HTML已返回但前端资源未加载或后端服务未响应，需分层定位是静态资源丢失、服务未启动、端口映射错误还是浏览器兼容问题。
第一步：确认服务是否真正运行并监听正确端口
白屏最常见原因是服务压根没起来，而不是界面卡住。先验证核心进程状态：
在终端执行：openclaw status → 观察输出中gateway和web两项是否显示running；若任一为stopped或unknown，直接跳到网关排查环节。
若状态正常，继续执行：netstat -ano | findstr :18789（Windows）或lsof -i :18789（Mac/Linux）。【必须看到0.0.0.0:18789而非127.0.0.1:18789】，后者会导致局域网设备无法访问，仅本机可见——这正是白屏的隐藏元凶之一。
如果命令无任何输出，说明端口根本没被监听，此时不是端口被占，而是Gateway因配置缺失静默退出。立刻检查~/.openclaw-dev/config.yaml中是否存在gateway.mode: local这一行，缺失则手动补上并重启服务。
第二步：用curl直连验证后端响应能力
绕过浏览器，用命令行测试服务真实可用性：
执行：curl -v http://127.0.0.1:18789/health。成功返回{"status":"ok"}说明后端HTTP服务正常；若返回Connection refused，证明服务未启动或绑定地址错误；若返回404，说明路由注册失败，大概率是前端构建包缺失。
再执行：curl -I http://127.0.0.1:18789/static/main.js。如果返回404 Not Found，问题锁定在前端资源路径错误或镜像未打包静态文件——Docker离线部署时极易发生，需重新构建镜像并确认/app/dist目录存在且含index.html、main.js等文件。
第三步：浏览器侧强制诊断
白屏常被误判为后端问题，实则90%源于前端加载失败。打开Chrome或Edge（【360/搜狗等国产浏览器会白屏，这是已知兼容性缺陷】），访问http://127.0.0.1:18789后立即按F12打开开发者工具：
切换到Network标签页 → 刷新页面 → 查看红色报错请求。重点关注main.js、vendor.css、/api/chat等资源是否全部200。若有404，复制URL在新标签页打开，确认是否路径拼写错误（如多出/dist前缀）。
切换到Console标签页 → 刷新 → 查看JS报错。若出现Failed to load resource: net::ERR_CONNECTION_REFUSED，说明WebSocket连接被拒，需检查gateway.mode是否为local且gateway.port与前端配置一致；若出现React is not defined，证明react依赖未注入，属于构建包损坏，必须重装部署包。
最后尝试无痕模式访问，排除浏览器插件干扰。若无痕模式正常，问题出在广告屏蔽插件或缓存策略上，清除localhost:18789站点数据即可。
第四步：Docker环境专项检查
如果你用Docker部署，白屏几乎必查三件事：
方法一：确认端口映射正确。运行docker ps，检查输出中是否有0.0.0.0:18789->80/tcp。若显示127.0.0.1:18789->80/tcp，需删掉容器重建，启动时加-p 18789:80而非-p 127.0.0.1:18789:80。
方法二：进入容器验证文件完整性。执行docker exec -it your-openclaw-container-name sh → 运行ls -la /app/dist/，确保目录下有index.html、static/子目录及其中的js/css文件。若dist为空，说明构建阶段失败，需检查Dockerfile中COPY指令路径是否匹配实际输出位置。
方法三：检查Nginx配置指向。执行cat /etc/nginx/conf.d/default.conf，确认root指令指向/app/dist而非/app/src，且location / { try_files $uri $uri/ /index.html; }规则存在。缺少该规则会导致React Router路由刷新404。
