龙虾 OpenClaw 升级后 Web 控制台白屏怎么办：3.22 缺 UI 资源的排查

升级 OpenClaw 到 3.22 版本后，发现 Web 控制台页面白屏，无法正常访问。这种情况通常是因为升级过程中某些 UI 资源文件未正确部署或路径配置错误导致的。以下是详细的排查与修复步骤，帮助你快速恢复 Web 控制台的正常访问。

一、确认问题现象

• 浏览器访问 OpenClaw 的 Web 控制台（如 http://<your-ip>:<port>/openclaw）时，页面显示空白。
• 页面加载时无任何报错信息（如 404、500 等），但无任何内容渲染。
• 通过浏览器开发者工具（F12）查看网络请求，发现部分 UI 资源（如 CSS、JS、图片）请求失败，返回 404 或 500 状态码。

二、检查 OpenClaw 配置文件

OpenClaw 的 Web 控制台依赖于前端资源，这些资源通常位于 web 或 ui 目录下。升级后，这些资源可能未被正确复制或路径配置错误。

1. 检查 openclaw.conf 配置文件

路径通常为：/etc/openclaw/openclaw.conf 或 /opt/openclaw/etc/openclaw.conf

查找以下配置项：

[web]
root = /usr/share/openclaw/web

确保 root 路径指向正确的前端资源目录。如果路径错误，会导致 Web 控制台无法加载资源。

2. 检查 web 目录是否存在

进入 OpenClaw 安装目录，检查 web 目录是否存在：

ls /usr/share/openclaw/web

如果目录不存在，说明升级过程中前端资源未正确部署。需要手动恢复或重新部署。

三、恢复缺失的 UI 资源

如果 web 目录缺失或资源不完整，需要从源码或备份中恢复。

1. 从源码恢复

如果你有 OpenClaw 的源码，可以手动复制前端资源：

cd /opt/openclaw
git checkout 3.22
cp -r web /usr/share/openclaw/

2. 从备份恢复

如果你有 OpenClaw 的备份目录（如 /backup/openclaw/web），可以恢复：

cp -r /backup/openclaw/web /usr/share/openclaw/

3. 从官方下载恢复

访问 OpenClaw 官方 GitHub 或下载页面，下载 3.22 版本的前端资源包，并解压到 /usr/share/openclaw/web：

wget https://github.com/OpenClaw/OpenClaw/archive/refs/tags/3.22.tar.gz
tar -xzvf 3.22.tar.gz
cp -r OpenClaw-3.22/web /usr/share/openclaw/

四、检查 Web 服务配置

OpenClaw 的 Web 控制台通常由 Nginx 或 Apache 提供服务。需要确保 Web 服务配置正确，并指向正确的资源目录。

1. 检查 Nginx 配置

路径通常为：/etc/nginx/sites-available/openclaw

检查以下配置项：

location /openclaw {
    root /usr/share/openclaw/web;
    index index.html index.htm;
}

确保 root 路径与 openclaw.conf 中的路径一致。

2. 检查 Apache 配置

路径通常为：/etc/apache2/sites-available/openclaw

检查以下配置项：

<VirtualHost *:80>
    DocumentRoot /usr/share/openclaw/web
    <Directory /usr/share/openclaw/web>
        Options Indexes FollowSymLinks
        AllowOverride None
        Require all granted
    </Directory>
</VirtualHost>

确保 DocumentRoot 路径正确，并且目录权限允许访问。

五、重启 Web 服务

在修改配置文件后，需要重启 Web 服务以使配置生效。

1. 重启 Nginx

systemctl restart nginx

2. 重启 Apache

systemctl restart apache2

六、验证 Web 控制台是否正常

访问 OpenClaw 的 Web 控制台，检查页面是否正常加载。如果仍然白屏，可以使用浏览器开发者工具（F12）查看网络请求，确认是否有资源加载失败。

七、常见问题排查

1. 权限问题

如果 Web 服务无法访问 /usr/share/openclaw/web 目录，会导致资源加载失败。

chown -R www-data:www-data /usr/share/openclaw/web
chmod -R 755 /usr/share/openclaw/web

2. 路径拼接错误

如果 openclaw.conf 中的 root 路径拼写错误，会导致资源无法加载。

[web]
root = /usr/share/openclaw/web

确保路径拼写正确，且目录存在。

3. 资源文件损坏

如果前端资源文件损坏，会导致页面无法正常加载。可以尝试重新部署或从源码中复制资源文件。

八、总结

OpenClaw 3.22 升级后 Web 控制台白屏，通常是由于 UI 资源缺失或路径配置错误导致的。通过检查配置文件、恢复缺失资源、验证 Web 服务配置，可以快速解决该问题。建议在升级前备份配置文件和资源目录，以避免类似问题。

如仍有问题，建议查看 OpenClaw 的官方文档或社区论坛，获取更多支持。