手打不易，如果转摘，请注明出处！
本文链接：

https://zhangxiaofan.blog.csdn.net/article/details/159408497

---

目录

问题背景

错误现象

原因分析

解决方案

1. 克隆 OpenClaw 完整源码

2. 进入 UI 子项目并构建

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

4. 重启 OpenClaw 服务

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

验证结果

常见问题与注意事项

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

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

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

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

---

问题背景

系统：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 build

node: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 build

sh: vite: command not found
 ELIFECYCLE  Command failed.

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

原因分析

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

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

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

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

解决方案

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

1. 克隆 OpenClaw 完整源码

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

2. 进入 UI 子项目并构建

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

构建成功后，ui/dist/control-ui 目录会包含 index.html 等静态文件。

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

验证结果

访问 Web 控制面板

http://127.0.0.1:18789/chat?session=main

应能正常显示 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 调整）。