黑屏问题主因是gateway服务异常、ui资源未构建、缓存干扰、浏览器缓存或端口被拦截；需依次检查gateway状态、构建ui资源、清除缓存、强制刷新及验证端口监听。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您启动 OpenClaw AI 后界面呈现黑屏且无任何响应，则极可能是前端 UI 资源未加载、Gateway 服务异常或本地环境缓存干扰所致。以下是解决此问题的步骤：
一、验证 Gateway 服务状态
OpenClaw 的 UI 完全依赖 Gateway 服务提供后端 API 与静态资源路由，若 Gateway 进程未运行或健康检查失败，前端将无法获取必要资源，直接表现为黑屏。
1、在终端中执行命令检查 Gateway 运行状态：openclaw gateway status
2、确认输出中同时包含 Runtime: running 和 RPC probe: ok
3、若显示 Runtime: stopped，执行重启命令：openclaw gateway restart
4、若重启失败，查看实时日志定位错误：openclaw logs --follow
二、检查 UI 资源是否构建完成
黑屏常见原因为 Control UI 前端静态资源缺失，尤其在汉化版安装、手动构建或首次部署后未执行构建流程时必然发生，系统日志中通常提示 “Control UI assets not found”。
1、进入 OpenClaw 安装目录：cd ~/.openclaw
2、执行 UI 构建命令（需已安装 pnpm）：pnpm ui:build
3、若提示 pnpm 未找到，先全局安装：npm install -g pnpm
4、构建完成后，重新启动 Gateway：openclaw gateway restart
三、清除残留配置与缓存
旧版本残留的配置文件、损坏的用户级目录或 npm 缓存可能引发 UI 初始化逻辑崩溃，导致白屏或黑屏，该问题在跨版本升级后高频出现。
1、删除用户级 OpenClaw 目录：rm -rf ~/.openclaw（macOS/Linux）
2、Windows 用户执行：Remove-Item -Recurse -Force $HOME\.openclaw
3、清除 npm 全局缓存：npm cache clean --force
4、重新安装 OpenClaw（推荐使用汉化版）：npm install -g @qingchencloud/openclaw-zh@latest
四、强制重载前端资源
浏览器可能缓存了失效的 JS/CSS 文件或过期的 Service Worker，导致页面脚本中断、样式丢失或入口文件 404，从而无法渲染 UI。
1、打开浏览器开发者工具（F12），切换至 Network 标签页
2、勾选 Disable cache 选项
3、在地址栏输入仪表板地址：http://127.0.0.1:18789
4、按 Ctrl+Shift+R（Windows/Linux）或 Cmd+Shift+R（macOS）硬性刷新
五、检查端口监听与防火墙拦截
即使 Gateway 显示运行中，若其未实际监听 18789 端口，或系统防火墙/安全软件阻止该端口的 HTTP 请求，浏览器仍将收到连接拒绝或超时响应，最终呈现黑屏。
1、检查端口监听状态：lsof -i :18789（macOS/Linux）或 netstat -ano | findstr :18789（Windows）
2、确认输出中存在 LISTEN 状态且 PID 对应 Gateway 进程
3、临时禁用系统防火墙（Windows Defender 防火墙 / ufw / firewalld）
4、关闭所有终端安全软件（如 360、火绒、Windows Defender 实时防护）
