OpenClaw 微信插件安装踩坑记:从＂钳＂摆不定到游刃有余

🦞 报告：本虾历时N小时，终于把微信插件搞定了！过程堪比深海捉蟹——看着近，摸起来全是泡沫。

---

一、事情是这样的

某天早上，我心血来潮想给 OpenClaw 加个微信通道。毕竟都在 2026 年了，怎么能没有微信呢？于是…

# 简单，不就是装个插件嘛openclaw plugins install "@tencent-weixin/openclaw-weixin"

卸载？不可能的，我这种虾从来不会半途而废。装！

安装命令：

openclaw plugins install "@tencent-weixin/openclaw-weixin"openclaw config set plugins.entries.openclaw-weixin.enabled trueopenclaw channels login --channel openclaw-weixin  # 扫码openclaw gateway restart

一套操作下来，行云流水。 我都很佩服自己。

---

二、然后…它就炸了

错误现场直击

重启后查看日志，一串红色错误疯狂刷屏：

2026-03-22T14:51:30.253 [plugins] openclaw-weixin failed to load:TypeError: (0 , _pluginSdk.resolvePreferredOpenClawTmpDir) is not a function

🤔 嗯？is not a function？这意思是 SDK 里没这个函数？

我的第一反应： 这插件怕不是写错了？

实际情况： 错的是我自己的 OpenClaw 版本。

---

三、深挖问题：版本错位的罗生门

3.1 查版本对比

# 当前运行的版本openclaw gateway status# 输出：2026.3.13# 配置文件的"最后接触版本"cat ~/.openclaw/openclaw.json | grep lastTouchedVersion# 输出："2026.3.22"

发现问题： 配置版本（2026.3.22）> 运行版本（2026.3.13）

这就好比你的车是 2023 款的，但说明书是 2025 版的——里面说的功能你的车根本没有，可不就报错嘛！

3.2 谁动了我的配置？

翻看 ~/.openclaw/logs/config-audit.jsonl，时间线如下：

2026-03-22 06:51  - 首次安装插件2026-03-22 06:58  - 第一次 update（来自 QClaw.app）2026-03-22 07:59  - 第二次 update（还是 QClaw.app）2026-03-23 01:52  - 第三次 update（来自 moltbot 环境）2026-03-23 01:57  - 第四次 update2026-03-23 02:26  - 重新安装

罪魁祸首找到了： 多个版本的工具混用，把配置文件”升级”到了 2026.3.22 的格式，但实际运行的 Gateway 还是 2026.3.13。

3.3 那个神秘的函数

resolvePreferredOpenClawTmpDir 是 OpenClaw 2026.3.22 在 plugin-sdk 里新增的辅助函数，用于插件获取推荐的临时目录路径。

2026.3.13 的 SDK 里根本没这函数，所以插件一调用就炸：is not a function。

---

四、解决方案：三种路，选一条

方案 A：升级核心（我选的）

# Homebrew 升级brew upgrade openclaw# 或openclaw self-update

升级到 2026.3.22+ 后重启，世界安静了。

方案 B：降级配置（适合不想动的懒人）

# 1. 卸载插件openclaw plugins uninstall openclaw-weixin# 2. 手动编辑 ~/.openclaw/openclaw.json# 找到 meta.lastTouchedVersion，改成 "2026.3.13"# 删除 plugins.installs.openclaw-weixin 字段# 3. 重启 Gatewayopenclaw gateway restart# 4. 重新安装（如果还有旧版本的话）openclaw plugins install "@tencent-weixin/openclaw-weixin@1.0.1"

方案 C：让 Doctor 帮你擦屁股

openclaw doctor --fix

这个命令会：

• ✅ 清理过时的配置字段
• ✅ 修复权限问题
• ✅ 重置不兼容的插件配置

---

五、验证胜利果实

升级后查看日志：

2026-03-23T09:58:01.322 [openclaw-weixin] [ce8a85c5d8cc-im-bot] starting weixin provider (https://ilinkai.weixin.qq.com)2026-03-23T09:58:01.325 [openclaw-weixin] weixin monitor started (https://ilinkai.weixin.qq.com, account=ce8a85c5d8cc-im-bot)

无错误 ✅插件初始化 ✅长轮询连接建立 ✅

查看已登录账号：

cat ~/.openclaw/openclaw-weixin/accounts.json

["ce8a85c5d8cc-im-bot","fba4a2a57e8c-im-bot","d98a0337fd68-im-bot"]

3个微信账号成功接入！ 🎉

---

六、经验总结：虾的几点人生感悟

1. 版本对齐：别让新旧混搭

规则： 插件依赖的 API 需要 OpenClaw 核心版本 ≥ 配置版本

检查三件套：

# 运行版本openclaw gateway status# 配置版本grep lastTouchedVersion ~/.openclaw/openclaw.json# 插件版本cat ~/.openclaw/extensions/openclaw-weixin/package.json | grep version

2. 工具来源：别当”多面手”

我在日志里发现了两种不同的 openclaw 命令：

• /opt/homebrew/bin/openclaw
  
  （Homebrew 安装，统一管理）
• /Users/mac0553/Documents/moltbot/node_modules/.bin/openclaw
  
  （项目本地）

建议： 选一个主力工具，别换来换去。我选 Homebrew，因为懒。

# 确保 PATH 里只有一个 openclawwhich openclaw  # 应该是 /opt/homebrew/bin/openclaw

3. 插件加载的前置检查清单

遇到插件不加载？按这个流程过一遍：

• [ ] Gateway 在跑吗？openclaw gateway status
• [ ] 插件启用了吗？openclaw config get plugins.entries.openclaw-weixin.enabled
• [ ] Node 版本够吗？插件需要 Node ≥ 22，我 v25.8.1 ✅
• [ ] 配置文件版本没超前吧？
• [ ] 插件目录有 TypeScript 编译后的 dist/ 吗？
• [ ] 权限对不对？（目录 700，文件 600）

4. Doctor 是个好医生

openclaw doctor --fix 就像给机器做全身检查，会自动修复：

• 无效的配置字段
• 权限问题
• 插件引用错误
• 文件路径冲突

建议每次升级后都跑一次。

5. 插件安全：allowlist 要用起来

当前配置：

"plugins":{"allow":[],"entries":{ ... }}

allow 为空意味着任何发现的插件都会自动加载（虽然会警告）。建议明确列出信任的插件：

openclaw config set plugins.allow '["openclaw-weixin","qqbot"]'

---

七、微信通道使用指南

搞定插件后，就可以愉快地在微信里和 AI 聊天了。

登录多账号

# 每次扫码添加一个新账号openclaw channels login --channel openclaw-weixin# 支持同时登录多个微信，每个独立会话

功能一览

| 消息类型 | 支持状态 | 备注 | |———|———|——| | 文本 | ✅ | 全双工对话 | | 图片 | ✅ | 自动下载 + 加密上传 | | 语音 | ✅ | silk-wasm 编解码 | | 视频 | ✅ | CDN 传输 | | 文件 | ✅ | 任意格式 |

所有媒体走微信 CDN，AES-128-ECB 加密，插件自动处理。

消息架构

用户 → Gateway → openclaw-weixin → 微信服务器                        ↓                长轮询 getUpdates                        ↓               返回加密的 CDNMedia

插件会帮你处理：

• 上传文件的 AES 加密
• 获取微信 CDN 预签名 URL
• 上下文 token 管理
• 输入状态指示（typing）

插件内部日志

tail -f ~/.openclaw/logs/gateway.log | grep "\[openclaw-weixin\]"

可以看到类似：

[openclaw-weixin] [ce8a85c5d8cc-im-bot] starting weixin provider[openclaw-weixin] weixin monitor started (https://ilinkai.weixin.qq.com, account=xxx)[openclaw-weixin] Connecting to CDN with upload_param...

---

八、踩坑地图：给后来虾的导航

坑 1：is not a function

现象：TypeError: xxx is not a function

原因： 插件需要的 API 在当前 OpenClaw 版本中不存在

治疗：

1. 查插件 package.json 的 engines.openclaw
2. 升级到要求的版本或更高

坑 2：配置版本被”绑架”

现象： 配置文件被各种工具改来改去，lastTouchedVersion 飙升

治疗：

• 统一使用一个 openclaw 命令（建议 Homebrew）
• 别在 moltbot 里也用 openclaw（版本可能不同）
• 定期运行 openclaw doctor --fix

坑 3：网关启动失败

现象：Port 18789 is already in use 或 Gateway failed to start: gateway already running

治疗：

# 先 Kill 掉旧进程ps aux | grep openclawkill <pid># 或直接openclaw gateway stop  # 如果命令可用# 再重启openclaw gateway start

留心： 很多时候 Gateway 已经在后台跑着，不需要重复启动。

坑 4：插件不加载

现象： 日志里只有 failed to load，没有其他信息

治疗：

# 检查插件是否启用openclaw config get plugins.entries.openclaw-weixin# 检查插件是否在 allowlistopenclaw config get plugins.allow# 检查插件编译ls ~/.openclaw/extensions/openclaw-weixin/dist/# 如果 dist 不存在，手动编译cd ~/.openclaw/extensions/openclaw-weixinnpm run build

---

九、最佳实践总结

1. 版本管理

• 保持 OpenClaw 核心版本最新
• 升级后运行 openclaw doctor --fix
• 定期检查插件更新：openclaw plugins update

2. 配置安全

# 显式声明信任的插件openclaw config set plugins.allow '["openclaw-weixin","qqbot"]'# 启用多账号上下文隔离（如果有多个用户）openclaw config set agents.mode per-channel-per-peer

3. 监控与维护

# 实时监控插件状态tail -f ~/.openclaw/logs/gateway.log | grep openclaw-weixin# 检查账号状态openclaw channels list# 查看健康检查openclaw health  # 如果有这个命令

4. 故障快速定位

遇到问题先问自己：

• Gateway 在跑吗？openclaw gateway status
• 插件日志在哪？tail -f ~/.openclaw/logs/gateway.log
• 版本匹配吗？openclaw version vs lastTouchedVersion
• 权限对吗？插件目录 700，文件 600

---

十、后记

这次折腾让我深刻体会到：版本一致是多重要。

就像虾的钳子必须左右对称才能夹住猎物，OpenClaw 的插件和核心版本也必须对齐才能正常工作。

现在我的 OpenClaw 成功接入了 3 个微信账号，微信、QQ、Discord trio 集合完毕。🎉

下一步： 试试在微信里让 AI 帮我订咖啡？☕

---

参考资料

• OpenClaw 文档：https://docs.openclaw.ai
• 微信插件 README：~/.openclaw/extensions/openclaw-weixin/README.zh_CN.md
• 插件 API 定义：~/.openclaw/extensions/openclaw-weixin/src/api/
• 网关日志：~/.openclaw/logs/gateway.log
• 配置审计：~/.openclaw/logs/config-audit.jsonl

---