紧急提醒!OpenClaw V2026.3.22 踩坑解决方案

一、问题现象

OpenClaw 升级到 V2026.3.22 版本后，许多用户发现全新安装或升级后，控制面板无法打开 ，浏览器访问 http://127.0.0.1:18789 报错如下：

Control UI assets not found. Build them with `pnpm ui:build` (auto-installs UI deps), or run `pnpm ui:dev` during development.

二、问题原因

这不是你的操作失误，也不是安装失败。根本原因是官方 npm 安装包在 V2026.3.22 版本中缺少了预编译的 UI 资源文件 ——dist/control-ui/ 目录为空，是官方发布流程中的一个疏漏。

Gateway 服务本身正常运行，但浏览器界面缺少 HTML/CSS/JS 资源，无法渲染。

三、解决方案

第一步：克隆 OpenClaw 源码

打开终端，执行以下命令克隆 GitHub 源码：

git clone https://github.com/openclaw/openclaw.git cd openclaw

注意： 如果终端无法访问 GitHub（网络超时），需要先配置代理：

git config --global http.proxy http://你的代理地址:端口 git config --global https.proxy http://你的代理地址:端口

或者直接使用 GitHub Personal Access Token（PAT）克隆：

git clone https://你的PAT@github.com/openclaw/openclaw.git cd openclaw

PAT 创建方法： 第一步：登录 GitHub，点击右上角头像 → Settings → Developer settings 第二步：Personal access tokens → Tokens (classic) → Generate new token (classic) 第三步：勾选 repo 权限（Full control of private repositories）第四步：点击 Generate token，复制生成的 Token

第二步：安装依赖并构建 UI

进入源码目录，执行：

cd openclaw pnpm install pnpm ui:build

构建过程需要几分钟，请耐心等待，直到看到类似 "Build complete" 的提示。

第三步：复制 UI 文件到正确位置

构建完成后，找到源码目录下的 dist/control-ui/ 文件夹（注意：是克隆下来的源码目录，不是 npm 安装目录）。

复制到 npm 全局安装路径：

将 dist/control-ui/ 整个文件夹复制到以下路径：

C:\Users\你的用户名\AppData\Roaming\npm\node_modules\openclaw\dist\control-ui\

如果安装时指定了其他路径，请根据实际情况调整。

第四步：重启 Gateway

在终端执行：

openclaw gateway restart

第五步：验证

打开浏览器，访问 http://127.0.0.1:18789/，正常显示控制面板即表示修复成功。

四、预防措施

措施一：升级前先查 GitHub Issues

在 GitHub OpenClaw 仓库的 Issues 页面搜索 "Control UI" 或 "ui:build"，确认没有已知问题再升级。

措施二：升级前备份旧版本

xcopy "C:\Users\你的用户名\AppData\Roaming\npm\node_modules\openclaw" "C:\backup\openclaw-旧版本备份" /E /I

措施三：使用源码安装（最稳妥）

如果经常使用 OpenClaw 开发版，建议直接从 GitHub 克隆源码运行：

git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install openclaw gateway start

措施四：关注官方动态

关注 OpenClaw GitHub Releases 页面，有新版本发布时等一两天再升级，避开刚发布的问题高峰期。

五、总结

问题现象：浏览器打开 http://127.0.0.1:18789 报错 "Control UI assets not found"

根本原因：npm 包发布时缺少 UI 资源文件（dist/control-ui/）

解决方案：从 GitHub 源码执行 pnpm ui:build 构建 UI，复制到 node_modules/openclaw/dist/control-ui/，重启 Gateway

预防：升级前查 Issues、备份旧版本、优先使用源码安装

六、Windows 常用路径

OpenClaw 安装目录： C:\Users\你的用户名\AppData\Roaming\npm\node_modules\openclaw\

Gateway 日志： C:\Users\你的用户名\AppData\Local\Temp\openclaw\openclaw-YYYY-MM-DD.log

配置文件： C:\Users\你的用户名.openclaw\openclaw.json

遇到问题欢迎在评论区交流，也可以直接向 GitHub 提交 Issue，帮助官方完善这个问题。