黑屏或无响应是因gateway未运行、ui资源缺失、构建失败、缓存残留或端口被拦截；需依次检查gateway状态、构建ui、清理配置、强制刷新及验证端口监听。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您完成 OpenClaw 安装后启动程序，界面显示黑屏或完全无响应，则可能是由于 Gateway 服务未成功运行、UI 资源缺失或前端构建失败所致。以下是解决此问题的步骤：
一、验证 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”，此时需主动构建 UI。
1、进入 OpenClaw 安装目录：cd ~/.openclaw
2、执行 UI 构建命令（需已安装 pnpm）：pnpm ui:build
3、若提示 pnpm 未找到，先全局安装：npm install -g pnpm
4、构建完成后，重新启动 Gateway：openclaw gateway restart
三、清除残留配置与缓存
旧版本残留文件或损坏的配置可能导致 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 文件，导致页面无法渲染。需绕过缓存强制获取最新资源。
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、若无输出，说明 Gateway 未绑定端口，确认配置中 gateway.port 未被设为 0 或空值
3、临时关闭系统防火墙进行测试：macOS 在“系统设置→网络→防火墙”中关闭；Windows 在“控制面板→Windows Defender 防火墙”中关闭
4、验证本地访问：curl -I http://127.0.0.1:18789 应返回 HTTP 200 或 302 响应头
