OpenCLaw Web UI 访问失败排查与配置修复方案

OpenCLaw Web UI 访问异常排查

最近遇到 OpenCLaw 启动后 Web UI 无法访问，返回 404 或 not found 的情况。经过调试，定位到问题的根源在于 Gateway 服务的初始化逻辑。

问题根源

Gateway 在启动时会调用 resolveControlUiRootSync 函数来自动查找控制 UI 的目录。然而，该函数的默认逻辑并没有将 node_modules/openclaw/dist/control-ui 包含在候选路径列表中。这意味着如果依赖包没有正确链接，或者工作目录解析存在偏差，程序就无法找到 UI 资源。特别是在手动指定相对路径时，很容易因为当前运行环境的工作目录不同而导致解析失败。

解决方案

为了稳定起见，建议采用'本地部署 + 绝对路径'的方式。具体步骤如下：

首先，将控制 UI 的文件从 node_modules/openclaw/dist/control-ui 复制到你的项目根目录下。为了方便管理，建议新建一个英文目录，避免使用特殊符号（如 - 或 _），以免在某些旧版本的路径解析器中引起混淆。

接下来，修改配置文件 openclaw.json。你需要显式指定 controlUi.root 为绝对路径。注意在 JSON 字符串中，Windows 路径的反斜杠需要转义。

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

这里有个细节需要注意：虽然 Windows 原生支持反斜杠，但在 JSON 配置文件中必须写成双反斜杠 \\，否则会被解释为转义字符。如果你使用的是 Linux 或 macOS，则直接使用正斜杠 / 即可。

完成上述配置后，重启 Gateway 服务，Web UI 应该就能正常访问了。这种配置方式虽然牺牲了一点灵活性，但能最大程度避免因路径解析导致的运行时错误。