OpenClaw 2026.3.22升级踩坑:UI界面不翼而飞?源码构建3分钟找回!

问题背景

系统：Mac OS M4

今天，不小心点了升级。去官网一看，OpenClaw 在 2026.3.22 版本升级后，原来是有重大更新，主要涉及：插件系统、权限配置、浏览器链接方式等。

部分通过 Homebrew 安装的用户，可能跟我一样，发现升级后，无法访问 Web 管理界面（http://127.0.0.1:18789/chat?session=main或 http://127.0.0.1:18789/__openclaw__/canvas/），浏览器提示Unauthorized或资源加载失败。与此同时，在终端运行openclaw doctor时可能会看到类似Control UI assets not found的警告。

本文记录了一次完整的排查与解决过程，并给出通用的修复步骤。

你可能和我的目录和系统等都不一样，但是原理是一样的，本质就是要重新构建UI。

具体更新查看官网：https://openclaw.ai/

错误现象

在升级到 OpenClaw 2026.3.22 后，尝试构建 UI 资源时遇到如下错误：

$cd /opt/homebrew/lib/node_modules/openclaw$ pnpm ui:build> openclaw@2026.3.23 ui:build /Users/mac/openclaw-source> node scripts/ui.js buildnode:internal/modules/cjs/loader:1478  throw err;  ^Error: Cannot find module '/opt/homebrew/lib/node_modules/openclaw/scripts/ui.js'    at Module._resolveFilename (node:internal/modules/cjs/loader:1475:15)    ...

当尝试在源码目录中构建时，又遇到vite: command not found错误：

$cd /Users/mac/openclaw-source/ui$ pnpm run build> openclaw-control-ui@ build /Users/mac/openclaw-source/ui> vite buildsh: vite: command not foundELIFECYCLECommand failed.

最终访问管理界面始终显示Unauthorized或资源缺失。

可能原因分析

Homebrew 安装的 OpenClaw 是预编译包

Homebrew 为了减小体积，只打包了运行所需的dist、node_modules等文件，不包含前端源码和构建脚本（如scripts/ui.js）。因此在 Homebrew 目录下直接运行pnpm ui:build会因找不到构建脚本而失败。

前端资源需要从源码独立构建

OpenClaw 的 UI 使用 Vite 构建，这部分代码位于源码仓库的ui/子项目中。要生成dist/control-ui目录，必须克隆完整仓库，安装依赖，然后执行pnpm run build。

构建依赖缺失

即使克隆了源码，如果在根目录执行pnpm install后直接进入ui目录运行vite build，可能因为vite未在 PATH 中而报错。正确做法是在ui目录内使用pnpm run build（它会使用 pnpm 的脚本执行器自动找到本地的vite可执行文件）。

UI 资源未正确放置

构建完成后，需要将生成的静态文件复制到 Homebrew 安装目录的dist/下，OpenClaw 网关才能正确提供这些资源。

解决方案

下面步骤已在 macOS（Intel 与 Apple Silicon）上验证通过。下面的路径大家自行替换，原理是一样的。

克隆 OpenClaw 完整源码

cd /Users/macgit clone https://github.com/openclaw/openclaw.git ~/openclaw-sourcecd /Users/mac/openclaw-source/ui

2. 进入 UI 子项目并构建

cd uipnpm install # 安装 UI 依赖（如果之前已在根目录安装过，可跳过）pnpm run build # 构建 UI 资源

3. 将构建产物复制到 Homebrew 安装目录

# 可选：备份原有 dist 目录sudo cp -r /opt/homebrew/lib/node_modules/openclaw/dist /opt/homebrew/lib/node_modules/openclaw/dist.backup# 复制新的 UI 资源sudo cp -r ~/openclaw-source/ui/dist/control-ui /opt/homebrew/lib/node_modules/openclaw/dist/

4. 重启 OpenClaw 服务

# 方式一：如果 OpenClaw 在前台运行，按 Ctrl+C 停止后重新启动openclaw gateway restart
# 方式二：如果使用 brew services 管理brew services restart openclaw# 方式三：通过 openclaw 自身命令重启（若支持）openclaw gateway restart

5. 清理临时源码目录（可选）

rm -rf ~/openclaw-source

验证结果

应能正常显示 UI，不再出现Unauthorized或资源加载失败。运行openclaw doctor检查，应不再有Control UI assets not found的警告。

常见问题与注意事项

Q1: 为什么 Homebrew 安装的包不能直接使用pnpm ui:build？

A: Homebrew 的 OpenClaw 公式（formula）通常只包含运行时必需的文件，不包括开发脚本和前端源码。要生成 UI，必须从源码仓库构建。

Q2: 我使用的是 Intel Mac，路径和 Apple Silicon 有何不同？

A: 对于 Intel Mac，Homebrew 默认安装目录是/usr/local，因此上述命令中的/opt/homebrew应替换为/usr/local。例如：

sudo cp -r ~/openclaw-source/ui/dist/control-ui /usr/local/lib/node_modules/openclaw/dist/

Q3: 构建 UI 时出现vite: command not found怎么办？

A: 确保在ui子目录内运行pnpm run build，而不是直接运行vite build。如果仍然报错，可以尝试在ui目录内执行pnpm exec vite build或重新运行pnpm install。

Q4: 复制文件时提示权限不足？

A: 使用sudo提升权限，或确保你对/opt/homebrew/lib/node_modules/openclaw/dist/目录有写权限（例如通过chown调整）。

下次我再也不敢随便升级了！