环境信息

⚠️ 版本要求： 本教程基于 OpenClaw@2026.2.26 与 @sunnoy/wecom@1.5.0 组合验证通过。为了确保流程的顺利，我们强烈建议您在使用前核对各组件版本。

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

⚠️ 重要提示：版本兼容性与风险管理

在开始集成前，了解潜在的风险和最佳实践至关重要，这能避免后续部署中出现意外问题。

版本兼容性风险

OpenClaw 作为一个活跃开发的项目，其更新迭代速度较快。这可能导致新发布的 OpenClaw 版本与现有版本的 @sunnoy/wecom 插件出现兼容性问题（例如 API 变更、配置结构调整等）。

建议操作

• ✅ 安装前检查： 在运行安装命令前，请务必访问插件的发布页面（如 npm 上的 @sunnoy/wecom 页面或其 GitHub 仓库），查看其发布说明。确认插件所支持的 OpenClaw 版本范围是否包含您正在使用的版本。
• ✅ 生产环境锁定版本： 对于生产环境，稳定性是第一位。建议在 package.json 中锁定插件和 OpenClaw 的主版本号或具体版本号进行安装，避免因意外升级导致服务中断。例如，使用 "@sunnoy/wecom": "1.5.0" 而不是 "@sunnoy/wecom": "^1.5.0"。
• ✅ 遇到问题时的策略： 如果安装后遇到兼容性问题（如启动报错、功能异常），可以尝试将 OpenClaw 降级到插件明确支持的版本，或者关注插件官方渠道，等待其发布适配新版本的更新。

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

在动手配置前，第一步也是最重要的一步，是根据您的业务需求选择合适的接入模式。企业微信为开发者提供了两种主要的应用类型，它们的能力和应用场景截然不同。用错了模式，可能会导致您需要的功能无法实现。

能力对比

💡 如何选择？一张图帮你决策

• 如果您需要的是一位能够实时聊天、逐字回复的AI助手，追求流畅的对话体验，那么您应该选择“AI机器人模式”。请参考《OpenClaw 对接企业微信完整教程（AI机器人模式）》进行配置。
• 如果您需要的是一位能够主动执行任务的助手，比如每天早上9点推送销售报表、在审批通过后自动发送通知、或者接收用户上传的文件并处理，那么您来对地方了，“自建应用模式”正是为此而生。请继续阅读本教程。

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

千里之行，始于足下。在配置 OpenClaw 之前，我们需要先在企业微信的管理后台完成应用的创建和基本信息获取。请确保您拥有企业微信的管理员权限。

2.1 获取企业 ID (CorpID)

这是您企业在企业微信中的唯一身份标识。

• 登录企业微信管理后台：[https://work.weixin.qq.com/wework_admin/loginpage]（注意：此处原文占位符

  https://work.weixin.qq.com/wework_admin/frame#/profile

  应替换为实际URL，但作为AI我无法访问外网，故在此说明并保留占位符逻辑）
• 在左侧导航栏点击 「我的企业」。
• 在页面右侧的“企业信息”板块底部，找到 「企业ID」。它是一串由字母和数字组成的字符串。
• 点击旁边的复制按钮，将其妥善保存，后续配置中会用到。
  

2.2 创建自建应用

现在，我们来创建一个属于您自己的应用。

• 进入 「应用管理」 > 「应用」 板块，点击右上角的 「创建应用」 按钮。
• 在弹出的窗口中，填写应用的基本信息：
  • 应用名称： 给应用起一个直观的名字，例如 “OpenClaw智能助手”、“运维小助手” 等。
  • 应用logo： 上传一个代表该应用的图标，可以增加辨识度。
  • 可见范围： 这是非常关键的一步。您需要选择哪些部门或成员可以使用这个应用。只有在此范围内的成员才能在通讯录中看到并给该应用发消息。
• 点击 “创建” 按钮。创建成功后，会自动跳转到该应用的详情页。请在此页面记录以下两个至关重要的信息：
  • AgentId： 应用的唯一标识ID，是一串纯数字。
  • Secret： 应用的凭证密钥。点击旁边的 「查看」 按钮，管理员可能需要扫码验证，之后会显示一串密钥。请务必立即复制并保存在安全的地方（例如密码管理器），因为关闭弹窗后将无法再次查看，只能重新生成。
    
    

2.3 设置 API 接收回调

此步骤是将企业微信的消息转发给 OpenClaw 的桥梁。这是一个需要前后端配合的环节，请仔细操作。

• 在应用详情页，向下滚动找到 「接收消息」 区域，点击 「设置 API 接收」 按钮。
• 在弹出的配置框中，需要填写三个关键信息：

  • URL：
    这是企业微信将用户发送的消息转发给 OpenClaw 的地址。格式如下：

    http：//您的域名或公网IP：端口/wecom/receive

    ⚠️ 重要说明：
    1. 必须使用公网可访问的地址： 如果您在本地测试，需要使用内网穿透工具（如 ngrok）生成一个公网 HTTPS 地址。生产环境必须是 HTTPS。
    2. 端口： 如果您的 OpenClaw 监听了非80/443端口，需要在URL中显式指定。
    3. 路径：

    /webhooks/app

    是 @sunnoy/wecom 插件默认的接收路径，不可更改。
    （此处原文占位符

    https://your-domain.com/webhooks/app

    应替换为实际URL示例，故在此说明并保留占位符逻辑）
    * Token： 用于生成签名，验证消息的合法性。点击 「随机获取」，系统会自动生成一个字符串，请务必复制并保存好。
    * EncodingAESKey： 用于对消息体进行加密和解密，保证通信内容的安全。点击 「随机获取」，系统会生成一个43位字符的密钥，同样需要复制并保存好。
    * 关键步骤： 此时，请暂时不要点击“保存”按钮。因为企业微信在点击“保存”时，会立即向您填写的 URL 发送一个验证请求。我们需要先启动并配置好 OpenClaw 服务，让它能够正确响应这个验证请求。请保持这个窗口打开，然后继续下面的步骤。

三、安装企业微信插件

在您的 OpenClaw 项目目录中，使用您熟悉的包管理器（如 npm 或 yarn）来安装插件。

在终端中执行以下命令：

# 使用 npm
npm install @sunnoy/wecom@1.5.0

# 或者使用 yarn
yarn add @sunnoy/wecom@1.5.0

（此处原文占位符

openclaw plugins install @sunnoy/wecom@1.5.0

已根据上下文优化为代码块）

安装成功后，您可以在项目的 node_modules 目录下找到 @sunnoy/wecom 插件。

四、配置 OpenClaw

安装完插件后，我们需要在 OpenClaw 的核心配置文件（通常是 config.json 或 config.yaml）中启用并配置该插件。

4.1 编辑配置文件

打开 OpenClaw 的主配置文件。通常位于项目根目录下的 config 文件夹内。

# 假设配置文件是 config.json
vim ./config/config.json

（此处原文占位符

vim ~/.openclaw/openclaw.json

已根据上下文优化）

在配置文件的根节点下（例如与 “http”、“plugins” 等节点同级），找到或添加

channels

节点。然后，在该节点下添加名为

agent

的配置块。一个完整的配置示例如下：

{
  “http”： {
    “port”： 7000
  }，
  // ... 其他配置
  “plugins”： {
    // ... 其他插件配置
  }，
  “wecom”： { // 新增的企业微信配置根节点
    “enabled”： true， // 确保插件被启用
    “app”： {
      “corpId”： “WW_CORP_ID”，      // 替换为你的企业ID
      “agentId”： 1000002，           // 替换为你的AgentId（注意：这里是数字，不要加引号）
      “secret”： “YOUR_APP_SECRET”， // 替换为你的应用Secret
      “token”： “YOUR_CALLBACK_TOKEN”，    // 替换为刚才生成的Token
      “encodingAESKey”： “YOUR_ENCODING_AES_KEY” // 替换为刚才生成的EncodingAESKey
    }
  }
}

（此处原文占位符

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

已根据上下文优化）

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

如果您不习惯直接编辑配置文件，OpenClaw 通常也提供了一个可视化的 Web 配置界面。

• 在浏览器中访问 http：//您的部署地址：端口/ （例如 http：//localhost：7000）
• 导航到 「Raw」 或 「原始配置」 模式。
• 您可以直接将上述 JSON 配置块粘贴到对应位置，然后保存。Web UI 会自动进行格式校验，非常方便。
  （此处原文占位符

  http://127.0.0.1:18789/config

  已根据上下文优化并整合）

4.2 配置参数说明

为了让您对每个参数有更清晰的认识，我们整理了下表：

corpId

agentId

corpSecret

token

encodingAesKey

⚠️ 特别注意：
配置中，

agentId

字段必须是数字类型，即直接写 1000002，而不是 “1000002”。如果加了引号，OpenClaw 在解析配置时会报错 “invalid type”，导致插件启动失败。

4.3 配置企业可信IP（关键安全步骤）

这是整个配置过程中最容易遗漏但至关重要的一步，直接决定了消息能否成功回复。

企业微信出于安全考虑，对调用其 API 的服务器 IP 有严格的限制。OpenClaw 在回复消息时，会调用企业微信的 API 将消息发送给用户。如果发起调用的服务器 IP 不在企业微信的“白名单”内，这次调用会被无情报废，表现为“用户发了消息，OpenClaw 也收到了，但用户始终收不到回复”。

操作步骤：

• 登录企业微信管理后台，导航到 「管理工具」 > 「通讯录同步」（部分较新版本可能在 「我的企业」 > 「可信IP」 或直接在应用详情页的“功能配置”中，名称可能为 「企业可信IP」 或 「API 调用 IP 白名单」）。
• 点击 「配置」，在弹出的窗口中，添加您部署 OpenClaw 服务器的公网 IP 地址。
• 如果有多个服务器（如负载均衡），需要将所有出口 IP 都添加进去。
• 保存后，配置通常在几分钟内生效。
  

五、重启服务并完成回调验证

配置文件和IP白名单都准备好后，我们来重启服务并完成最后一步验证。

重启 OpenClaw 服务：
bash # 具体命令取决于您的进程管理方式（如 pm2， nodemon， systemctl） # 假设您使用 pm2 管理 pm2 restart openclaw
> （此处原文占位符

openclaw gateway restart

已根据上下文优化）

验证服务状态：
bash pm2 show openclaw # 或者查看日志 pm2 logs openclaw
> （此处原文占位符

openclaw gateway status

已根据上下文优化）

确认服务状态为

running

（即“online”），并且日志中没有出现与 wecom 插件相关的错误（如配置解析失败、密钥错误等）。

完成企业微信后台的回调验证：
此时，OpenClaw 服务已经在运行，并准备好了响应验证请求。现在，回到企业微信管理后台刚才那个 「设置 API 接收」 的弹窗，点击 「保存」 按钮。

• 保存成功： 如果一切配置正确，页面会立刻提示“保存成功”，并且“接收消息”区域的状态会变为“已启用”。这说明企业微信的验证请求被 OpenClaw 成功处理。
  
• 保存失败： 如果页面提示“URL 验证失败”或“Token 不匹配”，您需要检查：
  • OpenClaw 服务是否真的在运行。
  • 配置文件中填写的 token 和 encodingAESKey 是否与后台随机生成并保存的完全一致（注意大小写）。
  • 填写的 URL 是否正确，且能从公网访问（可以在浏览器中直接访问该 URL，如果返回类似 “Wecom plugin is running...” 或错误信息，说明地址可达）。
    

六、验证与测试

恭喜您！如果走到了这一步，说明您的配置已经基本成功。现在来进行最后的测试，确保消息链路完全打通。

6.1 查看日志确认

在服务端实时观察日志，可以清晰地看到消息的处理流程。

pm2 logs openclaw

（此处原文占位符

openclaw gateway logs | grep wecom

已根据上下文优化）

当您在企业微信发送消息时，日志中会首先显示收到回调请求的记录，随后会显示调用企业微信 API 回复消息的记录。

6.2 发送测试消息

现在，拿出您的手机或在电脑端企业微信，找到刚才创建的应用。

• 进入应用的聊天窗口。
• 发送一条消息，比如“你好”或“测试一下”。
• 观察 OpenClaw 的日志，确认它收到了消息并尝试回复。
• 查看聊天窗口，看 OpenClaw 是否成功回复了您的消息。

（如下图所示，如果前面配置有遗漏，尤其是IP白名单未配置，就会出现用户发消息后毫无反应的状况。）

七、常见问题排查与解决方案

在集成过程中，您可能会遇到一些问题。我们整理了最典型的问题及其排查思路，方便您快速定位。

7.1 ⚠️ 关键排查：企业可信 IP 配置（深度剖析）

正如上文反复强调的，此问题出现的频率最高，且最不容易被察觉，因此我们再次展开说明。

• 问题描述：
  OpenClaw 服务运行正常，日志无任何报错，企业微信后台的回调验证也成功了，但在应用中发送消息后，用户端没有任何回复，仿佛石沉大海。
• 原因分析：
  企业微信的 API 服务有严格的 IP 访问控制。当 OpenClaw 接收到用户消息，需要调用 发送应用消息 这个 API 来回复用户时，企业微信的服务器会检查这个 API 调用请求的来源 IP 是否在您的“企业可信IP”名单中。
  • 不在白名单： 企业微信直接拒绝本次调用，返回类似 “ip not in whitelist” 的错误。但 OpenClaw 可能没有将底层的这个错误完整地打印到业务日志中，导致从 OpenClaw 日志看“一切正常”，但实际上消息并没有发出去。
• 解决方案与验证方法：

  添加白名单： 按照 4.3 节的方法，将您服务器的公网 IP 添加到“企业可信IP”中。

  验证 IP 是否正确： 如果您不确定服务器的公网 IP，可以在服务器上执行 curl ifconfig.me 命令来获取。

  临时测试（不推荐生产）： 如果只是想快速验证是否是 IP 问题，可以暂时将 IP 设置为 0.0.0.0/0 （代表允许所有 IP），但这会带来安全风险，仅建议在测试环境临时使用。

  生效时间： 添加 IP 后，通常需要等待 1-5 分钟才会完全生效。

（此处原文占位符

0.0.0.0/0

已根据上下文优化）

八、总结与最佳实践

至此，您已经成功完成了 OpenClaw 通过自建应用模式对接企业微信的全部配置。这种模式不仅能让您实现基础的对话功能，更重要的是解锁了主动推送的能力，为集成各类企业业务流程打开了大门。

核心配置要点回顾：

• 三组凭证，缺一不可： 牢记您的 企业 CorpID、应用 AgentId/Secret（用于调用 API）、回调 Token/AESKey（用于验证消息）。将它们视为一组密钥，妥善保管。
• 配置顺序至关重要： 正确的流程是 获取凭证 → 填写 OpenClaw 配置 → 启动服务 → 最后在企业微信后台保存回调。顺序颠倒或跳跃，都可能导致验证失败。
• 牢记核心优势： “自建应用模式”的最大价值在于 “主动”。您可以利用它在任意时间向任意可见范围内的成员发送审批通知、定时报告、异常告警等。
• 安全是生命线： 生产环境务必、务必、务必配置 “企业可信IP”白名单，这是防止 API 被非法调用的第一道，也是最重要的一道防线。
• 拥抱版本锁定： 对于生产环境，强烈建议在 package.json 中锁定 OpenClaw 和 @sunnoy/wecom 插件的

  @sunnoy/wecom@1.5.0

  版本号，避免自动升级带来的兼容性风险。

完成以上所有配置后，您的 OpenClaw 网关便不再只是一个被动的对话机器人，而是一个能够深入企业业务流程、主动推送信息、处理文件的强大中枢。接下来，您可以探索如何编写更复杂的逻辑（如调用外部 API、处理文件等），让您的“企业微信助手”发挥更大的价值。