OpenClaw 企业微信插件避坑指南

🦞 OpenClaw 企业微信插件避坑指南

------ 一次完整的 OpenClaw + WeCom 插件排错实录

如果你正在使用 OpenClaw + 企业微信插件（@wecom/wecom-openclaw-plugin） ，

并且遇到各种 plugin not found / configured not enabled / gateway already running 等问题，这篇文章可以帮你一次性避坑。

本文记录了一次完整的排错过程，希望后来者不要再踩同样的坑。

一、环境

系统环境：

复制代码

macOS
OpenClaw-CN 0.1.7
Node runtime
插件：@wecom/wecom-openclaw-plugin

配置文件：

复制代码

~/.openclaw/openclaw.json

插件安装目录：

复制代码

~/.openclaw/extensions/wecom-openclaw-plugin

二、常见错误一览

在配置企业微信插件时，会遇到下面这些典型报错：

1️⃣ plugin not found

复制代码

Config validation failed:
plugins.entries.wecom: plugin not found: wecom

2️⃣ plugin id mismatch

复制代码

WARN wecom-openclaw-plugin: plugin id mismatch
(config uses "wecom-openclaw-plugin", export uses "wecom")

3️⃣ wecom configured, not enabled yet

复制代码

wecom configured, not enabled yet.
Run "openclaw-cn doctor --fix"

4️⃣ gateway already running

复制代码

Gateway failed to start: gateway already running
Port 18789 is already in use
pid xxxx clawdbot-gateway

三、核心问题：插件 ID 不一致

这是整个问题的根本原因。

企业微信插件内部存在两个不同的 ID。

插件清单文件

复制代码

~/.openclaw/extensions/wecom-openclaw-plugin/openclaw.plugin.json

内容：

复制代码

{
  "id": "wecom-openclaw-plugin",
  "channels": ["wecom"]
}

插件 ID：

复制代码

wecom-openclaw-plugin

运行时代码

文件：

dist/index.esm.js

末尾代码：

复制代码

const plugin = {
  id: "wecom"
}

插件 ID：

复制代码

wecom

结果

OpenClaw 产生冲突：

来源	ID
manifest	wecom-openclaw-plugin
runtime	wecom

因此 Doctor 无法判断到底该启用哪个插件。

四、正确的配置方式

openclaw.json

复制代码

"plugins": {
  "entries": {
    "feishu": {
      "enabled": true
    },
    "wecom-openclaw-plugin": {
      "enabled": true
    }
  }
}

注意：

复制代码

plugins.entries 使用插件 ID

而不是 channel 名。

channels 配置

复制代码

"channels": {
  "wecom": {
    "enabled": true,
    "botId": "xxxx",
    "secret": "xxxx"
  }
}

注意：

复制代码

channels 使用 channel 名

五、插件修复方法

建议统一 ID。

修改插件运行时代码：

文件：

复制代码

~/.openclaw/extensions/wecom-openclaw-plugin/dist/index.esm.js

将：

复制代码

id: "wecom"

改成：

复制代码

id: "wecom-openclaw-plugin"

这样就与 manifest 一致。

六、Doctor 自动修复陷阱

Doctor 会提示：

复制代码

Apply recommended config repairs now?

如果选择：

复制代码

Yes

Doctor 会自动把配置改成：

复制代码

plugins.entries.wecom

但插件实际 ID 是：

复制代码

wecom-openclaw-plugin

于是配置再次损坏。

正确操作

选择：

复制代码

No

七、Gateway 已运行问题

如果出现：

复制代码

gateway already running
Port 18789 is already in use

说明 gateway 已经在后台运行。

查看：

复制代码

launchctl list | grep claw

停止：

复制代码

openclaw-cn gateway stop

或：

复制代码

launchctl bootout gui/$UID/com.clawdbot.gateway

重新启动：

复制代码

openclaw-cn gateway

八、确认 OpenClaw 配置文件位置

默认路径：

复制代码

~/.openclaw/openclaw.json

检查：

复制代码

ls ~/.openclaw

有时会存在两个配置：

复制代码

config.json
openclaw.json

应只保留：

复制代码

openclaw.json

九、查看 gateway 日志

日志位置：

复制代码

~/.openclaw/logs/gateway.log

查看：

复制代码

tail -n 100 ~/.openclaw/logs/gateway.log

十、最终正确结构

复制代码

~/.openclaw
├── openclaw.json
├── logs
├── extensions
│   └── wecom-openclaw-plugin
│       └── dist
└── agents

十一、最终启动方式

复制代码

openclaw-cn gateway stop
openclaw-cn gateway

或者前台调试：

复制代码

openclaw gateway start

十二、总结

企业微信插件当前版本存在：

插件 ID 不一致问题

manifest：

复制代码

wecom-openclaw-plugin

runtime：

复制代码

wecom

导致：

plugin not found
doctor 自动修复错误
gateway 启动失败

解决方案

1️⃣ 修改插件 runtime id

2️⃣ plugins.entries 使用 wecom-openclaw-plugin

3️⃣ channels 使用 wecom

4️⃣ doctor 修复选择 No

最后的建议

如果你要在团队使用 OpenClaw + 企业微信：

建议 fork 插件仓库并修复：

复制代码

id mismatch

否则 Doctor 每次都会提示修复。

🦞 一句话总结

OpenClaw 企业微信插件当前版本存在 plugin id 不一致问题，
plugins.entries 必须使用 wecom-openclaw-plugin，否则 Doctor 会不断把配置修坏。