跳到主要内容

企业微信

最近更新 2026/10/07

一、前置条件​

  • 拥有企业微信管理后台权限，可创建智能机器人；如需 OAuth，还需创建企业自建应用。
  • 拥有 Agentic Engine「管理后台 → 渠道管理」权限。
  • 已启用 Agentic Engine 渠道管理功能。
  • 部署服务器可访问企业微信官方长连接地址 wss://openws.work.weixin.qq.com。
  • 如需成员 OAuth 绑定，平台须通过 HTTPS 对用户开放，并准备好可用的公网域名。

二、创建企业微信智能机器人并获取凭证​

登录 企业微信管理后台，按以下步骤配置：

  1. 进入「安全与管理」->「管理工具」，找到「智能机器人」，点击「创建机器人」-> 「手动创建」。
  2. 滑动到最下方选择 API 模式创建，连接方式选择 使用长连接。
  3. 填写机器人名称、介绍、可见范围，并保存配置。
  4. 在 API 配置区域复制并妥善保存以下凭证：
企业微信字段平台字段说明
Bot IDBot ID智能机器人的唯一标识，用于长连接鉴权。
SecretBot Secret智能机器人密钥。仅在安全位置保存，不要写入代码、工单或聊天记录。
提示

无需配置机器人公网回调地址：Agentic Engine 会主动建立 WebSocket 长连接，并通过 Bot ID 与 Bot Secret 完成认证。

可选：创建成员 OAuth 自建应用​

OAuth 不是机器人收发消息的必需项。仅当需要用户在浏览器中一键绑定企业微信成员身份时，才需要在同一企业下创建自建应用。

  1. 在企业微信管理后台创建企业自建应用，并将需要使用的成员加入应用可见范围。
  2. 记录企业与应用凭证：
企业微信字段平台字段说明
企业 IDCorp ID通常以 ww 开头，可在企业信息中查看。
AgentIdAgent ID自建应用的应用 ID。
SecretCorp Secret自建应用 Secret，用于服务端获取成员身份。

必须：完成可信域名与 URL（域名）主体校验​

企业微信 OAuth 使用的回调域名必须先配置为自建应用的可信域名。保存可信域名前，企业微信可能同时检查域名所有权和域名备案主体，两项都需要通过。

  1. 进入「企业微信管理后台 → 应用管理 → 自建 → 目标应用 → 网页授权及 JS-SDK」，点击「设置可信域名」。
  2. 填写平台实际访问域名，例如 agent.example.com。只填写域名，不包含 https://、端口和路径；使用子域名时，按实际子域名单独配置。
  3. 点击「申请校验域名」，或按页面提示下载企业微信生成的 WW_verify_*.txt 校验文件。
  4. 保持文件名和内容不变，将文件部署到该域名的网站根目录。确认浏览器可直接访问：
域名所有权校验文件
https://agent.example.com/WW_verify_xxxxxxxxxxxx.txt
  1. 访问结果必须直接返回校验文件内容，不能跳转登录页、被鉴权拦截或返回前端 SPA 页面。
  2. 返回企业微信管理后台，勾选「已上传域名归属校验文件」并保存。若文件可访问但仍失败，检查 DNS/CDN 缓存，稍后重试。
警告

URL 主体校验：可信域名的 ICP 备案主体需与当前企业微信的认证/验证主体一致，或存在企业微信认可的关联关系。若提示“URL 主体校验未通过”或“域名主体不一致”，应用代码无法绕过；需改用主体一致的已备案域名，或先完成备案及主体关联后再配置。

配置项示例要求
可信域名agent.example.com企业微信后台只填写主机名
校验文件 URLhttps://agent.example.com/WW_verify_xxxxxxxxxxxx.txt部署在域名根目录并直接返回文件内容
OAuth 回调 URLhttps://agent.example.com/agent/api/wecom-oauth/callback示例为部署使用 /agent 子路径
来源白名单ALLOWED_ORIGINS=https://agent.example.com填写协议和主机名，不包含路径
提示

不要混淆两个 URL：校验文件必须位于域名根目录；OAuth 回调仍使用 /agent/api/wecom-oauth/callback 。两者路径不同，但主机名必须与可信域名一致。

  1. 完成可信域名、所有权和主体校验后，确保以下 OAuth 回调地址可以从浏览器正常访问：
未配置子路径时
https://<your-domain>/agent/api/wecom-oauth/callback

生产环境建议配置授权来源白名单，多个来源用英文逗号分隔：

ALLOWED_ORIGINS=https://<your-domain>

三、在平台中添加企业微信渠道​

管理员登录 Agentic Engine，进入「管理后台」→「渠道管理」：

  1. 点击「新建渠道」，渠道类型选择 企业微信。
  2. 填写以下配置项：
配置项是否必填说明
渠道名称必填显示名称，如「企业微信机器人」。
Bot ID必填企业微信智能机器人的 Bot ID。
Bot Secret必填企业微信智能机器人的 Secret。
启用成员 OAuth 绑定可选开启后优先通过浏览器授权绑定；关闭后仍可使用绑定码。
Corp ID条件必填启用 OAuth 时必须填写。
Agent ID条件必填启用 OAuth 时必须填写。
Corp Secret条件必填启用 OAuth 时必须填写。
默认模型可选不选择时使用系统全局默认模型。
系统提示词可选仅对该渠道中的 Agent 会话生效。
  1. 点击「保存」，然后打开渠道的「启用」开关。
  2. 确认渠道状态变为「在线」；如仍为「离线」或「异常」，按本文排障章节检查。
提示

每种渠道类型只允许创建一个实例。Secret 会加密存储且不会回显；编辑渠道时 Secret 留空表示保留原值。关闭 OAuth 会删除整组 OAuth 凭证。

四、用户绑定企业微信账号​

方式一：OAuth 授权绑定​

  1. 用户登录 Agentic Engine，点击左下角用户头像。
  2. 在账号菜单中找到「企业微信」，点击「绑定」。
  3. 系统打开企业微信成员授权页，用户使用同一企业的内部成员账号完成授权。
  4. 授权成功后窗口自动关闭，菜单中的企业微信状态变为「已绑定」。

方式二：一次性绑定码​

OAuth 未开启，或平台通过 HTTP 访问时，系统会自动使用绑定码：

  1. 点击左下角用户头像，在「企业微信」一行点击「绑定」。
  2. 复制系统生成的 6 位绑定码。绑定码 10 分钟有效，且只能使用一次。
  3. 在企业微信中向智能机器人发送以下任一命令：
绑定 ABC234
+bind ABC234

机器人回复“企业微信账号绑定成功”后，平台菜单会自动更新为「已绑定」。同一个企业微信成员不能覆盖其他 Agentic Engine 用户的活跃绑定。

解绑​

  1. 点击左下角用户头像，在「企业微信」一行点击「解绑」。
  2. 确认解绑后，状态变为「未绑定」。如需更换 Agentic Engine 账号，必须先完成原账号解绑。

五、常见问题​

渠道状态为「离线」或「异常」​

  • 确认 Bot ID 与 Bot Secret 来自同一个智能机器人，复制时没有多余空格。
  • 确认企业微信后台机器人未停用，且已选择 API 模式与长连接。
  • 确认服务端能够访问 wss://openws.work.weixin.qq.com。
  • Secret 重新生成后，旧值会失效；请编辑渠道、填写新 Secret 并重新启用。

OAuth 提示未启用或配置不完整​

  • 确认企业微信渠道已启用，且「启用成员 OAuth 绑定」开关已打开。
  • 确认 Corp ID、Agent ID、Corp Secret 均已填写，且来自同一企业的自建应用。
  • 确认自建应用可见范围包含当前成员。

OAuth 回调失败​

  • 确认回调域名、协议、端口和路径与平台实际访问地址完全一致。
  • 使用 NEXT_PUBLIC_BASE_PATH 时，回调地址必须包含该子路径。
  • 配置 ALLOWED_ORIGINS 后，确认当前访问来源在白名单中。
  • OAuth 绑定必须使用企业内部成员；外部联系人不支持绑定。

绑定码无效或已过期​

  • 重新生成绑定码，并在 10 分钟内使用。
  • 确认命令格式为 绑定 ABC234 或 +bind ABC234。
  • 绑定码只能消费一次；已使用的绑定码不能重复提交。

机器人能回复文本，但无法读取附件​

  • 确认 channel.wecom.fileUploads.enabled 未被关闭。
  • 确认文件类型受支持，且单文件大小和单条消息附件数未超过配置限制。
  • 确认沙箱附件存储与文件 API 可正常使用。

模板卡片点击后无响应​

  • 确认渠道长连接在线。
  • 确认卡片对应的交互未过期、未被回答，且当前点击用户就是绑定用户。
  • 检查服务端是否能在企业微信要求的时间内处理并更新卡片。

相关页面与下一步

这篇文档对你有帮助吗？
本页内容