企业微信通道配置诊断与修复技能
当用户遇到企业微信通道无法连接、消息无回复、配置错误等问题时，使用此技能进行诊断和修复。
触发场景
- "企微没反应"
- "企业微信通道配置错误"
- "wecom 连不上"
- "插件 ID 不匹配"
- "多账号模式不支持"
- "企微消息无回复"
诊断流程
步骤 1：检查通道状态
openclaw channels status 2>&1
判断标准：
enabled, configured, running✅ 正常enabled, not configured, stopped❌ 配置缺失error:*❌ 错误状态
步骤 2：检查配置文件
openclaw config get channels.wecom 2>&1
检查项：
botId是否存在secret是否存在- 是否使用了不支持的
accounts.*多账号结构
步骤 3：检查插件配置
grep -A 10 '"plugins"' ~/.openclaw/openclaw.json
常见问题：
- 插件 ID 不匹配（配置用
wecom-openclaw-plugin，实际导出wecom） - 插件未启用
步骤 4：查看日志
cat /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep -i wecom | tail -20
关键错误：
plugin id mismatchInvalid WebSocket frameAuthentication failednot configured
修复方案
问题 A：插件 ID 不匹配
症状：
[plugins] plugin id mismatch (config uses "wecom-openclaw-plugin", export uses "wecom")
plugins.entries.wecom: plugin not found: wecom
修复：
将 openclaw.json 中的插件配置从：
{
"plugins": {
"allow": ["wecom-openclaw-plugin"],
"entries": {
"wecom-openclaw-plugin": {"enabled": true}
}
}
}
改为：
{
"plugins": {
"allow": ["wecom"],
"entries": {
"wecom": {"enabled": true}
}
}
}
原因： 企微插件的 openclaw.plugin.json 中定义 id: "wecom"，但安装包名为 @wecom/wecom-openclaw-plugin，配置时应使用导出 ID 而非包名。
问题 B：多账号模式不支持
症状：
wecom default: 企业微信机器人 ID 或 Secret 未配置
config reload skipped (invalid config)
当前配置（错误）：
{
"channels": {
"wecom": {
"enabled": true,
"defaultAccount": "main",
"accounts": {
"main": {"botId": "...", "secret": "..."},
"ai-engineer": {"botId": "...", "secret": "..."}
}
}
}
}
修复（回退单账号模式）：
{
"channels": {
"wecom": {
"enabled": true,
"botId": "你的 botId",
"secret": "你的 secret",
"dmPolicy": "pairing"
}
},
"bindings": [
{
"agentId": "main",
"match": {"channel": "wecom", "accountId": "*"}
}
]
}
原因： 企微插件（v1.0.8）不支持多账号模式，只接受扁平的 botId/secret 配置。
问题 C：通道未配置
症状：
企业微信 default: enabled, not configured, stopped
企业微信机器人 ID 或 Secret 未配置
修复：
- 确认已安装企微插件：
openclaw plugins list | grep wecom
- 配置 botId 和 secret：
openclaw config set channels.wecom.botId <YOUR_BOT_ID>
openclaw config set channels.wecom.secret <YOUR_SECRET>
openclaw config set channels.wecom.enabled true
- 重启 gateway：
openclaw gateway restart
完整修复脚本
当用户确认需要修复时，可执行以下操作：
1. 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup.$(date +%Y%m%d%H%M%S)
2. 修复插件 ID
使用 edit 工具将 wecom-openclaw-plugin 替换为 wecom
3. 修复通道配置
如使用多账号模式，回退到单账号扁平结构
4. 验证修复
openclaw channels status 2>&1
openclaw gateway status 2>&1
5. 测试消息
让用户在企微发送测试消息，确认回复正常
配置模板
单账号模式（推荐，当前插件支持）
{
"channels": {
"wecom": {
"enabled": true,
"botId": "aibXXXXXXXXXXXXXXXXXX",
"secret": "XXXXXXXXXXXXXXXXXXXXXXXX",
"dmPolicy": "pairing",
"allowFrom": [],
"groupPolicy": "open"
}
},
"bindings": [
{
"agentId": "main",
"match": {
"channel": "wecom",
"accountId": "*"
}
}
]
}
多账号模式（需要插件支持，当前不可用）
{
"channels": {
"wecom": {
"enabled": true,
"defaultAccount": "main",
"accounts": {
"main": {
"botId": "aibXXXXXXXXXXXXXXXXXX",
"secret": "XXXXXXXXXXXXXXXXXXXXXXXX",
"dmPolicy": "pairing"
},
"agent-2": {
"botId": "aibYYYYYYYYYYYYYYYYYY",
"secret": "YYYYYYYYYYYYYYYYYYYYYYYY",
"dmPolicy": "pairing"
}
}
}
},
"bindings": [
{
"agentId": "main",
"match": {"channel": "wecom", "accountId": "main"}
},
{
"agentId": "agent-2",
"match": {"channel": "wecom", "accountId": "agent-2"}
}
]
}
⚠️ 注意：企微插件 v1.0.8 不支持多账号模式，使用上述配置会导致通道无法启动。
验证清单
修复完成后，确认以下项：
-
openclaw channels status显示enabled, configured, running - 日志中无
plugin id mismatch警告 - 日志中
Authentication successful - 企微发送测试消息能收到回复
- WebSocket 心跳正常（日志中每 30s 一次 heartbeat）
常见问题 FAQ
Q: 为什么插件 ID 不匹配？
A: 企微插件的包名是 @wecom/wecom-openclaw-plugin，但插件导出的 ID 是 wecom。配置时应使用导出 ID。
Q: 多账号模式什么时候支持？ A: 需要联系企微插件开发者添加此功能。目前只能使用单账号模式。
Q: 如何在单账号模式下使用多个 agent？ A: 可以通过 main 代理转发消息，或使用 Web Dashboard 直接访问不同 agent。
Q: 配对码在哪里查看？
A: openclaw pairing list wecom
Q: 如何批准配对？
A: openclaw pairing approve wecom <CODE>
参考资料
注意事项
- 修改配置前务必备份
openclaw.json - 修改配置后需要 重启 gateway 才能生效
- 多账号模式需要等待插件更新支持
- 如修复后仍有问题，查看完整日志：
/tmp/openclaw/openclaw-YYYY-MM-DD.log