OpenClaw Matrix 插件升级踩坑记录

最近在升级 OpenClaw 的 Matrix 插件时，遇到了一个让人抓狂的问题

❌ openclaw doctor 命令直接卡死

❌ Gateway 启动后端口死活不监听

❌ 日志里没有任何错误信息

折腾了大半天，终于找到了原因：二进制文件损坏！

把解决过程记录下来，希望能帮到遇到同样问题的朋友。

01

问题背景

OpenClaw 从 2026.3.x 版本开始，Matrix 频道换了全新的插件架构：

📌 旧版：内置实现，使用 @vector-im/matrix-bot-sdk

📌 新版：独立插件 @openclaw/matrix，使用官方 matrix-js-sdk

新插件支持私信、群组、线程、媒体、反应、投票、位置分享，以及 E2EE 端到端加密，功能丰富多了。

02

事情的起点：一个 GitHub Issue

之前我在 OpenClaw 的 GitHub 上提了一个 Issue，反馈 Matrix 扩展在升级后依赖解析失败：

[plugins] matrix failed to load: Error: Cannot find module '@vector-im/matrix-bot-sdk'

每次升级都要手动安装依赖才能解决，很烦。

没想到官方最近回复了：

OpenClaw now uses a new Matrix plugin built on the official matrix-js-sdk. The older Matrix implementation is no longer supported.

原来官方已经发布了全新的 Matrix 插件，基于官方 SDK 重写，旧的实现不再维护了。

Issue 被关闭后，我兴冲冲地去升级，以为问题就此解决。

结果… 新的坑出现了 😅

03

诡异的问题现象

升级新版插件后，出现了一堆诡异现象：

🔍 openclaw doctor 命令直接卡住，没有任何输出

🔍 Gateway 进程在运行，但端口 18789 就是不监听

🔍 日志里看不到任何错误信息

🔍 CPU 占用异常，进程像是陷入了死循环

04

诊断过程

在 Matrix 插件目录下尝试手动加载加密模块：

cd /你的node路径/lib/node_modules/openclaw/extensions/matrix/node_modules/@matrix-org/matrix-sdk-crypto-nodejsnode -e "require('./index.js'); console.log('OK')"

结果直接报错：

Bus error (core dumped)

这就是传说中的「总线错误」！

继续检查文件完整性：

file matrix-sdk-crypto.linux-x64-gnu.node

损坏的文件显示：

ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked, missing section headers at 22026872

注意看 missing section headers，文件明显损坏或不完整了。

05

解决方案

第一步：停止所有进程

pkill -9 -f openclaw

第二步：进入插件目录

cd /你的node路径/lib/node_modules/openclaw/extensions/matrix/node_modules/@matrix-org/matrix-sdk-crypto-nodejs

（根据你的 Node.js 安装路径调整）

第三步：删除损坏的文件

rm -f matrix-sdk-crypto.linux-x64-gnu.node

第四步：下载正确的二进制文件

这是最关键的一步，文件约 21MB：

wget -O matrix-sdk-crypto.linux-x64-gnu.node \  https://github.com/matrix-org/matrix-rust-sdk-crypto-nodejs/releases/download/v0.4.0/matrix-sdk-crypto.linux-x64-gnu.node

⚠️ GitHub 在国内访问可能较慢，建议使用代理或手动下载后上传

第五步：验证文件完整性

file matrix-sdk-crypto.linux-x64-gnu.node

✅ 正确的输出应该包含 BuildID[sha1]= 和 not stripped

第六步：测试模块加载

node -e "require('./index.js'); console.log('OK')"

如果输出 OK，恭喜你，问题解决了！

第七步：启动 Gateway

openclaw gateway

如果遇到「gateway already running」错误：

openclaw gateway stopsleep 3openclaw gateway

06

验证成功

启动成功后，你应该看到类似输出：

🦞 OpenClaw 2026.3.13 (61d171a)13:28:06 [gateway] listening on ws://127.0.0.1:1878913:28:08 [matrix] [default] starting provider

然后就可以在 Matrix 客户端（如 Element）给机器人发消息测试了！

07

为什么会出现这个问题？

可能的原因：

🌐 网络中断：npm 安装时下载二进制文件不完整

⏱️ 超时截断：下载超时，文件被截断但没有报错

💾 磁盘问题：虽然不太可能，但也不能排除

新版插件把加密模块独立出来，需要从 GitHub 下载约 21MB 的原生二进制文件，这个过程比较脆弱。

08

一些实用建议

📌 查看日志

# 前台运行openclaw gateway# 或查看日志文件tail -f /tmp/openclaw/openclaw-*.log

📌 禁用加密（临时方案）

如果暂时不需要 E2EE，可以在配置中禁用：

{  "channels": {    "matrix": {      "encryption": false    }  }}

📌 支持的平台

• Linux x64 (gnu/musl)• Linux ARM64• macOS x64/ARM64• Windows x64

09

总结

这次踩坑让我意识到两件事：

1️⃣ 开源项目的响应速度可以很快——我提的 Issue 很快就得到了官方回复，问题在新版本中确实得到了解决

2️⃣ 遇到「卡死」问题，不要只盯着配置看——要检查依赖的二进制文件是否完整，用 file 命令检查一下往往能发现问题

新的 Matrix 插件架构更加现代化，使用官方 SDK 意味着更好的兼容性和维护性。虽然升级过程有点曲折，但解决后一切运行得很顺畅。

感谢 OpenClaw 团队的快速响应！🦞

如果这篇文章帮到了你，欢迎点赞、在看、转发！

有问题欢迎在评论区交流~

相关链接

• OpenClaw 官方文档：https://docs.openclaw.ai

• Matrix 插件迁移指南：https://docs.openclaw.ai/install/migrating-matrix

•GitHub Issue：https://github.com/openclaw/openclaw/issues/31169