OpenClaw 2026.3.22 全局 npm 安装可能导致控制台 UI 失效：缺少 dist/control-ui 与 scripts/ui.js

有用户反馈：如果你是通过 全局 npm 安装（npm install -g openclaw）来使用 OpenClaw，并升级到 2026.3.22，可能会出现一种很“迷惑”的状态：

网关进程仍在运行、API/服务可能仍可访问
但本地 Control UI（控制台/仪表盘） 打不开，报“资源缺失”

核心判断：这更像是 npm 发布包的打包/发布回归，而不是你本地环境突然坏掉。

来源：

主问题： openclaw/openclaw#53019
相关报告 + 回滚可用方案： openclaw/openclaw#53013

你会看到什么现象

升级到 2026.3.22 后，常见表现包括：

打开本地仪表盘时出现提示：
- “Control UI assets not found. Build them with pnpm ui:build …”
访问网关根路径（例如 http://127.0.0.1:18789/）可能返回 503，但网关本身并不一定挂掉。

为什么提示你 `pnpm ui:build` 但依然修不好

报告显示：在 [email protected] 的 npm 发布包里，存在关键文件缺失：

dist/control-ui/（已构建的 UI 静态资源）缺失
scripts/ui.js（ui:build / ui:dev 等脚本实际引用的入口）也缺失

因此在“全局 npm 安装”的场景下，即使你照着提示运行 pnpm ui:build，也可能因为缺少 scripts/ui.js 而无法完成构建。

如何确认你遇到的就是这个打包回归

1）确认版本：

openclaw --version

2）定位全局安装路径：

which openclaw
npm config get prefix

3）进入全局包目录检查文件（不同机器路径不同；下面是报告中的示例）：

# 示例：macOS Homebrew 前缀
cd /opt/homebrew/lib/node_modules/openclaw

# 示例：Linuxbrew 前缀
cd /home/linuxbrew/.linuxbrew/lib/node_modules/openclaw

ls -la dist/control-ui scripts/ui.js

如果 dist/control-ui 和 scripts/ui.js 都不存在，基本可以确定是同一类问题。

快速分流：这是 npm 打包回归，还是你本机构建/权限出了问题

很多人第一次看到 Control UI 资源缺失，会先怀疑 Node、权限、pnpm 或本地目录污染。但更高效的分流是：

网关还能启动，但 UI 资源目录和 scripts/ui.js 同时缺失
- 这更像发布包本身缺文件，而不是你本地突然构建坏掉。
只有当前机器异常，别的同版本安装正常
- 这时才更值得回头查本地安装路径、权限、残留缓存或被清理过的文件。
错误提示建议 pnpm ui:build，但安装目录里根本没有相关脚本入口
- 这说明问题不只是“你没执行重建”，而是恢复路径本身在该安装形态下不可用。
不仅 UI 缺失，连 gateway 或 CLI 也一起异常
- 那就别只盯着 Control UI 资产丢失，还要扩大到更广泛的安装损坏或版本兼容问题。

这个分流能避免团队在错误方向上浪费时间，比如不断重装 pnpm、改权限，却忽略了真正坏掉的是发布出去的制品内容。

可落地的临时规避方案（等官方修复版发布前）

方案 A）回滚到已知可用版本（最快止血）

有报告称回滚后仪表盘恢复：

npm uninstall -g openclaw
npm install -g [email protected]
openclaw gateway restart

如果你团队有固定版本策略，建议在 CI/部署脚本里把 OpenClaw 版本 pin 住，避免“自动升级后 UI 直接不可用”。

方案 B）暂时避开“全局 npm 发布包”这条安装路径

如果你的使用方式允许，可以考虑使用会从源码构建 UI 的安装方式/流程，减少对 npm 发布包里预置产物的依赖（本次问题指向的就是发布包内容缺失）。

方案 C）网关可用但 UI 不可用时的操作建议

如果你确认网关服务仍在跑，短期内可以先避免依赖仪表盘的操作（例如需要通过 UI 才能完成的配置、可视化调试等），并尽快选择回滚或升级到官方修复后的版本。

维护者需要修复的点（从现象出发）

从 issue 描述看，合理的修复方向至少应满足其一：

npm 包里包含 dist/control-ui/
或者包含 pnpm ui:build 在“安装后目录”中可运行所需的脚本与输入
或者调整错误提示，避免在打包安装场景下推荐无法执行的恢复指令

常见上线判断问题

什么时候该停止排查本机环境，改把它当成发布包打包回归

如果网关还能启动，openclaw --version 显示 2026.3.22，并且全局安装目录里同时缺少 dist/control-ui/ 和 scripts/ui.js，这时就不该再把问题当成“本机偶发损坏”继续深挖。三个信号叠在一起，更接近坏掉的是发布出去的 npm 制品，而不是某一台机器单独构建失败。

团队在下一次通过 npm 升级 OpenClaw 前，最该固定或检查什么

至少做两件事：第一，把 OpenClaw 版本固定在部署脚本或安装流程里；第二，在升级后立刻检查安装目录里是否还存在 UI 资源目录和 rebuild 脚本入口。这样这次事故就会从“上线后才发现仪表盘打不开”，变成一次明确的升级验收失败。

值班团队怎么快速判断这是发布包缺件，而不是本地 UI 构建姿势错了

如果你一边看到 dist/control-ui/ 缺失，一边又看到 scripts/ui.js 也缺失，就应该优先把它判断成 已发布 npm 包内容不完整，而不是先怀疑某台机器单点构建坏了。

更像是 发布包缺件 的信号包括：

全局安装路径里同时缺少 UI 静态资源目录和 UI 重建脚本入口
多名用户在相近版本上复现相同缺件现象
pnpm ui:build 报的不是业务逻辑错误，而是脚本入口本身不存在

更像是 本地安装或构建问题 的信号包括：

包内容其实都在，只是权限、安装中断或路径损坏导致 UI 起不来
只有单机复现，换一台干净环境安装后无法复现
重装后文件完整，但服务启动或访问仍异常

这个分流很重要，因为它决定了值班团队到底该去查本机环境，还是该立即停止把同一 npm 版本继续往更多机器上铺。