AI助理服务集成企业微信-大数据开发治理平台 DataWorks(DataWorks)-阿里云帮助中心

功能说明

DataClaw 支持两种企业微信消息接收模式：

特性	URL 回调模式	长连接模式
连接方式	企微主动推送到回调地址	实例主动连接企微服务器
公网入口	需要（自动创建）	不需要
适用场景	容器化部署、需要精细管控	快速接入、无需公网
IP 管控	支持白名单	不涉及
鉴权方式	API Key	BotId + Secret

URL 回调模式：企业微信服务器将用户消息通过 HTTPS 回调地址主动推送到 DataClaw 实例，适合需要精细管控入口 IP 的场景。
长连接模式：DataClaw 实例主动连接企业微信服务器建立长连接，适合快速接入、无需公网入口的场景。

前置条件

已创建 DataClaw 实例且实例状态为运行中。
拥有企业微信管理后台操作权限。

创建企业微信机器人

访问企业微信管理后台，在左侧导航栏单击管理工具 > 智能机器人。单击创建机器人，单击手动创建。
通过API模式创建智能机器人。
1. 在创建智能机器人界面，下拉到页面底部单击API模式创建。
2. 配置如下参数后单击保存。
  1. 可见范围：配置机器人的可见范围。
  2. API配置：在连接方式区域选择连接模式。
    - 使用长连接：实例主动连接企微服务器。在配置方法的Secret区域单击点击获取，保存Bot ID和Secret。
    - 使用 URL 回调：企微服务器将消息通过 HTTPS 主动推送到回调地址。无需获取 Bot ID 和 Secret，后续在 DataWorks 控制台配置时手动设置 Token 和 EncodingAESKey 即可。
  3. 可使用权限：按需配置机器人的权限。

使用长连接模式配置

返回DataWorks控制台，进入实例详情页的基本信息Tab页的通道配置区域。

在通道配置区域，选择通道为企业微信。
连接模式选择使用长连接。
填写Bot ID和Secret（在企微管理后台获取）。
单击保存。

使用URL 回调模式配置

在DataWorks AI助理服务实例配置

返回DataWorks控制台，进入实例详情页的基本信息Tab页的通道配置区域。

在通道配置区域，选择通道为企业微信。
连接模式选择使用URL回调。

填写或随机获取以下参数：

参数	说明	格式要求
Token	验证请求来源，确保请求来自企业微信服务器。	3~32 位英文字母或数字
EncodingAESKey	加密消息内容，防止数据在传输过程中被窃听或篡改。	格式要求：必须为 43 位字符（数字或英文字母）。加密标准：AES-256-CBC 算法。

重要

请妥善保管Token和EncodingAESKey，切勿泄露给任何第三方。

Token 和 EncodingAESKey可以在Dataworks处生成也可以在企业微信处生成，在其中一处生成后，复制到另一处即可。但两边的参数值必须保持一致。

配置 IP 白名单：限制只有指定 IP 段才能访问回调地址。IP 白名单需要包含企业微信服务端 IP，获取方式参见企业微信回调 IP 说明。
单击保存。
保存配置后，请等待实例状态变为运行中。

在实例详情页的企微通道信息中，可查看回调地址（callbackUrl），格式如下：

https://ai-assistants.cn-beijing.data.aliyuncs.com/xxxx/plugins/wecom/bot?apikey=sk-ai-assistants-xxxxx

复制完整的回调地址（包含 ?apikey=... 参数），下一步配置企业微信后台时使用。如果页面显示回调配置失败，请查看失败原因并重新保存配置。

在企业微信管理后台配置

登录企业微信管理后台。
进入安全与管理 > 管理工具 > 智能机器人 > 创建机器人，切换至API 模式创建。
连接方式使用URL 回调。

填写以下三项：

配置项	值	说明
URL	从 DataWorks 控制台复制的回调地址	完整地址，包含 `?apikey=...` 参数
Token	与 DataWorks 控制台配置的 Token 一致	两边必须完全相同
EncodingAESKey	与 DataWorks 控制台配置的 EncodingAESKey 一致	两边必须完全相同（43 位）

单击保存。

保存后，企业微信服务器会自动向回调地址发送验证请求：

验证通过：企微后台显示配置成功，可以开始接收消息。
验证失败：请检查 Token 和 EncodingAESKey 是否完全一致、实例状态是否为运行中、回调地址是否完整复制（包含 ?apikey= 部分）、IP 白名单是否已放开。

IP 白名单说明

IP 白名单用于限制哪些 IP 可以访问回调地址，防止未授权请求。

配置方式

在实例编辑页面的IP 白名单区域操作：

添加 IP：输入 IP 或 CIDR 网段（如 101.226.62.xx 或 10.0.0.0/8），单击添加。
删除 IP：在白名单列表中单击删除。

建议通过企业微信管理后台获取最新回调 IP 列表并添加到白名单中，避免回调请求被拦截。

白名单为空时的行为

如果从未配置过白名单：不创建 IP 访问控制，所有 IP 均可访问。
如果删除了所有白名单 IP：自动添加 127.0.0.1，阻止所有外部访问（相当于临时关闭回调入口）。重新添加企业微信回调 IP 段即可恢复。

API Key 轮换

如果 API Key 泄露或需要定期更换，可将鼠标悬浮在URL回调按钮上，点击悬浮窗口的刷新按钮，即可刷新API Key，刷新后：

平台将生成新的 API Key，旧地址立即失效。
您需要将新的回调地址更新到企业微信管理后台。

重要

轮换后必须在企业微信管理后台同步更新回调 URL，否则无法接收消息。

测试机器人

在群聊中点击添加群成员，搜索创建完成的机器人名称，加入群聊。
在已添加机器人的群中@机器人即可实现流式对话。

说明

URL 回调模式测试：配置成功后，用户在企业微信中向机器人发送消息，DataClaw 实例即可实时收到并处理。可在实例详情页查看通道状态，确认为已连通即表示配置成功。

模式切换

从 WebSocket 切换到 URL 回调

在通道配置中将连接模式改为URL 回调。
填写 Token 和 EncodingAESKey。
保存后，按照在企业微信管理后台配置完成企微后台配置。

从 URL 回调切换回 WebSocket

在通道配置中将连接模式改为长连接。
填写Bot ID和Secret。
保存后，Webhook 网关资源会自动清理。

说明

修改通道配置会触发实例重启，重启后仅保留工作区数据（记忆和技能），如有自定义依赖需重新安装。

常见问题

回调地址验证失败？

检查 Token 和 EncodingAESKey 是否与 DataWorks 控制台配置完全一致。
确认实例状态为运行中且回调配置未显示失败。
确认回调地址完整复制（包含 ?apikey=... 部分）。

配置成功但收不到消息？

检查 IP 白名单是否包含企业微信回调 IP 段。
确认 API Key 未被轮换（如轮换过需更新企微后台的回调 URL）。
查看实例详情页是否有回调相关的错误提示。

删除实例后回调还在？

删除实例时会自动清理所有网关资源，回调地址立即失效，无需额外操作。

白名单删除后回调不通了？

删除所有白名单 IP 后会自动添加 127.0.0.1 阻止外部访问。重新添加企业微信回调 IP 段即可恢复。

如何获取企业微信服务端 IP 段？

参见企业微信回调 IP 说明。