把 AI 助手拉进企微群：企微助理接入完整指引
本篇涵盖的知识重点
- 前置条件：WorkBuddy >= 4.6.4、拥有可创建智能机器人的企微账号
- 管理员走管理后台：安全与管理 → 管理工具 → 智能机器人 → 创建机器人
- 普通成员走客户端：工作台 → 智能机器人应用 → 创建机器人
- 两种角色都需先点「手动创建」，再选择「API 模式创建」
- 长连接模式只需 Bot ID 与 Secret，无需 URL、Token、Encoding-AESKey
- 私有化部署需另填自定义 WebSocket 地址，协议必须是 ws:// 或 wss://
接入路径导览
接入步骤详解
作用管理员和普通成员能看到的入口不同，走错路径会在第一步就卡住。
操作管理员：浏览器打开企业微信管理后台，用管理员账号登录后，依次点击「安全与管理」→「管理工具」→「智能机器人」→「创建机器人」。普通成员：打开企业微信客户端，进入「工作台」→「智能机器人应用」→「创建机器人」。
注意如果先进入的是 AI 自动生成页面，点击左下角的「手动创建」，再选择「API 模式创建」。没有企微账号可前往企业微信官网免费注册企业。
- WorkBuddy：已在电脑上安装 WorkBuddy >= 4.6.4，版本不够先升级。
- 企业微信账号：拥有一个可创建智能机器人的企业微信账号，这是硬性门槛。
- 网络连接：电脑和手机均能正常访问互联网。
- WorkBuddy 运行中：电脑保持开机并运行 WorkBuddy，关机期间机器人不会响应。
作用名称决定同事能不能一眼认出它，可见范围决定谁能用，两者都影响后续推广。
操作在 API 模式页面填写公共配置：机器人名称建议填易识别的名字，如「WorkBuddy 助手」；可见范围选择哪些员工、部门或标签可以使用。管理员点击「可见范围」后的「添加」选择成员，普通成员点击「可使用成员」后的「修改」进行选择。
注意管理员需先点击页面底部的「保存」，再在右侧「API 配置」区域选择「使用长连接」；普通成员则直接在下方「API 配置」区域选择。
- 机器人名称：建议填写容易识别的名字，如「WorkBuddy 助手」，方便同事在通讯录里快速找到。
- 可见范围（管理员）：选择哪些员工、部门或标签可以使用这个机器人，按「添加」逐个选。
- 可使用成员（普通成员）：同样是选择哪些员工、部门或标签可用，按「修改」进行调整。
- 范围设置建议：先小范围试点再逐步放开，避免一上来全公司可见造成误用。
作用这两个值是 WorkBuddy 与企微机器人通信的凭据，缺一不可。
操作在「API 配置」区域选择「使用长连接」，复制 Bot ID；点击「点击获取」取得 Secret，并妥善保存。两种角色在此步骤的操作一致。
注意Secret 请自行妥善保存。长连接模式下不需要再填写 URL、Token 或 Encoding-AESKey。
- 长连接模式（推荐）：在 WorkBuddy 中填写 Bot ID 和 Secret 即可完成绑定，配置更简单，无需回填 Webhook URL。
- URL 回调模式：适用于需要 Webhook 回调的场景，需在 WorkBuddy 中填写 Token 和 Encoding-AESKey，生成 Webhook URL 后再回填到企业微信。
- 选型建议：没有特殊回调需求就走长连接，配置步骤更少，也少一次回填操作。
作用企微侧建好了机器人，还要在 WorkBuddy 侧注册一次，两端才算连通。
操作打开 WorkBuddy，点击左下角头像菜单中的「设置 - 助理设置」；在「集成（BETA）」区域找到「企微助理集成」，点击「配置」；在弹窗中选择「WebSocket 长连接」，可选手动填写 Bot ID 和 Secret，或点击快捷绑定接入用企微扫码完成绑定；填入后点击「注册」完成绑定。
注意复制 Bot ID 和 Secret 时注意不要带入多余空格；Secret 失效可在企微后台重新获取后再次注册。
作用私有化部署的企微不走公有云默认地址，不填专属地址就注册不上。
操作在企业微信管理后台获取私有化部署的 WebSocket 地址，格式形如 ws://<网关>:<端口>/im_openws?bizid=1；在「WebSocket 长连接」配置中，除 Bot ID 和 Secret 外，将该地址填入自定义 WebSocket 地址输入框；点击「注册」完成绑定。
注意地址协议必须为 ws:// 或 wss://，使用 http:// 等其他协议会被拦截并给出提示；留空时自动回落到公有云默认地址；该输入框仅在长连接模式下出现。
- 协议要求：地址协议必须为 ws:// 或 wss://，使用 http:// 等其他协议会被拦截并给出提示。
- 留空行为：留空时自动回落到公有云默认地址，不影响常规（非私有化）部署的绑定。
- 出现条件：该输入框仅在 WebSocket 长连接模式下出现，URL 回调模式不涉及。
- 故障反馈：配置保存后重启 WorkBuddy 会自动重连；若地址不可达，界面会显示明确的连接错误状态，便于排查网络或地址配置问题。
作用注册成功不等于消息能通，发一条消息验证一次最稳妥。
操作在企业微信通讯录的「企业创建的」分组下找到刚创建的机器人，点击「发消息」，发送一条简单消息（例如「你好」）进行测试。配置正确时 WorkBuddy 会在企微中返回回复。
注意若机器人无响应，依次检查 WorkBuddy 是否在运行且助理服务已开启、两端选择的接入方式是否一致、凭据是否正确、网络是否正常。
- 群聊 @机器人下发团队协作任务：WorkBuddy 自动执行并返回结果。
- 跟进任务进度：直接向机器人发送任务指令，随时跟进执行进度。
- 创建专属任务群：长期绑定 WorkBuddy 处理团队日常工作。
- 发布通知：任务完成后自动通知群聊相关人员。
- 任务提醒：将待办、验收、协作事项同步到企微群。
- 流程打通：连接 WorkBuddy 任务处理与团队现有工作流。
- 确认操作：批准命令执行、文件修改等需要确认的操作。
作用群里的任务跑在助理专属文件夹里，不了解规则就容易找不到产物。
操作本地操作优先使用主界面的普通任务；需要远程触发或统一查看记录时，再使用助理。在企业微信中发起的任务，可回到电脑上的 WorkBuddy 助理页面查看完整的执行记录，包括思考过程、操作步骤、生成文件及最终结果。
注意远程会话只有一个且历史不可清空，所有远程指令集中在这一个会话里处理。
- 工作目录：普通任务自由指定；助理远程任务固定使用助理专属文件夹。
- 新建对话：普通任务支持多个并行任务；远程任务仅一个会话，所有远程指令集中处理。
- 上下文管理：普通任务可清空历史重新开始；远程任务保留完整对话历史，不可清空。
- 选型建议：本地操作优先用主界面的普通任务；需要远程触发或统一查看记录时，再使用助理。
- 执行环境：企业微信仅发送指令、批准操作和后续消息；您的电脑提供 WorkBuddy 执行任务所需的全部环境。
作用已有 Webhook 配置或受网络、部署限制时，长连接走不通，需要这条备选路径。
操作在企业微信的「API 配置」区域选择「使用 URL 回调」，点击 Token 和 Encoding-AESKey 输入框右侧的「随机获取」并保存；打开 WorkBuddy 进入「助理设置」→「企微 AIBot 集成」→「配置」，在注册弹窗中切换到「使用 URL 回调」，填入 Token 和 Encoding-AESKey 后点击「注册」；复制生成的 Webhook URL，回到企业微信机器人创建页面粘贴到 URL 输入框并点击「保存」。
注意请务必保存好 Token 和 Encoding-AESKey，否则后续无法完成注册；回填时确认两端使用的是同一种接入方式。
常见故障排查
- 还没有企业微信账号，可以前往企业微信官网免费注册一个企业。
- 长连接模式不需要再填写 URL、Token 或 Encoding-AESKey，只需 Bot ID 和 Secret。
- URL 回调模式下，请务必保存好 Token 和 Encoding-AESKey，否则后续无法完成注册。
- 机器人没有响应：检查 WorkBuddy 是否运行且助理服务已开启；核对企业微信与 WorkBuddy 选择的是同一种接入方式；长连接核对 Bot ID 和 Secret、URL 回调核对 Token 和 Encoding-AESKey；检查网络连接。
- URL 验证失败：确保 WorkBuddy 处于运行状态、助理服务已正常启动；重新复制 Webhook URL 避免遗漏或多余字符；确认 Token 和 Encoding-AESKey 两端完全一致。
- 长连接注册失败：确认企业微信侧已选择「使用长连接」；重新复制 Bot ID 和 Secret 避免带入多余空格；Secret 失效可在后台重新获取后再注册；私有化部署还需核对自定义 WebSocket 地址的协议、网关与端口，并确认在当前电脑可正常访问。
上手挑战
```markdown
我要在企业微信里创建一个能连接 WorkBuddy 的智能机器人。请分别写出「管理员」和「普通成员」两种角色的完整创建路径，每一步写成「入口 → 操作」的形式。另外说明：如果进入后看到的是 AI 自动生成页面，应该点哪里进入手动创建，以及创建时要选择哪种模式。
```得到两条互不混淆的创建路径，并明确「手动创建」与「API 模式创建」的具体点击位置。
```markdown
我要用 WebSocket 长连接模式把企业微信机器人接入 WorkBuddy。请整理一份凭据清单，表格列包含：凭据名称、在哪里获取、是否必须、保存注意事项。同时明确列出该模式下不需要填写的三项配置。
```得到一张凭据清单表，能看清 Bot ID 与 Secret 的获取位置和注意事项，并明确 URL、Token、Encoding-AESKey 无需填写。
```markdown
我们公司用的是私有化部署的企业微信，我在填入自定义 WebSocket 地址时总被拦截。请帮我列出格式要求与排查清单：1）合法的地址格式示例；2）允许的两种协议；3）留空时会发生什么；4）该输入框出现在哪种接入模式下；5）地址不可达时界面会给出什么反馈。
```得到一份含格式示例、协议要求、留空行为与错误反馈的核对清单，可据此逐项修正地址。
```markdown
我按指引完成了企业微信机器人与 WorkBuddy 的绑定，但在企微里发消息机器人没有反应。请给我一份按「先查什么、再查什么、最后查什么」排序的排查步骤，每一步写清楚：检查项、在哪里看、异常时如何处理。至少 4 步。
```得到一份有优先级的排查流程，覆盖运行状态、接入方式一致性与凭据核对，每步都给出处理动作。
本文基于官方文档再创作，具体以官方文档站实际展示为准。