企微自建应用接入 OpenClaw

先叠个甲，部署过MOVIEPILOT v2的同学应该都用过他自带的企微通知，刚好我也部署了记账服务（ezbookkeeping）和备忘录服务（memos），本教程就是通过openclaw把所有服务都串起来（包括我让openclaw写的一个工资计算器也是可以通过按钮一键生成的）

最终效果

企微自建应用变成你的 AI 助手入口：

• 在企微客户端里发消息 → AI 实时回复

• 支持 MCP 工具调用（查通讯录、创建待办、读写文档、管理日程等）

• 双通道架构：Bot（WebSocket 长连接）+ Agent（HTTP 回调），互为备份

• 服务跑在自家 NAS 上，数据不出本地

一、架构总览

Plain Text ┌─────────────┐     ┌──────────────────┐     ┌────────────────┐     ┌──────────────────┐ │                    企业微信     │────▶│  Cloudflare       │────▶│  NAS (绿联       │────▶│  OpenClaw        │ │                  服务器        │                    │  Tunnel           │                    │  DXP4800)  │     │  Gateway :18799  │ │                                   │◀────│  (trycloudflare)  │◀────│                                 │◀────│                  │ └─────────────┘     └──────────────────┘     └────────────────┘     └──────────────────┘                            回调 HTTPS         免费临时隧道               Docker 容器              wecom 插件                           XML 加密回调        无需公网 IP               host 网络模式             Agent 模式

核心链路：

1. 企微把你的消息通过回调 URL 发出去

2. Cloudflare Tunnel 把外网请求转发到 NAS 本地

3. OpenClaw 的 wecom 插件解密、处理、回复

4. 回复通过 Agent HTTP API（或 Bot WebSocket）发回企微

为什么需要 Tunnel？

• NAS 在家宽后面，没有固定公网 IPv4（或者只有动态 IP）

• 企微回调要求 HTTPS + 公网可达

• Cloudflare Tunnel 免费，不需要买服务器、不用配端口转发

二、准备工作

项目	说明
企业微信管理后台权限	需要能创建自建应用
一台能跑 Docker 的 NAS/服务器	本次实操环境为绿联 DXP4800
OpenClaw 已安装并运行	监听在0.0.0.0:18799
域名 / DNS（可选）	使用 trycloudflare 临时隧道无需配置自有域名

软件版本

Plain Text OpenClaw: >= 2026.3.28 wecom-openclaw-plugin: 最新版 cloudflared: latest (cloudflare/cloudflared)

三、Step 1：安装企微插件（可以跳过，自带了）

在 OpenClaw 所在机器上执行对应安装命令，二选一即可：

Plain Text # 一键安装（推荐） npx -y @wecom/wecom-openclaw-cli install # 或者手动安装插件 openclaw plugins install @wecom/wecom-openclaw-plugin

安装完成后，可在 ~/.openclaw/extensions/wecom-openclaw-plugin/目录下查看插件文件，插件内置 15 项实用 Skill，涵盖通讯录查询、文档管理、待办创建、会议日程管理、消息推送等企微核心功能。

四、Step 2：创建企微自建应用

4.1 进入管理后台

登录 企业微信管理后台 → 应用管理 → 自建 → 创建应用。

基础信息填写：

• 应用名称：OpenClaw（可自定义）

• 应用 Logo：自行上传任意图片

• 可见范围：建议仅勾选个人账号，调试稳定后再放开全员权限

4.2 获取凭证

应用创建完成后，务必妥善保存以下核心凭证，后续配置全程需要用到：

参数	获取位置	说明
CorpId	管理后台 → 我的企业 → 企业信息	企业唯一标识
AgentId	应用详情页顶部	自建应用专属 ID
CorpSecret	应用详情页 → Secret 区域（点击查看获取）	应用核心密钥，隐私级别最高

4.3 配置接收消息（关键注意事项）

进入应用详情 → 接收消息 → 设置 API 接收，页面会展示三个配置字段，暂时全部留空：

字段	操作要求
URL	暂不填写，隧道部署完成后补充配置
Token	点击「随机获取」，复制保存
EncodingAESKey	点击「随机获取」，复制保存

重要禁忌：禁止提前点击保存！ 企微点击保存后会立即向填写的回调 URL 发送验证请求，此时隧道和本地服务未配置完成，会直接验证失败，导致配置重置。

五、Step 3：配置 OpenClaw Agent 模式

5.1 写入配置

将上一步获取的企微凭证替换下方对应参数，在设备终端依次执行命令写入配置：

Plain Text openclaw config set channels.wecom.agent.corpId "你的CorpId" openclaw config set channels.wecom.agent.corpSecret "你的CorpSecret" openclaw config set channels.wecom.agent.agentId "你的AgentId" openclaw config set channels.wecom.agent.token "你的Token" openclaw config set channels.wecom.agent.encodingAESKey "你的EncodingAESKey" openclaw config set channels.wecom.enabled true openclaw gateway restart

5.2 验证配置

网关重启后查看运行日志，出现以下格式输出，说明企微 Agent 模式配置、插件加载全部成功：

Plain Text [wecom] Agent mode configured: agentId=xxx corpId=xxx

5.3 配置结构参考

openclaw.json 完整合规配置参考（可对照自查）：

Plain Text {   "channels": {     "wecom": {       "enabled": true,       "botId": "your-bot-id",       "secret": "your-bot-secret",       "token": "your-token",       "encodingAESKey": "your-aes-key",       "corpId": "你的CorpId",       "corpSecret": "你的CorpSecret",       "agentId": "你的AgentId",       "agent": {         "corpId": "你的CorpId",         "corpSecret": "你的CorpSecret",         "agentId": "你的AgentId",         "token": "your-token",         "encodingAESKey": "your-aes-key"       }     }   } }

六、Step 4：搭建 Cloudflare Tunnel

若你的服务器具备固定公网 IP、独立域名且配置好 HTTPS 证书，可直接跳过本步骤，回调 URL 直接填写 https://你的域名/plugins/wecom/agent/default。家用 NAS、动态公网 IP 设备必须部署隧道。

6.1 启动 cloudflared 容器

执行 Docker 命令部署隧道服务，全程稳定保活：

Plain Text docker run -d \   --name cloudflared-test \   --network host \   --restart unless-stopped \   docker.m.daocloud.io/cloudflare/cloudflared:latest \   tunnel --no-autoupdate --url http://localhost:18799

核心参数说明：

• --network host：容器复用宿主机网络，可直接访问本地 18799 端口

• --restart unless-stopped：容器异常退出、设备重启后自动恢复运行，保障服务持续可用

• --no-autoupdate：禁用自动更新，避免版本变动导致隧道中断

• --url http://localhost:18799：将外网隧道请求转发至本地 OpenClaw 网关端口

补充说明：Docker Hub 访问异常时，默认使用国内镜像站加速拉取镜像，无需额外配置。

6.2 获取隧道公网 URL

执行以下命令提取临时公网隧道地址：

Plain Text docker logs cloudflared-test --tail 20 | grep trycloudflare

正常输出示例（即为公网入口地址）：

https://reviewed-obtained-mon-fabric.trycloudflare.com

关键注意事项：该 trycloudflare 临时 URL 为动态生成，容器重启、设备重启后会随机变更，仅适用于测试调试，不支持生产环境长期使用。

6.3 临时隧道优缺点与报错说明

✅ 优点	❌ 缺点
完全免费、无需自有域名、自动配置 SSL 证书	URL 动态变化、存在 Cloudflare 速率限制、不适配生产环境

网页解析失败报错说明：访问隧道默认页面 https://xxx.trycloudflare.com/plugins/wecom/agent/default 出现「网页解析失败，可能是不支持的网页类型，请检查网页或稍后重试」为正常现象。该接口为企微专属加密回调接口，仅支持企微服务器加密请求，不支持浏览器直接访问，无需排查修复。

生产环境进阶方案：参考 Cloudflare 官方文档，绑定个人域名与 Cloudflare 账号，实现固定隧道 URL，彻底解决动态地址问题。

七、Step 5：完成企微回调配置

7.1 填写回调配置信息

返回企微自建应用「接收消息」配置页面，完整填写三项参数：

字段	填写值
URL	https://获取的临时隧道URL/plugins/wecom/agent/default
Token	第四步随机获取并保存的 Token
EncodingAESKey	第四步随机获取并保存的 EncodingAESKey

填写完成后，点击保存提交配置。

7.2 回调验证原理

点击保存瞬间，企微服务器会主动发起 GET 验证请求，链路逻辑如下：

Plain Text GET /plugins/wecom/agent/default?msg_signature=xxx×tamp=xxx&nonce=xxx&echostr=xxx

OpenClaw 插件校验流程：

1. 通过 Token、时间戳、随机数计算 SHA1 签名，与请求携带的签名比对，防止请求伪造

2. 通过 EncodingAESKey 解密 echostr 加密字符串

3. 将解密后的明文原路返回企微服务器，验证通过则配置保存成功

7.3 验证失败常见故障排查

报错现象	核心原因	解决方法
企微提示「URL 不可达」	隧道容器未启动、隧道 URL 已更新失效	查看容器运行日志，重新获取最新隧道 URL 替换配置
提示「签名验证失败」	Token、EncodingAESKey 前后配置不一致	核对 OpenClaw 本地配置与企微后台参数，保持完全一致
系统超时	容器网络模式错误、本地端口被防火墙拦截	确认容器为 host 网络模式，放行 18799 端口防火墙规则

八、Step 6：消息收发故障专项排查（核心踩坑点）

配置保存成功不代表消息可正常收发，以下为实操高频故障及根治方案，覆盖 99% 连通异常问题。

8.1 典型故障症状

• 企微发送消息后，AI 无任何回复

• OpenClaw 后台无任何回调请求日志

• 手动 curl 隧道 URL 可正常连通，外网链路无异常

8.2 三大核心故障根因及解决方案

根因 1：回调可信 IP 白名单拦截（最常见）

企微后台应用「接收消息」页面底部的「回调可信 IP」，若填写过 NAS 本地公网 IP，会强制限制回调请求仅来自该 IP。而隧道模式下，请求来源为 Cloudflare 边缘节点 IP，与白名单不匹配，企微直接丢弃请求，不触发回调。

解决方案：清空「回调可信 IP」所有内容，无需填写任何地址。Token+AES 加密双重校验可完全保障回调安全，无需 IP 白名单兜底。

根因 2：企业可信 IP 不匹配（MCP 工具报错）

企微后台「企业可信 IP」用于校验应用 API 调用权限，若配置的旧公网 IP 与当前 NAS 公网 IP 不一致，会触发 60020 权限错误，导致通讯录查询、待办创建等 MCP 工具调用失败。

解决方案：在 NAS 终端执行 curl -s ifconfig.me 获取当前实时公网 IP，添加至企微「企业可信 IP」列表。

根因 3：纯 IPv6 域名链路异常（小众场景）

若使用仅配置 AAAA 记录（IPv6）、无 A 记录（IPv4）的自定义域名，企微服务器不完全兼容纯 IPv6 链路，会导致连接失败。

解决方案：放弃纯 IPv6 域名，切换为 Cloudflare Tunnel 临时隧道或同时配置 IPv4 解析的域名。

8.3 全网故障排查速查表

故障症状	可疑原因	快速检查方式
企微发消息无回复、无日志	隧道容器挂停	docker ps | grep cloudflared 查看容器运行状态
企微发消息无回复、无日志	隧道 URL 已变更未更新	重新执行日志查询命令，核对最新 URL
企微发消息无回复、无日志	回调可信 IP 拦截	进入企微后台确认白名单已清空
MCP 工具报错 60020	企业可信 IP 过期不匹配	核对 NAS 实时公网 IP 与后台配置
保存配置提示 URL 不可达	OpenClaw 端口未正常监听	ss -tlnp | grep 18799 校验端口监听状态

九、日常运维维护指南

9.1 隧道 URL 变更更新流程

临时隧道容器/设备重启后 URL 自动变更，按以下步骤快速更新：

1. SSH 连接 NAS，执行命令获取最新隧道 URL：sudo docker logs cloudflared-test --tail 20 | grep trycloudflare

2. 登录企微管理后台，进入自建应用「接收消息」配置页面

3. 替换全新回调 URL，Token、EncodingAESKey 无需修改，直接保存即可

进阶优化：可配置定时任务自动检测 URL 变更并同步更新，或直接绑定自有域名彻底规避该问题。

9.2 容器持久保活配置

若首次部署未添加自动重启参数，执行以下命令补配保活规则，避免服务中断：

Plain Text docker update --restart unless-stopped cloudflared-test

9.3 家用公网 IP 动态更新

家用宽带光猫、路由器重启后，公网 IPv4 会动态变化，需及时更新企微「企业可信 IP」，否则会导致 MCP 工具调用权限失效。建议定期核对 NAS 公网 IP 与后台配置。

十、安全配置规范与最佳实践

10.1 回调安全机制

• 企微所有回调消息采用 AES-256-CBC 加密 + SHA1 签名 双重校验机制，杜绝伪造、篡改请求

• Token 负责签名校验，EncodingAESKey 负责数据加解密，双重密钥保障通信安全

10.2 安全最佳实践（必做）

• ✅ 清空「回调可信 IP」：适配隧道架构，规避 IP 不匹配故障，不降低安全等级

• ✅ 精准配置「企业可信 IP」：仅填写当前 NAS 公网 IP，严控 API 调用权限

• ✅ 密钥分级保管：CorpSecret、Token、AES 密钥严禁外泄、硬编码、公开存储

• ✅ 权限分步开放：调试阶段仅个人可见，功能稳定后再放开全员访问权限

十一、实操全流程复盘

阶段	操作内容	耗时
① 插件安装	安装企微 OpenClaw 专属插件	2min
② 应用创建	企微后台创建自建应用，获取全套凭证	5min
③ 域名方案尝试	自定义域名+端口转发配置测试	30min
④ 故障排查	发现纯 IPv6 域名企微兼容问题	10min
⑤ 隧道部署	Docker 部署 cloudflared，获取临时公网隧道	5min
⑥ 参数配置	OpenClaw Agent 配置 + 企微回调参数填写	3min
⑦ 回调验证	企微回调校验通过，配置保存成功	1min
⑧ 连通故障排查	定位 IP 白名单拦截核心问题	20min
⑨ 全局修复	清空回调白名单、更新企业可信 IP	5min
⑩ 功能落地	企微 AI 消息、MCP 工具全部正常使用	——

实操总结：含踩坑排查全程耗时约 1.5 小时；直接采用隧道方案+规范配置，全程仅需 20 分钟即可完成部署。

附：脱敏凭证与配置对照参考

以下凭证已脱敏，仅用于配置格式核对，不可直接复用：

Plain Text CorpId:        ww31**************5f39 AgentId:       1000005 CorpSecret:    7TkJ****************************EXa4 Token:         0d44****************************5fde EncodingAESKey: hore****************************DYAU BotId:         aibH************************jXPPk BotSecret:     yTaV****************************VDAT 隧道 URL:      https://reviewed-XXXXXX-fabric.trycloudflare.com 回调路径:      /plugins/wecom/agent/default NAS 公网 IP:   14.1XX.121.25（动态，仅供参考） 企微可信 IP:   14.1XX.121.25 回调可信 IP:   已清空

教程基于 2026-05-25 实操记录编写。环境：绿联 DXP4800 NAS + OpenClaw + Cloudflare Tunnel + DeepSeek V4。

|（注：文档部分内容全部由 AI 生成)

skill自动化流程：

用户：帮我配置企微自建应用回调  ↓AI（自动）：  ① 检查 wecom 插件装没装 → 没装就自动装  ② 提示用户在企微后台拿 CorpId/AgentId/CorpSecret/Token/EncodingAESKey     → 用户把参数给 AI  ③ 自动检测服务器有没有公网 IP     → 有 → 直接配置     → 没有 → 自动检测 Docker，自动拉 cloudflared 容器，获取隧道 URL  ④ 自动写入 openclaw config + 重启  ⑤ 把回调 URL 告诉用户，让用户去企微后台填上点保存  ⑥ 保存后提醒用户做两个关键安全检查：     - 清空「回调可信 IP」（最大坑）     - 添加公网 IP 到「企业可信 IP」  ⑦ 让用户发测试消息验证

链接：https://ug.link/dxp4800-rss/file ... 174b1de42b681c54893

效果如图