站点图标 高效码农

OpenClaw企业微信接入生死局：我从6大报错中杀出血路的实战指南

高效码农

OpenClaw 接入企业微信完整教程：从报错到成功配对的真实排错记录

“

本文记录了在自托管服务器上将 OpenClaw AI 网关与企业微信智能机器人打通的完整过程，包括每一步踩过的坑和对应的解决方法。适合有基础 Linux 使用经验的技术人员参考。

这篇文章能解决什么问题？

如果你正在尝试用 OpenClaw 接入企业微信，大概率会遇到以下几类问题：

  • 启动时报 Invalid config，提示有未知字段
  • Gateway 进程在运行，但端口一直是 free 状态，健康检查超时
  • 插件加载失败，提示找不到 @wecom/aibot-node-sdk
  • 配置文件字段填错，把 Webhook 回调地址填进了 secret 字段
  • 不知道长连接模式和回调模式的区别，导致配置混乱

这些问题都有清晰的解决方法，本文逐一说明。

一、首先搞清楚两个概念：长连接 vs 回调模式

在配置之前，必须先弄清楚企业微信机器人的两种接入方式，否则配置字段会填错。

对比项 长连接（WebSocket） 回调模式（Webhook/HTTP）
连接方向 服务器主动连企业微信 企业微信主动请求你的服务器
需要公网 IP 不需要 需要
配置字段 botId + secret token + encodingAESKey + 公网回调地址
适合场景 内网服务器、云主机 有固定公网域名的生产环境
OpenClaw 推荐 ✅ 推荐 可选

结论：如果你是用普通云服务器或者内网机器，选长连接（WS）模式。 这也是本文的重点。

二、企业微信后台：创建智能机器人

这一步很多人会走错入口，需要特别注意。

第一步：进入正确的管理入口

  1. 浏览器打开 work.weixin.qq.com，用企业管理员账号登录
  2. 左侧菜单依次点击：安全与管理 → 管理工具 → 智能机器人
  3. 点击「创建机器人」→「手动创建」

第二步：选择 API 模式（关键步骤）

页面默认显示的是普通机器人，需要滑到页面底部，找到并点击**「API 模式创建」**。

“

⚠️ 注意：直接创建的普通机器人没有 API 能力，必须选 API 模式。

第三步：选择「长连接」模式

在 API 模式中，连接方式选择**「长连接」**，而不是「回调」。

第四步：获取 botId 和 Secret

机器人创建完成后，进入机器人的 API 配置页面，点击**「点击获取」**，会显示两个关键信息：

  • Bot ID：格式以 aib- 开头，例如 aib-xxxxxxxxxx
  • Secret：一串随机字符串，例如 aXk9Tz2mQpRv...

把这两个值复制保存，后面配置 OpenClaw 时会用到。

三、OpenClaw 配置文件详解

配置文件路径是 ~/.openclaw/openclaw.json。

正确的企业微信长连接配置

{
  "channels": {
    "wecom": {
      "enabled": true,
      "botId": "aib-你的BotID",
      "secret": "从企业微信后台复制的Secret字符串",
      "bot": {
        "streamPlaceholderContent": "正在思考...",
        "welcomeText": "你好！我是 AI 助手",
        "dm": {
          "policy": "open"
        }
      }
    }
  }
}

常见的配置错误

下面是实际踩过的几个典型错误，对照检查：

错误一：把回调地址填进了 secret 字段

// ❌ 错误
"secret": "http://159.75.78.224:18789/wecom"

// ✅ 正确：secret 是一串随机字符，不是 URL
"secret": "aXk9Tz2mQpRv..."

错误二：长连接模式里出现了回调模式的字段

// ❌ 错误：token 和 encodingAESKey 是回调模式专用
"bot": {
  "token": "jriCmneLxJKoKSs1dwIxzutLVMzL68",
  "encodingAESKey": "wBEdfD7GJkrbi3HgFcBH9XzGfKs5nDB1AaCXYAhX1kY"
}

长连接模式不需要这两个字段，保留了反而可能导致插件行为异常。

错误三：plugins.entries.wecom 里放了 path 字段

// ❌ 错误：path 不是 entries 下的合法字段
"plugins": {
  "entries": {
    "wecom": {
      "path": "/some/path",
      "enabled": true
    }
  }
}

本地插件路径应该放在 plugins.load.paths 下，而不是 entries 里。正确写法：

"plugins": {
  "load": {
    "paths": ["/some/path"]
  },
  "entries": {
    "wecom": {
      "enabled": true
    }
  }
}

用命令行修复非法字段

如果不想手动编辑 JSON，可以用这个脚本自动删除 path 字段：

python3 -c "
import json
with open('/root/.openclaw/openclaw.json') as f:
    cfg = json.load(f)

wecom = cfg.get('plugins', {}).get('entries', {}).get('wecom', {})
removed = wecom.pop('path', None)
print(f'Removed path: {removed}')

with open('/root/.openclaw/openclaw.json', 'w') as f:
    json.dump(cfg, f, indent=2, ensure_ascii=False)
print('Done.')
"

“

⚠️ 注意：openclaw doctor --fix 有一个已知问题——它会声称修复了无效字段，但实际上并不会真正从文件中删除，需要手动修改。

四、安装企业微信插件

方式一：使用官方插件命令

openclaw plugins install @wecom/wecom-openclaw-plugin

方式二：使用配置向导（推荐新手）

openclaw channels add
# 选择企业微信 → 输入 botId 和 secret → 选择 finish

方式三：用命令行直接写入配置

openclaw config set channels.wecom.enabled true
openclaw config set channels.wecom.botId "aib-你的BotID"
openclaw config set channels.wecom.secret "你的Secret"
openclaw config set gateway.bind lan

五、常见报错排查

报错一：Cannot find module ‘@wecom/aibot-node-sdk’

完整报错：

wecom failed to load from /root/.openclaw/extensions/wecom/index.ts: 
Error: Cannot find module '@wecom/aibot-node-sdk'

原因： 插件目录缺少 npm 依赖。

解决方法：

# 进入插件目录
cd /root/.openclaw/extensions/wecom

# 安装依赖（使用国内镜像加速）
npm install @wecom/aibot-node-sdk --registry=https://registry.npmmirror.com

# 验证安装结果
ls node_modules/@wecom/aibot-node-sdk/

如果 npm 一直卡住不动，大概率是在访问境外源超时，先设置镜像：

npm config set registry https://registry.npmmirror.com
npm install @wecom/aibot-node-sdk

装完后重启：

openclaw gateway restart

如果反复装不上，直接重新安装整个插件：

openclaw plugins uninstall wecom
openclaw plugins install @wecom/wecom-openclaw-plugin
openclaw gateway restart

报错二：Gateway 超时，端口 18789 始终是 free 状态

完整报错：

Timed out after 60s waiting for gateway port 18789 to become healthy.
Gateway process is running but port 18789 is still free (startup hang/crash loop).

排查步骤：

# 第一步：查看 gateway 日志
journalctl -u openclaw -n 100 --no-pager

# 或者查看 openclaw 自己的日志文件
tail -100 ~/.openclaw/logs/gateway.log 2>/dev/null || \
tail -100 ~/.openclaw/gateway.log 2>/dev/null

# 第二步：确认端口状态
ss -tlnp | grep 18789

# 第三步：Kill 掉挂起的进程，用前台模式重启，直接看报错
kill -9 <pid>
openclaw gateway

大多数情况下，Gateway 启动挂起的根本原因是配置文件有错误——修好配置文件（参考第三节），Gateway 就能正常启动。

报错三：Config invalid，提示有未知字段

完整报错：

Invalid config at /root/.openclaw/openclaw.json:
- plugins.entries.wecom: Unrecognized key: "path"

参考第三节中「错误三」的解决方法，删除 plugins.entries.wecom 下的 path 字段即可。

报错四：skillhub 插件警告

plugins.entries.skillhub: plugin disabled (not in allowlist) but config is present

这是一个警告，不是错误，不影响企业微信插件运行。如果想消除提示，从配置文件中删除 plugins.entries.skillhub 这一节，或者将其 enabled 设为 false。

六、完成配对

插件配置完成后，还需要和企业微信机器人完成配对，才能正常收发消息。

配对步骤

第一步： 在企业微信中找到你创建的智能机器人（从通讯录或搜索）

第二步： 给机器人发送任意一条消息，例如「你好」

第三步： 机器人会自动回复一个配对码（Pairing Code）

第四步： 复制消息中最后一行的密钥，粘贴到终端中按回车，配对完成

配对码过期怎么办？

如果配对码超时没有及时填写，重新在企业微信给机器人发一条消息，获取新的配对码，然后执行：

openclaw pairing approve

再输入新的配对码即可。

七、卸载企业微信插件

如果需要重新安装或更换插件方案，先干净地卸载：

# 方式一：使用插件命令卸载
openclaw plugins uninstall wecom
openclaw gateway restart

如果命令卸载不彻底，手动清理：

# 删除插件目录
rm -rf /root/.openclaw/extensions/wecom

# 删除配置文件中的 wecom 条目
python3 -c "
import json
with open('/root/.openclaw/openclaw.json') as f:
    cfg = json.load(f)
cfg.get('plugins', {}).get('entries', {}).pop('wecom', None)
with open('/root/.openclaw/openclaw.json', 'w') as f:
    json.dump(cfg, f, indent=2, ensure_ascii=False)
print('Done.')
"

openclaw gateway restart

八、完整配置流程总结

按照这个顺序操作，可以避免大多数踩坑：

1. 企业微信后台 → 管理工具 → 智能机器人 → API 模式 → 长连接 → 获取 botId 和 Secret

2. 编辑 ~/.openclaw/openclaw.json，填入正确的 botId 和 Secret（Secret 是字符串，不是 URL）

3. 安装依赖：
   cd /root/.openclaw/extensions/wecom
   npm install @wecom/aibot-node-sdk --registry=https://registry.npmmirror.com

4. 启动 Gateway：
   openclaw gateway

5. 企业微信给机器人发消息 → 复制配对码 → 粘贴到终端

6. 验证：再发一条消息，看是否有 AI 回复

FAQ

Q：长连接模式需要开放服务器端口给企业微信吗？

不需要。长连接是服务器主动连企业微信的 WebSocket，不需要公网可达的 HTTP 回调地址，也不需要在防火墙开放任何入站端口。

Q：botId 的格式是什么？

Bot ID 以 aib- 开头，后面跟一串字母数字，例如 aib-vdou5SX2cSLvDZxBwy7DViJ29iXYjIQF。

Q：Secret 填错了会有什么后果？

插件加载时会连接失败，Gateway 日志里会出现鉴权错误。回企业微信后台重新复制 Secret，更新配置文件后重启 Gateway 即可。

Q：npm install 一直卡住怎么办？

换国内镜像：npm install @wecom/aibot-node-sdk --registry=https://registry.npmmirror.com。如果还是慢，先把镜像永久设置好：npm config set registry https://registry.npmmirror.com，再重新安装。

Q：配置文件改完后要重启吗？

需要。每次修改 openclaw.json 后，都需要执行 openclaw gateway restart 让新配置生效。

Q：Gateway 启动后企业微信没有反应，怎么排查？

先看 Gateway 日志是否有 wecom 相关报错：

openclaw logs --follow

重点检查：插件是否加载成功、botId 和 Secret 是否正确、是否已完成配对。

结语

接入企业微信看起来步骤不少，但主要的坑就集中在三个地方：配置字段填错、npm 依赖没装到正确目录、长连接和回调模式混淆。把这三个问题解决，整个流程其实很顺畅。

如果按照本文步骤操作后仍有问题，可以将 Gateway 的完整日志贴出来进一步排查——大多数问题在日志里都有明确的错误提示。

退出移动版