OpenClaw 对接企业微信（自建应用模式）完整教程

环境信息

⚠️ 版本要求 ：本教程基于 OpenClaw@2026.2.26 与 @sunnoy/wecom@1.5.0 组合验证通过。

OpenClaw 版本: 2026.2.26 或更高
插件版本: @sunnoy/wecom@1.5.0
对接平台: 企业微信
接入模式: 自建应用模式

⚠️ 重要提示：

1. 版本兼容性风险

OpenClaw 更新迭代较快，可能出现插件尚未适配新版本的情况。

2. 建议操作

✅ 安装前查看插件发布说明，确认版本支持情况

✅ 生产环境建议锁定版本号安装

✅ 如遇兼容性问题，可尝试降级 OpenClaw 或等待插件更新

一、模式选择：机器人 vs 自建应用

在开始配置前，请根据实际需求选择合适的接入模式：

能力对比	AI 机器人模式	自建应用模式
私聊接收	✅ 支持	✅ 支持
流式回复	✅ 打字机效果	❌ 完整消息回复
主动发送	❌ 不支持	✅ 支持（核心优势）
发送文件/图片	❌ 受限	✅ 完整支持
消息格式	JSON 回调	XML 回调
适用场景	智能对话客服	审批通知、定时推送、文件处理

💡 如何选择？

如果您需要 流式对话体验 ，请参考 《OpenClaw 对接企业微信完整教程（AI机器人模式）》 配置。

如果您需要 主动推送消息、发送文件或集成企业业务流程，请继续阅读本教程。

二、准备工作：企业微信后台配置

2.1 获取企业 ID (CorpID)

登录企业微信管理后台：https://work.weixin.qq.com/wework_admin/frame#/profile
点击 「我的企业」 页面
在页面底部找到 「企业ID」 ，点击复制备用

2.2 创建自建应用

进入 「应用管理」 > 「应用」 > 点击 「创建应用」
填写应用基本信息：
- 应用名称：如 "OpenClaw智能助手"
- 应用logo：上传应用图标
- 可见范围：选择可使用该应用的部门或成员
点击创建后，进入应用详情页，记录以下信息：
- AgentId：应用 ID（纯数字）
- Secret ：点击「查看」获取应用凭证

2.3 设置 API 接收回调

此步骤为关键配置，需与 OpenClaw 配置配合完成。

在应用详情页，找到 「接收消息」 区域，点击 「设置 API 接收」
在弹出的配置框中填写：
- URL：
  复制代码
```
https://your-domain.com/webhooks/app
```
  ⚠️ 注意：必须使用公网可访问的 HTTPS 地址，路径 /webhooks/app 为插件默认接收路径。
- Token ：点击 「随机生成」，复制保存
- EncodingAESKey ：点击 「随机生成」，复制保存（43位字符）
暂时不要点击保存，需等待 OpenClaw 服务启动后再操作。企业微信点击保存时会向 URL 发送验证请求。

三、安装企业微信插件

在终端执行以下命令安装插件：

bash 复制代码

openclaw plugins install @sunnoy/wecom@1.5.0

安装成功后，插件将位于 `~/.openclaw/extensions/` 目录。

四、配置 OpenClaw

4.1 编辑配置文件

打开配置文件：

bash 复制代码

vim ~/.openclaw/openclaw.json

在 channels 节点下添加 agent 配置块。完整配置示例如下：

json 复制代码

{
  "channels": {
    "wecom": {
      "enabled": true,
      "agent": {
        "corpId": "你的企业ID",
        "agentId": 1000002,
        "corpSecret": "你的应用Secret",
        "token": "回调Token",
        "encodingAesKey": "回调EncodingAESKey"
      }
    }
  }
}

💡 替代方式：通过 Web UI 配置

访问 http://127.0.0.1:18789/config

点击 「Raw」 进入原始编辑模式

粘贴上述配置并保存

4.2 配置参数说明

参数	类型	必填	说明
`corpId`	string	✅	企业唯一标识，在「我的企业」页面获取
`agentId`	number	✅	应用唯一标识，在应用详情页获取
`corpSecret`	string	✅	应用凭证密钥，点击「查看」获取
`token`	string	✅	回调配置中的 Token，用于签名验证
`encodingAesKey`	string	✅	回调配置中的 EncodingAESKey，用于消息加解密

📌 注意：agentId 必须是 数字类型，不要加引号。

4.3 配置企业可信IP

需要将域名对应的IP填写进来，否则第六步问答会出现一直没回复的情况！

五、重启服务

配置完成后，重启 OpenClaw 网关使配置生效：

bash 复制代码

openclaw gateway restart

验证服务状态：

bash 复制代码

openclaw gateway status

确认状态为 `running` 且无报错。

此时回到企业微信后台 ，点击 API 接收配置页面的 「保存」 按钮。如果配置正确，页面将提示保存成功。

成功如下：

失败如下：

六、验证与测试

6.1 查看日志确认

bash 复制代码

openclaw gateway logs | grep wecom

成功启动后，日志中应显示回调 URL 验证通过的记录。

6.2 发送测试消息

在手机或电脑端企业微信中：

进入刚创建的应用
发送消息，如 "你好"
观察 OpenClaw 是否正常回复（如下图，前面一直失败，原因其实是因为没有配置IP白名单，可以看4.3步）

七、常见问题

问题现象	可能原因	解决方案
回调 URL 验证失败	服务未启动或端口不通	检查 OpenClaw 服务状态，确认防火墙开放端口
提示 "Token 不匹配"	配置文件中 Token 填写错误	核对后台生成的 Token 与配置文件是否完全一致
配置无误但提问无回复	未配置企业微信 IP 白名单	详见下方 7.1 章节
消息发送成功但无回复	权限不足或 Secret 错误	检查应用 Secret，确认应用在可见范围内
接收不到消息	回调配置未保存或被禁用	返回企业微信后台确认 API 接收状态已启用
配置报错 "invalid type"	agentId 格式错误	确保 `agentId` 为数字类型，未加引号

7.1 ⚠️ 关键排查：企业可信 IP 配置

问题描述 ：

OpenClaw 服务运行正常，日志无报错，企业微信后台回调验证通过，但在应用中发送消息后 没有任何回复 。
原因分析 ：

企业微信出于安全考虑，默认情况下可能限制了调用 API 的来源 IP。如果您的服务器公网 IP 未添加到企业微信的 「企业可信IP」 白名单中，OpenClaw 尝试调用 API 发送回复消息时会被企业微信服务器拒绝，且往往不会在前端给出明显提示。
解决方案：

登录企业微信管理后台，进入 「管理工具」 > 「企业可信IP」（或在应用详情页查找相关设置）。
点击 「配置」 ，添加您部署 OpenClaw 服务器的 公网 IP 地址。
保存后等待几分钟生效，再次尝试发送消息。

💡 提示：如果是动态 IP 或不确定 IP，可暂时先配置为 0.0.0.0/0（不推荐生产环境使用）进行测试，确认是 IP 白名单问题后再修改为固定 IP。

八、总结

自建应用模式核心配置要点：

三组凭证：企业 CorpID、应用 AgentId/Secret、回调 Token/AESKey
配置顺序：获取凭证 → 填写配置 → 启动服务 → 保存回调
核心优势：支持主动推送、文件发送，适合业务集成场景
安全设置 ：生产环境务必配置 企业可信IP 白名单
版本锁定 ：生产环境建议锁定 @sunnoy/wecom@1.5.0 版本
完成配置后，您的 OpenClaw 便具备了与企业微信深度集成的能力，不仅限于被动对话，更能主动参与企业业务流程。

OpenClaw 对接企业微信（自建应用模式）完整教程