OpenCLaw Web UI 访问报错 Not Found 排查与修复

OpenCLaw Web UI 访问报错 Not Found 排查

最近遇到 OpenCLaw 的 Web UI 无法访问，直接报 Not Found 的情况。排查后发现，这通常不是服务挂了，而是 Gateway 层在解析控制 UI 资源时找不到对应目录。

根本原因

Gateway 内部的 resolveControlUiRootSync 函数在自动扫描路径时，默认并没有把 node_modules/openclaw/dist/control-ui 纳入候选列表。这意味着如果依赖包没有正确链接或者工作目录解析有偏差，程序就找不到前端资源。另外，手动指定相对路径时，也容易因为当前运行目录的变化而失效。

解决方案

最稳妥的办法是明确指定绝对路径，并确保目录结构干净。

首先，把控制 UI 的文件从 node_modules/openclaw/dist/control-ui 复制到项目根目录下。建议新建一个纯英文、无特殊符号的文件夹（比如 control-ui），避免连字符 - 或下划线 _ 在某些环境下引起解析混淆。

E:\\你的实际安装目录\\control-ui

接着，修改配置文件 openclaw.json。这里的关键是把 root 字段指向刚才那个绝对路径。注意 Windows 系统下路径分隔符的处理，JSON 里需要双反斜杠转义。

{
  "controlUi": {
    "enabled": true,
    "root": "E:\\你的实际安装目录\\control-ui",
    "allowInsecureAuth": true,
    "dangerouslyDisableDeviceAuth": true
  }
}

保存后重启服务，通常就能正常访问了。如果还有问题，检查一下路径是否真的存在，以及是否有权限读取。