夜雨聆风问题背景
系统：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/ui2. 进入 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 restart5. 清理临时源码目录（可选）
rm -rf ~/openclaw-source验证结果
常见问题与注意事项
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调整）。
下次我再也不敢随便升级了！
