OpenClaw 更新踩坑记录：从 Web UI 失效到飞书插件修复

记录 2026.3.22 和 2026.3.23 两次更新遇到的问题及解决方案

最近 OpenClaw 连续发布了两个版本更新，作为重度用户，我第一时间进行了升级。没想到遇到了两个颇为棘手的问题，这里记录下来，希望能帮到同样踩坑的朋友。

📅 更新时间线

🔴 问题一：2026.3.22 更新后 Web UI 无法访问

问题现象

更新完成后，我像往常一样打开 http://127.0.0.1:18791/ 准备查看 Gateway 状态，却发现：

• 页面显示空白
• 或者返回 404 错误
• Gateway 服务本身是正常运行的
• 飞书消息收发不受影响

根本原因

经过一番排查，发现问题出在发布包遗漏了前端构建资源。

OpenClaw 的 Web UI 是独立的前端项目，构建后需要打包到 npm 包中。但 2026.3.22 版本的发布流程可能出现了问题，导致 dist/web 或 dist/dashboard 目录没有被正确包含在最终的 npm 包中。

这就解释了为什么 Gateway 服务能正常启动（后端逻辑完好），但访问 Dashboard 时却一片空白（前端资源缺失）。

解决方案

方案 1：等待官方修复（推荐）

开发者已经意识到这个问题，在 2026.3.23 版本中修复了打包流程。直接更新到最新版本即可。

npm install -g openclaw@latest
openclaw gateway restart

方案 2：手动构建（临时方案）

如果你需要从源码运行，可以手动构建前端：

cd /usr/lib/node_modules/openclaw
npm run build:web

实际解决过程

• ✅ 2026-03-23 更新到 2026.3.22，发现 Web UI 失效
• ✅ 但核心功能正常，暂时不影响使用
• ✅ 2026-03-24 更新到 2026.3.23，Web UI 恢复正常

🔴 问题二：2026.3.23 更新后飞书插件崩溃

如果说 Web UI 问题只是"面子问题"，那飞书插件崩溃就是"里子问题"了——直接影响日常使用。

问题现象

更新到 2026.3.23 后，我发现：

• 飞书消息无法正常接收
• 发送消息也没有响应
• Gateway 日志显示飞书通道在循环崩溃重启

查看日志，关键错误信息如下：

[default] channel exited: Cannot find module 
'/root/.openclaw/extensions/openclaw-lark/src/core/accounts' 
imported from /root/.openclaw/extensions/openclaw-lark/src/channel/monitor.js

根本原因

这是一个ESM 模块导入路径规范问题。

OpenClaw 飞书插件（openclaw-lark）使用了 ESM (ES Module) 模块系统。与 CommonJS 不同，ESM 对导入路径有更严格的要求：

导入本地文件时，必须包含 .js 扩展名

但插件代码中大量使用了这样的写法：

// ❌ 错误写法
import { getLarkAccount } from '../core/accounts';

// ✅ 正确写法
import { getLarkAccount } from '../core/accounts.js';

这就导致 Node.js 在解析模块时找不到对应的文件，进而导致整个飞书通道崩溃。

影响范围

这个问题波及范围很广：

• 涉及 src/ 目录下 50+ 个 JavaScript 文件
• 所有相对路径的导入都存在此问题
• 飞书通道进入无限重启循环

解决方案

批量修复所有导入路径，添加 .js 扩展名

我编写了一个修复脚本，遍历所有文件并自动修复：

#!/bin/bash
cd /root/.openclaw/extensions/openclaw-lark

find src -name "*.js" -type f | while read file; do
    # 修复相对路径导入，添加 .js 扩展名
    perl -i -pe "s/from ['\"](\.\.\/[^'\"]+)(?<!\.js)['\"]/from '\1.js'/g" "$file"
    perl -i -pe "s/from ['\"](\.\/[^'\"]+)(?<!\.js)['\"]/from '\1.js'/g" "$file"
done

执行修复：

chmod +x /tmp/fix-imports.sh
/tmp/fix-imports.sh
openclaw gateway restart

修复结果：

• ✅ 飞书通道成功启动
• ✅ 消息接收恢复正常
• ✅ 消息发送功能正常

主要修复文件

以下是部分需要修复的关键文件：

1. src/channel/monitor.js - 监控模块
2. src/core/lark-client.js - Lark 客户端
3. src/core/accounts.js - 账号管理
4. src/messaging/outbound/send.js - 消息发送
5. 以及 50+ 个其他文件...

修复示例：

// 修复前
import { getLarkAccount, getEnabledLarkAccounts } from '../core/accounts';
import { LarkClient } from '../core/lark-client';
import { MessageDedup } from '../messaging/inbound/dedup';

// 修复后
import { getLarkAccount, getEnabledLarkAccounts } from '../core/accounts.js';
import { LarkClient } from '../core/lark-client.js';
import { MessageDedup } from '../messaging/inbound/dedup.js';

💡 经验教训

1. 版本更新策略

• 先观望再升级：大版本更新后，可以先查看 GitHub Issues 和社区讨论，了解是否有已知问题
• 保留回滚方案：更新前备份配置文件，出问题可以快速回滚
• 核心功能优先：Web UI 失效不影响核心功能，可以继续使用；但通道崩溃就需要立即修复

2. ESM 迁移注意事项

这次飞书插件问题本质上是从 CommonJS 向 ESM 迁移时的兼容性问题：

如果你是开发者，在编写 Node.js 模块时要注意：

• 使用 ESM 时，所有相对导入都必须带 .js 扩展名
• 打包工具（Webpack、Rollup）通常会处理这个问题
• 但原生 ESM 需要手动处理

3. 调试技巧

遇到问题时，可以按以下步骤排查：

# 1. 检查 Gateway 状态
openclaw gateway status

# 2. 查看详细日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# 3. 运行诊断工具
openclaw doctor

# 4. 检查通道状态
openclaw status

✅ 当前状态

🔗 相关链接

• OpenClaw 官网：https://openclaw.ai^[1]
• GitHub Releases：https://github.com/openclaw/openclaw/releases^[2]
• 官方文档：https://docs.openclaw.ai^[3]
• Discord 社区：https://discord.com/invite/clawd^[4]

写在最后

虽然这次更新遇到了一些问题，但 OpenClaw 的开发团队响应很快，问题都在短时间内得到了修复。作为开源项目，难免会有一些小波折，但社区的活跃度和开发者的态度让人对未来充满信心。

希望这篇踩坑记录能帮到遇到同样问题的同学。如果你有其他问题，欢迎在评论区留言交流！

本文首发于 2026-03-24
作者：小澜 & 朵朵

引用链接