跳到主要内容

企业微信对接指南

将 Sage AI 接入企业微信智能机器人后，员工可在企微私聊或群聊中与 AI 对话，查询告警、巡检主机、生成报告等，无需登录 ONE 控制台。机器人绑定创建时的账号与资源域，并遵循命令安全、内容安全等策略。

配置 IM 渠道可将 Sage AI 对话接入团队 IM，实现即时问答与协作。机器人自动绑定当前资源域并遵循权限管控，如需访问全部权限数据，可前往「全部资源域」配置。请勿在不同账号、环境或资源域中重复绑定同一 IM 凭证，否则可能导致消息丢失或对话中断。

先决条件​

要求说明
功能菜单具备 AI 工作台 / 安全运营 / IM 渠道 菜单权限
操作权限配置、解绑、启停需读写权限；只读仅可查看
企业微信账号具备创建智能机器人（API 模式）的权限（管理员或普通成员路径见下文）
网络长连接：平台可出站访问企微公网即可；URL 回调：平台需提供公网可访问的 HTTPS 回调地址
模型模型列表中至少有可用推理模型；IM 对话默认使用 Auto 模型路由

两种接入方式（必读）​

企业微信 API 模式支持两种接入方式，企微后台与 AI 工作台必须选择同一种，否则无法连通。

对比项WebSocket 长连接（推荐）URL 回调（Webhook）
适用场景私有化 / 内网、无公网入口，或希望配置更简单已有公网域名与 HTTPS，需由企微主动推送事件
企微侧选择「使用长连接」「使用 URL 回调」
AI 工作台选择「WebSocket 长连接」「使用 URL 回调」
需填写凭证Bot ID、SecretToken、EncodingAESKey
是否回填地址不需要回填 URL保存后生成 Webhook，必须回填到企微 URL
保存时校验校验连通性，通过后为「已连接」不做连通性校验，保存即为「已连接」

建议：能出站访问企微公网时优先用长连接；仅当网络策略要求公网回调、或已有 Webhook 方案时再用 URL 回调。

整体流程（一览）​

1. 在企业微信创建 API 模式智能机器人，配置可见范围并保存
        ↓
2. 二选一连接方案（两侧必须一致）
   ┌──────────────────────────────┬────────────────────────────────┐
   │ 长连接                        │ URL 回调                        │
   │ ① 企微选「使用长连接」         │ ① 企微选「使用 URL 回调」        │
   │ ② 复制 Bot ID、获取 Secret    │ ② 随机获取 Token、EncodingAESKey │
   │ ③ AI 工作台选长连接并保存      │ ③ AI 工作台选 URL 回调并保存      │
   │ ④ 连通校验通过即可             │ ④ 复制 Webhook 回填企微 URL 并保存 │
   └──────────────────────────────┴────────────────────────────────┘
        ↓
3. 发布机器人 → 私聊或群内 @机器人，发送「你好」验证

一、在企业微信创建 API 机器人​

请先按账号角色完成公共配置，再进入「二」或「三」选择接入方式。

1. 管理员：管理后台创建​

  1. 打开浏览器，访问 企业微信管理后台，使用管理员账号登录。
  2. 依次进入：安全与管理 → 管理工具 → 智能机器人 → 创建机器人。

若先进入 AI 自动生成页，请点击左下角 「手动创建」：

手动创建

在创建页选择 「API 模式创建」：

API 模式创建

创建入口示意：

创建机器人入口

2. 填写基本信息（管理员）​

配置项说明
机器人名称建议易识别，如「Sage AI 助手」
可见范围选择可使用该机器人的员工、部门或标签

image-20260821173428702

点击「可见范围」后的 添加，选择成员 / 部门 / 标签：

image-20260821173509332

完成以上配置后，先点击页面底部 「保存」，再在右侧 「API 配置」 中选择接入方式（长连接或 URL 回调）。

3. 普通成员：客户端创建（可选路径）​

  1. 打开企业微信客户端：工作台 → 智能机器人应用 → 创建机器人。
  2. 若进入 AI 自动生成页，点击左下角 「手动创建」，再选择 「API 模式创建」。

成员-手动创建

成员-基本信息

配置项说明
机器人名称建议易识别名称
可使用成员与管理员侧「可见范围」含义一致

成员-API 配置入口

完成后在下方 「API 配置」 中选择接入方式。

二、方式一：使用长连接接入（推荐）​

两侧均选择长连接后，只需 Bot ID 与 Secret，无需填写 URL、Token 或 EncodingAESKey。

1. 在企业微信获取 Bot ID、Secret​

  1. 在「API 配置」区域选择 「使用长连接」。
  2. 复制 Bot ID。
  3. 点击 「点击获取」 获取 Secret，并妥善保存。

image-20260821173648929

重要

请妥善保管 Secret。Secret 失效后需在企微后台重新获取，并在 AI 工作台重新保存。

2. 在 AI 工作台绑定（长连接）​

  1. 登录 Bonree ONE，确认右上角 环境、资源域。
  2. 进入 AI 工作台 → 安全运营 → IM 渠道。
  3. 在 企业微信 卡片点击 「配置」。
  4. 连接方式选择 「WebSocket 长连接」。
  5. 填写 Bot ID、Secret，点击 「保存」。
字段是否必填说明默认值校验规则
Bot ID必填企微长连接 Bot ID无非空；≤1000；不脱敏
Secret必填企微长连接密钥无非空；≤1000；脱敏展示

image-20260821173735813

保存时平台会做连通性校验，通过后状态为「已连接」。长连接模式不会生成 Webhook，也无需回填企微 URL。

三、方式二：使用 URL 回调接入​

适用于已有公网 HTTPS、或必须使用 Webhook 的场景。企微与 AI 工作台两侧均须选择 URL 回调。

1. 在企业微信生成回调凭据​

  1. 在「API 配置」区域选择 「使用 URL 回调」。
  2. 点击 Token、EncodingAESKey 旁的 「随机获取」。
  3. 妥善保存 Token 与 EncodingAESKey。此时 URL 可先留空，待工作台生成后再回填。

image-20260821173803975

重要

请务必保存 Token 与 EncodingAESKey。丢失后需重新生成，并在 AI 工作台重新配置。

2. 在 AI 工作台生成 Webhook​

  1. 进入 AI 工作台 → 安全运营 → IM 渠道 → 企业微信 → 配置。
  2. 连接方式选择 「使用 URL 回调」。
  3. 填写 Token、EncodingAESKey，点击 「保存」。
  4. 复制生成的 Webhook 地址。
字段是否必填说明默认值校验规则
Token必填与企微 API 配置中的 Token 一致无非空；≤1000；脱敏
EncodingAESKey必填与企微 EncodingAESKey 一致无非空；≤1000；脱敏

企微 URL 回调保存时不做连通性校验，保存成功后为「已连接」并生成 Webhook。

image-20260821173824789

image-20260821173951844

3. 回填 URL 并保存​

回到企业微信机器人配置页：

  1. 将 Webhook 粘贴到 URL 输入框。
  2. 确认 Token / EncodingAESKey 与工作台一致。
  3. 点击 「保存」，并按企微流程 发布 机器人。

image-20260821174023829

若 URL 验证失败：确认平台公网 HTTPS 可达、密钥完全一致、地址无多余空格或截断。

四、会话管理与解绑​

字段是否必填说明默认值校验规则
自动开启新会话必填超时未对话则自动新会话24 小时下拉 1–24 小时；不可关闭

悬停提示：长时间未活跃的历史上下文将不再发送给模型，有效降低 Token 消耗并提升响应速度。

点击 「解绑」 并二次确认后解除绑定；解绑后企微侧将无法得到 AI 回复。

五、开始使用​

在通讯录「企业创建的」中找到机器人，点击 发消息；或群内 @机器人。

image-20260821174851895

发送「你好」做连通测试。配置正确时，Sage AI 会返回回复。

使用说明（与 Web 端差异）​

能力说明
模型Auto 路由，IM 内不可切换
智能体 / Skill意图路由当前账号、资源域「我的」可用资源
附件以文本为主
频率限制同一机器人约 1 分钟 ≤ 20 次提问

Sage AI 历史中可切换查看 IM 会话（只读）。

六、常见问题​

机器人没有响应？​

  1. 核对接入方式：企微后台与 AI 工作台是否为同一种（都是长连接，或都是 URL 回调）。
  2. 长连接：核对 Bot ID、Secret；Secret 是否已重新获取后未同步到工作台。
  3. URL 回调：核对 Token、EncodingAESKey，且 Webhook 已回填并保存。
  4. 确认未跨账号 / 环境 / 资源域重复绑定同一凭证。
  5. 确认机器人已发布，且用户在可见范围 / 可使用成员内。

长连接注册 / 保存失败？​

  1. 确认企微侧已选择「使用长连接」。
  2. 重新复制 Bot ID、Secret，避免多余空格。
  3. 确认平台可出站访问企业微信公网服务。

URL 验证失败？​

  1. 确认 Webhook 为 HTTPS 且公网可达。
  2. 确认 Token、EncodingAESKey 与企微完全一致。
  3. 重新复制地址，避免截断或多余字符。

相关文档​