企业微信接 WorkBuddy 走哪条路？两个入口两种模式，官方推荐长连接
企业微信这条接入路径，光「从哪儿进」就有两个答案，「怎么连」又有两个答案。四种组合，选错了就是走弯路。
官方文档其实把话说得挺明白，只是散在不同章节里。这篇把选择逻辑理出来：先按你的账号角色定入口，再按你有没有公网 IP 定模式。
本文依据 WorkBuddy 官方文档《接入企业微信指南》（
Platform-Integration/Wecom-Guide），核对日 2026-08-16。企业微信侧的规则以企业微信官方为准。我们没有安装客户端，界面文案以你实际看到的版本为准。
一、先看前提条件
官方给的两条：
- 已在电脑上安装 WorkBuddy，并开启了助理远程控制功能；
- 拥有一个可创建智能机器人的企业微信账号。
第二条是个门槛。没有企业微信账号的话，官方提示可以前往企业微信官网免费注册一个企业。
二、第一个选择：从哪个入口进
官方按账号角色给了两个入口，配置项是一致的，只是界面文案可能略有差异：
| 角色 | 入口路径 |
|---|---|
| 管理员 | 企业微信管理后台 →「安全与管理」→「管理工具」→「智能机器人」→「创建机器人」→ 选「API 模式创建」 |
| 普通成员 | 企业微信客户端 →「工作台」→「智能机器人应用」→「创建机器人」→「手动创建」→「API 模式创建」 |
普通成员这条路有个坑：官方专门写了——如果先进入了 AI 自动生成页面，要点左下角的「手动创建」，才能再选「API 模式创建」。
很多人在这一步被 AI 自动生成的流程带走了，配了半天发现不是要的东西。看到自动生成页面，先找左下角那个「手动创建」。
三、第二个选择：长连接还是 URL 回调
进入 API 模式之后，官方说明企业微信 API 模式支持两种接入方式，并且明确推荐长连接：
推荐优先使用长连接模式：在 WorkBuddy 中填写 Bot ID 和 Secret 即可完成绑定，配置更简单，无需回填 Webhook URL。
对照表：
| 长连接模式（推荐） | URL 回调模式 | |
|---|---|---|
| 要填什么凭证 | Bot ID + Secret | Token + Encoding-AESKey |
| 要不要回填 Webhook | 不需要 | 需要，生成 URL 后回填到企业微信 |
| 官方定位 | 主流程 | 备选方案（文档里放在文末） |
| 适合谁 | 绝大多数人 | 已在用 Webhook 配置，或因网络/部署限制必须走回调 |
判断方法很简单：你有没有一个稳定的、可对外访问的地址？没有的话选长连接，别犹豫。
选长连接还有一个连带的好处：Webhook 相关的那一整类问题从根上不会出现——官方 FAQ 里那条「企业微信提示 Webhook 域名主体校验未通过」，走长连接压根遇不上。
四、两种模式的完整步骤
公共部分（两种模式都要做）
进入 API 模式页面后，先完成公共信息并保存：
| 配置项 | 官方说明 |
|---|---|
| 机器人名称 | 建议填写容易识别的名字，如「Tencent WorkBuddy 助手」 |
| 可见范围 | 选择哪些员工、部门或标签可以使用这个机器人 |
点「可见范围」后的「添加」，选择需要使用机器人的成员、部门或标签。
完成后先点页面底部的「保存」，再在右侧「API 配置」区域选择接入方式。这个顺序别反——官方文档强调了要先保存。
顺带说一句：「可见范围」这一项是企业微信相对个人平台的主要优势。你可以只让某个部门用，这是 QQ、微信助理这类个人平台没有的管控能力。
长连接模式
企业微信侧：
- 在「API 配置」区域选择「使用长连接」；
- 复制 Bot ID；
- 点「点击获取」获取 Secret，并妥善保存。
官方提示：长连接模式不需要再填写 URL、Token 或 Encoding-AESKey。
WorkBuddy 侧：
- 点左下角头像菜单中的「设置 - 助理设置」；
- 在「集成（BETA）」区域找到「企微 AIBot 集成」，点「配置」；
- 弹窗中选择「WebSocket 长连接」；
- 填入 Bot ID 和 Secret；
- 点「注册」完成绑定。
URL 回调模式（备选）
企业微信侧生成凭据：
- 在「API 配置」区域选择「使用 URL 回调」；
- 点 Token 和 Encoding-AESKey 输入框右侧的「随机获取」；
- 保存这两个参数。
官方在这里标了「重要」：请务必保存好 Token 和 Encoding-AESKey，否则后续无法完成注册。
WorkBuddy 侧生成 URL：
- 进入「助理设置」→「企微 AIBot 集成」→「配置」；
- 注册弹窗中切换到「使用 URL 回调」；
- 填入 Token 和 Encoding-AESKey，点「注册」；
- 注册成功后复制生成的 Webhook URL。
回企业微信回填：把 Webhook 地址粘到 URL 输入框，点「保存」。
五、配好之后在哪找机器人
官方给的位置很具体：企业微信通讯录的「企业创建的」分组下，找到刚创建的机器人，点「发消息」。
先发一条简单消息（比如「你好」）做联通测试。能正常回复就说明通了。
六、官方给的三类排查
配不通的话，官方 FAQ 给了三条，都挺实用：
1）机器人没有响应
- 检查 WorkBuddy 状态：确保电脑上的客户端正在运行，且助理服务已开启；
- 核对接入方式：确认企业微信与 WorkBuddy 中选择的是同一种接入方式；
- 检查凭据：长连接核对 Bot ID 和 Secret；URL 回调核对 Token 和 Encoding-AESKey；
- 检查网络连接。
第二条是个高频错误——两边选的模式必须一致。企业微信那边选了长连接、WorkBuddy 这边选了 URL 回调，怎么配都不通。
2）URL 验证失败（仅回调模式）
- 确保 WorkBuddy 处于运行状态；
- 检查助理服务是否已正常启动；
- 重新复制 Webhook URL，确保没有遗漏或多余字符；
- 确认 Token 和 Encoding-AESKey 与 WorkBuddy 中配置的完全一致。
3）长连接注册失败
- 确认企业微信侧已选择「使用长连接」；
- 重新复制 Bot ID 和 Secret，避免带入多余空格；
- 如 Secret 已失效，可在企业微信后台重新获取后再次注册。
七、凭证处理的一个通用习惯
官方在两条排查里都提到了「多余空格」「遗漏或多余字符」——说明这是高频问题。
建议做法：复制凭证后，先粘到纯文本编辑器（记事本 / TextEdit）里看一眼首尾，确认没有多余的空格或换行，再填进去。首尾空白肉眼看不出来，但会让注册直接失败。
别在两个网页输入框之间直接来回复制，中间过一道纯文本最稳妥。
八、最容易被忘的前提
不管哪种模式，这条链路的终点都是你自己电脑上正在运行的那个客户端。官方在「机器人没有响应」的排查里，把它列在第一条。
电脑关机、休眠、客户端退出——机器人一定不回复，而且在企业微信后台里怎么查都查不出来。这也完美解释了「时好时坏」这类现象：你在电脑前的时候好好的，人一走电脑睡了就失联。
小结
- 两个入口按角色选：管理员走管理后台「安全与管理 → 管理工具 → 智能机器人」；普通成员走客户端「工作台 → 智能机器人应用」，注意要点**左下角「手动创建」**才能到 API 模式。
- 两种模式，官方推荐长连接：填 Bot ID + Secret，不需要回填 Webhook URL。URL 回调是备选，填 Token + Encoding-AESKey。
- 没有公网 IP 就选长连接，Webhook 那一整类问题从根上不会出现。
- 公共配置（机器人名称 + 可见范围）要先点底部「保存」，再选接入方式。
- 配好后在通讯录「企业创建的」分组下找机器人。
- 高频错误：两边选的接入方式必须一致；凭证别带多余空格（先过一道纯文本编辑器）。
- 「可见范围」是企业微信相对个人平台的核心优势。
功能与流程以官方为准，企业微信侧规则以企业微信官方为准，核对日 2026-08-16。